Sanka MCP Server

Sanka MCP服务器

此存储库包含托管的Sanka MCP服务和用于调用Sanka的外部可调用API表面的TypeScript客户端。它现在被维护为一个正常的TypeScript工作区，而不是一个不锈钢管理的存储库。

生产服务是一个远程可流式HTTP MCP端点：

• POST /mcp 作为主要终点
• POST /sse 作为仍然需要SSE样式路径的客户端的兼容性别名
• POST / 作为兼容性别名
• GET /health 用于健康检查

这 /mcp endpoint从单个MCP表面公开通用SDK工具和只读CRM工具。

实时端点：

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

暂存端点：

• 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：在不使用不锈钢的情况下保持API覆盖范围最新的指南

认证

sanka-mcp 不运行自己的OAuth堆栈。它直接使用Sanka OAuth：

• 授权服务器： https://app.sanka.com
• 授权页面： /oauth/authorize
• 令牌终结点： /api/v1/oauth/token
• 吊销终结点： /api/v1/oauth/revoke

对于托管或本地HTTP传输，MCP客户端应使用本机OAuth 在受保护的资源元数据中公开的Sanka授权服务器。这 MCP服务器只接受Sanka OAuth承载令牌，并通过以下方式进行验证：

• GET /api/v1/oauth/introspect

然后将相同的承载令牌转发到Sanka公共API。

支持原生OAuth的客户端，如Codex和Claude，会收到MCP OAuth 连接或受保护工具调用期间的挑战。不支持的客户端 原生MCP OAuth仍然可以使用受保护的工具回退，该回退返回 连接用户要打开的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 在其授权服务器元数据中。

当地桑卡先决条件：

• 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 OAuth 访问令牌通过 SANKA_API_KEY 作为当地发展的便利。

然后验证：

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

部署

此仓库部署到Fly from packages/mcp-server/Dockerfile.

• 手动生产部署： fly deploy -c fly.toml
• 手动暂存部署： fly deploy -c fly.staging.toml
• 自动暂存部署：推送 staging
• 自动生产部署：发布针对目标的GitHub版本 main

释放流量

使用与主要Sanka应用程序相同的促销形状：

1. 将功能PR打开到 staging.
2. 合并 staging CI通过部署后 sanka-mcp-staging.
3. 验证分期MCP端点。
4. 打开 staging -> main.
5. 之后 main 准备好了，快跑 Create new Sanka MCP Tag and Release.
6. 发布的版本部署了生产。

必需的Fly应用程序和秘密：

• 生产应用程序： sanka-mcp
• 暂存应用程序： sanka-mcp-staging
• 设置相同 MCP_SERVER_* 除非stage有意使用不同的身份验证堆栈，否则这两个应用程序上都有秘密。

维修指导

此存储库在运行时或正在进行的开发中不再依赖于Stainless项目访问。应在本回购中直接维持API覆盖范围。

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

repo现在包含一个starter typegen命令：

pnpm generate:openapi-types

默认情况下，它在以下位置读取兄弟Sanka规范 ../sanka-sdks/openapi.json.