How baidu-maps/mcp works
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