<div align="center">

# 🇱🇰 sinhala-mcp

### **🚀 Sri Lanka's First AI-Powered MCP Server for Sinhala Developers**

**Break the language barrier. Code in your mother tongue.**

[![PyPI Version](https://img.shields.io/pypi/v/sinhala-mcp?color=blue&label=PyPI)](https://pypi.org/project/sinhala-mcp/)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange)](https://modelcontextprotocol.io/)
[![Made in Sri Lanka](https://img.shields.io/badge/Made%20in-Sri%20Lanka-red)](https://github.com/Thamindu-Dev/sinhala-mcp)

**A production-ready Model Context Protocol server that translates Sinhala/Singlish instructions into precise English technical specifications using Google Gemini AI.**

</div>

---

## ⚠️ Compatibility Notice

**VS Code MCP Extension**: This tool may experience compatibility issues with some VS Code MCP extensions due to model validation restrictions. We are actively working on improvements to enhance compatibility. For the best experience, consider using Claude Desktop or Claude Code CLI.

---

## 🌟 Why sinhala-mcp?

As the **first of its kind in Sri Lanka**, `sinhala-mcp` empowers Sinhala-speaking developers to:

- 💬 **Code naturally** in your preferred language (Sinhala or Singlish)
- 🎯 **Get precise technical translations** optimized for AI coding agents
- 🚀 **Boost productivity** by removing language friction from development workflows
- 🔥 **Stay ahead** with cutting-edge AI integration via Google's Gemini

## ✨ Features

- 🌍 **Sinhala/Singlish Translation**: Convert colloquial commands into structured English technical specifications
- 🧠 **Context-Aware**: Automatically infers technical context (e.g., "Login" → "Authentication flow")
- 🔒 **Environment Variable Auth**: Secure API key management via environment variables
- 🚀 **Production-Ready**: Comprehensive error handling, retry logic, timeout protection, input validation, and health checks
- 📦 **MCP Compliant**: Works with Claude Desktop, VS Code, Claude Code CLI, and other MCP-compatible tools
- 🎯 **Latest AI**: Uses Google GenAI SDK with Gemini models (supports 1.5-flash, 2.5-flash, 2.5-flash-lite, 2.5-pro)

## 📦 Installation

```bash
pip install sinhala-mcp
```

Or with uv:

```bash
uv pip install sinhala-mcp
```

### Manual Installation from Source

If you encounter issues with PyPI installation:

```bash
git clone https://github.com/Thamindu-Dev/sinhala-mcp.git
cd sinhala-mcp
pip install -e .
```

## 🔑 Configuration

### Step 1: Get a Google Gemini API Key

1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
2. Create a new API key
3. Keep it secure - never commit it to version control

### Step 2: Configure Your MCP Client

**IMPORTANT**: The server reads the API key from the `GEMINI_API_KEY` environment variable.

---

### Method 1: Claude Desktop / Claude Code

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

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

```json
{
  "mcpServers": {
    "sinhala-mcp": {
      "type": "stdio",
      "command": "sinhala-mcp",
      "args": [],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Optional**: Override the default model by adding `"GEMINI_MODEL": "gemini-2.5-flash-lite"` to env.

**Available models**: `gemini-2.5-flash` (default), `gemini-2.5-flash-lite`, `gemini-2.5-pro`, `gemini-1.5-flash`

---

### Method 2: VS Code MCP Extension

Create or update `.vscode/settings.json`:

```json
{
  "mcp.servers": {
    "sinhala-mcp": {
      "command": "sinhala-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

For advanced configuration with model sampling, create `.vscode/mcp.json`:

```json
{
  "servers": {
    "sinhala-mcp": {
      "command": "uvx",
      "args": ["sinhala-mcp"],
      "env": {
        "GEMINI_API_KEY": "${input:gemini_api_key}",
        "GEMINI_MODEL": "${input:gemini_model}"
      },
      "type": "stdio"
    }
  },
  "inputs": [
    {
      "id": "gemini_api_key",
      "type": "promptString",
      "description": "Google Gemini API Key",
      "default": ""
    },
    {
      "id": "gemini_model",
      "type": "promptString",
      "description": "Gemini Model (optional)",
      "default": "gemini-2.5-flash"
    }
  ]
}
```

Then update `.vscode/settings.json` for model sampling:

```json
{
  "chat.mcp.serverSampling": {
    "sinhala-mcp/.vscode/mcp.json: sinhala-mcp": {
      "allowedModels": [
        "copilot/auto",
        "gemini-1.5-flash",
        "gemini-2.5-flash",
        "gemini-2.5-flash-lite",
        "gemini-2.5-pro"
      ]
    }
  }
}
```

---

### Method 3: Command-Line Installation

Quick setup via command line:

```bash
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -- sinhala-mcp
```

Or with model override:

```bash
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -e GEMINI_MODEL=gemini-2.5-flash-lite -- sinhala-mcp
```

---

### Method 4: Project-Specific Configuration

For project-specific MCP server configuration, add to your Claude config:

```json
{
  "M:/Projects/your-project": {
    "allowedTools": [],
    "mcpContextUris": [],
    "mcpServers": {
      "sinhala-mcp": {
        "type": "stdio",
        "command": "sinhala-mcp",
        "args": [],
        "env": {
          "GEMINI_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}
```

Replace `M:/Projects/your-project` with your actual project path.

---

## 🛠️ Available Tools

### translate_sinhala_instruction

Translates Sinhala or Singlish instructions into precise English technical prompts.

**Usage:**
```
Use translate_sinhala_instruction to translate "mata login form ekak hadanna one"
```

**Parameters:**
- `instruction` (string, required): The Sinhala or Singlish instruction (max 5000 characters)

**Example Output:**
```
Original (Sinhala/Singlish):
mata login page ekak hadanna one

Translated (English Technical Prompt):
Implement a user authentication system with login functionality including:
- Username/email and password input fields
- Form validation for credentials
- Authentication endpoint integration
- Session management after successful login
- Error handling for failed authentication attempts
```

### health_check

Check if the MCP server and Gemini API connection are working.

**Usage:**
```
Run health_check
```

## 💡 Usage Examples

### Web Development

**Input:** "Mata dashboard ekak denna user stats display karanna"

**Output:**
```
Create a user analytics dashboard with:
- Real-time user statistics display
- Data visualization charts
- Filtering and search capabilities
- Responsive layout for mobile/desktop
- Authentication-protected access
```

### Backend Development

**Input:** "Database eka connect karanna API endpoint ekak hadala denna"

**Output:**
```
Implement database integration with REST API:
- Set up database connection pool
- Create CRUD endpoints for data access
- Implement proper error handling
- Add data validation and sanitization
- Include authentication/authorization middleware
```

### Frontend Features

**Input:** "Profile page eke photo upload eka hadanna"

**Output:**
```
Implement profile photo upload feature:
- File upload input with image type validation
- Client-side image preview
- Size and format restrictions
- Upload progress indicator
- Server-side file storage integration
- Error handling for upload failures
```

## 🏗️ Development

```bash
# Clone the repository
git clone https://github.com/Thamindu-Dev/sinhala-mcp.git
cd sinhala-mcp

# Install in editable mode
pip install -e .

# Test server
python test_simple.py
```

### Project Structure

```
sinhala-mcp/
├── src/
│   └── sinhala_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml              # Package configuration
├── README.md
└── LICENSE
```

## 🔒 Security

- ✅ API keys stored in environment variables only
- ✅ No local file storage of credentials
- ✅ Input validation and sanitization
- ✅ Protection against injection attacks
- ✅ Rate limit handling
- ✅ Open source - fully auditable

## 📊 Technical Specifications

- **Build Backend**: hatchling
- **Python Version**: 3.10+ (tested on 3.10-3.13)
- **Dependencies**: `mcp>=0.9.0`, `google-genai>=1.0.0`, `google-api-core>=1.0.0`
- **Default Model**: `gemini-2.5-flash`
- **Supported Models**: `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.5-pro`, `gemini-1.5-flash`
- **Max Instruction Length**: 5000 characters
- **API Timeout**: 30 seconds
- **Retry Logic**: 2 retries with exponential backoff

## 🔧 Troubleshooting

### "GEMINI_API_KEY not found" Error
- Ensure the key is added to your MCP client configuration
- Restart your MCP client after updating configuration

### VS Code Compatibility Issues
- **See compatibility notice above** - Some VS Code MCP extensions have model validation restrictions
- **Workaround**: Set `GEMINI_MODEL=gemini-1.5-flash` in your configuration for better compatibility
- **Important**: After changing `GEMINI_MODEL`, restart your MCP client for changes to take effect
- **Alternative**: Use Claude Desktop or Claude Code CLI for better compatibility
- Future updates will improve VS Code extension compatibility

### Model Changes Not Taking Effect
- **Issue**: Setting `GEMINI_MODEL` doesn't change the model being used
- **Solution**: Restart your MCP client (Claude Desktop, VS Code) after modifying environment variables
- **Verify**: Check MCP server logs for "Using Gemini model: ..." message on startup

### Translation Issues
- The model may block content due to safety settings
- Try rephrasing the instruction

## 🆘 Support

- **Report Issues**: [GitHub Issues](https://github.com/Thamindu-Dev/sinhala-mcp/issues)
- **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)

## 🤝 Contributing

Contributions are welcome! Fork the repository, create a feature branch, and submit a Pull Request.

## 📝 License

MIT License - see [LICENSE](LICENSE) for details.

## 👨‍💻 About the Developer

**sinhala-mcp** was created by **Thamindu Hatharasinghe** — a passionate Sri Lankan developer dedicated to breaking language barriers in technology.

As **Sri Lanka's first Sinhala-to-English technical translation tool for developers**, this project represents a milestone in making AI-assisted development accessible to Sinhala-speaking developers worldwide.

- 🌐 **Portfolio**: [www.thamidu.me](https://www.thamidu.me)
- 🐙 **GitHub**: [Thamindu-Dev](https://github.com/Thamindu-Dev)

---

<div align="center">

**Made with ❤️ in Sri Lanka, for Sinhala developers worldwide**

**⭐ If you find this project helpful, please consider giving it a star on GitHub!**

</div>
