README.md•17.5 kB
# 🌐 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!**