sinhala-mcp 0.1.8

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.

---

⚠️ 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

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 .

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

---

Method 1: Claude Desktop / Claude Code

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.

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:

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

---

Method 3: Command-Line Installation

Quick setup via command line:

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

Or with model override:

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:

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

# 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
• 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.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!