sinhala-mcp 0.1.6

MCP server for translating Sinhala/Singlish commands into English technical prompts

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

---

🌟 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 2.5 Flash Lite

✨ 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 and logging
  • Retry logic for API failures
  • Timeout protection (30s default)
  • Input validation and sanitization
  • Health check endpoint for monitoring
  • Rate limit handling
• 📦 MCP Compliant: Works with Claude Desktop, VS Code MCP client, and other MCP-compatible tools
• 🎯 Latest AI: Uses Google GenAI SDK with Gemini 2.5 Flash Lite (optimized for high throughput)

📦 Installation

Quick Install with pip (Recommended)

pip install sinhala-mcp

Quick Install with uv

uv pip install sinhala-mcp

Using uvx (Run without installing)

# Just run it directly - no installation needed!
uvx sinhala-mcp

Prerequisites for uvx

If you want to use uvx to run without installing, you need uv installed:

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Manual Installation from Source

If you encounter issues with PyPI installation (especially "model not found" errors in VS Code), install directly from source:

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

# Install in editable mode
pip install -e .

# Or using uv
uv pip install -e .

Benefits of manual installation:

• ✅ Bypasses PyPI validation issues
• ✅ Always uses the latest code from the repository
• ✅ No waiting for PyPI updates
• ✅ Works with VS Code MCP extension

Command-Line Installation for CLI Tools

For Claude Code CLI:

# Option 1: Install from PyPI
pip install sinhala-mcp
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -- sinhala-mcp

# Option 2: Manual installation from source
cd sinhala-mcp
pip install -e .
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -- sinhala-mcp

# Option 3: Use uvx (no installation needed)
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -- uvx sinhala-mcp

For other MCP-compatible CLI tools: Replace claude mcp add with the appropriate command for your CLI tool.

🔑 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. Do not use the old set_gemini_key tool - it has been removed for security and store compatibility.

Claude Desktop Configuration

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

Windows: %APPDATA%\Roaming\claude-code\mcp_settings.json or %APPDATA%\claude-code\claude_desktop_config.json

