first-mcp-server

Projektübersicht

• Ein minimaler MCP-Server (Model Context Protocol), der ein einzelnes Tool namens add bereitstellt, das zwei Zahlen add iert und das Ergebnis als Text zurückgibt.

• Erstellt mit den @modelcontextprotocol-Paketen und zod für die Eingabevalidierung.

Wichtige Dateien

• index.js – die zentrale Server-Datei, die das Tool add registiert und den Server startet.

Voraussetzungen

• Node.js 16+ (empfohlene LTS)

• npm oder yarn

Installation

1. Klone das Repositorium und wechsle in das Projektverzeichnis:

   git clone && cd /Users/sagar/Documents/Learning/MCP-Server

2. Installiere die Abhängigkeiten (Beispiel mit npm):

   npm install

Verwendete Abhängigkeiten in dasen Projekt (hier Beispiele aus dem Code):

• @modelcontextprotocol/server (server)

• @modelcontextprotocol/server/stdio (STDIO-Transport)

• @modelcontextprotocol/express (Express-Hilfer)

• @modelcontextprotocol/node (Node HTTP-Transport)

• zod (Validierung)

Ausführen:

• Standard-HTTP-Transport (so wie das Projekt der zezeit startet):

  node index.js

  Der Server lauscht auf Port 3001 und stellt den MCP-Endpunktepunkt über /mcp bereit (siehe index.js).

• STDO-Transport (nützlich für lokale CLI-artige Integrations):

  Komentrieen Sie ie Aufruf aus gg? Tie. Enkomentieren Sie den Aufruf von runServerOnSTDIOTransport() in index.js und führen Sie aus:

  node index.js

Verwendungsbeispiele

1. HTTP-Beispiel (mit curl)

• Anforderungs-Ppayload (JSON):

{ "tool": "add", "input": { "num1": 10, "num2": 20 } }

• Beispiel-Aufruf mit curl (Host/port bei Bedarf anpassen):

curl -X POST http://localhost:3001/mcp
-H "Content-Type: application/json"
-d '{"tool":"add","input":{"num1":10,"num2":20}}'

• Erwartete Antwort (das Tool des Servers gibt ein content-Array mit Text -Blöcken zuruck):

{ "content": [ { "type": "text", "text": "30" } ] }

Hinweis: index.js nutzt für den HTTP-Transport NodeStreamableHTTPServerTransport and ruft transport.handleRequest(req, res, req.body) auf (siehe index.js). Das genaue Format, das der Transport erwartet, hängt von der Implementierung des @modelcontextprotocol/node-Transports ab; das obige Beispiel folgt der einfachen Form, die in this'en project used (tool + input).

2. STDO-Beispiel (lokale CLI-Integration)

• Das Projekt enthält eine Hilfsfunktion zur Ausführung des Servers üßber STDO mit StdioServerTransport. Im STDO-Betrieb erwartet der Server JSON-Anfragen auf stdin und antwortet auf stdout. Das in index.js registierte Tool validiert die Eingaben mit zod und gibt die Suche als Text.

Tool-Details () Beim Code)

• Tool-Name: add

• Beschreibung: „Add two numbers"

• E ingabeschema (zod):

  • num1: number

  • num2: number

Implementierung snippet (from [index.js]...:11-33):

server.registerTool(
  "add",
  {
    title: "add",
    description: "Add two numbers",
    inputSchema: z.object({ num1: z.number(), num2: z.number() }),
  },
  async (ctx) => ({
    content: [{ type: "text", text: `${ctx.num1 + ctx.num2}` }],
  }),
);

Hinweise:

• Validierung: zod validiert die Eingaben bereits. Stellen Sie sicher, dass aufrufer numerische Werte senden und validierungsfehler:

• Fehlerbehandlung: Fügen Sie try/catc around transport.handleRequest and the Tool-Handler hinzu, um konsistente Fehler-Payloads and HTTP-Statuscodes (4xx bei Clientfehler, 5xx bei Serverfehler) zurückgegeben.

• Logging & Monititoring: Führe Sie strukturertes Local, Request-Ids and grundlegende Metriken ein, um Nutzung und Fehler zu überwachen.

• Sicherheit: Falls öffentlich erreichbar, schützen Sie den /mcp-Endkpkt (Authentifizierung, Rate-Limiting) and( die abiaufen)h zu: ** related

• Tests: Führen Sie eine Einheit-Tests für of the Tool Handler and integration tests für die Transports (HTTP and STDO) hin zu.

Mitwirken

• Öffnen Sie Issues oder Pull Requests for Feature-Anfragen oder Fehlerbehehinzusen.