# 🌐 POEditor MCP Server

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

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/r-pedraza/poeditor-mcp)](https://github.com/r-pedraza/poeditor-mcp/releases)
[![Python](https://img.shields.io/badge/Python-3.8+-3776ab?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/r-pedraza/poeditor-mcp?style=social)](https://github.com/r-pedraza/poeditor-mcp/stargazers)

[![MCP Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue?logo=openai&logoColor=white)](https://github.com/modelcontextprotocol)
[![POEditor API](https://img.shields.io/badge/POEditor-API%20Integration-orange?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTEyIDJMMTMuMDkgOC4yNkwyMCA5TDEzLjA5IDE1Ljc0TDEyIDIyTDEwLjkxIDE1Ljc0TDQgOUwxMC45MSA4LjI2TDEyIDJaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K)](https://poeditor.com/)
[![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-Compatible-8A2BE2?logo=anthropic&logoColor=white)](https://claude.ai/)
[![VS Code](https://img.shields.io/badge/VS%20Code-Compatible-007ACC?logo=visual-studio-code&logoColor=white)](https://code.visualstudio.com/)

[![GitHub issues](https://img.shields.io/github/issues/r-pedraza/poeditor-mcp)](https://github.com/r-pedraza/poeditor-mcp/issues)
[![GitHub pull requests](https://img.shields.io/github/issues-pr/r-pedraza/poeditor-mcp)](https://github.com/r-pedraza/poeditor-mcp/pulls)
[![GitHub last commit](https://img.shields.io/github/last-commit/r-pedraza/poeditor-mcp)](https://github.com/r-pedraza/poeditor-mcp/commits/main)
[![GitHub repo size](https://img.shields.io/github/repo-size/r-pedraza/poeditor-mcp)](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**

[![Development Status](https://img.shields.io/badge/Development%20Status-Stable-brightgreen)](https://github.com/r-pedraza/poeditor-mcp)
[![Maintenance](https://img.shields.io/badge/Maintained-Yes-green)](https://github.com/r-pedraza/poeditor-mcp/commits/main)
[![API Coverage](https://img.shields.io/badge/POEditor%20API%20Coverage-100%25-success)](https://poeditor.com/docs/api)
[![Documentation](https://img.shields.io/badge/Documentation-Complete-blue)](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!**