Bluente Translate

bluente-translate-mcp-server 是官方开源 MCP 服务，可向 AI 客户端提供 Bluente 翻译功能。

它将 Bluente API 封装为可用于生产环境的 MCP 工具，帮助团队通过 Claude Desktop、Cursor 和其他兼容 MCP 的运行时自动化多语言文档工作流。

为什么选择 Bluente

Bluente 专注于企业级文档翻译，准确性、格式完整性和速度至关重要。

Bluente.com 和 Blu Translate 的核心产品定位包括：

• 面向专业场景的 AI 驱动翻译
• 在以文档为中心的工作流中保留原始版式
• 广泛支持多种语言和文件类型
• 优先保障安全，妥善处理敏感内容

此 MCP 服务通过标准协议接口，将这些功能融入 Agent 工作流。

品牌标识

此仓库由 Bluente 维护，是 Bluente 公开开发者生态系统的一部分。

• 公司网站：https://www.bluente.com
• 产品页面：https://www.bluente.com/translator
• API 文档：https://www.bluente.com/docs

目录

• 你将获得什么
• 架构
• 支持的 Bluente API
• MCP 工具
• 快速开始
• 本地开发
• 运行说明
• 数据处理与隐私
• 安全
• 路线图
• 贡献与治理
• 许可证

你将获得什么

• 模块化 Node.js MCP 服务，层次清晰（config、client、service、tools）
• 每个工具单独使用一个文件实现，便于维护
• 统一的工具响应封装（ok/tool/data 和结构化错误）
• 端到端翻译工作流工具（上传 -> 启动 -> 轮询 -> 下载）
• CI 检查和本地冒烟测试

架构

AI Client (Claude / Cursor / Agents)
            |
            | MCP (stdio)
            v
+---------------------------------------+
| Bluente Translate MCP Server          |
|                                       |
|  tools/  -> MCP tool handlers         |
|  services/ -> workflow orchestration  |
|  clients/ -> Bluente HTTP API client  |
|  config/ + lib/ -> env/errors/results |
+---------------------------------------+
            |
            | HTTPS
            v
      Bluente Translation APIs

项目结构：

