# baidu-maps/mcp architecture

> Architecture diagram of the GitHub repository baidu-maps/mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baidu-maps/mcp
- Repository: https://github.com/baidu-maps/mcp

## Overview

##### Project Type and Purpose
- This is an open-source MCP (Model Context Protocol) Server implementation for Baidu Maps, delivered as both a Python library/CLI and a TypeScript/Node.js CLI.
- Its purpose is to expose Baidu Map services (geocoding, routing, weather, traffic, POI extraction, etc.) through the MCP protocol so that any MCP-capable agent (Claude, Cursor, AppBuilder, etc.) can invoke these tools via a unified interface.

##### File Structure Analysis
Top-level:
- LICENSE, README.md, img/ (screenshots)
- src/baidu-map/
– node/
· index.ts – TypeScript CLI entrypoint
· package.json, tsconfig.json – Node.js package and compiler settings
– python/
· pyproject.toml – Python package metadata
· src/mcp_server_baidu_maps/
__main__.py – CLI entrypoint for `python -m mcp_server_baidu_maps`
.py – core implementation calling Baidu REST/SSE APIs
Patterns & Config:
- Separate adapters/CLI for each language
- Uses MCP SDK clients under the hood to translate MCP calls to HTTP(S)/SSE requests
- Configuration via environment variable (BAIDU_MAPS_API_KEY)

##### Key Insights from README
- The server implements 10 MCP‐standard tools for map/geolocation features.
- Two delivery mechanisms:
a) Python package (via pip or uvx)
b) TypeScript/Node.js package (via npx @baidumap/mcp-server-baidu-map)
- Emphasizes SSE support for low latency.
- Example integration with ChatGPT‐style agents (Agent pattern with interrupt hooks).

a. Main Components
1. MCP Client (Agent) – any client supporting MCP (Claude.app, custom agent, AppBuilder).
2. Language-specific Server CLI/Adapter
- Python CLI (`mcp_server_baidu_maps`)
- Node.js CLI (`@baidumap/mcp-server-baidu-map`)
3. Baidu Maps MCP Server Core (map.py / index.ts) – implements the 10 MCP tools.
4. Baidu Map REST & SSE Endpoints – official Baidu backend providing raw map data.
5. External Dependencies
– MCP Python SDK, MCP TypeScript SDK
– SSE or HTTP transport layer

b. Component Interactions
1. Agent issues an MCP tool call → MCP Client serializes request → CLI Adapter receives it.
2. CLI Adapter maps MCP tool name/arguments → invokes core module (map.py or index.ts).
3. Core module constructs HTTP or SSE request to Baidu Map API using the API key.
4. Baidu Map API responds with JSON/stream → core module parses response → wraps it into MCP tool response.
5. CLI Adapter streams/writes response back to MCP Client → Agent consumes result.

c. Architectural Patterns & Design Principles
- Adapter/Facade: abstracts Baidu Map REST/SSE behind a uniform MCP interface
- Modular: separate language bindings; each binding reuses core logic structures
- Pluggable CLI: delivered as scripts (uvx, pip, npx)
- Streamed vs. non‐streamed mode: support for SSE for real‐time tools

d. Technologies & Frameworks
- Python: pyproject.toml, `asyncio`, MCP Python SDK
- TypeScript/Node.js: index.ts, `@mcp/typescript-sdk`, npx CLI
- SSE: for streaming endpoints (traffic, route progress)
- HTTP: for standard REST endpoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Agent["Agent / MCP Client"]:::client

    %% Adapter Layer
    subgraph "CLI Adapters" 
        direction TB
        PyCLI["Python CLI Adapter\n(mcp_server_baidu_maps)"]:::our
        NodeCLI["Node.js CLI Adapter\n(@baidumap/mcp-server-baidu-map)"]:::our
    end

    %% Core Modules
    subgraph "Core Modules" 
        direction TB
        PyCore["Python Core Module\n(map.py)"]:::our
        NodeCore["TypeScript Core Module\n(index.ts)"]:::our
    end

    %% External Services & Dependencies
    subgraph "External Services & SDKs"
        direction TB
        SDKPy["MCP Python SDK"]:::external
        SDKTs["MCP TypeScript SDK"]:::external
        BaiduAPI["Baidu Map REST & SSE API"]:::external
    end

    %% Configuration
    Env["Env: BAIDU_MAPS_API_KEY"]:::config

    %% Documentation
    README["README.md"]:::doc
    LICENSEF["LICENSE"]:::doc

    %% Flow
    Agent -->|1. MCP request| PyCLI
    Agent -->|1. MCP request| NodeCLI

    PyCLI -->|2. invoke tool\nargs mapping| PyCore
    NodeCLI -->|2. invoke tool\nargs mapping| NodeCore

    PyCore -->|3. HTTP/SSE| BaiduAPI
    NodeCore -->|3. HTTP/SSE| BaiduAPI

    BaiduAPI -->|4. JSON/stream| PyCore
    BaiduAPI -->|4. JSON/stream| NodeCore

    PyCore -->|5. MCP response| PyCLI
    NodeCore -->|5. MCP response| NodeCLI

    PyCLI -->|5.b stream/write| Agent
    NodeCLI -->|5.b stream/write| Agent

    %% Config arrow
    Env -.->|used by| PyCore
    Env -.->|used by| NodeCore

    %% Documentation & License
    README & LICENSEF

    %% Click Events
    click PyCLI "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/python/src/mcp_server_baidu_maps/__main__.py"
    click PyCore "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/python/src/mcp_server_baidu_maps/map.py"
    click SDKPy "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/python/pyproject.toml"
    click NodeCore "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/node/index.ts"
    click NodeCLI "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/node/index.ts"
    click NodeSDK "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/node/package.json"
    click TSConfig "https://github.com/baidu-maps/mcp/blob/main/src/baidu-map/node/tsconfig.json"
    click README "https://github.com/baidu-maps/mcp/blob/main/README.md"
    click LICENSEF "https://github.com/baidu-maps/mcp/tree/main/LICENSE"

    %% Classes
    classDef our fill:#cce5ff,stroke:#004085,color:#004085;
    classDef external fill:#d4edda,stroke:#155724,color:#155724;
    classDef client fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef config fill:#fff3cd,stroke:#856404,color:#856404;
    classDef doc fill:#f8f9fa,stroke:#343a40,color:#343a40;
```
