Sanka MCP-Server

Dieses Repository enthält den gehosteten Sanka MCP-Dienst und den TypeScript-Client, den er verwendet, um die extern aufrufbare API-Oberfläche von Sanka anzusprechen. Es wird jetzt als normaler TypeScript-Workspace gepflegt und nicht mehr als Stainless-verwaltetes Repository.

Der Produktionsdienst ist ein entfernter Streamable HTTP MCP-Endpunkt:

• POST /mcp als primärer Endpunkt

• POST /sse als Kompatibilitäts-Alias für Clients, die noch einen SSE-artigen Pfad erwarten

• POST / als Kompatibilitäts-Alias

• GET /health für Gesundheitsprüfungen

Der /mcp-Endpunkt stellt sowohl die allgemeinen SDK-Tools als auch die schreibgeschützten CRM-Tools über eine einzige MCP-Oberfläche bereit.

Live-Endpunkte:

• https://mcp.sanka.com/mcp

• https://mcp.sanka.com/sse

Staging-Endpunkt:

• https://sanka-mcp-staging.fly.dev/mcp

Repository-Struktur

• src/: TypeScript-Client für die extern aufrufbare API-Oberfläche von Sanka, der vom MCP-Dienst verwendet wird

• src/internal/: Paket-private SDK-Laufzeit-Helfer, kein privater Sanka-Backend-Code

• packages/mcp-server/: die MCP-Serveranwendung und der Docker-Einstiegspunkt

• .github/workflows/: CI sowie Staging- und Produktions-Fly-Deployment-Workflows

• fly.toml: Konfiguration der Produktions-Fly-App

• fly.staging.toml: Konfiguration der Staging-Fly-App

• docs/openapi-maintenance.md: Anleitung zur Aufrechterhaltung der API-Abdeckung ohne Stainless

Related MCP server: Isolator MCP Server

Authentifizierung

sanka-mcp betreibt keinen eigenen OAuth-Stack. Es verwendet direkt Sanka OAuth:

• Autorisierungsserver: https://app.sanka.com

• Autorisierungsseite: /oauth/authorize

• Token-Endpunkt: /api/v1/oauth/token

• Widerrufs-Endpunkt: /api/v1/oauth/revoke

Für gehostete oder lokale HTTP-Transporte sollten MCP-Clients natives OAuth gegenüber dem Sanka-Autorisierungsserver verwenden, der in den Metadaten der geschützten Ressource offengelegt wird. Der MCP-Server akzeptiert nur Sanka OAuth-Bearer-Token und validiert diese durch:

• GET /api/v1/oauth/introspect

Das gleiche Bearer-Token wird dann an die öffentliche Sanka-API weitergeleitet.

Native OAuth-fähige Clients wie Codex und Claude erhalten während der Verbindung oder bei Aufrufen geschützter Tools eine MCP OAuth-Herausforderung. Clients, die kein natives MCP OAuth unterstützen, können weiterhin das Fallback für geschützte Tools verwenden, das eine Connect Sanka-URL zurückgibt, die der Benutzer öffnen kann.

Entwickler-API-Token werden für den MCP-Zugriff absichtlich nicht unterstützt. Sie bleiben für die direkte Nutzung der Sanka-API und des SDK außerhalb von MCP gültig.

Lokale Entwicklung

pnpm install
pnpm build
export MCP_SERVER_AUTHORIZATION_SERVER_URL="http://app.localhost:8000"
export MCP_SERVER_OAUTH_CLIENT_ID="your-public-oauth-client-id"
export SANKA_BASE_URL="http://api.localhost:8000"
node packages/mcp-server/dist/index.js --transport=http --port=8080

MCP_SERVER_OAUTH_CLIENT_ID ist optional. Wenn vorhanden, bewirbt der Server diese OAuth client_id in seinen Metadaten des Autorisierungsservers.

Lokale Sanka-Voraussetzungen:

• app.localhost:8000 bedient /oauth/authorize und /api/v1/oauth/token

• api.localhost:8000 bedient /api/v1/public/*

• Erstellen Sie zuerst die OAuth-App/den Client in Sanka:

  • First-Party: /manage/oauth

  • Third-Party: /:wsid/developers/oauth

• Registrieren Sie den MCP-Redirect-URI/Origin bei diesem OAuth-Client

Wenn Sie lokal stdio anstelle von HTTP-Transport verwenden möchten, ist natives OAuth nicht Teil des stdio-Handshakes. Übergeben Sie in diesem Fall ein bereits ausgestelltes Sanka OAuth-Zugriffstoken über SANKA_API_KEY als Komfortfunktion für die lokale Entwicklung.

Dann überprüfen:

curl http://127.0.0.1:8080/health
curl -sS -D - http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

Für einen nativen OAuth-fähigen MCP-Client richten Sie den Client auf http://127.0.0.1:8080/mcp ohne statische Auth-Header aus und lassen Sie den Client den Metadaten der geschützten Ressource zu Sanka OAuth folgen.

Für manuelle Bearer-Token-Tests:

curl -sS -D - http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'authorization: Bearer soat_your_access_token' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

Bereitstellung

Dieses Repo wird von packages/mcp-server/Dockerfile auf Fly bereitgestellt.

• Manuelle Produktionsbereitstellung: fly deploy -c fly.toml

• Manuelle Staging-Bereitstellung: fly deploy -c fly.staging.toml

• Automatische Staging-Bereitstellung: Push nach staging

• Automatische Produktionsbereitstellung: Veröffentlichen eines GitHub-Releases, das auf main abzielt

Release-Ablauf

Verwenden Sie die gleiche Promotionsform wie bei der Haupt-Sanka-App:

1. Öffnen Sie Feature-PRs in staging.

2. Mergen Sie staging, nachdem die CI bestanden wurde, um sanka-mcp-staging bereitzustellen.

3. Validieren Sie den Staging-MCP-Endpunkt.

4. Öffnen Sie staging -> main.

5. Nachdem main bereit ist, führen Sie Create new Sanka MCP Tag and Release aus.

6. Das veröffentlichte Release stellt die Produktion bereit.

Erforderliche Fly-Apps und Secrets:

• Produktions-App: sanka-mcp

• Staging-App: sanka-mcp-staging

• Setzen Sie die gleichen MCP_SERVER_*-Secrets auf beiden Apps, es sei denn, das Staging verwendet absichtlich einen anderen Auth-Stack.

Wartungsrichtung

Dieses Repository hängt zur Laufzeit oder für die laufende Entwicklung nicht mehr vom Zugriff auf das Stainless-Projekt ab. Die API-Abdeckung sollte direkt in diesem Repo gepflegt werden.

Der empfohlene nächste Schritt ist die Einführung von Open-Source-OpenAPI-Tools für Updates des TypeScript-Clients, anstatt eine gehostete Generator-Abhängigkeit wieder einzuführen. Siehe openapi-maintenance.md.

Das Repo enthält jetzt einen Starter-Typegen-Befehl:

pnpm generate:openapi-types

Standardmäßig liest er die Sanka-Spezifikation des Geschwisterverzeichnisses unter ../sanka-sdks/openapi.json.