src/
  clients/bluente-http-client.js
  config/env.js
  constants/api.js
  lib/errors.js
  lib/mcp-result.js
  services/translation-workflow-service.js
  tools/*.tool.js
  tools/schemas.js
  tools/register-tools.js
  server.js
  index.js
tests/smoke/core-smoke.test.js

支持的 Bluente API

• GET /blu_translate/supported_languages
• POST /blu_translate/upload
• GET /blu_translate/check
• POST /blu_translate/translate
• GET /blu_translate/download
• GET /blu_translate/account

参考：Bluente API 文档

MCP 工具

• bluente_get_supported_languages
• bluente_upload_file
• bluente_get_translation_status
• bluente_translate_file
• bluente_download_file
• bluente_translate_document_workflow
• bluente_get_account — 只读：已登录用户的邮箱和姓名、所属组织（名称和角色），以及各项功能的额度余额、付款方（组织额度池或个人额度）和最近的到期时间。

这些工具与 Bluente 托管 MCP 服务公开的工具一致，因此，针对其中一个编写的提示词或 Agent 也适用于另一个。两者仅有两项差异，是只有本地服务才能实现的功能：将 file_path 用作来源，以及使用 output_path 将结果保存到磁盘（托管服务则会提供下载链接）。

工具行为说明：

• 确认步骤：bluente_translate_document_workflow 是一个分两次调用的流程。首次调用会上传文件，并返回 page_count 和一张供用户确认的卡片；此时不会开始翻译，也不会扣除额度。卡片包含一行 Balance:，显示当前翻译额度、此次翻译后的余额和付款方；如果额度不足，则会显示警告。如果账户查询失败或耗时超过 3 秒，卡片会在不显示账户信息的情况下呈现。要实际开始翻译，请再次调用，并传入返回的 task_id、confirmed=true，以及明确的 to、to_type 和 bilingual 值。bluente_translate_file 无需确认步骤，会立即开始。
• 文件来源：file_path（此计算机上的文件）、file_url（公开链接）或 file_content_base64（小于 2MB）。
• bluente_translate_file：当 action="start" 时，必须提供 from 和 to；当 action="cancel" 时，这两个参数可选。
• to_type：pdf、word 或 pptx。工作流工具也接受数组（例如 ["word", "pdf"]）——额外格式是在下载时转换同一份译文，不会额外扣除额度。
• entry / status_entry：get_status（翻译进度，默认值）或 get_page_count（已上传文件的页数）。
• 语言代码：Bluente 使用非标准代码（zh、cht、jp、kor、fra、spa 等）。常见的 ISO 写法（zh-CN、zh-TW、ja、ko、fr、es）会自动映射；完整列表请调用 bluente_get_supported_languages。
• bilingual：on 会保留原文并附上译文；off（默认值）会生成纯译文文档。设置为 on 时，需将 bilingual_layout 设为 left-right（左右并排）或 top-down（上下排列）——这是 Bluente 支持的仅有两种布局。数字型 vertical_bilingual 标志是已弃用的别名。
• mode：standard（适用于大多数数字文档）、scanned (text)（对扫描件进行 OCR，生成纯文本文档）、scanned (overlay)（将译文覆盖回原扫描件版式）或 image（以目标语言重新渲染宣传册或海报等图形；每页 5 个额度——这是唯一收费高于标准费率的模式，扫描件模式与标准模式收费相同）。数字型 scanned 0–3 标志是已弃用的别名。
• page_range（例如 "1-3,5"）：仅翻译所选页面；只对这些页面扣除额度。
• translate_images：on 还会翻译 Word 或 PowerPoint 文件（DOC、DOCX、PPT、PPTX）中嵌入的图像内文本，例如图表、屏幕截图和扫描图；off（默认值）则仅翻译文档文本。不额外扣除额度。仅适用于标准模式；不适用于 PDF，也不能与双语输出同时使用（后端会拒绝此类请求）。请在确认后的调用中再次传入此参数；省略时表示关闭。
• 术语表：工作流工具始终启用术语表进行翻译（与 Bluente 网页产品一致）；其 glossary / custom_glossary 参数已弃用且会被忽略。对于原始 bluente_translate_file 工具，后端仅在 glossary 和 custom_glossary 均为 1 时应用术语表。

成功响应格式：

{
  "ok": true,
  "tool": "bluente_upload_file",
  "data": {
    "code": 0,
    "message": "success",
    "data": { "id": "task_xxx" }
  }
}

错误响应格式：

{
  "isError": true,
  "ok": false,
  "tool": "bluente_translate_file",
  "error": {
    "name": "BluenteApiError",
    "message": "Bluente API request failed.",
    "details": { "status": 401 }
  }
}

快速开始

要求：Node.js >= 20（使用 node --version 检查；从 nodejs.org 安装）和 Bluente API 密钥。

**获取 API 密钥：**登录 translate.bluente.com，然后前往 My Files → API Keys and Webhook。请像对待密码一样保管密钥——它可授权使用你的账户计费的翻译，因此不要将其提交到版本控制中，也不要放在共享文档里。

选项 1：直接让你的编码 Agent 来处理

最快的安装方法：不自己安装。如果你使用 Claude Code、Cursor 或任何支持 MCP 的编码 Agent，只需粘贴这段提示词，看它在不到一分钟内处理好一切——配置文件、密钥、验证。将 YOUR_KEY_HERE 替换为你的 API 密钥：

将 Bluente Translate MCP 服务安装到此客户端中。它是 npm 包 @bluente/translate-mcp-server，通过 npx -y @bluente/translate-mcp-server 运行（stdio），并需要在服务配置的 env 块中设置环境变量 BLUENTE_API_KEY。请使用 YOUR_KEY_HERE 作为密钥。完成配置后，调用 bluente_get_supported_languages 工具验证安装，并向我展示结果。文档：https://github.com/Bluente/bluente-translate-mcp-server

Agent 会找到适用于其客户端的配置文件，写入配置块，并通过展示支持的语言列表来证明安装成功。

不想在与 Agent 的对话中粘贴 API 密钥？让 Agent 使用 REPLACE_ME 作为密钥，然后手动编辑配置文件并重启客户端。

选项 2：手动安装

Claude Desktop

1. 打开 Settings → Developer → Edit Config（会打开 claude_desktop_config.json）。

2. 添加以下配置块（如果已有 mcpServers，则合并到其中），并填入你的 API 密钥：

   {
     "mcpServers": {
       "bluente-translate": {
         "command": "npx",
         "args": ["-y", "@bluente/translate-mcp-server"],
         "env": {
           "BLUENTE_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

3. 退出并重新打开 Claude Desktop。工具图标中应会列出七个 bluente_* 工具。

Claude Code — 运行一条命令，然后重启会话并使用 /mcp 验证：

claude mcp add bluente-translate -e BLUENTE_API_KEY=your_api_key_here -- npx -y @bluente/translate-mcp-server

Cursor — 前往 Settings → MCP → Add server，或在项目中创建 .cursor/mcp.json，并使用与 Claude Desktop 相同的 JSON 配置块。

**冒烟测试（任何客户端均可）：**询问 “Bluente 翻译支持哪些语言？”——这是一次免费的只读调用。返回语言列表即表示密钥和连接均正常。首次运行时，npx 下载软件包会多花几秒钟。

API 密钥故障排查

服务会从其环境中读取 BLUENTE_API_KEY——你无需将其作为工具参数传递，也不必存储在文件中。如果服务报告 Missing BLUENTE_API_KEY，说明密钥没有传递到服务进程：检查 env 块中是否有拼写错误，并重启客户端。从终端测试时，请在服务命令本身前加上密钥（BLUENTE_API_KEY=your_api_key_here npx -y @bluente/translate-mcp-server）；在 Shell 管道中，赋值必须紧挨着 npx 前面——如果放在行首，则只会应用于管道中的第一个命令。

可选环境变量：

变量	默认值	用途
BLUENTE_API_KEY	(required)	你的 Bluente API 密钥
BLUENTE_API_BASE_URL	https://api.bluente.com/api/20250924	API 基础 URL
BLUENTE_API_TIMEOUT_MS	90000	HTTP 超时时间（毫秒）

本地开发

git clone https://github.com/bluente/bluente-translate-mcp-server.git
cd bluente-translate-mcp-server
npm install
cp .env.example .env   # then set BLUENTE_API_KEY
npm start              # run the server on stdio
npm run check          # syntax check
npm test               # run tests

要让 MCP 客户端连接到你的本地检出目录，请使用 "command": "node" 和 "args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"]，而不是上面的 npx 配置。

运行说明

• 工作流工具会在翻译开始时立即返回。轮询 bluente_get_translation_status，直到状态为 READY，然后调用 bluente_download_file。
• auto_download=true 则会一直阻塞，直到翻译完成并将文件保存到磁盘。仅适用于较小的文档——翻译通常需要几分钟，而 MCP 客户端可能会先达到请求超时。
• max_poll_attempts 是上传和翻译阶段共用的单一预算。
• 可通过 BLUENTE_API_TIMEOUT_MS 配置超时时间。
• 在生产环境中，每个环境使用单独的 API 密钥。

数据处理与隐私

• 你翻译的文档会上传到 Bluente 的 API（默认地址为 api.bluente.com）进行处理。请勿翻译未经许可发送给第三方服务的文档。
• 工具由 AI 模型控制。 在本地运行（stdio）时，file_path 允许模型读取你的用户帐户有权读取的任何文件，并将其上传到 Bluente；output_path 允许模型将下载的文件写入任何可写路径。请在批准前检查 MCP 客户端中的工具调用，尤其是在处理不可信文档时——恶意文档可能会试图指示模型滥用这些工具。
• 工具返回的翻译结果（文件内容、状态负载）会进入 AI 客户端的上下文，因此你的大模型提供商也可以看到这些内容。
• 你的 API 密钥保留在本机：它从环境变量中读取，并且仅作为 Authorization 标头发送到配置的 Bluente API 基础 URL。它绝不会被记录，也不会包含在工具响应中。

安全

• 请勿提交 API 密钥或 .env 文件。
• 立即轮换已泄露的密钥。
• 使用仓库的私有漏洞报告渠道。

请参阅 SECURITY.md 了解漏洞披露政策。

路线图

• 如果公开 API 文档中提供文本翻译工具，则添加这些工具
• 通过 API 模拟添加更丰富的集成测试
• 添加容器镜像和一键本地启动配置

贡献与治理

• 贡献指南：CONTRIBUTING.md
• 安全政策：SECURITY.md
• 更新日志：CHANGELOG.md
• 代码所有权：.github/CODEOWNERS

关于 Bluente

Bluente 为专业团队打造 AI 翻译和商务沟通解决方案。

• 网站：bluente.com
• 产品页面：Blu Translate
• API 文档：bluente.com/docs

许可证

MIT