JinDaGe - poeditor-mcp MCP Details

article

README

🚀 🌐 POEditor MCP Server

POEditor MCP Server 是一个全面的模型上下文协议（MCP）服务器，专为 POEditor 翻译管理而设计，具备先进的自动化脚本和工作流优化工具，能有效提升翻译管理的效率和质量。

GitHub release (latest by date)

GitHub issues GitHub pull requests GitHub last commit GitHub repo size

🚀 快速开始

1. 自动设置（推荐）

# 克隆仓库
git clone https://github.com/yourusername/poeditor-mcp.git
cd poeditor-mcp

# 运行自动设置脚本
python setup.py

# 按照交互式提示配置你的 POEditor API 令牌

2. 手动设置

# 安装依赖项
pip install -r requirements.txt

# 复制环境模板
cp .env.template .env

# 使用你的 POEditor API 令牌编辑 .env 文件
nano .env

# 测试连接
python test_connection.py

3. 开始使用

# 显示所有可用命令
python control_center.py help

# 运行每日监控
python control_center.py monitor

# 生成进度报告
python control_center.py daily_report

# 启动自动调度
python control_center.py schedule start

✨ 主要特性

🔌 完整的 MCP 服务器：与 POEditor API 完全集成。
🎛️ 控制中心：主脚本，用于管理所有自动化工具。
📊 智能报告：带有进度跟踪的交互式 HTML 报告。
🚨 监控系统：自动警报，用于检测翻译问题。
🤖 AI 自动化：智能翻译建议和一致性检查。
📧 通知：通过电子邮件和 Slack 集成向团队更新信息。
📦 批量导出：多格式导出系统，适用于所有平台。
🕒 调度器：具有类似 cron 功能的自动任务执行。

🎯 为何选择此 MCP？

与其他需要复杂 Docker 设置的 MCP 服务器不同，POEditor MCP 设计简洁：

❌ 无需 Docker - 纯 Python 实现。
🎯 专注于翻译 - 专为本地化工作流而构建。
🔧 最少的设置 - 只需添加你的 API 令牌并运行。
🚀 即时执行 - python setup.py && python control_center.py。
📊 可视化报告 - 漂亮的 HTML 仪表盘。
🤖 内置 AI - 智能翻译建议。

📊 项目状态

| 特性 | 状态 | 描述 | |---------|--------|-------------| | 🔌 MCP 服务器 | ✅ 完成 | 完整的 MCP 协议实现 | | 🎯 POEditor API | ✅ 完成 | 覆盖所有 API 端点 | | 🤖 Claude Desktop | ✅ 支持 | 即使用配置 | | 🔧 VS Code | ✅ 支持 | 与 MCP 扩展兼容 | | 📊 自动化 | ✅ 完成 | 10 多个自动化脚本 | | 📖 文档 | ✅ 完成 | 全面的指南 | | 🧪 测试 | ✅ 完成 | 全面的测试覆盖 | | 🌐 国际化 | 🚧 计划中 | 多语言支持 |

💻 使用示例

基础用法

from mcp_poeditor.server import call_tool

# 列出所有项目
projects = await call_tool("list_projects", {})

# 获取项目语言
languages = await call_tool("list_languages", {"project_id": "123456"})

# 搜索特定术语
results = await call_tool("search_terms", {
    "project_id": "123456",
    "search_query": "login"
})

# 导出翻译
export_url = await call_tool("export_translations", {
    "project_id": "123456",
    "language_code": "es",
    "file_format": "json"
})

自动化工作流

# 早上例行操作
python control_center.py monitor        # 检查问题
python control_center.py daily_report   # 生成进度报告

# 开发工作流
python control_center.py automate       # 获取 AI 建议
python control_center.py export         # 为开发人员导出

# 每周优化
python control_center.py optimize       # 分析工作流效率
python control_center.py sync          # 同步相关项目

与 CI/CD 集成

# GitHub Actions 示例
name: Translation Export
on:
  schedule:
    - cron: '0 8 * * *'  # 每天早上 8 点
  
jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Export translations
        env:
          POEDITOR_API_TOKEN: ${{ secrets.POEDITOR_API_TOKEN }}
        run: python control_center.py export

📚 详细文档

📖 安装指南 - 详细的设置说明
⚙️ 配置指南 - 高级配置选项
🔧 API 参考 - 完整的 API 文档
🚀 集成指南 - 平台集成示例
🤝 贡献指南 - 如何为项目做出贡献

