Sanka

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

预发布端点：

• 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 覆盖范围最新的指南

身份验证

托管 HTTP 客户端通过 Connect Sanka 进行身份验证。MCP 服务会签发与资源绑定的会话 ID，并从 connect_sanka 或受保护工具的结果中返回已签名的 https://app.sanka.com/oauth/mcp/connect URL，然后通过 POST /oauth/internal/mcp-session-token 在内部将获批的会话兑换为有效期较短的 Sanka 访问令牌。

在 Sanka V2 实现完整的授权码服务端之前，原生 MCP OAuth 将保持禁用。MCP 服务不会发布 OAuth 授权服务器或受保护资源元数据，并会拒绝客户端提供的 Authorization 和 X-Sanka-API-Key 标头。令牌兑换密钥仅用于 sanka-mcp 与 sanka-api 之间；绝不能发送给 MCP 客户端。

读取工作区以及成功调用 switch_workspace 后，都会刷新 MCP 会话中保存的已解析工作区身份。因此，切换工作区后，记录 URL 丰富功能会立即使用所选工作区代码，而不是沿用初始连接时获取的代码。工作流预览／启动调用也会在提交前重新读取当前 MCP 会话，将请求绑定到该工作区；如果 API 解析出的工作区不同，则会安全失败。这样可确保会计试运行和工作流写入操作与 current_workspace 显示的租户一致。

所有托管客户端，包括 Codex 和 Claude，均使用相同的 Connect Sanka URL 流程。未经身份验证的初始化和工具列表请求仍可使用，以便客户端加载 connect_sanka 和受保护工具的后备选项。

MCP 访问不支持开发者 API 令牌。这些令牌仍可用于 MCP 之外直接访问 Sanka API 和使用 SDK。

本地开发

pnpm install
pnpm build
export MCP_SERVER_AUTHORIZATION_SERVER_URL="http://app.localhost:8000"
export MCP_SERVER_INTERNAL_AUTHORIZATION_SERVER_URL="http://api.localhost:8000"
export MCP_SERVER_TOKEN_EXCHANGE_SHARED_SECRET="local-shared-secret"
export SANKA_BASE_URL="http://api.localhost:8000"
node packages/mcp-server/dist/index.js --transport=http --port=8080

本地 Sanka 前置条件：

