JinDaGe - translation_mcp MCP Details

article

README

🚀 翻译 MCP 服务器

这是一个基于 Model Context Protocol (MCP) 的文本翻译服务，支持 OpenAI 以及兼容 OpenAI API 的模型，能高效解决多语言文本翻译问题，为各类应用提供标准化、灵活的翻译支持。

✨ 主要特性

🌍 多语言支持：可实现 20+ 种主要语言之间的翻译。
🤖 AI 驱动：依托 OpenAI 兼容的大语言模型进行翻译。
📄 长文本处理：自动对大文档进行分块处理，有效突破 API 长度限制。
🔍 语言检测：能自动识别输入文本的语言。
🔌 MCP 协议：采用标准化接口，便于集成到支持 MCP 的应用中。
⚡ 异步处理：基于 asyncio 的高性能异步架构，提升处理效率。
🛠️ 灵活配置：支持自定义模型和 API 端点。

📦 安装指南

环境要求

Python 3.10+
OpenAI API 密钥（或兼容的 API 服务）

安装依赖

# 克隆项目
git clone <repository-url>
cd translation_mcp

# 使用 uv 安装依赖（推荐）
uv sync

# 或使用 pip 安装
pip install -e .

环境配置

创建 .env 文件并配置必要的环境变量：

# OpenAI API 配置
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1  # 可选，默认为 OpenAI 官方 API
OPENAI_MODEL=gpt-3.5-turbo  # 可选，默认模型

💻 使用示例

作为 MCP 服务器使用

本项目是一个 MCP (Model Context Protocol) 服务器，需在支持 MCP 的客户端中配置使用，而非直接运行。

在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "translation": {
      "command": "python",
      "args": ["/path/to/translation_mcp.py"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用 uvx 运行（推荐）

首先构建分发包：

# 构建 wheel 包
uv build

# 查看生成的 whl 文件
ls dist/

然后在 Claude Desktop 配置中使用：

{
  "mcpServers": {
    "translation": {
      "command": "uvx",
      "args": ["/path/to/translation_mcp/dist/translation_mcp-0.1.0-py3-none-any.whl"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

或者直接从 PyPI 安装（如果已发布）：

{
  "mcpServers": {
    "translation": {
      "command": "uvx",
      "args": ["translation-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

开发和测试

# 直接运行进行测试
python translation_mcp.py

# 运行测试套件
python test_mcp.py

MCP 工具

服务器提供以下 MCP 工具：

1. translate_text

翻译普通文本到指定语言。参数：

text (string, 必需)：要翻译的文本
target_language (string, 必需)：目标语言代码
source_language (string, 可选)：源语言代码，不指定则自动检测

示例：

{
  "text": "Hello, world!",
  "target_language": "zh",
  "source_language": "en"
}

2. detect_language

检测文本的语言。参数：

text (string, 必需)：要检测语言的文本

示例：

{
  "text": "Bonjour le monde!"
}

3. translate_long_text

翻译长文本，自动分块处理。参数：

text (string, 必需)：要翻译的长文本
target_language (string, 必需)：目标语言代码
source_language (string, 可选)：源语言代码
max_chunk_size (integer, 可选)：每个文本块的最大字符数，默认 2000

示例：

{
  "text": "很长的文本内容...",
  "target_language": "en",
  "max_chunk_size": 1500
}

MCP 资源

translation://languages

获取所有支持的语言列表，包含语言代码和名称。

📚 详细文档

支持的语言

| 语言代码 | 语言名称 | 语言代码 | 语言名称 | |---------|---------|---------|----------| | en | English | zh | 中文 | | ja | 日本語 | ko | 한국어 | | es | Español | fr | Français | | de | Deutsch | it | Italiano | | pt | Português | ru | Русский | | ar | العربية | hi | हिन्दी | | th | ไทย | vi | Tiếng Việt | | id | Bahasa Indonesia | ms | Bahasa Melayu | | tl | Filipino | tr | Türkçe | | pl | Polski | nl | Nederlands |

API 响应格式

成功响应

{
  "translated_text": "翻译后的文本",
  "source_language": "en",
  "target_language": "zh",
  "model": "gpt-3.5-turbo",
  "success": true
}

错误响应

{
  "error": "错误信息",
  "success": false
}

长文本翻译响应

{
  "translated_text": "完整的翻译文本",
  "source_language": "auto-detected",
  "target_language": "zh",
  "chunks_count": 3,
  "success": true
}

配置选项

环境变量

| 变量名 | 描述 | 默认值 | |--------|------|--------| | OPENAI_API_KEY | OpenAI API 密钥 | 必需 | | OPENAI_BASE_URL | API 基础 URL | https://api.openai.com/v1 | | OPENAI_MODEL | 默认模型 | gpt-3.5-turbo |

自定义模型

支持使用兼容 OpenAI API 的其他服务：

# 使用本地模型服务
OPENAI_BASE_URL=http://localhost:8000/v1
OPENAI_API_KEY=your_local_api_key

# 使用其他云服务
OPENAI_BASE_URL=https://your-service.com/v1
OPENAI_API_KEY=your_service_api_key

开发

项目结构

translation_mcp/
├── translation_mcp.py    # 主程序文件
├── pyproject.toml       # 项目配置和依赖
├── uv.lock             # 锁定的依赖版本
├── MANIFEST.in         # 打包配置
├── .env                # 环境变量配置
├── dist/               # 构建输出目录
└── README.md          # 项目文档

构建和分发

# 构建项目
uv build

# 发布到 PyPI（可选）
uv publish

核心组件

OpenAITranslator：翻译服务核心类
TranslationMCPServer：MCP 服务器实现
异步处理：基于 asyncio 的异步架构
错误处理：完善的异常处理机制

📄 许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v0.1.0

初始版本发布
支持基础文本翻译
支持语言检测
支持长文本分块翻译
MCP 协议集成

translation_mcp