Metadata-Version: 2.4
Name: sinhala-mcp
Version: 0.1.7
Summary: MCP server for translating Sinhala/Singlish commands into English technical prompts
Project-URL: Homepage, https://github.com/Thamindu-Dev/sinhala-mcp
Project-URL: Repository, https://github.com/Thamindu-Dev/sinhala-mcp
Project-URL: Issues, https://github.com/Thamindu-Dev/sinhala-mcp/issues
Author: Thamindu Hatharasinghe
License: MIT
License-File: LICENSE
Keywords: ai,gemini,mcp,sinhala,translation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: mcp>=0.9.0
Description-Content-Type: text/markdown

<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

# Run automatic setup (creates VS Code config)
sinhala-mcp-setup
```

### Quick Install with uv

```bash
uv pip install sinhala-mcp

# Run automatic setup
sinhala-mcp-setup
```

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

### Manual Installation from Source

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

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

# Install in editable mode
pip install -e .

# Run automatic setup
sinhala-mcp-setup

# Or using uv
uv pip install -e .
sinhala-mcp-setup
```

**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
- ✅ Automatic VS Code configuration with `sinhala-mcp-setup`

### Command-Line Installation for CLI Tools

**For Claude Code CLI:**

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

**⚡ Automatic VS Code Setup:**

After installing, simply run:
```bash
sinhala-mcp-setup
```

This command automatically:
- ✅ Creates `.vscode/settings.json` in your project
- ✅ Configures model sampling for sinhala-mcp
- ✅ Sets up all required permissions

No manual configuration needed!

#### Manual Setup for Antigravity IDE & Other IDEs

**For IDEs that don't support pip installation (v0.1.7+):**

If your IDE cannot install packages via pip, follow these manual setup steps:

**Step 1: Clone the repository**
```bash
git clone https://github.com/Thamindu-Dev/sinhala-mcp.git
cd sinhala-mcp
```

**Step 2: Create `.vscode/mp.json` in your project root**

Create a file named `.vscode/mp.json` with the following configuration:

```json
{
    "servers": {
        "sinhala-mcp": {
            "command": "uvx",
            "args": [
                "sinhala-mcp==0.1.7"
            ],
            "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-lite"
        }
    ]
}
```

**Step 3: Configure VS Code settings for model sampling**

Create or update `.vscode/settings.json` with:

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

**Note:** Using `uvx sinhala-mcp==0.1.7` will automatically download the package from PyPI without requiring local pip installation.

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

```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 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](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:
      ```bash
      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:
      ```json
      {
        "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](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/).