{
  "mcpServers": {
    "sinhala-mcp": {
      "command": "sinhala-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Optional - Override the default Gemini model:

{
  "mcpServers": {
    "sinhala-mcp": {
      "command": "sinhala-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "GEMINI_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

Note: If you installed with pip, use "command": "sinhala-mcp". If using uvx without installing, use "command": "uvx", "args": ["sinhala-mcp"].

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

VS Code MCP Extension

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

Optional - Override the default Gemini model:

{
  "mcp.servers": {
    "sinhala-mcp": {
      "command": "sinhala-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "GEMINI_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

Note: If you installed with pip, use "command": "sinhala-mcp". If using uvx without installing, use "command": "uvx", "args": ["sinhala-mcp"].

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

⚠️ Important - VS Code Model Sampling Configuration:

VS Code requires you to configure allowed models before installing the MCP server. Follow these steps in order:

Step 1 - Setup VS Code Configuration (Choose one option):

Option 1 - Automatic Setup (Recommended):

# Run this in your project root BEFORE installing MCP:
cd your-project-folder
python setup_vscode.py

This script automatically creates .vscode/settings.json with the required model sampling configuration.

Option 2 - Manual Setup: Create .vscode/settings.json in your project root with:

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

Claude Code CLI

The Claude Code CLI reads the configuration from mcp_settings.json:

Windows: %APPDATA%\Roaming\claude-code\mcp_settings.json macOS / Linux: ~/.config/claude-code/mcp_settings.json

{
  "mcpServers": {
    "sinhala-mcp": {
      "command": "python",
      "args": ["-m", "sinhala_mcp.server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or if you installed the package:

{
  "mcpServers": {
    "sinhala-mcp": {
      "command": "sinhala-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Optional - Override the default Gemini model:

{
  "mcpServers": {
    "sinhala-mcp": {
      "command": "python",
      "args": ["-m", "sinhala_mcp.server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "GEMINI_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

After updating the configuration, restart the Claude Code CLI to load the MCP server.

Command Line / Development

# Linux/macOS
export GEMINI_API_KEY="your-api-key-here"

# Windows CMD
set GEMINI_API_KEY=your-api-key-here

# Windows PowerShell
$env:GEMINI_API_KEY="your-api-key-here"

Optional - Override the default Gemini model:

# Linux/macOS
export GEMINI_MODEL="gemini-2.5-flash-lite"

# Windows CMD
set GEMINI_MODEL=gemini-2.5-flash-lite

# Windows PowerShell
$env:GEMINI_MODEL="gemini-2.5-flash-lite"

Available models:

• gemini-1.5-flash (default) - Best VS Code compatibility
• gemini-2.5-flash-lite - Highest rate limits, most cost-efficient (override with GEMINI_MODEL)
• gemini-2.5-flash - Best price-performance (override with GEMINI_MODEL)
• gemini-2.5-pro - Advanced thinking model (override with GEMINI_MODEL)

Note: VS Code users can override to newer models by setting GEMINI_MODEL environment variable.

🛠️ Available Tools

How to Use

This MCP server translates your Sinhala/Singlish instructions into English technical prompts. You need to explicitly request the translation tool.

To translate:

• Say: "Use translate_sinhala_instruction to translate: [your Sinhala text]"
• Or: "Translate using sinhala-mcp: [your instruction]"
• Or: "MCP: translate_sinhala_instruction [your text]"

Example:

You: Use translate_sinhala_instruction to translate "mata login form ekak hadanna one"

Claude: [Original: mama login ekak hadanna one
         Translated: Implement a user authentication system with login functionality...]

1. translate_sinhala_instruction

Translates Sinhala or Singlish instructions into precise English technical prompts.

Parameters:

• instruction (string, required): The Sinhala or Singlish instruction to translate (max 5000 characters)

Example:

Translate "mata login page ekak hadanna one" using translate_sinhala_instruction

Output:

Original (Sinhala/Singlish):
mama login 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

2. health_check

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

Parameters: None

Example:

Run health_check

Output:

Health Check: PASSED
Server: sinhala-mcp v0.1.0
API Connection: Active
Timestamp: 2025-01-26T12:00:00.000000

💡 Usage Examples

Example 1: Web Development

Input (Sinhala):

"Mata dashboard ekak denna user stats display karanna example ekka"

Translated 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

Example 2: Backend Development

Input (Sinhala):

"Database eka connect karanna API endpoint ekak hadala denna"

Translated 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

Example 3: Frontend Features

Input (Sinhala):

"Profile page eke photo upload eka hadanna"

Translated 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

🎯 Real-World Example (Actual Output)

Here's an actual translation from the tool in action:

Input (Sinhala):

"mata dn ona me tool eka pypi ekata dala uvx wage commands walin quick install karanna puluwn wenna hadanna. wade karala dennako. readme.md ekath update karanna."

Translated Output:

1.  **Package for PyPI:**
    *   Structure the project as a Python package with a `setup.py` or `pyproject.toml` file.
    *   Define package metadata including name, version, author, description, and dependencies.
    *   Ensure the package is installable via `pip install <package-name>`.
2.  **Command-Line Interface (CLI) Integration:**
    *   Implement a CLI entry point using a library like `click` or `argparse`.
    *   Register the CLI command (e.g., `uvx`) in the package setup to be available after installation.
    *   Define subcommands and arguments for the CLI based on the tool's functionality.
3.  **README.md Update:**
    *   Add a comprehensive "Installation" section detailing how to install the package using pip.
    *   Include instructions on how to run the CLI commands (e.g., `uvx <command> [options]`).
    *   Update other relevant sections (e.g., Usage, Features) to reflect the CLI integration.
4.  **Testing:**
    *   Develop unit and integration tests for the CLI functionality.
    *   Ensure tests cover installation, command execution, and argument parsing.
5.  **Deployment to PyPI:**
    *   Build the package distribution files (sdist and wheel).
    *   Upload the package to the Python Package Index (PyPI) using `twine`.

This real example demonstrates how sinhala-mcp transformed a complex Sinhala instruction into a structured, actionable technical specification that was directly used to package this project for PyPI distribution!

🏗️ Development

Setup Development Environment

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

# Install dependencies
pip install -e .

# Or using uv
uv pip install -e .

Running Tests

# Test server import
python test_simple.py

# Run with verbose logging
LOGLEVEL=DEBUG python -m sinhala_mcp.server

Project Structure

sinhala-mcp/
├── src/
│   └── sinhala_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml              # Package configuration
├── smithery.yaml              # Store publishing configuration
├── README.md                  # This file
└── LICENSE                    # MIT 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
• Package Layout: Modern src/ layout
• Python Version: 3.10+ (tested on 3.10-3.13)
• Dependencies:
  • mcp>=0.9.0 - Model Context Protocol SDK
  • google-genai>=1.0.0 - Official Google GenAI SDK (GA)
• AI Model: Gemini 1.5 Flash (default, VS Code compatible) - Supports all 2.x models via GEMINI_MODEL override
• Max Instruction Length: 5000 characters
• API Timeout: 30 seconds
• Retry Logic: 2 retries with exponential backoff

🚀 Production Deployment

The server is production-ready with:

• Structured Logging: Timestamped logs for debugging
• Error Handling: Graceful failure with user-friendly messages
• Health Checks: Monitor API connectivity
• Timeout Protection: Prevents hanging requests
• Retry Logic: Handles transient API failures
• Input Validation: Prevents abuse and injection attacks

📚 Architecture

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│ User (Sinhala)  │─────>│  MCP Server      │─────>│ Google Gemini   │
│ "mama login eka │      │  (translate_     │      │ AI API          │
│  karanna one"   │      │   sinhala_       │      │                 │
└─────────────────┘      └──────────────────┘      └─────────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ English Output   │
                         │ "Implement user  │
                         │  authentication │
                         │  with login form"│
                         └──────────────────┘

🤝 Contributing

Contributions are welcome! Please feel free to:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a Pull Request

📝 License

MIT License - see LICENSE for details.

🔧 Troubleshooting

Common Issues

1. "GEMINI_API_KEY not found" Error

   • Ensure you have added the key to your configuration file (Claude Desktop or VS Code).
   • If using the terminal, ensure you ran export GEMINI_API_KEY=... (Mac/Linux) or $env:GEMINI_API_KEY=... (Windows).
   • Restart your MCP client after changing the configuration.

2. Connection Refused / Server Error

   • Check if you have the latest version installed: uv tool upgrade sinhala-mcp
   • Verify your internet connection (Google Gemini API requires internet access).

3. Translation is empty or incorrect

   • The model might have blocked the content due to safety settings. Try rephrasing the instruction.

4. "Model not supported" or "Model not found" Error in VS Code

   • Cause: VS Code's MCP extension validates model names and may reject newer models.
   • Solution 1 - Manual Installation: Install from source instead of PyPI:

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

   • Solution 2 - Use Compatible Configuration: Ensure your VS Code settings.json uses the installed command:

     {
       "mcp.servers": {
         "sinhala-mcp": {
           "command": "sinhala-mcp",
           "env": {
             "GEMINI_API_KEY": "your-api-key-here",
             "GEMINI_MODEL": "gemini-1.5-flash"
           }
         }
       }
     }
     

   • Solution 3 - Override to Newer Model: After successful installation, add GEMINI_MODEL environment variable to use newer models like gemini-2.5-flash-lite for better rate limits.

🆘 Support

• Report Issues: GitHub Issues
• Documentation: This README
• MCP Protocol: modelcontextprotocol.io

🙏 Acknowledgments

Built with:

• Model Context Protocol - Standard for AI context
• Google GenAI SDK - Official Python SDK
• MCP Python SDK - MCP implementation

👨‍💻 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
• 🐙 GitHub: Thamindu-Dev

---

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

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

For more information about MCP, visit modelcontextprotocol.io.