Salta ai contenuti
@aws/nx-plugin
Blog

ts#mcp-server

Generatore di Server TypeScript MCP

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

Cos’è l’MCP?

Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti AI di interagire con strumenti e risorse esterne. Fornisce un metodo consistente per gli 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 l’importazione di file markdown
        • Directoryresources/
          • example-context.md File markdown di esempio utilizzato 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", "tool description",
      { 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 bundled 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 di configurazione simile. 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 bundled.

    Configurazione Specifica per Assistante

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

    Traduzione italiana:

    Flusso di Sviluppo

    Target di Build

    Il generatore è basato sul generatore di progetti TypeScript e quindi eredita i suoi target, aggiungendo inoltre i seguenti target:

    Bundle

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

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

    Questo crea una versione bundled 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

    Questo è particolarmente utile durante lo sviluppo poiché garantisce che l’assistente AI utilizzi l’ultima versione del tuo server MCP.