MCP

配置 Claude Desktop

Sonenta 自带原生 MCP 服务器,任何支持 MCP 的客户端 — Claude Desktop、Cursor,或你自己的 agent — 都能搜索 key、提交翻译、Review PR、查看缺失键队列。两行配置加 token,搞定。

1. 获取 API key

在 dashboard 进入 Org Settings → API Keys → Create。授予 mcp:* scope(覆盖下面五个工具)。Secret 只显示一次;请复制完整字符串 snt_live_<prefix>.<secret>。

存放到你 OS 的 keychain 或本地 .env — 永远不要 commit。Key 绑定到你的 org(可选地绑定到一个项目);超出 scope 的调用返回 404。可随时在 dashboard 撤销;被撤销的 key 在下一次调用时返回 401。

2. 安装(或跳过)

MCP 服务器发布在 npm 和 Homebrew。用 npx 你不需要安装任何东西 — Claude Desktop 每次启动都拉取最新版本。用 brew 你得到一个固定的本地二进制,适合在严格防火墙后使用。

npx(推荐)

1// 无需安装 — npx 按需拉取最新的 @sonenta/mcp2npx -y @sonenta/mcp --version

Homebrew(可选) Tap 在 V1 发布

1// 可选:全局安装一次 — 随 V1 上线提供2brew install sonenta/tap/sonenta-mcp

3. 接入 Claude Desktop

打开 Claude Desktop 的配置文件,在 mcpServers 下添加 sonenta 条目,然后退出并重新启动应用。

claude_desktop_config.json

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "sonenta": {6      "command": "npx",7      "args": ["-y", "@sonenta/mcp"],8      "env": {9        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

总共三个环境变量:SONENTA_TOKEN(必填)、SONENTA_PROJECT(可选 — 预先指定项目,这样 agent 就不必先调用 list_projects),以及 SONENTA_API_BASE(可选 — 默认 https://api.sonenta.com;自托管或 staging 时覆盖)。

SONENTA_PROJECTS 需要 @sonenta/mcp ≥ 0.11.0。在更早的版本上，请参见下方的向后兼容。

多项目工具调用

当 SONENTA_PROJECTS 列出多个 UUID 时，agent 无法推断你指的是哪个项目——每个工具调用都必须包含 project_uuid。若只有一个 UUID（或只设置了 legacy 的 SONENTA_PROJECT），它是可选的，调用会默认指向该项目。

tools/call 参数

1// list_missing_keys — project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID2{3  "name": "list_missing_keys",4  "arguments": {5    "project_uuid": "<uuid1>",6    "namespace": "checkout",7    "language_code": "ja"8  }9}

组织你的 prompt 时点明项目（「在 Checkout 项目中，列出 ja 的缺失 key」）——agent 会将该项目解析为它的 UUID，并在工具调用上传入 project_uuid。对于跨多个项目含糊不清的 prompt，agent 会先调用 list_projects。

Cursor(以及其他 MCP 客户端)

同一份 JSON,不同文件。在 Cursor 里,放在 .cursor/mcp.json(项目级)或 ~/.cursor/mcp.json(用户级)。其他客户端请参考各自的 MCP 配置文档 — mcpServers.sonenta 条目是相同的。

.cursor/mcp.json

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "sonenta": {5      "command": "npx",6      "args": ["-y", "@sonenta/mcp"],7      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }8    }9  }10}

V1 的 5 个工具

配置完成后,agent 就拥有这些工具。你不需要按名调用 — 在 chat 里描述意图,agent 自行选择。下面的名称是规范标识符,在阅读 agent trace 或在同一服务器上构建自定义 agent 时有用。

list_projects 枚举当前 API key 能访问的项目。在 chat 开头挑选 workspace 时很有用。

参数

limit number 返回项目数量的可选上限

示例 prompt

“List my Sonenta projects.”

get_project_info 拉取项目元数据:源语言、目标语言、namespace、key 总数。

参数

project_uuid string required

示例 prompt

“Checkout 项目支持哪些语言和 namespace?”

list_missing_keys 列出运行时 SDK 捕获的待处理缺失键事件(cursor 分页)。可按 namespace 或语言过滤。

参数

project_uuid string required
namespace string 限定到某个 namespace(例如 "checkout")
language_code string 限定到某个语言(例如 "ja")
cursor string 上一次调用返回的分页 cursor
limit number 每页大小(默认 20)

示例 prompt

“checkout namespace 下 ja 缺少哪些翻译 key?”

propose_translation 为目标语言的某个 key 提交一个翻译值。始终写为 draft;之后由人类审阅者晋升 — Sonenta 是管理者,不是引擎。

参数

project_uuid string required
key string required
namespace string required
language_code string required
value string required

示例 prompt

“Propose \"Confirmer la commande\" for checkout.review.confirm in fr-CA.”

validate_translations Push 前对 JSON i18next payload 做 lint:ICU 占位符是否一致、缺失/多余的 key、跨 locale 的类型漂移。

参数

project_uuid string required
language_code string required
payload object required JSON i18next 形式的翻译映射

示例 prompt

“把这份翻译文件和项目的英文源对比校验一下。”

按套餐的限制与配额

当 agent 变更你的项目时你才付费，而非它观察项目时。读取和列举是免费的；写入消耗一个单位；bulk 和 AI 辅助的操作按其所做的工作量伸缩计费。

什么算作可计费调用

读取——免费

list_missing、list_keys、get_translation、search，以及 auth / discover / meta。整天浏览缺失 key 队列——它都不会动用你的配额。

写入——1 个单位

在一个 key 或一条翻译上的每次 set / create / update / delete 都消耗一个单位，无论 payload 大小如何。

Bulk——每个 key 1 个单位

多 key 端点（例如 acknowledge）按所触及的每个 key 计费：一次 50 个 key 的 acknowledge 扣除 50 个单位，并在部分拒绝时回滚。

AI / auto-translate——×5

调用 LLM 的操作（auto-translate、AI Quality Review、suggest）每次调用计费 5 个单位。更高的权重反映了模型成本。

按套餐的上限

月度配额、每分钟的硬性速率上限、并发 MCP session 数，以及是否允许写入。相同的数值也驱动每个响应上的 X-MCP-Quota-Remaining 头。

套餐	单位 / 月	速率	Session	写入
Free	NaN	NaNreq/min	NaN	禁止
Hobby	NaN	NaNreq/min	NaN	禁止
Pro	NaN	NaNreq/min	NaN	禁止
Team	NaN	NaNreq/min	NaN	禁止

当你触及上限时

超过每分钟速率 → 429 mcp_rate_limited，带 Retry-After（秒）。超过月度配额 → 429 mcp_quota_exceeded，Retry-After 设为下次滚动时间。Free 套餐的写入 → 403 mcp_writes_disabled。配额在每个日历月的 1 号、UTC 时间重置。

验证可用

1 完全重启 Claude Desktop(退出再启动 — 配置在启动时读取)。
2 打开新 chat。锤子图标里应该看到 sonenta,可用 5 个工具。
3 输入 “List my Sonenta projects.”。Agent 应该会调用 list_projects 并返回你的 workspace。

卡住了?查看 Claude Desktop 的日志 ~/Library/Logs/Claude/mcp*.log(macOS)。90% 的问题来自 JSON 拼写错误或过期 token。

向后兼容

0.4.0 之前的名称 SONENTA_TOKEN 和 SONENTA_API_BASE 仍作为回退支持；当未设置标准名时，SDK 会静默读取。

接下来