Stackbilt MCP Gateway

MCP-Registry: dev.stackbilt.mcp/gateway — veröffentlicht in der offiziellen MCP-Registry

OAuth-authentifiziertes Model Context Protocol (MCP)-Gateway für Stackbilt-Plattformdienste. Erstellt als Cloudflare Worker unter Verwendung von @cloudflare/workers-oauth-provider.

Funktionsweise

Ein einziger MCP-Endpunkt (mcp.stackbilt.dev/mcp), der Tool-Aufrufe an mehrere Backend-Produkt-Worker weiterleitet:

Die Scaffold-Pipeline (E2E)

You: "Build a restaurant menu API with D1 storage"
  ↓
scaffold_create → structured facts + 9 deployable project files
  ↓
scaffold_publish → GitHub repo with atomic initial commit
  ↓
git clone → npm install → npx wrangler deploy → live Worker

Keine LLM-Aufrufe für die Dateigenerierung. ~20ms für die Struktur, ~2s mit Oracle-Prosa. 21x schneller als flow_create.

Related MCP server: forgemesh-imagegen

Hauptmerkmale

• OAuth 2.1 mit PKCE — GitHub SSO, Google SSO und E-Mail/Passwort-Authentifizierung

• Backend-Adapter-Muster — Tool-Kataloge, die aus mehreren Service-Bindungen aggregiert und zur Vermeidung von Kollisionen mit Namespaces versehen wurden

• Ratenbegrenzung pro Stufe — Fixed-Window-Limits pro Mandant via RATELIMIT_KV (kostenlos=20/Min, Hobby=60, Pro=300, Enterprise=1000); 429 mit Retry-After- und X-RateLimit-*-Headern

• Kostenzuordnung & Kontingente — jeder Tool-Aufruf verursacht Kreditkosten; das Kontingent wird vor dem Versand via edge-auth reserviert und bei Abschluss verbucht/erstattet; die Kosten für image_generate skalieren mit der effektiven Qualitätsstufe (1×/1×/3×/5×/8× für Draft/Standard/Premium/Ultra/Ultra_plus); wenn model festgelegt ist, hat dies bei der Abrechnung Vorrang vor quality_tier

• Bereichs- + Stufendurchsetzung — tools/list wird nach Token-Bereichen gefiltert; tools/call erfordert den generate-Bereich für mutierende Tools; teure image_generate-Qualitätsstufen (premium und höher) sind auf Pro+-Pläne beschränkt; die direkte Angabe von model erzwingt dieselbe Beschränkung über die Modell-zu-Stufen-Zuordnung

• Einhaltung der Sicherheitsverfassung — jedes Tool deklariert eine Risikostufe (READ_ONLY, LOCAL_MUTATION, EXTERNAL_MUTATION); strukturiertes Audit-Logging mit Schwärzung von Geheimnissen; HMAC-signierte Identitäts-Token

• „Demnächst“-Sperre — PUBLIC_SIGNUPS_ENABLED-Flag zur Steuerung des öffentlichen Zugangs

• MCP JSON-RPC über HTTP — unterstützt sowohl Streaming (SSE) als auch Request/Response-Transport

Schnellstart

Voraussetzungen

• Node.js 18+

• Wrangler CLI (npm i -g wrangler)

• Cloudflare-Konto mit den erforderlichen konfigurierten Service-Bindungen

Installation & Ausführung

npm install
npm run dev

Tests ausführen

npm test

Deployment

npm run deploy

Bereitstellung auf der benutzerdefinierten Domain mcp.stackbilt.dev über Cloudflare Workers.

Umgebungsvariablen & Geheimnisse

Geheimnisse festlegen mit:

wrangler secret put SERVICE_BINDING_SECRET

Projektstruktur

src/
  index.ts           # Entry point — OAuthProvider setup, CORS, health check, MCP Registry well-known
  gateway.ts         # MCP JSON-RPC transport, session management, tool dispatch
  oauth-handler.ts   # OAuth 2.1 flows: login, signup, social SSO, consent
  tool-registry.ts   # Tool catalog aggregation, namespacing, schema validation
  audit.ts           # Structured audit logging, secret redaction, trace IDs
  auth.ts            # Bearer token extraction & validation
  route-table.ts     # Static routing table, tool-to-backend mapping, risk levels
  types.ts           # Type definitions, RiskLevel enum, interfaces

test/
  audit.test.ts
  auth.test.ts
  gateway.test.ts
  oauth-handler.test.ts
  route-table.test.ts
  tool-registry.test.ts

docs/
  user-guide.md      # End-user guide: account creation, client setup, tool usage
  api-reference.md   # MCP tool surface, authentication flow, tool routing
  architecture.md    # System design, security model, request flow

Test-Suite

122 Tests in 6 Testdateien, die Folgendes abdecken:

• OAuth-Handler — Signierung/Verifizierung von Identitäts-Token, Login, Registrierung, soziale OAuth-Flows, Zustimmung, HTML-Escaping

• Gateway — Sitzungslebenszyklus, initialize, tools/list, tools/call, SSE-Streaming, Fehlerbehandlung

• Audit — Muster zur Schwärzung von Geheimnissen (API-Schlüssel, Bearer-Token, Hex-Hashes, Passwortfelder), Trace-IDs, Queue-Emission

• Auth — Extraktion von Bearer-Token, API-Schlüssel vs. JWT-Validierung, Fehlerzuordnung

• Tool-Registry — Katalogerstellung, Namenszuordnung, Schema-Validierung, Durchsetzung der Risikostufe

• Routentabelle — Routenauflösung, Suche nach Risikostufen

npm test          # single run
npm run test:watch # watch mode

Dokumentation

• Benutzerhandbuch — Kontoerstellung, Client-Einrichtung, Tool-Nutzung

• API-Referenz — MCP-Tools, Authentifizierung, Tool-Routing

• Architektur — Systemdesign, Sicherheitsmodell, Datenfluss

Lizenz

MIT — siehe LICENSE