MCP TypeScript Starter

MCP TypeScript Starter ist eine produktionsorientierte Grundlage für die Entwicklung eines Model Context Protocol-Servers mit TypeScript. Der Starter enthält ein typisiertes Beispiel-Tool, stdio- und Streamable-HTTP-Transporte, strikte Validierung, Tests, einen gehärteten Container und automatisierte GHCR-Veröffentlichung.

Klonen Sie das Repository, ersetzen Sie die Beispiel-Domäne und behalten Sie die Infrastruktur, die echte MCP-Server benötigen.

Navigation

• Verwendung dieses Starters

• Über

• Funktionen

• MCP-Tools

• Tech-Stack

• Installation

• Konfiguration

• MCP-Client-Einrichtung

• Anpassen des Starters

• Verifizierung

• Einschränkungen

• Mitwirken

• Lizenz

Related MCP server: mcp-server-http-streamable

Verwendung dieses Starters

Klicken Sie auf GitHub auf Use this template, um einen neuen MCP-Server mit einer unabhängigen Git-Historie zu erstellen. Ersetzen Sie anschließend das Beispiel-Tool und aktualisieren Sie die Projektidentität gemäß Anpassen des Starters.

Forken Sie dieses Repository, wenn Sie Verbesserungen über einen Pull Request beisteuern möchten. Lesen Sie Mitwirken, bevor Sie Änderungen einreichen.

Wenn Ihnen dieser Starter geholfen hat, erwägen Sie, dem Repository einen Stern zu geben. Das hilft anderen TypeScript-Entwicklern, das Projekt zu entdecken.

Über

Der Starter demonstriert den vollständigen Weg von einer validierten MCP-Tool-Definition zu einem für Clients sichtbaren strukturierten Ergebnis. Der Server verwendet das aktuelle modulare MCP TypeScript SDK und das Web-Standard-HTTP-Modell von Hono anstelle eines eigenen Server-Frameworks.

Der standardmäßige stdio-Transport ist für lokale Clients gedacht, die den Server als Kindprozess starten. Streamable HTTP ist zustandslos und erstellt für jede Anfrage einen neuen MCP-Server, sodass der Transport ohne gemeinsam genutzten Sitzungsspeicher repliziert werden kann.

Das Beispiel führt begrenzte In-Memory-Arbeit aus. Es gibt keine Telemetrie, Anwendungsdatenbank, persistenten Speicher, Authentifizierung oder Abhängigkeit von externen Diensten.

Funktionen

• Registriert Tools mit strikten Zod-Eingabe- und -Ausgabeschemas.

• Gibt sowohl menschenlesbare Inhalte als auch typisierte strukturierte Inhalte zurück.

• Enthält präzise MCP-Sicherheitsannotationen.

• Unterstützt stdio und zustandsloses Streamable HTTP.

• Verwendet Hono mit Host- und Origin-Validierung gegen DNS-Rebinding.

• Bindet HTTP standardmäßig an Loopback und erfordert für andere Schnittstellen eine Allowlist.

• Begrenzt Tool-Eingaben und HTTP-Anforderungstexte.

• Hält stdout im stdio-Modus exklusiv für MCP-Protokollnachrichten.

• Behandelt SIGINT und SIGTERM mit idempotentem Graceful Shutdown.

• Läuft als Nicht-Root-Container mit Unterstützung für ein schreibgeschütztes Root-Dateisystem.

• Testet Konfiguration, stdio-Anbindung, MCP-Verhalten, Hono-Routen und echten HTTP-Verkehr.

• Veröffentlicht Multi-Architektur-Images erst nach bestandenen Qualitätsprüfungen.

MCP-Tools

echo

Gibt eine validierte Nachricht und optionale String-Metadaten zurück. Es ist bewusst einfach gehalten, damit das Repository MCP-Schemas, Registrierung, Annotationen und Ergebnisse vermittelt, ohne eine Geschäftsdomäne zu erfinden.

Beispieleingabe:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

Beispiel für die strukturierte Ausgabe:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

Nachrichten sind auf 10.000 Zeichen begrenzt. Metadaten akzeptieren höchstens 20 Einträge; Schlüssel sind auf 64 Zeichen und Werte auf 1.024 Zeichen begrenzt.

Tech-Stack

• Node.js 24+

• TypeScript mit strengen Projektregeln

• Model Context Protocol TypeScript SDK 2

• Hono

• Zod

• Vitest

• pnpm

• Docker

Installation

Voraussetzungen

• Node.js 24+ und pnpm 11 für die lokale Entwicklung.

• Docker und Docker Compose für die Container-Bereitstellung.

Docker Compose

Die empfohlene HTTP-Bereitstellung verwendet das veröffentlichte Multi-Architektur-Image:

ghcr.io/lukegskw/mcp-typescript-starter:latest

Laden Sie das Compose-Beispiel herunter und geben Sie den Hostnamen an, den Clients verwenden werden:

curl -O https://raw.githubusercontent.com/lukegskw/mcp-typescript-starter/main/compose.example.yaml
export MCP_ALLOWED_HOSTS='mcp.example.internal'
docker compose -f compose.example.yaml up -d

Die Streamable-HTTP- und Health-Endpunkte sind verfügbar unter:

http://<host>:3000/mcp
http://<host>:3000/healthz

