Salta ai contenuti
@aws/nx-plugin
Blog

ts#mcp-server

Generatore di Server TypeScript MCP

Genera un server TypeScript per il Model Context Protocol (MCP) per fornire contesto ai Large Language Model (LLM).

Cos’è il MCP?

Il Model Context Protocol (MCP) è uno standard aperto che consente agli assistenti AI di interagire con strumenti e risorse esterne. Fornisce un modo coerente per i LLM di:

  • Eseguire strumenti (funzioni) che compiono azioni o recuperano informazioni
  • Accedere a risorse che forniscono contesto o dati

Utilizzo

Generare un Server MCP

Puoi generare un server MCP TypeScript in due modi:

  1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
  2. Apri la console Nx in VSCode
  3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
  4. Cerca @aws/nx-plugin - ts#mcp-server
  5. Compila i parametri richiesti
    • Clicca su Generate

    Opzioni

    Parametro Tipo Predefinito Descrizione
    name Obbligatorio string - MCP server project name.
    directory string packages Parent directory where the MCP server is placed.
    subDirectory string - The sub directory the MCP server is placed in. By default this is the MCP server project name.

    Output del Generatore

    Il generatore creerà i seguenti file del progetto:

    • Directorypackages/<name>/
      • README.md Documentazione del server MCP con istruzioni d’uso
      • project.json Configurazione del progetto Nx con target per build, bundle e dev
      • Directorysrc/
        • index.ts Punto d’ingresso del server MCP
        • server.ts Definizione principale del server, con strumenti e risorse
        • global.d.ts Dichiarazioni di tipo TypeScript per importare file markdown
        • Directoryresources/
          • example-context.md File markdown di esempio usato come risorsa per il server MCP

    Lavorare con il Tuo Server MCP

    Aggiungere Strumenti

    Gli strumenti sono funzioni che l’assistente AI può chiamare per eseguire azioni. Puoi aggiungere nuovi strumenti nel file server.ts:

    server.tool("toolName",
      { param1: z.string(), param2: z.number() }, // Schema di input usando Zod
      async ({ param1, param2 }) => {
        // Implementazione dello strumento
        return {
          content: [{ type: "text", text: "Result" }]
        };
      }
    );

    Aggiungere Risorse

    Le risorse forniscono contesto all’assistente AI. Puoi aggiungere risorse statiche da file o risorse dinamiche:

    // Risorsa statica da file
    import exampleContext from './resources/example-context.md';
    

    server.resource('resource-name', 'example://resource', async (uri) => ({
      contents: [{ uri: uri.href, text: exampleContext }],
    }));
    

    // Risorsa dinamica
    server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
      const data = await fetchSomeData();
      return {
        contents: [{ uri: uri.href, text: data }],
      };
    });

    Configurazione con Assistanti AI

    Per utilizzare il tuo server MCP con assistanti AI, devi prima creare un bundle:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    Questo crea una versione aggregata in dist/packages/your-mcp-server/bundle/index.js (il percorso può variare in base alle impostazioni della directory).

    File di Configurazione

    La maggior parte degli assistanti AI che supportano MCP utilizza un approccio simile alla configurazione. Dovrai creare o aggiornare un file di configurazione con i dettagli del tuo server MCP:

    {
      "mcpServers": {
        "your-mcp-server": {
          "command": "node",
          "args": [
            "/path/to/workspace/dist/packages/your-mcp-server/bundle/index.js"
          ],
          "transportType": "stdio"
        }
      }
    }

    Sostituisci /path/to/workspace/dist/packages/your-mcp-server/bundle/index.js con il percorso effettivo del tuo server MCP aggregato.

    Configurazione Specifica per Assistente

    Consulta la seguente documentazione per configurare MCP con assistenti AI specifici:

    Workflow di Sviluppo

    Target di Build

    Il generatore si basa sul generatore di progetti TypeScript e ne eredita i target, aggiungendo inoltre i seguenti target:

    Bundle

    Il task bundle utilizza esbuild per creare un singolo file JavaScript aggregato utilizzabile con gli assistenti AI:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    Questo crea una versione aggregata in dist/packages/your-mcp-server/bundle/index.js (il percorso può variare in base alle impostazioni della directory).

    Dev

    Il task dev monitora le modifiche nel progetto e ricostruisce automaticamente il bundle:

    Terminal window
    pnpm nx run your-mcp-server:dev

    Particolarmente utile durante lo sviluppo, garantisce che l’assistente AI utilizzi sempre l’ultima versione del tuo server MCP.