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

---

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

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

### Quick Install with uv

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

### Using uvx (Run without installing)

```bash
# 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](https://github.com/astral-sh/uv) installed:

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

**macOS / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

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

**Optional - Override the default Gemini model:**

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

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

**Optional - Override the default Gemini model:**

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



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

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

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

**Optional - Override the default Gemini model:**

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

```bash
# 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:**

```bash
# 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-2.5-flash` (default) - Best price-performance
- `gemini-2.5-flash-lite` - Highest rate limits, most cost-efficient
- `gemini-2.5-pro` - Advanced thinking model
- `gemini-1.5-flash` - Widest compatibility for older systems

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

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

```bash
# 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 2.5 Flash Lite (optimized for high throughput and cost efficiency)
- **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](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.

## 🆘 Support

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

## 🙏 Acknowledgments

Built with:
- [Model Context Protocol](https://modelcontextprotocol.io/) - Standard for AI context
- [Google GenAI SDK](https://github.com/googleapis/python-genai) - Official Python SDK
- [MCP Python SDK](https://github.com/jlowin/mcp-python) - 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](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>

For more information about MCP, visit [modelcontextprotocol.io](https://modelcontextprotocol.io/).
