MapmyIndia (Mappls) MCP Server (FastMCP)

MapmyIndia (Mappls) REST API 向けの高性能な Model Context Protocol (MCP) サーバーで、FastMCP オープンソースフレームワークを使用して構築されています。

このサーバーにより、AIアシスタント（Claude、Gemini、ChatGPT、Cursor、Antigravity など）は、地理データのクエリ、ジオコーディング、運転・徒歩ルートの生成、距離行列の所要時間計算、周辺の興味深い地点（POI）の発見、インド全土の eLoc プレース詳細の検索を行うことができます。

機能

• FastMCP フレームワーク: Prefect HQ の fastmcp Python フレームワークに基づき、自動スキーマ生成、堅牢な検証、低レイテンシーを実現します。

• 柔軟な認証:

  • 静的アクセストークンモード: 直接のベアラートークン MAPPLS_ACCESS_TOKEN を渡します。

  • OAuth 2.0 クライアントクレデンシャルフロー: MAPPLS_CLIENT_ID と MAPPLS_CLIENT_SECRET を渡すことで、トークンの自動生成と有効期限前の更新を行います。

• 包括的な Mappls ツール:

  • mappls_geocode: 場所名を緯度経度座標と eLoc コードに変換します。

  • mappls_reverse_geocode: 座標をフォーマットされた住所詳細に変換します。

  • mappls_autosuggest: ライブ予測型の場所検索候補を提供します。

  • mappls_get_directions: ターンバイターンのステップ付きルート案内（運転、自転車、徒歩、トラック）を提供します。

  • mappls_distance_matrix: N対Mの移動時間と距離行列の計算を行います。

  • mappls_snap_to_road: ノイズの多いGPS座標トレースを道路ネットワークにスナップします。

  • mappls_search_nearby: 周辺のPOI（レストラン、ATM、病院、EV充電器、給油所）を発見します。

  • mappls_place_details: 任意の6文字の Mappls eLoc コードのリッチな属性を取得します。

  • mappls_text_search: スペル修正付きのAIスマートプレース検索。

• 組み込みの MCP プロンプト: plan_itinerary や optimize_logistics_hub などの事前設定テンプレート。

• デュアルトランスポートサポート: stdio（デスクトップアプリ用）または sse（HTTPマイクロサービス用）で実行できます。

• オフライン / モックモード: APIキーが提供されていない場合、ドライランモードでシームレスに実行されます。

インストールとセットアップ

1. 要件

• Python 3.10 以上

• MapmyIndia (Mappls) 開発者資格情報またはアクセストークン（Mappls Console から）

2. 環境設定

このリポジトリをクローンまたはコピーし、.env.example から .env ファイルを作成します：

cp .env.example .env

.env を編集し、Mappls トークンまたはクライアント資格情報を入力します：

# 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. パッケージのインストール

パッケージを編集可能モードでインストールします：

pip install -e .

または、開発依存関係を含めてインストールします：

pip install -e ".[dev]"

誰でも簡単セットアップ（GitHub から直接 uvx で実行）

誰でも uvx（uv に含まれています）を使用して、クローンやローカルインストールなしで GitHub から直接この MCP サーバーを使用できます。

1. Claude Desktop（claude_desktop_config.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）

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

ローカル開発と使用法

Stdio 経由で実行（デフォルト）

mmi-mcp
# or
python -m mmi_mcp.server --transport stdio

SSE 経由で実行（HTTPサーバー）

python -m mmi_mcp.server --transport sse --host 127.0.0.1 --port 8000

テストの実行

ユニットテストと統合テストスイートを実行します：

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

ライセンス

MIT ライセンス