Textra 日语到英语翻译 MCP 服务器

概述

该项目提供了一个 模型上下文协议 (MCP) 服务器，使用 textra 翻译 API 服务将日语文本翻译成英文。

它特别适用于与日语理解能力有限的 LLM（大型语言模型）进行交互。通过将日语指令通过此 MCP 服务器路由，输入可以在传递给 LLM 之前被翻译成英文。

该服务器使用 fastmcp 框架构建。

设置

1. 克隆仓库：

   git clone <repository_url>
   cd <repository_directory>
   

2. 创建并激活虚拟环境：

   uv venv
   source .venv/bin/activate
   

   （在 Windows 上，请使用 .venv\Scripts\activate）

3. 安装依赖项：
   安装运行项目和开发/测试所需的库。

   # 仅安装运行时依赖项
   uv pip install .
   
   # 安装运行时和开发/测试依赖项
   uv pip install '.[dev]'
   

   （依赖项基于 pyproject.toml 安装。）

4. 设置环境变量：
   该服务器需要设置以下环境变量，以包含您的 Textra API 凭证：

   • TEXTRA_API_KEY: 您的 Textra API 密钥。
   • TEXTRA_API_SECRET: 您的 Textra API 密码。
   • TEXTRA_USER_NAME: 您的 Textra 登录 ID。

   强烈建议在 shell 的配置文件中设置这些变量（例如 ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish），而不是使用 .env 文件。这可以确保在客户端应用程序运行 MCP 服务器时，这些变量是可用的。

   对于 .zshrc 或 .bashrc 的示例：

   export TEXTRA_API_KEY="your_api_key"
   export TEXTRA_API_SECRET="your_api_secret"
   export TEXTRA_USER_NAME="your_username"
   

   在添加这些行后，记得重新加载文件（例如 source ~/.zshrc）或重启 shell。

   可选变量：

   • TEXTRA_JA_EN_API_URL: 覆盖默认的翻译 API 端点。
   • TEXTRA_TOKEN_URL: 覆盖默认的 OAuth 令牌端点。

   （请参阅 .env.example 以获取变量名称和默认值。虽然在本地开发时可以使用 .env 文件，特别是在使用 fastmcp dev 时，但为 MCP 服务器部署设置系统范围的环境变量更为稳健。）

运行测试

确保您的虚拟环境已激活。

pytest

或

uv run test

使用

确保您的虚拟环境已激活，并且必需的环境变量 (TEXTRA_API_KEY, TEXTRA_API_SECRET, TEXTRA_USER_NAME) 已正确设置在您的 shell 环境中。

本地运行服务器

有两种主要方法在本地运行服务器：

1. 使用 fastmcp dev（推荐用于开发）：
   该命令提供了代码更改时自动重新加载的功能。

   fastmcp dev server.py
   

2. 使用 uvx：
   该命令在由 uv 管理的临时环境中直接运行服务器脚本，并按需安装依赖项。这对于无需安装即可快速执行非常有用。

   uvx python server.py
   

这两个命令都将启动服务器，默认通过 stdio 监听 MCP 连接。然后，您可以使用像 MCP Inspector 这样的 MCP 客户端连接到它。

1. 直接从 GitHub 使用 uvx（需要安装 uv）：
   您可以直接从 GitHub 仓库运行服务器，而无需先克隆它。这对于与支持自定义命令的 MCP 客户端集成非常有用。uvx 将处理代码获取并在临时环境中安装依赖项。

   uvx python server.py --git https://github.com/hokupod/textra-ja-to-en-mcp.git
   

   注意：与从本地克隆运行相比，此方法可能在初始启动时花费更长的时间。

为 MCP 客户端安装服务器（例如 Claude Desktop）

使用 fastmcp install 命令使服务器对系统上的 MCP 客户端应用程序可用。

fastmcp install server.py --name "Japanese to English Translator"

安装后，像 Claude Desktop 这样的 MCP 客户端应该能够发现并使用“日语到英语翻译器”工具。

或者，如果您的 MCP 客户端支持通过命令定义服务器（如 Claude Desktop 的 mcp_servers.json），您可以配置它使用 uvx 直接从 GitHub 运行服务器：

{
  "mcpServers": {
    "textra-translator": {
      "command": "uvx",
      "args": [
        "python",
        "server.py",
        "--git", "https://github.com/hokupod/textra-ja-to-en-mcp.git"
        // Optionally specify a branch or commit:
        // "--git", "https://github.com/hokupod/textra-ja-to-en-mcp.git#main"
      ]
    }
  }
}

（确保 uv 已安装并且在客户端环境中可访问。）

当通过此类客户端与 LLM 交互时，如果您提供日语文本输入，LLM（如果根据其描述正确配置了使用此工具）应自动调用此服务器将文本翻译成英语，然后再进一步处理请求。翻译后的英文文本将被视为用户的原始请求。