TypeScript MCP SDK: McpServer & Zod Schema în Model Context Protocol (MCP)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "dex-server", version: "1.0.0" });
server.tool(" curs_valutar", { moneda: z.enum(["EUR", "USD"]) }, async ({ moneda }) => ({
  content: [{ type: "text", text: `Curs : 4.97 RON` }]
}));

Descriere & Utilizare

Ecosistemul Node.js / TypeScript este extrem de popular pentru serverele MCP deoarece orice pachet publicat pe npm poate fi rulat instantaneu de utilizatori cu o singură comandă npx -y pachetul-tau, fără a configura medii virtuale Python.

SDK-ul oficial @modelcontextprotocol/sdk oferă clasa de nivel înalt McpServer, care se integrează nativ cu biblioteca Zod pentru definirea și validarea schemelor de intrare ale uneltelor (server.tool()), resurselor (server.resource()) și prompturilor (server.prompt()).

La finalul scriptului, conectezi instanța serverului la transportul dorit (de exemplu new StdioServerTransport() sau StreamableHTTPServerTransport cu Express) prin await server.connect(transport).

Cum să o reții ușor

💡 Clasa McpServer este echivalentul Express.js pentru lumea AI, iar schemele Zod sunt paznicii de la intrare care verifică fiecare parametru trimis de model.

Opțiuni și parametri tehnici

• server.tool(name, description, zodShape, handler): înregistrează o unealtă asincronă cu validare Zod automată.
• z.string().describe("..."): metoda .describe() din Zod este esențială deoarece devine descrierea parametrului văzută de LLM în JSON Schema!
• content: [{ type: "text", text: "..." }]: structura standard de răspuns returnată de handler-ul unei unelte.
• StdioServerTransport: clasa de transport pentru rularea din linia de comandă.

Exemple practice și cazuri de utilizare

• Instalarea dependențelor: npm install @modelcontextprotocol/sdk zod
• Descrierea parametrilor cu Zod: { cnp: z.string().length(13).describe("CNP-ul de 13 cifre al persoanei") }
• Conectarea transportului: const transport = new StdioServerTransport(); await server.connect(transport);

Sfaturi de configurare & capcane

Adaugă întotdeauna linia shebang #!/usr/bin/env node în vârful fișierului TypeScript compilat și câmpul "bin" în package.json dacă vrei ca serverul tău să poată fi lansat direct cu npx.

Comenzi și ghiduri înrudite

• fastmcp-python-server: Resursă asociată din acest modul.
• mcp-servers-json-config: Resursă asociată din acest modul.
• mcp-inspector-debug: Resursă asociată din acest modul.