<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.**

---

> **Note (v0.1.8+)**: Previous versions of this README documented incorrect configuration methods that resulted in silent failures. The methods below have been tested and verified. If you previously configured sinhala-mcp using the old instructions, remove the old config and follow the updated steps below.

</div>

## 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 .
```

### Verifying Installation

After installing, verify the server is accessible:

```bash
sinhala-mcp --help
```

If this returns a help message, the package is installed correctly and available on your PATH.

> **Windows users**: If `sinhala-mcp` is not found, the Python Scripts directory may not be on your PATH. The executable is located at `C:\Users\<you>\AppData\Local\Programs\Python\PythonXX\Scripts\sinhala-mcp.exe` where `XX` is your Python version (e.g., `Python313`). See [Troubleshooting](#-troubleshooting) for details.

## 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. Without this key, the server will silently fail to connect — you will see **"Failed to reconnect"** in your MCP client, not a clear error message.

---

### Method 1: Claude Code CLI (Recommended)

The fastest way to add sinhala-mcp to Claude Code:

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

With a specific Gemini model:

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

**What this does**: Writes the server config to `~/.claude.json` under the `mcpServers` key. This is the correct config file for Claude Code — do NOT use `~/.claude/settings.json` (it does not support MCP servers) or `~/.claude/.mcp.json`.

To verify it was added:

```bash
claude mcp list
```

To remove it later:

```bash
claude mcp remove sinhala-mcp
```

#### Manual Claude Code Config

If you prefer to edit the config file directly:

**macOS/Linux**: `~/.claude.json`
**Windows**: `%USERPROFILE%\.claude.json`

Add under the `"mcpServers"` key:

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

> **Windows users**: If `sinhala-mcp` is not on PATH, use the full path:
>
> ```json
> "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\sinhala-mcp.exe"
> ```
>
> Replace `<you>` with your Windows username and `Python313` with your installed Python version.

#### Project-Specific Config

To add sinhala-mcp for a specific project only, navigate to the project directory and run:

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

Or add it manually to the project entry in `~/.claude.json` under `"<project-path>"` → `"mcpServers"`.

---

### Method 2: Claude Desktop

**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.

---

### Method 3: 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"
      ]
    }
  }
}
```

---

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

### "Failed to reconnect" in Claude Code / Claude Desktop

This is the **most common issue** and has two root causes:

1. **Missing `GEMINI_API_KEY`**: The server silently fails to start without the API key. You won't see a clear error — just "Failed to reconnect".
2. **Stale Python path (Windows)**: If you upgraded Python, the `command` path in your config points to the old version (e.g., `Python310` instead of `Python313`). The executable no longer exists at the old path, so the server can't start. This was the primary issue reported by users — **the old documentation did not account for Python version path changes on Windows**.

**Fix**: Ensure both the API key and the correct executable path are set:

```json
{
  "mcpServers": {
    "sinhala-mcp": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\sinhala-mcp.exe",
      "args": [],
      "env": {
        "GEMINI_API_KEY": "your-actual-key-here"
      }
    }
  }
}
```

> **Windows**: Always verify the path exists. Run `where sinhala-mcp` in terminal to find the correct path. If you upgraded Python, the old path won't work — see [Python version path changes](#python-version-path-changes-windows) below.

After updating the config, restart Claude Code / Claude Desktop.

### "sinhala-mcp" command not found

**Cause**: The Python Scripts directory is not on your system PATH, or the package was installed under a different Python version.

**Fix (Windows)**: Use the full path to the executable:

```
C:\Users\<you>\AppData\Local\Programs\Python\PythonXX\Scripts\sinhala-mcp.exe
```

Replace `<you>` with your username and `XX` with your Python version folder (e.g., `Python313`).

**Fix (macOS/Linux)**: Find the executable path:

```bash
which sinhala-mcp
# or
python -c "import shutil; print(shutil.which('sinhala-mcp'))"
```

Use the full path in your MCP config if needed.

### Python version path changes (Windows)

**This is the #1 cause of "Failed to reconnect" on Windows.**

When you upgrade Python (e.g., 3.10 → 3.13), pip installs packages into the new version's Scripts directory. The old executable path becomes invalid:

```
Python 3.10: C:\...\Python310\Scripts\sinhala-mcp.exe
Python 3.13: C:\...\Python313\Scripts\sinhala-mcp.exe
```

If your MCP config points to the old path, the server won't start. Reinstall the package on the new Python version and update the path in your config:

```bash
# Reinstall on new Python
pip install sinhala-mcp

# Update config with new path
claude mcp remove sinhala-mcp
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -- "C:\Users\<you>\AppData\Local\Programs\Python\Python313\Scripts\sinhala-mcp.exe"
```

### VS Code Compatibility Issues

- 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

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

### Wrong config file location (Claude Code)

Claude Code reads MCP servers from `~/.claude.json` (the `"mcpServers"` key at the top level), **not** from:

- `~/.claude/settings.json` — this file only holds settings like env vars and plugins, not MCP servers
- `~/.claude/.mcp.json` — this is not a valid Claude Code config location
- `.claude/settings.local.json` — this only holds per-project permissions

Use `claude mcp add` to add servers correctly, or edit `~/.claude.json` directly.

## 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.thamindu.zynthlab.com](https://www.thamindu.zynthlab.com)
- **GitHub**: [Thamindu-Dev](https://github.com/Thamindu-Dev)

---

**Made in Sri Lanka, for Sinhala developers worldwide**