mcp-suite

Ein produktionsreifer TypeScript-MCP-Server, der KI-Agenten (Claude Desktop, Cursor, Windsurf, benutzerdefinierte Agenten) strukturierten Zugriff auf reale Daten in vier Bereichen bietet: Finanzmärkte, Web3/DeFi, Entwicklertools und Gesundheitswesen (FHIR).

• Auth-first — JWT-Validierung standardmäßig aktiviert

• Domänenisolierung — fehlende API-Schlüssel deaktivieren nur eine Domäne, nicht den gesamten Server

• Antwort-Cache (LRU + TTL) und Token-Bucket-Ratenbegrenzung pro Domäne

• Typisierte Schemas (Zod) für jeden Tool-Input und -Output

• Zwei Transporte: stdio (lokal) und HTTP + SSE (remote/gehostet)

Schnellstart

# Run directly (no global install required)
npx mcp-suite

# Or install globally
npm install -g mcp-suite
mcp-suite

Voraussetzungen: Node.js ≥ 20, npm ≥ 10

Installation

1. Umgebungsvariablen einrichten

Kopieren Sie .env.example nach .env und tragen Sie die Schlüssel für die Domänen ein, die Sie aktivieren möchten:

cp .env.example .env

# Authentication (required in production)
MCP_JWT_SECRET=your-secret-here

# Financial Markets (Alpha Vantage + CoinGecko)
ALPHA_VANTAGE_API_KEY=

# Web3 / DeFi (Alchemy + OpenSea + Blur)
ALCHEMY_API_KEY=
OPENSEA_API_KEY=

# Developer Tools (GitHub)
GITHUB_TOKEN=

# Healthcare / FHIR (optional — defaults to public HAPI sandbox)
FHIR_BASE_URL=https://hapi.fhir.org/baseR4

# Server
LOG_LEVEL=info         # debug | info | warn | error
MCP_PORT=3000          # HTTP transport only
AUTH_DISABLED=false    # set true for local dev only

Sie benötigen nur Schlüssel für die Domänen, die Sie verwenden. Domänen ohne Schlüssel werden beim Start stillschweigend deaktiviert.

2. Entwicklungstoken generieren

npx mcp-suite gen-token
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Zu Claude Desktop hinzufügen

