toy-mcp-server

Ein minimaler Model Context Protocol (MCP)-Server, der von Grund auf neu gebaut wurde, um zu lernen, wie MCP wirklich funktioniert – keine Boilerplate-Generatoren, keine Templates, nur das SDK.

Gebaut als erstes praktisches MCP-Projekt: zwei Tools und eine Resource, über stdio mit Claude Desktop verbunden.

Was es tut

MCP ermöglicht einem LLM-Client (wie Claude Desktop), Funktionen aufzurufen, die auf deinem eigenen Rechner laufen, anstatt nur Text aus seinen Trainingsdaten zu generieren. Dieser Server stellt bereit:

Tools (Funktionen, die Claude aufrufen kann):

• roll_dice – würfelt N Würfel mit einer konfigurierbaren Seitenanzahl

• flip_coin – wirft eine Münze N-mal

Ressourcen (schreibgeschützte Daten, die Claude abrufen kann):

• server-info – grundlegende Metadaten über den Server (Name, Zweck, Startzeit)

Warum das existiert

LLMs können nicht auf etwas außerhalb ihrer Trainingsdaten zugreifen und standardmäßig nichts tun – sie generieren nur Text. MCP ist eine Standardmethode, um einem Modell Folgendes zu geben:

• Fähigkeiten, die es von sich aus nicht hat (z. B. echte Zufälligkeit – LLMs sind dafür berüchtigt, dass sie selbst keine wirklich zufälligen Zahlen auswählen können)

• Zugriff auf Live- oder private Daten, von denen es auf keine andere Weise erfahren kann

Dieses Projekt ist eine kleine, sichere Sandbox für diese Idee, bevor man einen MCP-Server an etwas Echtes anbindet (eine Datenbank, eine API mit Authentifizierung usw.).

Technologie-Stack

• TypeScript

• @modelcontextprotocol/sdk – das offizielle MCP-SDK

• zod – Laufzeit-Schema-Validierung für Tool-Argumente

• stdio-Transport (lokale Subprozess-Kommunikation mit Claude Desktop)

Projektstruktur

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

Einrichtung

1. Abhängigkeiten installieren

npm install

2. Kompilieren

npm run build

3. Mit Claude Desktop verbinden

Finde deine Claude-Desktop-Konfigurationsdatei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: normalerweise unter %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json – der genaue Pfad kann je nach Installationsmethode variieren (Microsoft Store vs. direkter Installer). Der zuverlässigste Weg, ihn zu finden: Öffne Claude Desktop → Einstellungen → Entwickler → Lokale MCP-Server → Konfiguration bearbeiten, wodurch die genaue Datei geöffnet wird, die die App liest.

Füge diesen Server unter mcpServers hinzu (füge ihn also in die vorhandene Datei ein, statt sie zu überschreiben):

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

Ersetze den Pfad durch den tatsächlichen absoluten Pfad zu build/index.js auf deinem Rechner. Auf Windows musst du die Backslashes (\\) im JSON-String escapen.

4. Claude Desktop neu starten

Beende Claude Desktop vollständig (nicht nur das Fenster schließen) und öffne es wieder. Bestätige, dass toy-mcp-server als verbunden angezeigt wird.

5. Probiere es aus

Stelle in einem Chat eine folgende Frage:

• „Wurf 3 sechsseitige Würfel"

• „Wirf eine Münze 10-mal."

Über der Antwort solltest du einen kleinen Indikator für einen Tool-Aufruf sehen (z. B. „Roll Dice"), der bestätigt, dass Claude die Funktion tatsächlich aufgerufen hat und nicht geraten hat.

So funktioniert es, kurz

• McpClient – das Objekt, das die Fähigkeiten des Servers gegenüber jedem verbundenen Client deklariert

• registerTool(name, config, handler) – registriert eine aufrufbare Funktion. config.inputSchema nutzt Zod, um jede Argumentationsargumente zu validieren, die das Modell sendet, bevor der Handler läuft

• registerResource(name, uri, config, handler) – erlaubt schreibgeschützte Daten, die über eine URI adressierbar sind und ohne Argument abgerufen werden

• StdioServerTransport – das Wire-Modell: Claude Desktop startet diese Datei als Subprozess und kommuniziert über stdin/stdout mittels JSON-RPC. console.log wird hier nie zum Loggen verwendet, da stdout der eigentliche Protokollkanal ist – stattdessen wird console.error (stderr) eingesetzt

Nächste Schritte

*the Tools durch echte heraus ersetzen, die auf eine echte Datenbank zugreifen (z. B. Postgres via Prisma)

• Ein GitHub-gestütztes Tool hinzufügen (z. B. list_open_prs), um dienzusübung der tokenbasierte Authentifizierung zu üben

• Den Streamable HTTP-Transport erkunden, um den Server remote zu hosten (lokal von einer Anwendung zu fern)

Lizenz

MIT