r-pedraza/poeditor-mcp

🌐 POEditor MCP Server

A comprehensive Model Context Protocol (MCP) server for POEditor translation management, featuring advanced automation scripts and workflow optimization tools.

🚀 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

📋 Quick Start

1. Automatic Setup (Recommended)

# 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

# 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

# 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

{
  "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

{
  "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:

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:

# 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:

{
  "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

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

# 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

# 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

• - Detailed setup instructions
• - Advanced configuration options
• - Complete API documentation
• - Platform integration examples
• - How to contribute to the project

🆘 Troubleshooting

Common Issues

Connection Failed

# Test your POEditor API token
python test_connection.py

# Check configuration
python control_center.py status

Missing Dependencies

# Reinstall requirements
pip install -r requirements.txt

# Run system diagnostics
python control_center.py test

Permission Errors

# 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 for details on:

• 🐛 Reporting bugs
• 💡 Suggesting features
• 🔧 Submitting pull requests
• 📖 Improving documentation

📄 License

This project is licensed under the MIT License - see the file for details.

🌟 Acknowledgments

• Model Context Protocol for the excellent MCP framework
• POEditor 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!