MapmyIndia (Mappls) MCP 서버 (FastMCP)

MapmyIndia (Mappls) REST API를 위한 고성능 Model Context Protocol(MCP) 서버로, FastMCP 오픈소스 프레임워크를 사용하여 구축되었습니다.

이 서버는 AI 어시스턴트(예: Claude, Gemini, ChatGPT, Cursor, Antigravity)가 지리 데이터를 조회하고, 지오코딩을 수행하고, 운전 및 보행 경로를 생성하고, 거리 행렬 ETA를 계산하고, 관심 지점(POI)을 검색하며, 인도 전역의 eLoc 장소 세부 정보를 조회할 수 있게 해줍니다.

주요 기능

• FastMCP 프레임워크: 자동 스키마 생성, 강력한 검증, 낮은 지연 시간을 위해 Prefect HQ의 fastmcp Python 프레임워크를 기반으로 구축되었습니다.

• 유연한 인증:

  • 고정 액세스 토큰 모드: 직접 Bearer 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-to-M 이동 시간 및 거리 행렬 계산을 수행합니다.

  • mappls_snap_to_road: 노이즈가 있는 GPS 좌표 트레이스를 도로 네트워크에 스냅합니다.

  • mappls_search_nearby: 주변 관심 지점(레스토랑, ATM, 병원, EV 충전소, 주유소)을 검색합니다.

  • mappls_place_details: 6자리 Mappls eLoc 코드에 대한 풍부한 속성 정보를 조회합니다.

  • mappls_text_search: 맞춤법 교정 기능이 포함된 AI 스마트 장소 검색을 제공합니다.

• 내장 MCP 프롬프트: plan_itinerary 및 optimize_logistics_hub와 같은 사전 구성된 템플릿이 포함되어 있습니다.

• 이중 전송 지원: stdio(데스크톱 앱용) 또는 sse(HTTP 마이크로서비스용)로 실행할 수 있습니다.

• 오프라인 / 모의(Mock) 모드: API 키가 제공되지 않으면 dry-run 모드에서 원활하게 실행됩니다.

설치 및 설정

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. 패키지 설치

패키지를 편집 가능한(editable) 모드로 설치합니다:

pip install -e .

또는 개발 의존성과 함께 설치합니다:

pip install -e ".[dev]"

누구나 사용할 수 있는 빠른 설정 (uvx로 GitHub에서 직접 실행)

누구나 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 라이선스