verbatra

@verbatra/mcp

Stdio MCP 服务，将 verbatra 的翻译状态、术语表和编辑功能作为工具提供给任何 MCP 客户端，无需浏览器。

文档 | 连接客户端 | 更新日志 | 问题

描述

@verbatra/mcp 通过 stdio 启动 Model Context Protocol 服务。stdio 是 MCP 客户端用于启动工具服务并与之通信的标准本地进程传输方式。它让终端托管或无头 Agent 无需浏览器、端口或托管的单页应用，即可使用 Verbatra Studio 在浏览器中提供的同一套翻译状态、术语表和编辑功能。它是基于 SDK 的精简接口，与 @verbatra/cli 一样，构建于 @verbatra/sdk 之上。

安装

大多数 MCP 客户端会自行启动服务，无需本地安装：将客户端指向 npx -y @verbatra/mcp，npx 就会按需获取该服务。若要在项目中固定安装：

npm install --save-dev @verbatra/mcp

需要 Node.js ^22.18.0 || >=24。安装 @verbatra/cli 和 @verbatra/mcp 后，也可以通过 verbatra mcp 访问该服务。

配置 MCP 客户端

将客户端指向 @verbatra/mcp 包提供的 verbatra-mcp 二进制文件。以下示例通过 npx 运行它。大多数客户端使用下方的配置格式；对于编辑器或桌面客户端，请将其放入该客户端的 MCP 服务配置文件中。

{
  "mcpServers": {
    "verbatra": {
      "command": "npx",
      "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"],
      "env": {}
    }
  }
}

在 Claude Code 中，npx @verbatra/cli init --agent（或 claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp）会将等效配置写入已提交的 .mcp.json。verbatra 插件将 Agent 技能与其自带的此 MCP 服务副本打包在一起，因此请使用它，而不要使用 .mcp.json 条目，切勿同时使用两者：否则会重复注册此服务。VS Code（GitHub Copilot 的 Agent 模式）会读取 .vscode/mcp.json，其顶层键为 servers，而不是 mcpServers。每种客户端对应的文件、键和工作目录处理方式详见连接 MCP 客户端。

此配置仅支持只读操作和本地编辑：不会调用任何提供商，也不需要 API 密钥。如果还想使用两个会调用提供商的工具，请在 args 中添加 --allow-spend，并设置已配置的提供商读取密钥的环境变量。--config <path> 用于加载指定配置文件，而不是搜索配置文件；VERBATRA_MCP_ALLOW_SPEND 是该标志对应的环境变量，但始终以标志为准。

工具

按服务公布的顺序列出所有工具。

