amap-mcp-streamable_http

Keldon-Pro/amap-mcp-streamable_http

3.3

If you are the rightful owner of amap-mcp-streamable_http and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This project implements a Gaode Map Server and Client that supports the Model Context Protocol (MCP) Streamable HTTP transport protocol.

高德地图 MCP Server & Client

本项目实现了支持 MCP (Model Context Protocol) Streamable HTTP 传输协议的高德地图 Server（无状态/有状态）与配套 Client。

📖 本项目基于 MCP 最新规范 2025-03-26 开发。

📂 目录结构

.
├── server_stateless/   # 无状态高德地图 MCP Server
├── server_statefull/   # 有状态（会话管理）高德地图 MCP Server
├── client/             # MCP 协议客户端及测试用例
├── env.example         # 环境变量示例
├── 高德地图MCP工具.md   # 高德地图 MCP 工具接口文档
└── README.md

✨ 功能特性

  • MCP 协议支持：兼容 Claude、IDE 等 LLM 工具生态
  • Streamable HTTP：支持流式 HTTP 传输
  • 高德地图 API 封装：地理/逆地理编码、路径规划、POI 搜索、天气、距离测量、IP定位等
  • 无状态/有状态两种服务模式：满足不同业务需求
  • TypeScript 实现：类型安全，易于维护和扩展

📚 高德地图 MCP 工具文档

本项目内置的 文件，详细介绍了高德地图 MCP 工具的所有接口，包括地理编码、路径规划、天气查询、POI 搜索、距离测量、IP定位等功能的参数说明、示例和返回格式。
该文档适用于开发者快速查阅 MCP 工具的用法和集成细节，便于二次开发和接口调试。

你也可以参考高德开放平台官方的 MCP Server 产品文档，获取最新的能力介绍和接口说明：
高德地图 MCP Server 官方文档

🔌 MCP 传输协议对比：Streamable HTTP vs Stdio

🖥️ Stdio 传输协议

  • 基于标准输入输出流（stdin/stdout），适合本地进程间通信
  • 适合 CLI 工具、插件与本地 LLM 的集成
  • 不支持 HTTP 网络请求，不适合云端或分布式场景
  • 仅限本机使用，消息流动受限于本地进程生命周期

🌐 Streamable HTTP 传输协议

  • 基于 HTTP/1.1，支持 POST/GET 请求，适合 Web 服务和云原生部署
  • 支持流式消息（如 Server-Sent Events, SSE），可实时推送多条消息给客户端
  • 便于与浏览器、云端 LLM、远程 IDE 等现代应用集成
  • 适合多客户端并发、跨平台、跨网络环境
🚦 使用场景对比
协议类型适用场景网络访问扩展性
Stdio本地 CLI、插件、单机开发❌一般
Streamable HTTPWeb 服务、云端部署、远程 LLM、团队协作✅极佳
💡 为什么选择 Streamable HTTP？
  • 更现代、更通用，易于与各类 LLM 平台（如 Claude Desktop、云端 IDE）对接
  • 支持流式响应，提升交互体验
  • 安全性与可扩展性更好，可结合 HTTP 认证、CORS、负载均衡等 Web 标准能力

⚠️ 注意： MCP 官方推荐新项目优先采用 Streamable HTTP 协议，Stdio 主要用于兼容老旧本地插件场景。

🏷️ Stateless Server vs Stateful Server

🟢 无状态（Stateless）MCP Server

  • 架构简单：每个请求独立处理，不保存任何会话或上下文信息
  • 高并发、易扩展：适合云原生、负载均衡等场景
  • 部署灵活：可随时横向扩展，无需考虑会话同步
  • 适用场景：一次性查询、无多轮上下文需求的 LLM 工具、API 服务等

🟠 有状态（Stateful）MCP Server

  • 会话管理：为每个客户端分配独立的会话（Session），可保存上下文、历史、用户状态等
  • 多轮交互：支持复杂的多轮对话、任务跟踪、用户定制等高级功能
  • 资源消耗更高：需管理会话生命周期和资源释放
  • 适用场景：需要上下文记忆、长会话、多轮推理的 LLM 应用、个性化服务等

会话管理机制简介：

  • 服务端在初始化时通过 Mcp-Session-Id 响应头分配唯一会话 ID，客户端后续请求需携带该 ID
  • 服务端可随时终止会话，客户端收到 404 后应重新初始化
  • 客户端可通过 HTTP DELETE 主动关闭会话
    详细规范见 MCP 2025-03-26 Session Management

