Sanka MCP Server

このリポジトリには、ホストされたSanka MCPサービスと、Sankaの外部呼び出し可能なAPIサーフェスを呼び出すために使用されるTypeScriptクライアントが含まれています。現在はStainless管理のリポジトリではなく、通常のTypeScriptワークスペースとして保守されています。

本番サービスは、リモートのStreamable HTTP MCPエンドポイントです：

• POST /mcp （プライマリエンドポイント）

• POST /sse （SSEスタイルのパスを期待するクライアントとの互換性エイリアス）

• POST / （互換性エイリアス）

• GET /health （ヘルスチェック用）

/mcp エンドポイントは、一般的なSDKツールと読み取り専用のCRMツールの両方を単一のMCPサーフェスから公開します。

ライブエンドポイント：

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

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

ステージングエンドポイント：

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

リポジトリ構成

• src/: MCPサービスで使用される、Sankaの外部呼び出し可能なAPIサーフェス用のTypeScriptクライアント

• src/internal/: パッケージプライベートなSDKランタイムヘルパー（Sankaのプライベートバックエンドコードではありません）

• packages/mcp-server/: MCPサーバーアプリケーションおよびDockerエントリーポイント

• .github/workflows/: CI、およびステージングと本番環境へのFlyデプロイワークフロー

• fly.toml: 本番Flyアプリ設定

• fly.staging.toml: ステージングFlyアプリ設定

• docs/openapi-maintenance.md: StainlessなしでAPIカバレッジを最新に保つためのガイダンス

Related MCP server: Isolator MCP Server

認証

sanka-mcp は独自のOAuthスタックを実行しません。Sanka OAuthを直接使用します：

• 認可サーバー: https://app.sanka.com

• 認可ページ: /oauth/authorize

• トークンエンドポイント: /api/v1/oauth/token

• 取り消しエンドポイント: /api/v1/oauth/revoke

ホスト型またはローカルのHTTPトランスポートの場合、MCPクライアントは保護されたリソースメタデータで公開されているSanka認可サーバーに対してネイティブOAuthを使用する必要があります。MCPサーバーはSanka OAuthベアラートークンのみを受け入れ、以下を通じて検証します：

• GET /api/v1/oauth/introspect

同じベアラートークンがSankaパブリックAPIに転送されます。

CodexやClaudeのようなネイティブOAuth対応クライアントは、接続時または保護されたツール呼び出し時にMCP OAuthチャレンジを受け取ります。ネイティブMCP OAuthをサポートしていないクライアントは、保護されたツールのフォールバックを使用できます。これはユーザーが開くためのConnect Sanka URLを返します。

開発者APIトークンは、MCPアクセス用としては意図的にサポートされていません。これらはMCP外での直接的なSanka APIおよびSDK使用に対しては有効なままです。

ローカル開発

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 はオプションです。存在する場合、サーバーはそのOAuth client_id を認可サーバーメタデータでアドバタイズします。

ローカルSankaの前提条件：

• app.localhost:8000 が /oauth/authorize および /api/v1/oauth/token を提供

• api.localhost:8000 が /api/v1/public/* を提供

• Sankaで最初にOAuthアプリ/クライアントを作成：

  • ファーストパーティ: /manage/oauth

  • サードパーティ: /:wsid/developers/oauth

• そのOAuthクライアントでMCPリダイレクトURI/オリジンを登録

HTTPトランスポートの代わりにローカルでstdioを使用したい場合、ネイティブOAuthはstdioハンドシェイクの一部ではありません。その場合は、ローカル開発の利便性として SANKA_API_KEY を通じて発行済みのSanka OAuthアクセストークンを渡してください。

その後、以下を確認します：

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"}}}'

ネイティブOAuth対応のMCPクライアントの場合、静的認証ヘッダーなしでクライアントを http://127.0.0.1:8080/mcp に向け、クライアントが保護されたリソースメタデータに従ってSanka OAuthへ接続できるようにします。

手動ベアラートークンテストの場合：

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"}}}'

デプロイ

このリポジトリは packages/mcp-server/Dockerfile からFlyにデプロイされます。

• 手動本番デプロイ: fly deploy -c fly.toml

• 手動ステージングデプロイ: fly deploy -c fly.staging.toml

• 自動ステージングデプロイ: staging へのプッシュ

• 自動本番デプロイ: main をターゲットとするGitHubリリースの公開

リリースフロー

メインのSankaアプリと同じプロモーション形式を使用します：

1. 機能PRを staging に開く。

2. CI通過後、staging をマージして sanka-mcp-staging をデプロイする。

3. ステージングMCPエンドポイントを検証する。

4. staging -> main のPRを開く。

5. main の準備ができたら、Create new Sanka MCP Tag and Release を実行する。

6. 公開されたリリースが本番環境にデプロイされる。

必要なFlyアプリとシークレット：

• 本番アプリ: sanka-mcp

• ステージングアプリ: sanka-mcp-staging

• ステージングで意図的に異なる認証スタックを使用する場合を除き、両方のアプリで同じ MCP_SERVER_* シークレットを設定してください。

保守の方向性

このリポジトリは、実行時または継続的な開発において、もはやStainlessプロジェクトへのアクセスに依存していません。APIカバレッジはこのリポジトリ内で直接保守されるべきです。

推奨される次のステップは、ホストされたジェネレーターの依存関係を再導入するのではなく、TypeScriptクライアントの更新にオープンソースのOpenAPIツールを採用することです。openapi-maintenance.md を参照してください。

リポジトリにはスターターのtypegenコマンドが含まれています：

pnpm generate:openapi-types

デフォルトでは、../sanka-sdks/openapi.json にある兄弟のSanka仕様を読み取ります。