# MapmyIndia (Mappls) MCP Server (FastMCP)

A high-performance Model Context Protocol (MCP) server for **MapmyIndia (Mappls) REST APIs**, built using the **FastMCP** open-source framework.

This server enables AI assistants (such as Claude, Gemini, ChatGPT, Cursor, and Antigravity) to query geographic data, perform geocoding, generate driving & walking directions, calculate distance matrix ETAs, discover points of interest (POIs), and look up eLoc place details across India.

---

## Features

- **FastMCP Framework**: Built on Prefect HQ's `fastmcp` Python framework for automatic schema generation, robust validation, and low latency.
- **Flexible Authentication**:
  - **Static Access Token Mode**: Pass a direct bearer `MAPPLS_ACCESS_TOKEN`.
  - **OAuth 2.0 Client Credentials Flow**: Pass `MAPPLS_CLIENT_ID` and `MAPPLS_CLIENT_SECRET` for automated token generation and pre-expiry refreshing.
- **Comprehensive Mappls Tools**:
  - `mappls_geocode`: Convert location names to lat/long coordinates & eLoc codes.
  - `mappls_reverse_geocode`: Convert coordinates to formatted address details.
  - `mappls_autosuggest`: Live predictive location search suggestions.
  - `mappls_get_directions`: Route directions (driving, biking, walking, trucking) with turn-by-turn steps.
  - `mappls_distance_matrix`: N-to-M travel time and distance matrix calculations.
  - `mappls_snap_to_road`: Snap noisy GPS coordinate traces to road networks.
  - `mappls_search_nearby`: Discover POIs (restaurants, ATMs, hospitals, EV chargers, fuel stations) nearby.
  - `mappls_place_details`: Retrieve rich attributes for any 6-character Mappls eLoc code.
  - `mappls_text_search`: AI smart place search with spelling correction.
- **Built-in MCP Prompts**: Pre-configured templates like `plan_itinerary` and `optimize_logistics_hub`.
- **Dual Transport Support**: Run via `stdio` (for desktop apps) or `sse` (for HTTP microservices).
- **Offline / Mock Mode**: Runs seamlessly in dry-run mode when API keys are not provided.

---

## Installation & Setup

### 1. Requirements
- Python 3.10 or higher
- MapmyIndia (Mappls) Developer Credentials or Access Token (from [Mappls Console](https://auth.mappls.com/console/))

### 2. Environment Configuration
Clone or copy this repository, then create a `.env` file from `.env.example`:

```bash
cp .env.example .env
```

Edit `.env` and fill in your Mappls token or client credentials:

```env
# Option A: Direct Access Token (Recommended for Token Input)
MAPPLS_ACCESS_TOKEN=your_access_token_here

# Option B: Client Credentials
MAPPLS_CLIENT_ID=your_client_id_here
MAPPLS_CLIENT_SECRET=your_client_secret_here

MCP_TRANSPORT=stdio
```

### 3. Install Package
Install the package in editable mode:

```bash
pip install -e .
```

Or install with development dependencies:

```bash
pip install -e ".[dev]"
```

---

## Quick Setup for Anyone (Run via `uvx` directly from GitHub)

Anyone can use this MCP server directly from GitHub **without cloning or local installation** by using [`uvx`](https://docs.astral.sh/uv/) (included with `uv`).

### 1. Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mappls": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Bhupendrajee07/MMI-MCP.git",
        "mmi-mcp"
      ],
      "env": {
        "MAPPLS_CLIENT_ID": "YOUR_MAPPLS_CLIENT_ID",
        "MAPPLS_CLIENT_SECRET": "YOUR_MAPPLS_CLIENT_SECRET"
      }
    }
  }
}
```

### 2. Antigravity / Cursor / VS Code (`mcp_config.json`)

```json
{
  "mcpServers": {
    "mappls": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Bhupendrajee07/MMI-MCP.git",
        "mmi-mcp"
      ],
      "env": {
        "MAPPLS_ACCESS_TOKEN": "YOUR_MAPPLS_ACCESS_TOKEN"
      }
    }
  }
}
```

---

## Local Development & Usage

### Run via Stdio (Default)
```bash
mmi-mcp
# or
python -m mmi_mcp.server --transport stdio
```

### Run via SSE (HTTP Server)
```bash
python -m mmi_mcp.server --transport sse --host 127.0.0.1 --port 8000
```


---

## Running Tests

Run the unit and integration test suite:

```bash
$env:PYTHONPATH="src"; python -m pytest tests/ -v
```

---

## License
MIT License