# 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 协议集成