translate-mcp

# translate-mcp 一款适用于 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 的生产级、与模型无关的翻译服务器。您可以将其作为单个静态二进制文件、Docker 容器或 Kubernetes 服务运行，并连接任何与 MCP 兼容的主机 — Claude Desktop、Cursor、Windsurf、自定义客户端 — 以翻译文本、文档和 JSON 国际化文件，并支持缓存、词汇表、翻译记忆库和多提供商故障转移。 [](https://github.com/mohammadraufzahed/translate-mcp/actions/workflows/ci.yml) [](https://github.com/mohammadraufzahed/translate-mcp/releases) [](https://github.com/mohammadraufzahed/translate-mcp/pkgs/container/translate-mcp) [](LICENSE) - [功能](#features) - [安装](#installation) - [快速开始](#quick-start) - [配置](#configuration) - [提供商](#providers) - [MCP 工具](#mcp-tools) - [文档翻译](#document-translation) - [部署](#deployment) - [可观察性](#observability) - [开发](#development) - [架构](#architecture) - [许可证](#license) ## 功能 - **MCP 原生工具**：`translate`、`detect_language`、`batch_translate`、`translate_document`、`list_languages`、`add_glossary_entry`、`get_glossary`、`add_translation_memory`、`search_translation_memory`。 - **可插拔的翻译提供商**：OpenAI、OpenRouter、Anthropic、DeepL、Google（Gemini）、Ollama、LibreTranslate，以及任何 OpenAI 兼容的端点。 - **多级缓存**：L1 内存 LRU、L2 Redis、L3 SQL（SQLite/Postgres），具有单个键空间。 - **词汇表管道**：通过在翻译前替换术语和品牌名称为占位符，并在翻译后恢复它们来保护术语和品牌名称。 - **翻译记忆**：对之前存储或批准的翻译进行模糊搜索。 - **弹性**：每个提供商的并发限制、速率限制、熔断器和可配置的故障转移链。 - **可观察性**：结构化 JSON 日志、`health` 和 Prometheus `metrics`。 - **安全性**：Bearer token 认证、CORS 允许列表、输入长度限制和请求超时。 - **多个传输**：`stdio` 用于本地客户端，**Streamable HTTP** (`/mcp`) 用于远程访问。 - **可安装的发布**：预构建的二进制文件，以及每个发布的 `.deb`、`.rpm`、`.apk`、Arch `.pkg.tar.zst`、`.dmg` 和 NSIS `.exe` 安装程序。 ## 安装 ### 预构建的二进制文件 从 [Releases 页面](https://github.com/mohammadraufzahed/translate-mcp/releases) 下载您平台的最新版本。 ### 包管理器 每次发布后，都会发布可安装的工件： | 格式 | 安装命令 | |--------|-----------------| | Debian/Ubuntu | `sudo dpkg -i translate-mcp_*.deb` | | RHEL/CentOS/Fedora | `sudo rpm -i translate-mcp-*.rpm` | | Alpine | `sudo apk add --allow-untrusted translate-mcp_*.apk` | | Arch Linux | `sudo pacman -U translate-mcp-*.pkg.tar.zst` | | macOS | 打开 `.dmg` 并将 `translate-mcp` 复制到 `/usr/local/bin` | | Windows | 运行 `*_setup.exe` 安装程序 | ### Go 安装 ```bash go install github.com/mohammadraufzahed/translate-mcp/cmd/translate-mcp@latest ``` ### Docker ```bash docker pull ghcr.io/mohammadraufzahed/translate-mcp:latest ``` ## 快速开始 1. 复制示例配置： ```bash cp config.example.yaml config.yaml ``` 2. 编辑 `config.yaml` 并设置至少一个提供商的 API 密钥，例如 `OPENAI_API_KEY`。 3. 运行服务器： ```bash # stdio 模式适用于 Claude Desktop translate-mcp --transport stdio # HTTP 模式 translate-mcp --transport http --port 8787 ``` 4. 在 HTTP 模式下，测试健康检查端点： ```bash curl http://localhost:8787/health ``` ### 使用 Docker 运行 ```bash cp config.example.yaml config.yaml # 编辑 config.yaml 并设置您的提供商 API 密钥 docker run -p 8787:8787 \ -e TRANSLATE_MCP_TOKEN=sk-... \ -e OPENAI_API_KEY=sk-... \ -v ./config.yaml:/app/config.yaml:ro \ ghcr.io/mohammadraufzahed/translate-mcp:latest \ --config /app/config.yaml --transport http --port 8787 ``` ### 使用 Redis 和 Postgres 的 Docker Compose ```bash cp config.example.yaml config.yaml # 编辑 config.yaml 并设置您的提供商 API 密钥 docker compose up -d ``` ## 配置 所有设置都在 `config.yaml` 中。环境变量可以引用为 `${VAR}` 或 `${VAR:-default}`。 ```yml server: transport: http host: 0.0.0.0 port: 8787 auth: type: bearer token: ${TRANSLATE_MCP_TOKEN} cors: allowed_origins: ["*"] logging: format: json level: info mask_text: true metrics: enabled: true path: /metrics cache: default_ttl: 24h l1: type: memory max_entries: 10000 l2: type: redis address: redis:6379 password: ${REDIS_PASSWORD} l3: type: postgres dsn: ${DATABASE_DSN} providers: openai: api_key: ${OPENAI_API_KEY} default_model: gpt-4o openrouter: api_key: ${OPENROUTER_API_KEY} default_model: openai/gpt-4o-mini site_url: https://github.com/mohammadraufzahed/translate-mcp site_name: translate-mcp anthropic: api_key: ${ANTHROPIC_API_KEY} default_model: claude-3-5-sonnet-20241022 deepl: api_key: ${DEEPL_API_KEY} base_url: https://api.deepl.com google: api_key: ${GOOGLE_API_KEY} default_model: gemini-1.5-flash ollama: base_url: http://localhost:11434 default_model: llama3.1 libretranslate: base_url: https://libretranslate.com api_key: ${LIBRETRANSLATE_API_KEY} custom: base_url: http://localhost:8000/v1 default_model: default translation: default_provider: openai max_text_length: 10000 max_batch_items: 50 request_timeout: 60s fallback_chain: [openai, deepl, ollama] glossary_preprocessing: true vector: enabled: false provider: openai embedding_model: text-embedding-3-small similarity_threshold: 0.85 ``` 参见 [`config.example.yaml`](config.example.yaml) 和 [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) 以获取完整的参考资料。 ## 提供商 | 提供商 | 所需配置 | 备注 | |----------|-----------------|-------| | `openai` | `api_key` | GPT-4o、GPT-4o-mini 等 | | `openrouter` | `api_key` | 任何 OpenRouter 模型（例如 `openai/gpt-4o-mini`、`anthropic/claude-3.5-sonnet`） | | `anthropic` | `api_key` | Claude 3.5 Sonnet 等 | | `deepl` | `api_key` | 通过 `base_url` 支持免费/专业端点 | | `google` | `api_key` | 通过生成式语言 API 实现 Gemini | | `ollama` | `base_url` | 本地模型，如 `llama3.1` | | `libretranslate` | 可选 `api_key` | 本地或托管的 LibreTranslate | | `custom` | `base_url` | OpenAI 兼容的聊天补全 | 参见 [`docs/PROVIDERS.md`](docs/PROVIDERS.md) 以获取设置示例、模型 ID 和地区特定端点。 ## MCP 工具 ### `translate` 将文本翻译成目标语言。 ```json { "text": "Hello world", "target_language": "es", "source_language": "auto", "provider": "openai", "tone": "neutral" } ``` 参数： | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `text` | 字符串 | 是 | 要翻译的文本 | | `target_language` | 字符串 | 是 | BCP-47 代码，例如 `es`、`zh-CN`、`fr-FR` | | `source_language` | 字符串 | 否 | 源 BCP-47 代码或 `auto`（默认为 `auto`） | | `provider` | 字符串 | 否 | 提供商名称（默认为 `translation.default_provider`） | | `model` | 字符串 | 否 | 特定模型 ID | | `context` | 字符串 | 否 | 领域/语气提示，例如 `medical`、`software UI` | | `tone` | 字符串 | 否 | `formal`、`informal` 或 `neutral`（默认为 `neutral`） | | `use_cache` | 布尔值 | 否 | 使用缓存（默认为 `true`） | | `alternatives` | 数字 | 否 | 返回的替代翻译数量（默认为 `0`） | ### `detect_language` 检测一段文本的语言。 ```json { "text": "Hola mundo" } ``` ### `batch_translate` 一对多源语言翻译： ```json { "text": "Hello", "source_language": "en", "targets": ["es", "fr", "de"] } ``` 多文本至单一目标语言： ```json { "items": [ {"text": "Hello"}, {"text": "World"} ], "target_language": "es", "source_language": "en" } ``` ### `translate_document` 翻译 Markdown、JSON i18n、XML、HTML 或纯文本，同时保留结构。 ```json { "content": "{\"greeting\": \"Hello\"}", "format": "json", "target_language": "es", "source_language": "en" } ``` ### `add_glossary_entry` / `get_glossary` 添加和检索术语。服务器在翻译前屏蔽源术语，翻译后恢复目标翻译。 ```json { "source_term": "OpenAI", "target_language": "es", "translation": "OpenAI", "case_sensitive": false } ``` ### `add_translation_memory` / `search_translation_memory` 存储和搜索以前翻译的片段。 参见 [`docs/TOOLS.md`](docs/TOOLS.md) 以获取完整的工具模式和响应格式。 ## 文档翻译 `translate_document` 保留原始结构： - **JSON**：递归翻译所有字符串值，保留键。 - **HTML/XML**：保留标签，翻译文本节点。 - **Markdown**：保留代码块，翻译文本段。 - **纯文本**：翻译整个文本。 JSON i18n 示例： ```json { "content": "{\"nav\":{\"home\":\"Home\",\"about\":\"About\"}}", "format": "json", "target_language": "es" } ``` 结果： ```json { "nav": { "home": "Inicio", "about": "Acerca de" } } ``` ## MCP 客户端集成 ### Claude Desktop（stdio） 编辑 `claude_desktop_config.json`: ```json { "mcpServers": { "translate": { "command": "/usr/local/bin/translate-mcp", "args": ["--transport", "stdio", "--config", "/etc/translate-mcp/config.yaml"] } } } ``` ### Cursor / Windsurf / 自定义客户端（HTTP） ```json { "mcpServers": { "translate": { "url": "http://localhost:8787/mcp", "headers": { "Authorization": "Bearer sk-your-token" } } } } ``` ## 部署 - **单个二进制文件**：从 [Releases](https://github.com/mohammadraufzahed/translate-mcp/releases) 或 `go install` 下载。 - **Docker / Docker Compose**：参见 [`Dockerfile`](Dockerfile) 和 [`docker-compose.yml`](docker-compose.yml)。 - **systemd**：参见 [`systemd/translate-mcp.service`](systemd/translate-mcp.service)。 - **Kubernetes**：参见 [`kubernetes/`](kubernetes)。 参见 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) 以获取生产部署强化、密钥管理和水平扩展。 ## 可观察性 - `GET /health` 返回服务器状态和提供商健康状况： ```json { "status": "ok", "version": "1.0.0", "providers": { "openai": "healthy", "deepl": "unhealthy: api key not configured" } } ``` - `GET /metrics` 暴露 Prometheus 指标： - `mcp_requests_total` - `mcp_request_duration_seconds` - `translate_cache_hits_total` - `translate_provider_calls_total` - `translate_errors_total` - `translate_input_tokens_total` - `translate_output_tokens_total` ## 开发 ```bash go mod download go build ./... go test -race ./... go vet ./... gofmt -w . ``` 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 以获取内部实现。 ## 架构 ``` ┌─────────────┐ stdio / HTTP ┌─────────────────┐ │ MCP Host │◄─────────────────────►│ translate-mcp │ └─────────────┘ └────────┬────────┘ │ ┌────────┬────────┬────────┬────────┬────┴────┬──────────────┐ ▼ ▼ ▼ ▼ ▼ ▼ Tools Cache Glossary Memory Metrics Providers ``` 服务器公开 MCP 工具，通过缓存路由每个翻译请求，可选地应用词汇表掩码，查询翻译记忆，然后调用配置的提供商链。结果被缓存，并在成功时可选地存储在翻译记忆中。 参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 以获取深入了解。 ## CI/CD - **拉取请求** 触发 `go vet`、`gofmt`、`go test -race`、交叉编译和 Docker 构建。 - **合并到 `main` 分支** 运行 CI 管道和任何未完成的 workflow dispatch 任务。 - **版本号标签 `v*.*.*`** 触发 GoReleaser，它发布 Linux、macOS 和 Windows 的二进制文件，以及 `.deb`、`.rpm`、`.apk`、Arch 包、`.dmg` 和 `.exe` 安装程序。相同的标签触发 Docker 构建，它推送 `ghcr.io/mohammadraufzahed/translate-mcp`，并使用标签 `latest`、`{{version}}` 和 `{{major}}.{{minor}}`。 ## 发布 ```bash git checkout main git pull git tag v1.0.0 git push origin v1.0.0 ``` GoReleaser 和 Docker 工作流将处理其余部分。 ## 许可证 [MIT](LICENSE)