Metadata-Version: 2.4
Name: mcp-translation-text
Version: 1.0.0
Summary: MCP provider wrapping the Niutrans translation API
Author-email: Niutrans <tianfengning@niutrans.com>
License: MIT
Project-URL: Homepage, https://niutrans.com
Project-URL: Source, https://github.com/niutrans/mcp-translation-text
Keywords: mcp,translation,niutrans,ai
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=0.2.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: uv; extra == "dev"
Dynamic: license-file

# MCP 翻译服务

基于小牛翻译（Niutrans）API 的 MCP Provider，提供文字翻译工具和语种目录资源，方便在 Cursor/mcp-cli 等客户端中引用。

## 快速开始

### 通过 PyPI 安装

```bash
pip install mcp-translation-text
mcp-translation-text  # 直接启动 Provider
```

若希望使用 `uv` 管理环境：

```bash
uv tool install mcp-translation-text
mcp-translation-text
```

### 本地源码运行

1. 克隆或下载本项目。
2. 复制环境变量示例并填写 Key：
   ```powershell
   Copy-Item .env.example .env
   ```
3. 安装依赖并启动：
   - **Windows**：
     ```powershell
     scripts\start.ps1
     ```
   - **macOS/Linux**：
     ```bash
     chmod +x scripts/start.sh
     ./scripts/start.sh
     ```
   脚本会：
   - 从 `.env`（默认）加载 `NIUTRANS_API_KEY` 等变量；
   - 使用 `uv` 创建 `.venv` 并安装项目依赖；
   - 通过 `uv run python server.py` 启动 MCP Provider。

## 环境变量

- `NIUTRANS_API_KEY`（必填）：小牛翻译开放平台提供的 API Key。
- `NIUTRANS_API_URL`（可选）：自定义接口地址，默认为 `https://api.niutrans.com/NiuTransServer/translation`。

## MCP 客户端配置示例

若已通过 PyPI 安装，可在 `mcp.json` 中写：

```json
{
  "mcpServers": {
    "translation": {
      "type": "stdio",
      "command": "mcp-translation-text",
      "env": {
        "NIUTRANS_API_KEY": "${env.NIUTRANS_API_KEY}",
        "NIUTRANS_API_URL": "${env.NIUTRANS_API_URL}"
      }
    }
  }
}
```

若仍使用源码目录，请将 `command` 指向虚拟环境中的 `python.exe` 并设置 `cwd`，如：

```json
{
  "translation": {
    "type": "stdio",
    "command": "E:\\MCP\\.venv\\Scripts\\python.exe",
    "args": ["server.py"],
    "cwd": "E:\\MCP",
    "env": {
      "NIUTRANS_API_KEY": "${env.NIUTRANS_API_KEY}",
      "NIUTRANS_API_URL": "${env.NIUTRANS_API_URL}"
    }
  }
}
```

启动 Cursor 后执行 `ListTools` 即可看到 `translate_text`，同时支持 `ListResources` 读取 `language://catalog`。

## 可用功能

### 工具：`translate_text`

- **参数**：
  - `text`：待翻译内容。
  - `source`：源语言代码或别名（会通过本地映射表规范化）。
  - `target`：目标语言代码或别名。
- **返回**：
  ```json
  {
    "source": "zh",
    "target": "en",
    "original_text": "你好",
    "translated_text": "Hello",
    "raw": { ... 小牛原始响应 ... }
  }
  ```

### 资源：`language://catalog`

提供所有可用语种及别名，示例如下：

```json
{
  "total": 655,
  "languages": [
    {"code": "zh", "zh": "中文(简体)", "en": "Chinese (Simplified)"},
    {"code": "en", "zh": "英语", "en": "English"}
    // ... 其余省略 ...
  ],
  "aliases": {
    "zhongwenjianti": "zh",
    "english": "en"
    // ... 其余省略 ...
  }
}
```

推荐在客户端的 LLM 中先读取该资源，完成语种描述到代码的映射后，再调用 `translate_text`。

## 调试与常见问题

- **缺少 API Key**：启动时报 `缺少环境变量 NIUTRANS_API_KEY`，请确认已在 `.env` 或系统环境中设置。
- **语种不支持**：`translate_text` 会校验语种代码/别名，若报错请检查是否使用了 `language://catalog` 中列出的值。
- **路径或依赖问题**：脚本依赖 `uv`，请先安装 `pip install uv` 或参考 [uv 文档](https://github.com/astral-sh/uv)。
- **命令名称**：通过 PyPI 安装后，可直接运行 `mcp-translation-text`；若 global PATH 中找不到，记得激活虚拟环境或使用 `python -m mcp_translation_text`。
- **发布/升级包**：
  ```bash
  python -m build
  twine upload dist/*
  ```

## 目录结构（关键文件）

```
E:\MCP
├── pyproject.toml
├── server.py                # 入口包装，确保 python server.py 可运行
├── src/
│   └── translation_server.py
├── scripts/
│   ├── start.ps1
│   └── start.sh
├── .env.example
├── LICENSE
└── README.md
```

发布后，用户只需设置 Niutrans API Key，即可通过 `mcp-translation-text` 直接加载该 Provider。

