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:

VSCode
CLI

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

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

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

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

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

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:

pnpm nx run your-mcp-server:bundle

yarn nx run your-mcp-server:bundle

npx nx run your-mcp-server:bundle

bunx 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:

Amazon Q Developer (Configurazione MCP da riga di comando)
Cline (Panoramica su MCP)
Cursor (Protocollo Model Context)
Claude Code (Configurare il Model Context Protocol - MCP)

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:

pnpm nx run your-mcp-server:bundle

yarn nx run your-mcp-server:bundle

npx nx run your-mcp-server:bundle

bunx 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:

pnpm nx run your-mcp-server:dev

yarn nx run your-mcp-server:dev

npx nx run your-mcp-server:dev

bunx 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.