amap-mcp-streamable_http

# Gaode Map MCP Server & Client This project implements Gaode Map Server (Stateless/Stateful) and supporting Client **supporting [MCP (Model Context Protocol)](https://modelcontextprotocol.io/specification/2025-03-26) Streamable HTTP transport protocol**. > 📖 This project is based on [MCP latest specification 2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) development. ## 📂 Directory Structure ``` . ├── server_stateless/ # Stateless Gaode Map MCP Server ├── server_statefull/ # Stateful (Session Management) Gaode Map MCP Server ├── client/ # MCP protocol client and test cases ├── env.example # Environment variable example ├── 高德地图MCP工具.md # Gaode Map MCP Tool Interface Documentation └── README.md ``` ## ✨ Features - **MCP Protocol Support**: Compatible with Claude, IDE and other LLM tool ecosystems - **Streamable HTTP**: Supports streaming HTTP transport - **Gaode Map API Encapsulation**: Geocoding/Reverse Geocoding, Route Planning, POI Search, Weather, Distance Measurement, IP Location, etc. - **Stateless/Stateful Service Modes**: Meets different business needs - **TypeScript Implementation**: Type-safe, easy to maintain and extend ## 📚 Gaode Map MCP Tool Documentation The [`高德地图MCP工具.md`](./高德地图MCP工具.md) file included in this project provides a detailed introduction to all interfaces of the Gaode Map MCP Tool, including parameter descriptions, examples, and return formats for functions such as geocoding, route planning, weather queries, POI search, distance measurement, and IP location. This document is suitable for developers to quickly look up the usage and integration details of MCP tools, facilitating secondary development and interface debugging. You can also refer to the official MCP Server product documentation of Gaode Open Platform for the latest capability introduction and interface description: [Gaode Map MCP Server Official Documentation](https://lbs.amap.com/api/mcp-server/summary) ## 🔌 MCP Transport Protocol Comparison: Streamable HTTP vs Stdio ### 🖥️ Stdio Transport Protocol - Based on **standard input/output streams** (stdin/stdout), suitable for local inter-process communication - Suitable for integration of CLI tools, plugins and local LLMs - Does not support HTTP network requests, not suitable for cloud or distributed scenarios - Limited to local use, message flow is limited by the life cycle of local processes ### 🌐 Streamable HTTP Transport Protocol - **Based on HTTP/1.1**, supports POST/GET requests, suitable for Web services and cloud-native deployment - Supports **streaming messages** (such as Server-Sent Events, SSE), which can push multiple messages to the client in real time - Easy to integrate with modern applications such as browsers, cloud LLMs, and remote IDEs - Suitable for multi-client concurrency, cross-platform, and cross-network environments #### 🚦 Usage Scenario Comparison | Protocol Type | Applicable Scenarios | Network Access | Scalability | | ------------------ | ------------------------------------------------- | ------------- | -------- | | Stdio | Local CLI, plugins, stand-alone development | ❌ | General | | Streamable HTTP | Web services, cloud deployment, remote LLM, team collaboration | ✅ | Excellent | #### 💡 Why Choose Streamable HTTP? - More modern and universal, easy to connect with various LLM platforms (such as Claude Desktop, cloud IDE) - Supports streaming responses, improving the interactive experience - Better security and scalability, can be combined with HTTP authentication, CORS, load balancing and other Web standard capabilities > ⚠️ **Note:** MCP officially recommends that new projects prioritize the Streamable HTTP protocol, and Stdio is mainly used to be compatible with old local plugin scenarios. ## 🏷️ Stateless Server vs Stateful Server ### 🟢 Stateless MCP Server - **Simple architecture**: Each request is processed independently, without saving any session or context information - **High concurrency, easy to scale**: Suitable for cloud-native, load balancing and other scenarios - **Flexible deployment**: Can be horizontally scaled at any time without considering session synchronization - **Applicable scenarios**: One-time queries, LLM tools without multi-round context requirements, API services, etc. ### 🟠 Stateful MCP Server - **Session Management**: Assigns an independent session to each client, which can save context, history, user status, etc. - **Multi-round Interaction**: Supports complex multi-round dialogues, task tracking, user customization and other advanced functions - **Higher resource consumption**: Need to manage session life cycle and resource release - **Applicable scenarios**: LLM applications that require context memory, long sessions, multi-round reasoning, personalized services, etc. <br> > **Introduction to Session Management Mechanism:** > - The server allocates a unique session ID through the `Mcp-Session-Id` response header during initialization, and the client needs to carry this ID in subsequent requests > - The server can terminate the session at any time, and the client should re-initialize after receiving 404 > - The client can actively close the session through HTTP DELETE > See [MCP 2025-03-26 Session Management](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management) for detailed specifications ## 🚀 Quick Start ### 1️⃣ Clone the Project ```bash git clone https://github.com/Keldon-Pro/amap-mcp-streamable_http.git cd amap-mcp-streamable_http ``` ### 2️⃣ Configure Environment Variables Copy `env.example` under the root directory to each sub-project directory and rename it to `.env`, fill in your Gaode Map API Key: ```bash cp env.example server_stateless/.env cp env.example server_statefull/.env # Edit the .env file and fill in AMAP_MAPS_API_KEY ``` ### 3️⃣ Install Dependencies Install dependencies in each sub-project directory respectively: ```bash cd server_stateless && npm install cd ../server_statefull && npm install cd ../client && npm install ``` ### 4️⃣ Build and Start #### Stateless Server ```bash cd server_stateless npm run build npm start ``` #### Stateful Server ```bash cd server_statefull npm run build npm start ``` #### Client Test ```bash cd client npm run build npm start # Basic function test npm run test # Full tool automated test ``` > 📝 **Note:** > If you need to switch between Stateless/Stateful MCP Server, please modify the `MCP_SERVER_URL` variable in the `client/src/index.ts` file, corresponding to: > - Stateless Server: `http://localhost:3000/mcp` > - Stateful Server: `http://localhost:3001/mcp` ## 🧪 Server Test Instructions You can verify the server functions in the following ways: ### 1. Start the Server Make sure that `server_stateless` or `server_statefull` has been started (see above). ### 2. Use the Official MCP Inspector for Visual Testing - In the server directory, directly use npx to start Inspector and debug the local MCP Server: ```bash npx @modelcontextprotocol/inspector ``` - After starting, visit `http://localhost:6274` in your browser to interactively test all tools, view request and response details in the Web UI, which is convenient for debugging and demonstration. <img src="./images/MCP%20Inspector.png" alt="MCP Inspector"> As shown above, - Select "Streamable Http" for Transport Type; - Fill in "http://localhost:3001/mcp" for URL // Depends on your Server URL - After filling in, you can connect with one click! - For more detailed instructions on how to use Inspector, please visit [MCP Inspector](https://github.com/modelcontextprotocol/inspector) ### 3. Use the Server's Own Test Script - There is `test.js` in the `server_stateless` directory, which can be used to quickly verify the stateless server function: ```bash cd server_stateless npm run test ``` - There are `test-stateful.js` and `test-resume-session.js` in the `server_statefull` directory, which can be used to verify the basic functions and session recovery of the stateful server: ```bash cd server_statefull node .\test-stateful.js # Test the stateful server function node test-resume-session.js [session-id] # Test the session recovery function ``` These scripts will directly call the local server interface and output the test results, which is suitable for development debugging and regression testing. > ❗ If you encounter a connection failure, please check whether the server has been started correctly and whether the port and environment variable configuration are consistent. ## 🐳 Docker Deployment ### Using Docker Compose (Recommended) First, make sure you are in the project root directory: ```bash cd amap-mcp-streamable_http # Enter the project root directory ``` 1. Configure environment variables: ```bash cp env.example .env # Edit the .env file and fill in AMAP_MAPS_API_KEY ``` 2. Start all services: ```bash docker-compose up -d ``` This command will start both the stateless server (port 3000) and the stateful server (port 3001). ### Log Viewing Server logs are stored in Docker named volumes: - Stateless server log volume: `stateless_logs` - Stateful server log volume: `stateful_logs` You can view the logs using the following commands: ```bash # View container real-time logs docker-compose logs -f stateless # Stateless server logs docker-compose logs -f stateful # Stateful server logs # View log volume information docker volume inspect amap-mcp_stateless_logs # Stateless server log volume information docker volume inspect amap-mcp_stateful_logs # Stateful server log volume information ``` ### Using Docker Separately If you only need to run one of the servers: #### Stateless Server: ```bash cd server_stateless docker build -t amap-mcp-stateless . docker run -d \ -p 3000:3000 \ -v stateless_logs:/app/logs \ --env-file ../.env \ amap-mcp-stateless ``` #### Stateful Server: ```bash cd server_stateful docker build -t amap-mcp-stateful . docker run -d \ -p 3001:3001 \ -v stateful_logs:/app/logs \ --env-file ../.env \ amap-mcp-stateful ``` ### Data Persistence Docker named volumes automatically manage the persistence of log files, and log data will be retained even if the container is restarted or deleted. If you need to completely clear the log data, you can use: ```bash # Delete the specified log volume docker volume rm amap-mcp_stateless_logs amap-mcp_stateful_logs # Or delete the volume while stopping the service docker-compose down -v ``` ## 📚 Reference Documents - [MCP Official Documentation](https://modelcontextprotocol.io/specification/2025-03-26) - [Gaode Open Platform](https://lbs.amap.com/dev/) ## 🤝 Contribution Welcome issues, PRs and suggestions!