Um einen anderen Host-Port zu veröffentlichen, setzen Sie MCP_PUBLISHED_PORT. Die Anwendung verwendet im Container weiterhin Port 3000.

Das latest-Tag folgt dem neuesten erfolgreichen Build aus dem Standard-Branch. Verwenden Sie für eine kontrollierte Bereitstellung und ein Rollback ein Versions- oder unveränderliches sha-*-Tag.

Docker run

docker run -d \
  --name mcp-typescript-starter \
  --restart unless-stopped \
  --read-only \
  --user 10001:10001 \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:size=16m,mode=1777 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_ALLOWED_HOSTS=127.0.0.1,localhost,mcp.example.internal \
  -p 3000:3000 \
  ghcr.io/lukegskw/mcp-typescript-starter:latest

Container aus dem Quellcode erstellen

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .

Lokale Node.js-Installation

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
pnpm install --frozen-lockfile
pnpm build
pnpm start -- --transport stdio

Für die lokale Streamable-HTTP-Entwicklung:

MCP_TRANSPORT=streamable-http pnpm dev

Konfiguration

Die Befehlszeilenoption --transport überschreibt MCP_TRANSPORT. MCP_ALLOWED_HOSTS enthält Hostnamen, keine URLs; nehmen Sie jeden Hostnamen auf, den legitime Clients und Health-Checks verwenden.

Der Server enthält keine Geheimnisse in seiner Beispielkonfiguration. Fügen Sie Domänen-Anmeldeinformationen über die Bereitstellungsplattform oder die Umgebung hinzu, niemals als MCP-Tool-Argumente oder in eingecheckten Dateien.

MCP-Client-Einrichtung

Für einen Client, der Streamable-HTTP-Serverdefinitionen akzeptiert:

mcp_servers:
  starter:
    url: http://127.0.0.1:3000/mcp

Für einen Client, der einen lokalen stdio-Server startet:

{
  "mcpServers": {
    "starter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-typescript-starter/dist/main.js",
        "--transport",
        "stdio"
      ]
    }
  }
}

Damit ein lokaler Client den Container über stdio starten kann, verwenden Sie docker run -i --rm und übergeben Sie --transport stdio nach dem Image-Namen. -i ist erforderlich, damit der Client MCP-Nachrichten über Standardeingabe und -ausgabe austauschen kann.

Die Konfigurationsformate der Clients unterscheiden sich. Konsultieren Sie die Dokmentation des Clients für das genaue Schema und starten Sie den Client nach der Änderung seiner Serverdefinition neu oder laden Sie ihn neu.

Anpassen des Starters

Die wichtigsten Erweiterungspunkte sind bewusst direkt:

1. Kopieren oder ersetzen Sie src/tools/echo.ts.

2. Definieren Sie strikte Eingabe- und Ausgabeschemas, bevor Sie den Handler schreiben.

3. Registrieren Sie das Tool in src/server.ts.

4. Fügen Sie MCP-Verhaltenstests und gegebenenfalls Domänen-Integrationstests hinzu.

5. Ersetzen Sie Paketname, Serveridentität, Image-Referenzen und README-Inhalt.

Halten Sie Tool-Module für ihre eigenen Schemas und Handler verantwortich. Halen Sie Transportmodul uninabhängig von Domänen-Tools. Führen Sie Dienste oder Persistenz nur ein, wenn echtes Verhalten sie erfordert.

Verifizierung

Führen Sie die vollständige Repositor-Testsuite aus:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build

Für Container-Änderungen:

docker buildx build --load -t mcp-typescript-starter:test .

Verbinden Sie abschließend einen MCP-Client und bestätigen Sie, dass echo aufgelistet ist und sowoht Text als auch strukturierte Inhalte zurückgibt. Bestätigen Sie im HTTP-Modus, dass /healthz {"status":"ok"} meldet.

Einschränkungen

• Das Beispiel stellt ein Tool und keine Ressourcen oder Prompts bereit.

• Streamable HTTP hat keine Authentifizierung. Beschränken Sie es auf Loopback, ein vertauenswürdiges LAN, ein VPN, ein privates Containernetzwerk oder einen authentifizierten Reverse-Proxy.

• Host- und Origin-Allowlists verhindern bestimmte Klassen von DNS-Rebinding-Angrifen, authentizieren Aufrufer jedoch nicht.

• Der HTTP-Server ist zustandslos und enthält keine gemeinsame Persistenz oder verteilte Koordination.

• Rate Limiting, Tracing, Metriken und domänenspezifisches Logging sind nicht enthalten.

• Das Repositorium ist ein Quellcode-Starter, keine veröffentlichte npm-Bibliothek.

Lesen Sie SECURITY.md, bevor Sie den HTTP-Transport öffentlich zugänglich machen oder ein Sicherheitsproblem melden.

Mitwirken

Beiträge sind willkommen. Bevor Sie einen Pull Request öffnen:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t mcp-typescript-starter:test .

Änderungen müssen strenge Typisierung, begrenzte Validierung, strukturierte MCP-Ergebnisse, die Reinheit des stdout-Protokolls, sichere HTTP-Standardwerte, deterministische Tests und Dokumentation benutzersichtbaren Verhaltens bewahren. Fügen Sie keine Abstraktionen hinzu, ohne einen konkreten Anwendungsfall für sie zu haben.

Lizenz

MIT. Siehe LICENSE.