# 🌍 MCP-Localization-Engine

**Global localization data for 174 locales via MCP (Model Context Protocol)**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

## 🎯 What is this?

A Model Context Protocol (MCP) server that provides comprehensive localization data for 174 locales worldwide. Perfect for AI agents and applications that need to generate culturally-adapted multilingual content.

## ✨ Features

- **174 Locales**: Complete coverage across Europe, Asia, Americas, Middle East, Africa, and Oceania
- **3 MCP Tools**:
  - `get_locale_config`: Technical metadata (timezone, currency, script, etc.)
  - `get_cultural_data`: Cultural adaptation data (values, tone, references)
  - `get_rules`: Global rules (slug generation, SEO, content adaptation)
- **Smart Caching**: 24-hour TTL with 98% hit rate
- **Fast**: 2-5ms response time (cached), 50ms (cold)
- **Production Ready**: Validated schemas, error handling, comprehensive tests

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/supernovae/mcp-localization-engine.git
cd mcp-localization-engine

# Install dependencies
pip install -r requirements.txt

# Verify installation
python src/server.py --version
```

### Running the MCP Server

```bash
# Start the server
python src/server.py

# Output:
# 🚀 MCP-Localization-Engine v1.0.0
# 📂 Loaded 174 locales
# 💾 Cache initialized (TTL: 24h)
# ✅ Server ready on stdio
```

### Configure with Claude Desktop

**macOS:**
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Linux:**
```bash
nano ~/.config/Claude/claude_desktop_config.json
```

**Windows:**
```
notepad %APPDATA%\Claude\claude_desktop_config.json
```

**Add this configuration:**
```json
{
  "mcpServers": {
    "localization": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/mcp-localization-engine/src/server.py"]
    }
  }
}
```

⚠️ **Replace `/ABSOLUTE/PATH/TO/` with your actual path!**

**Restart Claude Desktop** to load the configuration.

### Test in Claude

Open Claude and try:

```
"Use the localization MCP to get the configuration for French (France)"
```

Claude should call `get_locale_config("fr-FR")` and return technical data!

## 📚 Documentation

- **[Complete Documentation](docs/)** - Full guides in `docs/` folder
- **[Architecture](docs/ARCHITECTURE.md)** - System architecture
- **[MCP Tools](docs/MCP_TOOLS.md)** - Detailed tool documentation
- **[Quick Start](docs/QUICK_START.md)** - 10-minute setup guide
- **[Development](docs/DEVELOPMENT.md)** - Contributing guide

## 🔧 Usage Example

```python
from src.loader import load_locale_config, load_cultural_data

# Get technical config
config = load_locale_config("ja-JP")
print(config["timezone"])    # "Asia/Tokyo"
print(config["currency"])    # "JPY"
print(config["script"])      # "CJK"

# Get cultural data
cultural = load_cultural_data("ja-JP")
print(cultural["cultural_values"])  # ["Harmony (和)", "Respect for hierarchy", ...]
print(cultural["tone_preferences"]["business"])  # "Formal, polite, humble"
```

## 🌍 Supported Locales

**174 locales** across:
- 🇪🇺 Europe: 75 locales
- 🌏 Asia: 45 locales
- 🌎 Americas: 20 locales
- 🌍 Middle East: 20 locales
- 🌍 Africa: 9 locales
- 🇦🇺 Oceania: 5 locales

[View complete list →](docs/DATA_STRUCTURE.md#supported-locales)

## 🧪 Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Validate all locale data
python tests/validate_data.py

# Run specific test
pytest tests/test_tools.py -v
```

## 🛠️ Development

```bash
# Install dev dependencies
pip install -r requirements-dev.txt

# Generate a new locale template
python scripts/generate_locale.py pt-BR

# List all locales
python scripts/list_locales.py

# Benchmark performance
python scripts/benchmark.py
```

## 📊 Project Stats

- **Code**: ~1,000 lines of Python
- **Data**: ~4.5 MB (174 configs + 174 culturals + 3 rules)
- **Tests**: 20+ test cases
- **Cache Hit Rate**: 98%
- **Response Time**: 2-5ms (cached), 50ms (cold)

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Adding a New Locale

1. Generate template: `python scripts/generate_locale.py xx-YY`
2. Fill in the data in `data/locales/config/xx-YY.json` and `data/locales/cultural/xx-YY.json`
3. Validate: `python tests/validate_data.py --locale xx-YY`
4. Submit PR

## 📄 License

MIT License - see [LICENSE](LICENSE)

## 🔗 Links

- [GitHub Repository](https://github.com/supernovae/mcp-localization-engine)
- [Documentation](docs/)
- [Issues](https://github.com/supernovae/mcp-localization-engine/issues)
- [MCP Protocol](https://modelcontextprotocol.io/)

## 💡 Use Cases

- **Content Generation**: Generate culturally-adapted marketing content
- **SEO Optimization**: Get locale-specific SEO rules
- **URL Generation**: Generate proper slugs per locale
- **Cultural Adaptation**: Avoid cultural faux-pas
- **Multi-project**: Shared foundation for all your localization needs

## 🏢 Built by SuperNovae Studio

Made with ❤️ for the global developer community.

---

**Questions?** Open an [issue](https://github.com/supernovae/mcp-localization-engine/issues) or check the [docs](docs/)!