🔧 技术细节

MCP 客户端配置

安装完成后，配置你的 MCP 客户端以使用 POEditor 服务器：

🎯 Claude Desktop

将此配置添加到你的 Claude Desktop 配置文件中： macOS/Linux：~/.claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "poeditor": {
      "command": "python",
      "args": ["-m", "mcp_poeditor"],
      "cwd": "/path/to/your/poeditor-mcp",
      "env": {
        "POEDITOR_API_TOKEN": "your_poeditor_token_here"
      }
    }
  }
}

🔧 Visual Studio Code

将此配置添加到你的 VS Code 设置中：文件：.vscode/settings.json（工作区）或用户设置

{
  "mcp.servers": {
    "poeditor": {
      "command": "python",
      "args": ["-m", "mcp_poeditor"],
      "cwd": "/path/to/your/poeditor-mcp",
      "env": {
        "POEDITOR_API_TOKEN": "your_poeditor_token_here"
      }
    }
  }
}

📝 配置说明

将 /path/to/your/poeditor-mcp 替换为你实际的安装路径。
将 your_poeditor_token_here 替换为你实际的 POEditor API 令牌。
配置完成后重启你的 MCP 客户端。
使用提供的示例文件：claude_desktop_config_example.json 和 vscode_settings_example.json。

🛠️ 可用工具

MCP 服务器通过以下工具类别提供全面的 POEditor 管理：

📋 项目管理

list_projects - 列出所有项目
get_project - 获取项目详细信息
create_project - 创建新项目

🌍 语言管理

list_languages - 列出项目语言
add_language - 向项目添加语言
remove_language - 从项目中移除语言

🔍 术语管理

list_terms - 列出项目术语
search_terms - 按键/值搜索术语
add_terms - 添加新术语
delete_terms - 移除术语

✏️ 翻译管理

list_translations - 获取语言翻译
add_translation - 添加新翻译
update_translation - 更新现有翻译
export_translations - 以多种格式导出

📊 统计与分析

get_project_stats - 项目统计信息
get_translation_progress - 按语言显示进度
compare_languages - 语言比较分析

🎛️ 自动化脚本

项目包含一套强大的自动化脚本，可通过控制中心访问：

python control_center.py <command>

📊 报告与分析

daily_report - 生成全面的 HTML 进度报告
status - 检查系统健康状况和配置

🚨 监控与警报

monitor - 扫描翻译问题和质量问题
test - 运行系统诊断

🤖 自动化

automate - 基于 AI 的翻译建议和一致性检查
schedule - 自动任务调度和执行

📈 优化

optimize - 工作流分析并提供可操作的建议
sync - 在类似项目之间同步翻译

📦 导出与集成

export - 以多种格式（JSON、Android XML、iOS Strings 等）批量导出
notify - 通过电子邮件/Slack 发送团队通知

🔧 管理

setup - 交互式环境配置
demo - 完整的系统演示

📁 项目结构

poeditor-mcp/
├── 📄 README.md                     # 本文件
├── 📄 requirements.txt              # Python 依赖项
├── 📄 .env.template                 # 环境模板
├── 📄 setup.py                      # 自动设置脚本
├── 📄 test_connection.py            # 连接测试工具
├── 📄 claude_desktop_config_example.json # Claude Desktop 配置示例
├── 📄 vscode_settings_example.json # VS Code 配置示例
├── 📄 CONFIG_README.md             # 配置指南
│
├── 📁 mcp_poeditor/                # 核心 MCP 包
│   ├── 📄 __init__.py
│   ├── 📄 __main__.py              # 入口点
│   ├── 📄 server.py                # MCP 服务器实现
│   ├── 📄 poeditor_client.py       # POEditor API 客户端
│   │
│   ├── 📁 tools/                   # MCP 工具
│   │   ├── 📄 projects.py          # 项目管理
│   │   ├── 📄 languages.py         # 语言管理
│   │   ├── 📄 terms.py             # 术语管理
│   │   ├── 📄 translations.py      # 翻译管理
│   │   └── 📄 stats.py             # 统计与分析
│   │
│   └── 📁 utils/                   # 实用工具
│       ├── 📄 config.py            # 配置管理
│       └── 📄 helpers.py           # 辅助函数
│
├── 📁 scripts/                     # 🎛️ 自动化套件
│   ├── 📄 README.md                # 脚本文档
│   ├── 📄 control_center.py        # 🎛️ 主控制脚本
│   ├── 📄 daily_report.py          # 📊 每日进度报告
│   ├── 📄 translation_monitor.py   # 🚨 质量监控
│   ├── 📄 workflow_optimizer.py    # 📈 工作流优化
│   ├── 📄 project_sync.py          # 🔄 项目同步
│   ├── 📄 notification_manager.py  # 📧 团队通知
│   ├── 📄 translation_automator.py # 🤖 AI 自动化
│   ├── 📄 mass_exporter.py         # 📦 多格式导出
│   ├── 📄 scheduler.py             # 🕒 任务调度
│   └── 📄 demo_workflow.py         # 🎯 完整演示
│
├── 📁 examples/                    # 使用示例
│   ├── 📄 basic_usage.py          # 基本 MCP 使用
│   ├── 📄 automation_examples.py  # 自动化示例
│   └── 📄 integration_guide.md    # 集成指南
│
└── 📁 docs/                       # 文档
    ├── 📄 INSTALLATION.md         # 详细安装说明
    ├── 📄 CONFIGURATION.md        # 配置指南
    ├── 📄 API_REFERENCE.md        # API 文档
    └── 📄 CONTRIBUTING.md         # 贡献指南

