README.md•6.11 kB
# Translation MCP Server
一个基于 Model Context Protocol (MCP) 的文本翻译服务，支持 OpenAI 和兼容 OpenAI API 的模型。
## 功能特性
- 🌍 **多语言支持**: 支持 20+ 种主要语言之间的翻译
- 🤖 **AI 驱动**: 基于 OpenAI 兼容的大语言模型
- 📄 **长文本处理**: 自动分块处理大文档，突破 API 长度限制
- 🔍 **语言检测**: 自动识别输入文本的语言
- 🔌 **MCP 协议**: 标准化接口，易于集成到支持 MCP 的应用中
- ⚡ **异步处理**: 基于 asyncio 的高性能异步架构
- 🛠️ **灵活配置**: 支持自定义模型和 API 端点
## 支持的语言
| 语言代码 | 语言名称 | 语言代码 | 语言名称 |
|---------|---------|---------|----------|
| 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 |
## 安装
### 环境要求
- Python 3.10+
- OpenAI API 密钥（或兼容的 API 服务）
### 安装依赖
```bash
# 克隆项目
git clone <repository-url>
cd translation_mcp
# 使用 uv 安装依赖（推荐）
uv sync
# 或使用 pip 安装
pip install -e .
```
### 环境配置
创建 `.env` 文件并配置必要的环境变量：
```bash
# 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 的配置文件中添加：
```json
{
"mcpServers": {
"translation": {
"command": "python",
"args": ["/path/to/translation_mcp.py"],
"env": {
"OPENAI_API_KEY": "your_api_key_here"
}
}
}
}
```
#### 使用 uvx 运行（推荐）
首先构建分发包：
```bash
# 构建 wheel 包
uv build
# 查看生成的 whl 文件
ls dist/
```
然后在 Claude Desktop 配置中使用：
```json
{
"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 安装（如果已发布）：
```json
{
"mcpServers": {
"translation": {
"command": "uvx",
"args": ["translation-mcp"],
"env": {
"OPENAI_API_KEY": "your_api_key_here"
}
}
}
}
```
### 开发和测试
```bash
# 直接运行进行测试
python translation_mcp.py
# 运行测试套件
python test_mcp.py
```
### MCP 工具
服务器提供以下 MCP 工具：
#### 1. translate_text
翻译普通文本到指定语言。
**参数**:
- `text` (string, 必需): 要翻译的文本
- `target_language` (string, 必需): 目标语言代码
- `source_language` (string, 可选): 源语言代码，不指定则自动检测
**示例**:
```json
{
"text": "Hello, world!",
"target_language": "zh",
"source_language": "en"
}
```
#### 2. detect_language
检测文本的语言。
**参数**:
- `text` (string, 必需): 要检测语言的文本
**示例**:
```json
{
"text": "Bonjour le monde!"
}
```
#### 3. translate_long_text
翻译长文本，自动分块处理。
**参数**:
- `text` (string, 必需): 要翻译的长文本
- `target_language` (string, 必需): 目标语言代码
- `source_language` (string, 可选): 源语言代码
- `max_chunk_size` (integer, 可选): 每个文本块的最大字符数，默认 2000
**示例**:
```json
{
"text": "很长的文本内容...",
"target_language": "en",
"max_chunk_size": 1500
}
```
### MCP 资源
#### translation://languages
获取所有支持的语言列表，包含语言代码和名称。
## API 响应格式
### 成功响应
```json
{
"translated_text": "翻译后的文本",
"source_language": "en",
"target_language": "zh",
"model": "gpt-3.5-turbo",
"success": true
}
```
### 错误响应
```json
{
"error": "错误信息",
"success": false
}
```
### 长文本翻译响应
```json
{
"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 的其他服务：
```bash
# 使用本地模型服务
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 # 项目文档
```
### 构建和分发
```bash
# 构建项目
uv build
# 发布到 PyPI（可选）
uv publish
```
### 核心组件
- **OpenAITranslator**: 翻译服务核心类
- **TranslationMCPServer**: MCP 服务器实现
- **异步处理**: 基于 asyncio 的异步架构
- **错误处理**: 完善的异常处理机制
## 许可证
MIT License
## 贡献
欢迎提交 Issue 和 Pull Request！
## 更新日志
### v0.1.0
- 初始版本发布
- 支持基础文本翻译
- 支持语言检测
- 支持长文本分块翻译
- MCP 协议集成