Server MCP TypeScript

Genera un server TypeScript per il Model Context Protocol (MCP) per fornire contesto ai Modelli Linguistici di Grandi Dimensioni (LLMs).

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 modo coerente per gli LLM di:

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

Utilizzo

Genera un Server MCP

Puoi generare un server MCP TypeScript in due modi:

VSCode

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
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server

npm

npx nx g @aws/nx-plugin:ts#mcp-server

bun

bunx nx g @aws/nx-plugin:ts#mcp-server

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:ts#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:ts#mcp-server --dry-run

Consiglio

Prima utilizza il generatore ts#project per creare un progetto a cui aggiungere il tuo server MCP.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	string	-	The project to add an MCP server to
name	string	-	The name of your MCP server (default: mcp-server)

Output del Generatore

Il generatore aggiungerà i seguenti file al tuo progetto TypeScript esistente:

• Directoryyour-project/

  • Directorysrc/

    • Directorymcp-server/ (o nome personalizzato se specificato)

      • index.ts Punto di ingresso del server MCP
      • server.ts Definizione principale del server
      • Directorytools/

        • add.ts Strumento di esempio
      • Directoryresources/

        • sample-guidance.ts Risorsa di esempio
  • package.json Aggiornato con entry bin e dipendenze MCP
  • project.json Aggiornato con target serve del server MCP

Lavorare con il 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" }]
    };
  }
);

Attenzione

L’SDK MCP supporta attualmente solo Zod v3. Per consentire l’uso di Zod v4 in altri generatori, la dipendenza su Zod v3 è installata come zod-v3. Per gli schemi degli strumenti MCP, dovrai importare Zod come segue:

import { z } from 'zod-v3';

Una volta risolto questo problema con l’SDK MCP, potrai rimuovere la dipendenza aggiuntiva zod-v3 e importare direttamente da zod.

Aggiungere Risorse

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

const exampleContext = 'alcuni contesti da restituire';

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

File di configurazione

La maggior parte degli assistenti AI che supportano MCP utilizza un approccio di configurazione simile. È necessario creare o aggiornare un file di configurazione con i dettagli del server MCP:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/index.ts"]
    }
  }
}

Attenzione

Se ricevi un errore come ENOENT npx durante la connessione al server, potrebbe essere necessario specificare il percorso completo di npx, che puoi ottenere eseguendo which npx nel terminale.

Ricarica a caldo

Durante lo sviluppo del server MCP, puoi configurare il flag --watch affinché l’assistente AI visualizzi sempre le versioni più recenti di strumenti/risorse:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/index.ts"]
    }
  }
}

Nota

Se aggiungi nuovi strumenti o risorse, potrebbe essere necessario aggiornare il server MCP nell’assistente AI.

Configurazione specifica dell’assistente

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

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Consiglio

Alcuni assistenti AI, come Amazon Q Developer, consentono di specificare una configurazione del server MCP a livello di workspace, particolarmente utile per definire i server MCP rilevanti per un progetto specifico.

Esecuzione del Server MCP

Il modo più semplice per testare e utilizzare un server MCP è configurarlo con un assistente AI (come sopra). Puoi comunque eseguire il server usando il target <your-server-name>-serve, utile se passi dal trasporto STDIO al trasporto HTTP streamable.

pnpm

pnpm nx run your-project:your-server-name-serve

yarn

yarn nx run your-project:your-server-name-serve

npm

npx nx run your-project:your-server-name-serve

bun

bunx nx run your-project:your-server-name-serve

Questo comando utilizza tsx --watch per riavviare automaticamente il server quando i file cambiano.