• app.localhost:8000 提供 /oauth/mcp/connect
• api.localhost:8000 提供 /api/v2/public/*
• api.localhost:8000 提供 /oauth/internal/mcp-session-token
• MCP 服务和 API 使用相同的本地令牌兑换密钥

Stdio 仍是本地开发传输方式。此处的 SANKA_API_KEY 是进程配置，而不是客户端提供的 bearer 模式；托管客户端必须使用 Connect Sanka。

然后进行验证：

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

将 HTTP MCP 客户端指向 http://127.0.0.1:8080/mcp，不要设置静态身份验证标头。调用 connect_sanka 或受保护工具，打开返回的 Connect Sanka URL，然后使用服务端签发的 MCP 会话 ID 重试。

Browser Use 工作器

browser_use MCP 工具会将允许列表中的浏览器工作流分派给独立的工作器。MCP 服务负责会话身份验证、审计元数据、工作流路由和确认关卡；工作器负责浏览器状态和与第三方界面的交互。首个注册的工作流是：

• demo.hubspot.company_avatar：当 CRM API 无法设置可见头像时，通过 HubSpot 界面更新 HubSpot 演示公司的头像。

使用 agent-browser 运行本地工作器：

npm install -g agent-browser
agent-browser install

export SANKA_BROWSER_USE_WORKER_TOKEN="local-worker-token"
export SANKA_BROWSER_USE_PROFILE_ROOT=".browser-use-profiles"
export SANKA_BROWSER_USE_ARTIFACT_DIR=".browser-use-artifacts"
pnpm --dir packages/mcp-server browser-use-worker

将 MCP 服务指向该工作器：

export SANKA_BROWSER_USE_WORKER_URL="http://127.0.0.1:8787/run"
export SANKA_BROWSER_USE_WORKER_TOKEN="local-worker-token"

在生产环境中，将工作器部署为独立服务，例如部署到 Fly，并在 SANKA_BROWSER_USE_PROFILE_ROOT 挂载持久卷，以便 HubSpot 登录 Cookie 在重启后仍然有效。将工作器设为私有或使用令牌保护，并且只向 MCP 服务开放 /run。

请参阅 docs/browser-use-worker-fly.md，了解 Fly 工作器应用、持久卷、密钥配置和配置文件初始化运行手册。

部署

此仓库使用 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_* 密钥。

重试策略

TypeScript 客户端默认会对 408、409、429、5xx 和连接错误重试两次。只有 metadata.operation: 'read' 的工具才会保留这些自动重试。每个写入工具只会调用 API 一次，并将任何错误返回给 Agent：写入操作可能在副作用已经发生后失败，例如 Gmail 已接受邮件，但 Sanka 尚未记录；重试就会再次执行该操作。API 还会为投递路由产生的错误标记 x-should-retry: false。回复工具会将 DELIVERY_UNKNOWN 报告为禁止重新发送的错误。

维护方向

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

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

此仓库现在包含一个初始版 typegen 命令：

pnpm generate:openapi-types

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

Developer Cloud（候选发布版）

托管工具提供与 CLI 和 SDK 相同的 V2 source、run、receipt、certificate 和 Fleet 合约。此 source 更改不会启用生产执行。请先阅读 get_developer_cloud_availability，并遵守每项能力的可用性标记。免费的本地迁移和客户端证据注册保持不变。

每次调用都需要固定的 workspace_id。付费创建和选择性重试需要明确的请求、经批准的额度上限、confirm: true 和稳定的 idempotency_key。现有用户授权已足够。响应丢失时，不得创建新的意图：请读取结果，或使用相同的 key 和请求重放。任何工具都不会购买额度、创建仓库 PR、合并或部署。

• Source/run：upload_developer_cloud_source、create_developer_cloud_run、 list_developer_cloud_runs、get_developer_cloud_run、cancel_developer_cloud_run。
• 证据：list_developer_cloud_events、get_developer_cloud_receipt、 list_developer_cloud_artifacts、download_developer_cloud_artifact。
• Certificates：list_developer_cloud_certificate_keys、 get_developer_cloud_certificate、revoke_developer_cloud_certificate。
• Fleet：create_developer_cloud_fleet、list_developer_cloud_fleets、 get_developer_cloud_fleet、cancel_developer_cloud_fleet、 retry_developer_cloud_fleet。

修复和证书签发分别使用 create_developer_cloud_run.request.repair 和 .certification。计算费用为每个 worker-minute 100 个额度，每次 run 只进行一次舍入。成功的修复额外收取 1,000 个额度；独立签发证书额外收取 2,000 个额度。所有计算费用和附加费用均在经批准的额度上限内。未通过门禁时不收取附加费用。Fleet 不收取额外费用：其额度上限为明确指定的子任务额度上限之和，并以原子方式预留；每个 workspace 最多有五个活跃 worker。原始 Fleet 结算后，重试仅选择失败的子任务；它会创建新的 Fleet，并保留已完成子任务的 receipts。

请上传精确的 ZIP 摘要和声明的完整 revision；服务会固定上传的字节，但不会独立证明其 Git 来源。请检查证书的范围、场景、限制和撤销状态。下载证书不会验证其签名：请使用 CLI 和已发布的密钥进行离线验证。工件下载会根据记录的 SHA-256 元数据验证字节。MCP 支持最大 64 MiB 的文件；更大的工件请使用 CLI/API。大文件下载使用现有的会话绑定 URL 或 read_binary_download_chunk 流程。

请求 schema 重新生成使用共享的 V2 SDK 输入：

python3 scripts/sync-developer-cloud-contract.py ../sanka-sdks/openapi.json
pnpm exec prettier --write packages/mcp-server/src/generated/developer-cloud-schemas.ts

嵌入式 workspace

Sanka 应用会打开已连接的完整 Flow workspace：其侧边栏、仪表板、记录表、工作流和报告。访问完整 workspace 需要明确的 Sanka 授权。访问权限较窄的连接会显示授权控件；此前的 Invoice 助手试用版界面不再提供。

托管的 invoice MCP 工具仍可在现有范围和确认要求下使用。移除试用版界面不会更改 invoice 记录或 API 合约。