Sanka MCP 服务器

本仓库包含托管的 Sanka MCP 服务及其用于调用 Sanka 外部可调用 API 接口的 TypeScript 客户端。它现在作为普通的 TypeScript 工作区进行维护，而非 Stainless 管理的仓库。

生产服务是一个远程 Streamable HTTP MCP 端点：

• POST /mcp 作为主要端点

• POST /sse 作为兼容性别名，用于仍期望 SSE 风格路径的客户端

• POST / 作为兼容性别名

• GET /health 用于健康检查

/mcp 端点通过单个 MCP 界面公开通用 SDK 工具和只读 CRM 工具。

实时端点：

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

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

预发布（Staging）端点：

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

仓库布局

• src/: 用于 Sanka 外部可调用 API 接口的 TypeScript 客户端，由 MCP 服务使用

• 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 持有者令牌 (Bearer Token)，并通过以下方式验证它们：

• GET /api/v1/oauth/introspect

相同的持有者令牌随后会被转发到 Sanka 公共 API。

支持原生 OAuth 的客户端（如 Codex 和 Claude）在连接或调用受保护工具时会收到 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/来源

如果您想在本地使用 stdio 而不是 HTTP 传输，原生 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 Release

发布流程

使用与主 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. 已发布的 Release 会部署到生产环境。

所需的 Fly 应用和密钥：

• 生产应用：sanka-mcp

• 预发布应用：sanka-mcp-staging

• 除非预发布环境有意使用不同的身份验证堆栈，否则请在两个应用上设置相同的 MCP_SERVER_* 密钥。

维护方向

本仓库在运行时或持续开发中不再依赖 Stainless 项目访问权限。API 覆盖率应直接在本仓库中维护。

建议的下一步是采用开源 OpenAPI 工具来更新 TypeScript 客户端，而不是重新引入托管的生成器依赖项。请参阅 openapi-maintenance.md。

该仓库现在包含一个入门级类型生成命令：

pnpm generate:openapi-types

默认情况下，它会读取同级的 Sanka 规范 ../sanka-sdks/openapi.json。