MCP

API 参考

Verbumia ships a native MCP server so any MCP-aware client — Claude Desktop, Cursor, your own agent — can search keys, propose translations, review PRs, and inspect the missing-key queue. Two lines of config, your token, done.

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. Install (or skip)

The MCP server is published to npm and Homebrew. With npx you don't need to install anything — Claude Desktop pulls the latest version on every launch. With brew you get a pinned local binary, useful behind strict firewalls.

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"],8      "env": {9        "VERBUMIA_TOKEN":   "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECT": "<project_uuid>"11      }12    }13  }14}

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

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"],7      "env": { "VERBUMIA_TOKEN": "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

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

验证可用

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