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

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

pip install sinhala-mcp

Or with uv:

uv pip install sinhala-mcp

Manual Installation from Source

If you encounter issues with PyPI installation:

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:

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 for details.

Configuration

Step 1: Get a Google Gemini API Key

1. Visit Google AI Studio
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:

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

With a specific Gemini model:

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:

claude mcp list

To remove it later:

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:

{
  "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:

"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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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

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

{
  "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 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:

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:

# 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
• MCP Protocol: modelcontextprotocol.io

Contributing

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

License

MIT License — see 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
• GitHub: Thamindu-Dev

---

Made in Sri Lanka, for Sinhala developers worldwide