工具	功能
project.snapshot	读取已解析的项目配置：是否已加载可用配置（configured）、区域设置、格式、路径模式、提供方 ID、配置来源，以及是否配置了术语表
project.doctor	检查项目设置（配置、格式、提供方、API 密钥变量名、网络策略、源文件），并为每项未通过的检查提供修复方案；无论是否有可用配置都可检查
status.check	按目标区域设置，统计缺失、过时或最新的键数量，并检查该区域设置是否同步
status.diff	按目标区域设置，列出下一次翻译运行将新增、重新翻译或标记为孤立的确切键
glossary.get	获取所有术语及其在所有区域设置中的译文、各区域设置的译文、禁用译法、大小写敏感性、备注和词性、不翻译的术语、术语表版本及其来源；指定 locale 时，还会列出该区域设置必须遵循的术语
glossary.write	修改一个术语（所有区域设置或指定 locale 的译文、forbidden 禁用译法、note 备注、partOfSpeech 词性、caseSensitive 大小写敏感性或 doNotTranslate 是否不翻译），并返回修改后的术语表
lock.state	获取锁定文件的版本及各区域设置的键数量；首次运行前返回 exists: false
history.list	获取近期修改过区域设置文件的 Git 提交，包括哈希、作者姓名（不包括邮箱）、日期、主题和涉及的路径
key.integrity	按区域设置检查一个键相对于锁定文件基线的占位符、行内标记和 ICU 差异
locale.integrity	按目标区域设置列出当前未通过占位符、标记或 ICU 检查的所有译文
key.value	获取一个键当前的源文本、源文件说明；如果已翻译，还会获取其在一个目标区域设置中的当前文本及译者
key.context	返回 key.value 的内容，以及适用的术语表术语、该键的 maxLength 和可选 draft 的检查结果
locale.values	按 keys 或 query 筛选，以每页最多 1,000 条的形式获取多个键的源文本和目标文本
translation.editEntry	为一个区域设置中的一个键写入人工译文；仅当通过完整性门槛时才接受
translation.estimate	估算 translation.translatePending 将发送的内容和费用；可选指定部分区域设置，且不会调用提供方
translation.retranslateEntry	请求已配置的提供方重新翻译一个区域设置中的一个键
translation.translatePending	在一次运行中翻译所有已配置目标区域设置中缺失或过时的键，或指定的部分区域设置；可选设置 maxTokens 上限
review.queue	从已提交的文件中读取所有尚未获批的机器生成译文，并显示上次运行的标记
report.provenance	按区域设置统计各来源类别中的值数量；指定 includeEntries 时，还会分页列出相关键
review.approve	根据用户指示，记录指定人员批准了一个键的当前译文
review.reject	根据用户指示，记录指定人员拒绝了一个键的当前译文，并移除该译文以便替换
usage.summary	获取上次运行留下的 Token 用量和剩余预算状态

安全与支出

• 支出由用户选择启用。 translation.retranslateEntry 和 translation.translatePending 是两个会调用服务提供商的工具。只有在使用 --allow-spend 或 VERBATRA_MCP_ALLOW_SPEND 启动服务时，才会公布这两个工具；如果两者都未设置，客户端将看不到它们，按名称调用时会因工具未知而失败。使用 provider: { id: "none" } 的配置永远不会列出这两个工具，即使设置了 --allow-spend 也一样。
• 值可以留在本地。 --redact-values（或 VERBATRA_MCP_REDACT_VALUES）会将结果中的每个源文本、译文、描述和术语替换为类似 [redacted length=12 hash=3f9a0c1d2e4b5a6c] 的标记，并省略审核者和作者姓名。键名、计数、状态和完整性判定会保留。此时，review.approve 和 review.reject 只接受标记的哈希作为 expectedHash，locale.values 会拒绝 query，而 key.context 会拒绝 draft。这可以让值不出现在结果中；但无法阻止故意探查的 Agent，也不会改变服务提供商收到的内容。
• 密钥会被清除。 每条结果和日志行都会先经过脱敏处理，因此，符合服务提供商 API 密钥格式的值，或已配置的服务提供商变量的确切值，在发送到客户端或写入 stderr 前都会变成 [REDACTED]。
• 标准输出仅用于协议。 标准输出中只会写入 MCP 消息；所有日志和诊断信息都会写入 stderr。
• 配置更改无需重启。 服务启动时可以没有可用配置（project.snapshot 会报告 configured: false，project.doctor 会说明需要修复的内容），并会在每次调用前重新加载配置及其术语表文件。--allow-spend 在启动时固定，配置更改不会扩大其权限。

每个工具的输入以及每个固定结构的工具输出，都使用根据同一份 zod schema 生成的 JSON Schema；服务会根据这份 schema 验证调用。完整的工具参考、退出代码约定和示例，请参阅 verbatra mcp 文档。

文档

• verbatra mcp 参考
• 连接 MCP 客户端
• Agent 使用指南

相关软件包

• @verbatra/sdk：此服务所依托的引擎；本服务只是它的轻量接口。
• @verbatra/cli：包含 verbatra mcp 在内的 verbatra 命令。
• @verbatra/studio：通过浏览器仪表板提供相同功能。

参与贡献

请参阅 CONTRIBUTING.md。

许可证

MIT (c) Mario Kreitz