POEditor MCP Server

# 🌐 POEditor MCP Server A comprehensive Model Context Protocol (MCP) server for POEditor translation management, featuring advanced automation scripts and workflow optimization tools. [](https://github.com/r-pedraza/poeditor-mcp/releases) [](https://www.python.org/) [](https://opensource.org/licenses/MIT) [](https://github.com/r-pedraza/poeditor-mcp/stargazers) [](https://github.com/modelcontextprotocol) [](https://poeditor.com/) [](https://claude.ai/) [](https://code.visualstudio.com/) [](https://github.com/r-pedraza/poeditor-mcp/issues) [](https://github.com/r-pedraza/poeditor-mcp/pulls) [](https://github.com/r-pedraza/poeditor-mcp/commits/main) [](https://github.com/r-pedraza/poeditor-mcp) ## 🚀 **Features** - **🔌 Complete MCP Server**: Full integration with POEditor API - **🎛️ Control Center**: Master script to manage all automation tools - **📊 Smart Reporting**: Interactive HTML reports with progress tracking - **🚨 Monitoring System**: Automated alerts for translation issues - **🤖 AI Automation**: Intelligent translation suggestions and consistency checking - **📧 Notifications**: Email and Slack integration for team updates - **📦 Mass Export**: Multi-format export system for all platforms - **🕒 Scheduler**: Automated task execution with cron-like functionality ## 🎯 **Why This MCP?** Unlike other MCP servers that require complex Docker setups, POEditor MCP is designed for simplicity: - ❌ **No Docker required** - Pure Python implementation - 🎯 **Translation-focused** - Built specifically for localization workflows - 🔧 **Minimal setup** - Just add your API token and run - 🚀 **Instant execution** - `python setup.py && python control_center.py` - 📊 **Visual reports** - Beautiful HTML dashboards - 🤖 **Built-in AI** - Smart translation suggestions ## 📊 **Project Status** [](https://github.com/r-pedraza/poeditor-mcp) [](https://github.com/r-pedraza/poeditor-mcp/commits/main) [](https://poeditor.com/docs/api) [](https://github.com/r-pedraza/poeditor-mcp#documentation) | Feature | Status | Description | |---------|--------|-------------| | 🔌 MCP Server | ✅ Complete | Full MCP protocol implementation | | 🎯 POEditor API | ✅ Complete | All API endpoints covered | | 🤖 Claude Desktop | ✅ Supported | Ready-to-use configuration | | 🔧 VS Code | ✅ Supported | MCP extension compatible | | 📊 Automation | ✅ Complete | 10+ automation scripts | | 📖 Documentation | ✅ Complete | Comprehensive guides | | 🧪 Testing | ✅ Complete | Thorough test coverage | | 🌐 Internationalization | 🚧 Planned | Multi-language support | ## 📋 **Quick Start** ### 1. **Automatic Setup** (Recommended) ```bash # Clone the repository git clone https://github.com/yourusername/poeditor-mcp.git cd poeditor-mcp # Run the automatic setup script python setup.py # Follow the interactive prompts to configure your POEditor API token ``` ### 2. **Manual Setup** ```bash # Install dependencies pip install -r requirements.txt # Copy environment template cp .env.template .env # Edit .env with your POEditor API token nano .env # Test the connection python test_connection.py ``` ### 3. **Start Using** ```bash # Show all available commands python control_center.py help # Run daily monitoring python control_center.py monitor # Generate progress report python control_center.py daily_report # Start automated scheduling python control_center.py schedule start ``` ## � **MCP Client Configuration** Once installed, configure your MCP client to use the POEditor server: ### **🎯 Claude Desktop** Add this configuration to your Claude Desktop config file: **macOS/Linux**: `~/.claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```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** Add this configuration to your VS Code settings: **File**: `.vscode/settings.json` (workspace) or user 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" } } } } ``` ### **📝 Configuration Notes** - Replace `/path/to/your/poeditor-mcp` with the actual path to your installation - Replace `your_poeditor_token_here` with your actual POEditor API token - Restart your MCP client after configuration - Use the provided example files: `claude_desktop_config_example.json` and `vscode_settings_example.json` ## �🛠️ **Available Tools** The MCP server provides comprehensive POEditor management through these tool categories: ### **📋 Project Management** - `list_projects` - List all projects - `get_project` - Get project details - `create_project` - Create new project ### **🌍 Language Management** - `list_languages` - List project languages - `add_language` - Add language to project - `remove_language` - Remove language from project ### **🔍 Term Management** - `list_terms` - List project terms - `search_terms` - Search terms by key/value - `add_terms` - Add new terms - `delete_terms` - Remove terms ### **✏️ Translation Management** - `list_translations` - Get language translations - `add_translation` - Add new translation - `update_translation` - Update existing translation - `export_translations` - Export in multiple formats ### **📊 Statistics & Analytics** - `get_project_stats` - Project statistics - `get_translation_progress` - Progress by language - `compare_languages` - Language comparison analysis ## 🎛️ **Automation Scripts** The project includes a powerful suite of automation scripts accessible through the control center: ```bash python control_center.py <command> ``` ### **📊 Reporting & Analytics** - `daily_report` - Generate comprehensive HTML progress reports - `status` - Check system health and configuration ### **🚨 Monitoring & Alerts** - `monitor` - Scan for translation issues and quality problems - `test` - Run system diagnostics ### **🤖 Automation** - `automate` - AI-powered translation suggestions and consistency checks - `schedule` - Automated task scheduling and execution ### **📈 Optimization** - `optimize` - Workflow analysis with actionable recommendations - `sync` - Synchronize translations between similar projects ### **📦 Export & Integration** - `export` - Mass export in multiple formats (JSON, Android XML, iOS Strings, etc.) - `notify` - Send team notifications via email/Slack ### **🔧 Management** - `setup` - Interactive environment configuration - `demo` - Complete system demonstration ## 📁 **Project Structure** ``` poeditor-mcp/ ├── 📄 README.md # This file ├── 📄 requirements.txt # Python dependencies ├── 📄 .env.template # Environment template ├── 📄 setup.py # Automatic setup script ├── 📄 test_connection.py # Connection test utility ├── 📄 claude_desktop_config_example.json # Claude Desktop config example ├── 📄 vscode_settings_example.json # VS Code config example ├── 📄 CONFIG_README.md # Configuration guide │ ├── 📁 mcp_poeditor/ # Core MCP package │ ├── 📄 __init__.py │ ├── 📄 __main__.py # Entry point │ ├── 📄 server.py # MCP server implementation │ ├── 📄 poeditor_client.py # POEditor API client │ │ │ ├── 📁 tools/ # MCP tools │ │ ├── 📄 projects.py # Project management │ │ ├── 📄 languages.py # Language management │ │ ├── 📄 terms.py # Term management │ │ ├── 📄 translations.py # Translation management │ │ └── 📄 stats.py # Statistics & analytics │ │ │ └── 📁 utils/ # Utilities │ ├── 📄 config.py # Configuration management │ └── 📄 helpers.py # Helper functions │ ├── 📁 scripts/ # 🎛️ AUTOMATION SUITE │ ├── 📄 README.md # Scripts documentation │ ├── 📄 control_center.py # 🎛️ Master control script │ ├── 📄 daily_report.py # 📊 Daily progress reports │ ├── 📄 translation_monitor.py # 🚨 Quality monitoring │ ├── 📄 workflow_optimizer.py # 📈 Workflow optimization │ ├── 📄 project_sync.py # 🔄 Project synchronization │ ├── 📄 notification_manager.py # 📧 Team notifications │ ├── 📄 translation_automator.py # 🤖 AI automation │ ├── 📄 mass_exporter.py # 📦 Multi-format export │ ├── 📄 scheduler.py # 🕒 Task scheduling │ └── 📄 demo_workflow.py # 🎯 Complete demo │ ├── 📁 examples/ # Usage examples │ ├── 📄 basic_usage.py # Basic MCP usage │ ├── 📄 automation_examples.py # Automation examples │ └── 📄 integration_guide.md # Integration guide │ └── 📁 docs/ # Documentation ├── 📄 INSTALLATION.md # Detailed installation ├── 📄 CONFIGURATION.md # Configuration guide ├── 📄 API_REFERENCE.md # API documentation └── 📄 CONTRIBUTING.md # Contribution guidelines ``` ## 🔧 **Configuration** ### **Environment Variables** Create a `.env` file in the root directory: ```env # POEditor API Configuration POEDITOR_API_TOKEN=your_api_token_here POEDITOR_API_URL=https://api.poeditor.com/v2/ # MCP Server Configuration MCP_SERVER_NAME=poeditor-mcp MCP_SERVER_VERSION=1.0.0 # Notification Settings (Optional) 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/... # Automation Settings DEFAULT_EXPORT_FORMAT=json MAX_RETRIES=3 REQUEST_TIMEOUT=30 LOG_LEVEL=INFO ``` ### **Scheduler Configuration** Customize automation schedules in `scripts/scheduler_config.json`: ```json { "schedules": { "daily_report": { "time": "08:00", "enabled": true, "weekdays_only": true, "description": "Generate daily progress report" }, "monitoring": { "time": "09:00", "enabled": true, "weekdays_only": true, "description": "Run translation quality monitoring" }, "weekly_optimization": { "day": "monday", "time": "08:30", "enabled": true, "description": "Weekly workflow optimization analysis" } } } ``` ## 🚀 **Usage Examples** ### **Basic Translation Management** ```python from mcp_poeditor.server import call_tool # List all projects projects = await call_tool("list_projects", {}) # Get project languages languages = await call_tool("list_languages", {"project_id": "123456"}) # Search for specific terms results = await call_tool("search_terms", { "project_id": "123456", "search_query": "login" }) # Export translations export_url = await call_tool("export_translations", { "project_id": "123456", "language_code": "es", "file_format": "json" }) ``` ### **Automation Workflow** ```bash # Morning routine python control_center.py monitor # Check for issues python control_center.py daily_report # Generate progress report # Development workflow python control_center.py automate # Get AI suggestions python control_center.py export # Export for developers # Weekly optimization python control_center.py optimize # Analyze workflow efficiency python control_center.py sync # Sync related projects ``` ### **Integration with CI/CD** ```yaml # GitHub Actions example name: Translation Export on: schedule: - cron: '0 8 * * *' # Daily at 8 AM 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 ``` ## 🔄 **Automated Workflows** ### **Daily Automation** - 🌅 **Morning**: Quality monitoring and progress reports - 🕙 **Midday**: AI-powered translation suggestions - 🌆 **Evening**: Export updates for development teams ### **Weekly Optimization** - 📊 **Monday**: Workflow analysis and optimization recommendations - 🔄 **Wednesday**: Project synchronization and consistency checks - 📦 **Friday**: Complete backup and multi-format export ### **Real-time Monitoring** - 🚨 **Quality alerts**: Fuzzy translations, consistency issues - 📈 **Progress tracking**: Language completion milestones - 👥 **Team notifications**: Slack/email updates for important events ## 🎯 **Supported Export Formats** Perfect for any development workflow: - 📱 **Mobile**: Android XML, iOS Strings, React Native JSON - 🌐 **Web**: JSON, CSV for React/Vue/Angular applications - 🖥️ **Backend**: Gettext PO, Java Properties, YAML - 📊 **Analysis**: Excel XLSX, CSV for progress tracking - 🔄 **Integration**: XLIFF, TMX for CAT tools ## 📚 **Documentation** - [📖 Installation Guide](docs/INSTALLATION.md) - Detailed setup instructions - [⚙️ Configuration Guide](docs/CONFIGURATION.md) - Advanced configuration options - [🔧 API Reference](docs/API_REFERENCE.md) - Complete API documentation - [🚀 Integration Guide](examples/integration_guide.md) - Platform integration examples - [🤝 Contributing](docs/CONTRIBUTING.md) - How to contribute to the project ## 🆘 **Troubleshooting** ### **Common Issues** **Connection Failed** ```bash # Test your POEditor API token python test_connection.py # Check configuration python control_center.py status ``` **Missing Dependencies** ```bash # Reinstall requirements pip install -r requirements.txt # Run system diagnostics python control_center.py test ``` **Permission Errors** ```bash # Fix file permissions chmod +x setup.py chmod +x control_center.py ``` ### **Getting Help** 1. 🔍 **Check logs**: `./logs/` directory contains detailed execution logs 2. 🧪 **Run diagnostics**: `python control_center.py test` 3. 📊 **System status**: `python control_center.py status` 4. 🐛 **Report issues**: Create a GitHub issue with log details ## 🤝 **Contributing** We welcome contributions! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for details on: - 🐛 Reporting bugs - 💡 Suggesting features - 🔧 Submitting pull requests - 📖 Improving documentation ## 📄 **License** This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🌟 **Acknowledgments** - [Model Context Protocol](https://github.com/modelcontextprotocol) for the excellent MCP framework - [POEditor](https://poeditor.com) for their comprehensive translation management API - The open-source community for inspiration and best practices --- **⭐ If this project helps you, please consider giving it a star!** **🚀 Start automating your translation workflow today!**