Hinzufügen zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mcp-suite": {
      "command": "npx",
      "args": ["mcp-suite"],
      "env": {
        "MCP_JWT_SECRET": "your-secret-here",
        "ALPHA_VANTAGE_API_KEY": "...",
        "ALCHEMY_API_KEY": "...",
        "OPENSEA_API_KEY": "...",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

4. Als HTTP-Server starten (Remote-/gehostete Deployments)

npx mcp-suite --transport http --port 3000

Dies stellt GET /health, GET /tools und den SSE-Endpunkt für Remote-MCP-Clients bereit.

CLI-Befehle

Verfügbare Tools

Finanzmärkte

Unterstützt durch Alpha Vantage und CoinGecko. Erfordert: ALPHA_VANTAGE_API_KEY

Beispiel:

{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }

Web3 / DeFi

Unterstützt durch Alchemy, OpenSea und Blur. Erfordert: ALCHEMY_API_KEY, OPENSEA_API_KEY

Beispiel:

{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }

Entwicklertools

Unterstützt durch die GitHub API. Erfordert: GITHUB_TOKEN

Beispiel:

{ "tool": "get_pipeline_status", "arguments": { "repo": "vercel/next.js", "branch": "canary" } }

Gesundheitswesen (FHIR)

Unterstützt durch HAPI FHIR R4. Erfordert: nichts (standardmäßig öffentliche Sandbox) oder FHIR_BASE_URL für benutzerdefinierte Endpunkte.

HIPAA-Hinweis: Alle Tools für das Gesundheitswesen verbinden sich mit einer öffentlichen Sandbox, die nur synthetische Daten enthält. Es wird auf keine echten Patientendaten (PHI) zugegriffen. Ersetzen Sie für den produktiven Einsatz FHIR_BASE_URL durch einen HIPAA-konformen EHR-Endpunkt und konfigurieren Sie entsprechende SMART on FHIR OAuth 2.0-Anmeldedaten.

Beispiel:

{ "tool": "lookup_patient", "arguments": { "name": "Smith", "birth_date": "1980-01-15" } }

Authentifizierung

Die Authentifizierung ist standardmäßig aktiviert. Jeder Tool-Aufruf muss ein gültiges JWT enthalten.

Produktion

Setzen Sie MCP_JWT_SECRET auf ein starkes Geheimnis. Der Server verweigert den Start im Produktionsmodus ohne dieses.

Entwicklung

Option A — Authentifizierung vollständig deaktivieren (nur lokal):

AUTH_DISABLED=true

Option B — ein Entwicklungs-JWT verwenden:

npx mcp-suite gen-token

Übergeben Sie das generierte Token im _meta-Feld der MCP-Anfrage (stdio) oder im Authorization: Bearer-Header (HTTP).

JWT-Struktur

{
  "sub": "your-client-id",
  "scope": "mcp:tools",
  "iat": 1713484800,
  "exp": 1716076800
}

Architektur

MCP Clients (Claude Desktop · Cursor · Windsurf · Custom Agents)
        │  MCP Protocol
┌───────▼────────────────────────────────────────┐
│  Transport Layer  (stdio  |  HTTP + SSE)        │
├────────────────────────────────────────────────┤
│  Auth Middleware  (JWT validation / bypass)     │
├────────────────────────────────────────────────┤
│  Tool Registry    (register · list · route)     │
├──────────┬──────────┬──────────┬───────────────┤
│Financial │  Web3    │ DevTools │  Healthcare   │
├──────────┴──────────┴──────────┴───────────────┤
│  Shared: Rate Limiter · Cache · Logger · Errors │
└─────────────────────────────────────────────────┘
         │           │          │          │
   Alpha Vantage  Alchemy   GitHub API  HAPI FHIR
   CoinGecko      OpenSea
                  Blur

• Caching: LRU + TTL In-Process-Cache (node-cache). TTLs sind domänenspezifisch (15s für Krypto, 300s für GitHub-Repo-Statistiken).

• Ratenbegrenzung: Token-Bucket pro Domäne schützt API-Kontingente des kostenlosen Tarifs.

• Fehlertypen: AuthError, ValidationError, DomainUnavailableError, UpstreamError, RateLimitError — alle erzeugen strukturierte MCP-Fehlerantworten.

• Logging: Strukturiertes JSON bei jedem Tool-Aufruf: Domäne, Tool-Name, Latenz, Cache-Treffer, Status.

Hinzufügen einer Domäne

Jede Domäne folgt dem gleichen Muster. Um eine neue Domäne hinzuzufügen:

1. Erstellen Sie src/domains/[name]/ mit index.ts, schemas.ts, client.ts und tools/

2. Exportieren Sie ein Domain-Objekt:

export const myDomain: Domain = {
  name: 'my-domain',
  isAvailable: () => !!config.MY_API_KEY,
  registerTools: (server) => { /* server.tool(...) calls */ }
}

3. Registrieren Sie es in src/server.ts

4. Dokumentieren Sie die Tools in docs/API.md

Siehe docs/TDD.md §5 und docs/CODING_STANDARDS.md für das vollständige Muster.

Entwicklung

git clone https://github.com/ayenisholah/mcp-suite.git
cd mcp-suite
npm install
cp .env.example .env   # fill in your API keys

npm run build          # compile TypeScript → dist/
npm run dev            # watch mode
npm run typecheck      # type check without emit
npm run lint           # ESLint
npm test               # unit tests (Vitest)
npm run test:coverage  # tests + coverage report

# Integration tests — hits real APIs, requires .env keys
RUN_INTEGRATION=true npm test

HTTP-Transport-Endpunkte

Beim Ausführen mit --transport http:

Fehlerreferenz

Lizenz

MIT — siehe LICENSE

Mitwirken

Issues und PRs sind willkommen. Bitte lesen Sie docs/CODING_STANDARDS.md, bevor Sie etwas einreichen.