MCP

配置 Claude Desktop

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

1. 获取 API key

在 dashboard 进入 Org Settings → API Keys → Create。授予 mcp:* scope(覆盖下面五个工具)。Secret 只显示一次;请复制完整字符串 vrb_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 按需拉取最新的 @verbumia/mcp2npx -y @verbumia/mcp --version

Homebrew(可选) Tap 在 V1 发布

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

3. 接入 Claude Desktop

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

claude_desktop_config.json

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

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

VERBUMIA_PROJECTS requires @verbumia/mcp ≥ 0.11.0. On older releases, see Backwards compatibility below.

Multi-project tool calls

When VERBUMIA_PROJECTS lists more than one UUID, the agent can't infer which project you mean — every tool call must include project_uuid. With a single UUID (or only the legacy VERBUMIA_PROJECT set), it's optional and defaults to that project.

tools/call arguments

1// list_missing_keys — project_uuid is REQUIRED when VERBUMIA_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}

Phrase your prompt with the project in mind (« in the Checkout project, list missing keys for ja ») — the agent will resolve the project to its UUID and pass project_uuid on the tool call. For ambiguous prompts across multiple projects, the agent will call list_projects first.

Cursor(以及其他 MCP 客户端)

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

.cursor/mcp.json

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "verbumia": {5      "command": "npx",6      "args": ["-y", "@verbumia/mcp@^0.11.0"],7      "env": { "VERBUMIA_API_KEY": "vrb_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 Verbumia 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;之后由人类审阅者晋升 — Verbumia 是管理者,不是引擎。

参数

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

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

Plan limits & quotas

You pay when an agent mutates your project, not when it observes it. Reads and listings are free; writes burn one unit; bulk and AI-assisted ops scale with the work they do.

What counts as a billable call

Reads — free

list_missing, list_keys, get_translation, search, plus auth / discover / meta. Browse the missing-key queue all day — it never touches your quota.

Writes — 1 unit

Each set / create / update / delete on a key or translation costs one unit, regardless of payload size.

Bulk — 1 unit per key

Multi-key endpoints (e.g. acknowledge) bill per key touched: a 50-key acknowledge debits 50 units, with rollback on partial-reject.

AI / auto-translate — ×5

Calls that invoke an LLM (auto-translate, AI Quality Review, suggest) bill 5 units per call. Higher weight reflects model cost.

Per-plan ceilings

Monthly quota, hard per-minute rate, concurrent MCP sessions, and whether writes are allowed. The same numbers feed the X-MCP-Quota-Remaining header on every response.

Plan	Units / month	Rate	Sessions	Writes
Free	NaN	NaNreq/min	NaN	blocked
Hobby	NaN	NaNreq/min	NaN	blocked
Pro	NaN	NaNreq/min	NaN	blocked
Team	NaN	NaNreq/min	NaN	blocked

When you hit a ceiling

Over the per-minute rate → 429 mcp_rate_limited with Retry-After (seconds). Over the monthly quota → 429 mcp_quota_exceeded with Retry-After set to the rollover. Free plan writes → 403 mcp_writes_disabled. Quotas reset on the 1st of each calendar month, UTC.

验证可用

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

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

Backwards compatibility

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

接下来