🚀 快速开始

1️⃣ 克隆项目

git clone https://github.com/Keldon-Pro/amap-mcp-streamable_http.git
cd amap-mcp-streamable_http

2️⃣ 配置环境变量

复制根目录下的 env.example 到各子项目目录并重命名为 .env，填写你的高德地图 API Key：

cp env.example server_stateless/.env
cp env.example server_statefull/.env
# 编辑 .env 文件，填写 AMAP_MAPS_API_KEY

3️⃣ 安装依赖

分别在各子项目目录下安装依赖：

cd server_stateless && npm install
cd ../server_statefull && npm install
cd ../client && npm install

4️⃣ 构建与启动

无状态服务端
cd server_stateless
npm run build
npm start
有状态服务端
cd server_statefull
npm run build
npm start
客户端测试
cd client
npm run build
npm start         # 基本功能测试
npm run test      # 全量工具自动化测试

📝 注意：
如需切换无状态/有状态 MCP Server，请修改 client/src/index.ts 文件中的 MCP_SERVER_URL 变量，分别对应：

  • 无状态服务端：http://localhost:3000/mcp
  • 有状态服务端：http://localhost:3001/mcp

🧪 服务端测试说明

你可以通过以下方式对服务端进行功能验证：

1. 启动服务端

确保 server_stateless 或 server_statefull 已启动（见上文）。

2. 使用官方 MCP Inspector 可视化测试

  • 在server目录下，直接用 npx 启动 Inspector 并调试本地 MCP Server：

    npx @modelcontextprotocol/inspector

  • 启动后，浏览器访问 http://localhost:6274，即可在 Web UI 交互式测试所有工具、查看请求与响应详情，便于调试和演示。

    MCP Inspector 如上图所示，

    • Transport Type选择"Streamable Http";
    • URL填"http://localhost:3001/mcp" // 取决于你的Server URL
    • 填好后，便可一键连接！

  • 更详细的Inspector使用方法请访问 MCP Inspector

3. 使用服务端自带测试脚本

  • server_stateless 目录下有 test.js，可用于快速验证无状态服务端功能： 
    cd server_stateless
npm run test
  • server_statefull 目录下有 test-stateful.js 和 test-resume-session.js，可用于验证有状态服务端的基本功能和会话恢复： 
    cd server_statefull
node .\test-stateful.js         # 测试有状态服务端功能
node test-resume-session.js [session-id]      # 测试会话恢复功能

这些脚本会直接调用本地服务端接口，输出测试结果，适合开发调试和回归测试。

❗ 如遇到连接失败，请检查 server 是否已正确启动，端口和环境变量配置是否一致。

🐳 Docker 部署

使用 Docker Compose（推荐）

首先，确保你在项目根目录下：

cd amap-mcp-streamable_http  # 进入项目根目录
  1. 配置环境变量：
cp env.example .env
# 编辑 .env 文件，填写 AMAP_MAPS_API_KEY
  1. 启动所有服务：
docker-compose up -d

此命令会同时启动无状态服务器（端口3000）和有状态服务器（端口3001）。

日志查看

服务器日志存储在 Docker 命名卷中：

  • 无状态服务器日志卷：stateless_logs
  • 有状态服务器日志卷：stateful_logs

你可以通过以下命令查看日志：

# 查看容器实时日志
docker-compose logs -f stateless  # 无状态服务器日志
docker-compose logs -f stateful   # 有状态服务器日志

# 查看日志卷信息
docker volume inspect amap-mcp_stateless_logs  # 无状态服务器日志卷信息
docker volume inspect amap-mcp_stateful_logs   # 有状态服务器日志卷信息

单独使用 Docker

如果你只需要运行某一个服务器：

无状态服务器：
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
有状态服务器：
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

数据持久化

Docker 命名卷会自动管理日志文件的持久化，即使容器重启或删除，日志数据也会保留。如果需要完全清理日志数据，可以使用：

# 删除指定日志卷
docker volume rm amap-mcp_stateless_logs amap-mcp_stateful_logs

# 或者在停止服务的同时删除卷
docker-compose down -v

📚 参考文档

🤝 贡献

欢迎 issue、PR 和建议！