# Riyadh Districts MCP Server

An MCP (Model Context Protocol) server that provides tools for finding distances between districts in Riyadh, Saudi Arabia.

## Features

- **192 Riyadh districts** with coordinates
- **Arabic & English** name support with normalization
- **5 MCP tools** for querying district data
- Distance calculation using **Haversine formula**

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_nearest_districts` | Get top N nearest districts to a given district |
| `get_distance_between_districts` | Calculate distance (km) between two districts |
| `list_all_districts` | List all available Riyadh districts |
| `search_districts` | Search districts by partial name (Arabic/English) |
| `get_district_info` | Get district details including coordinates |

## Installation

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/riyadh-districts-mcp.git
cd riyadh-districts-mcp

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

## Usage

### As MCP Server (for Cursor/Claude)

Add to your MCP configuration (`.cursor/mcp.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "riyadh-districts": {
      "command": "/path/to/project/.venv/bin/python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/project"
    }
  }
}
```

### As HTTP Server

```bash
source .venv/bin/activate
uvicorn src.main:app --host 0.0.0.0 --port 4501 --reload
```

Health check: `http://localhost:4501/health`

### CLI Usage (Legacy)

```bash
python main.py "Al Olaya" --top 10
python main.py --distance "Al Olaya" "Al Yasmin"
python main.py --list
```

## Data Source

District data sourced from [alioh/Saudi-Districts-Dataset](https://github.com/alioh/Saudi-Districts-Dataset).

## License

MIT