🔧 配置

环境变量

在根目录下创建一个 .env 文件：

# POEditor API 配置
POEDITOR_API_TOKEN=your_api_token_here
POEDITOR_API_URL=https://api.poeditor.com/v2/

# MCP 服务器配置
MCP_SERVER_NAME=poeditor-mcp
MCP_SERVER_VERSION=1.0.0

# 通知设置（可选）
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@company.com
SMTP_PASSWORD=your_app_password

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# 自动化设置
DEFAULT_EXPORT_FORMAT=json
MAX_RETRIES=3
REQUEST_TIMEOUT=30
LOG_LEVEL=INFO

调度器配置

在 scripts/scheduler_config.json 中自定义自动化调度：

{
  "schedules": {
    "daily_report": {
      "time": "08:00",
      "enabled": true,
      "weekdays_only": true,
      "description": "生成每日进度报告"
    },
    "monitoring": {
      "time": "09:00",
      "enabled": true,
      "weekdays_only": true,
      "description": "运行翻译质量监控"
    },
    "weekly_optimization": {
      "day": "monday",
      "time": "08:30",
      "enabled": true,
      "description": "每周工作流优化分析"
    }
  }
}

🔄 自动化工作流

每日自动化

🌅 早上：质量监控和进度报告。
🕙 中午：基于 AI 的翻译建议。
🌆 晚上：为开发团队导出更新。

每周优化

📊 周一：工作流分析和优化建议。
🔄 周三：项目同步和一致性检查。
📦 周五：完整备份和多格式导出。

实时监控

🚨 质量警报：模糊翻译、一致性问题。
📈 进度跟踪：语言完成里程碑。
👥 团队通知：通过 Slack/电子邮件更新重要事件。

🎯 支持的导出格式

适用于任何开发工作流：

📱 移动：Android XML、iOS Strings、React Native JSON。
🌐 Web：JSON、CSV，适用于 React/Vue/Angular 应用程序。
🖥️ 后端：Gettext PO、Java Properties、YAML。
📊 分析：Excel XLSX、CSV，用于进度跟踪。
🔄 集成：XLIFF、TMX，用于 CAT 工具。

🆘 故障排除

常见问题

连接失败

# 测试你的 POEditor API 令牌
python test_connection.py

# 检查配置
python control_center.py status

缺少依赖项

# 重新安装依赖项
pip install -r requirements.txt

# 运行系统诊断
python control_center.py test

权限错误

# 修复文件权限
chmod +x setup.py
chmod +x control_center.py

获取帮助

🔍 检查日志：./logs/ 目录包含详细的执行日志。
🧪 运行诊断：python control_center.py test。
📊 系统状态：python control_center.py status。
🐛 报告问题：创建一个 GitHub 问题，并附上日志详细信息。

🤝 贡献

我们欢迎贡献！请参阅贡献指南了解以下详细信息：

🐛 报告错误。
💡 建议功能。
🔧 提交拉取请求。
📖 改进文档。

📄 许可证

本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

🌟 致谢

Model Context Protocol 提供了出色的 MCP 框架。
POEditor 提供了全面的翻译管理 API。
开源社区提供了灵感和最佳实践。

⭐ 如果这个项目对你有帮助，请考虑给它点个星！

🚀 立即开始自动化你的翻译工作流！