🚀 高德地图导航 MCP Tool
这是一个基于 FastAPI 和 fastmcp 的高德地图导航 MCP (Model Context Protocol) 工具。它提供了交互式地图页面，支持驾车、骑行、步行三种导航类型，可通过 MCP 接口发送导航命令实现实时路线规划。系统采用 WebSocket 实时通信和基于 sessionid 的会话管理，保障多用户使用的安全性与独立性。
🚀 快速开始
1. 环境设置
我们使用 uv 进行 Python 环境管理。首先确保已安装 uv：
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建新的虚拟环境
uv venv
# 激活虚拟环境
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
2. 安装依赖
# 使用 uv 安装依赖
uv pip install -r requirements.txt
# 同步依赖（推荐）
uv sync
3. 设置环境变量（可选）
如果你有自己的高德地图 API 密钥，可以设置环境变量：
# 设置环境变量
export AMAP_API_KEY="你的高德地图API密钥"
export AMAP_SECURITY_CODE="你的高德地图安全密钥"
4. 启动服务器
# 直接运行
python main.py
# 或者使用 uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000
服务器启动后，你会看到以下信息：
🚀 启动高德地图导航 MCP 服务器...
🔧 MCP 端点: http://localhost:8000/mcp
📚 API 文档: http://localhost:8000/docs
使用说明:
1. 使用 MCP tool 'create_session' 创建会话
2. 使用返回的 sessionid 访问地图页面
3. 使用 MCP tool 'send_navigation_to_map' 发送导航命令
✨ 主要特性
- WebSocket 实时通信：地图页面通过 WebSocket 实时接收导航命令
- 会话隔离：每个用户有独立的地图会话和连接
- 多种导航类型：支持驾车、骑行、步行导航
- 混合输入：支持经纬度坐标和关键字混合使用
- 自动重连：WebSocket 连接断开时自动重连
- 安全访问：基于 sessionid 的访问控制
- 环境变量支持：支持通过环境变量设置自定义 API 密钥
- URL 参数传递：密钥通过 URL 参数动态传递，灵活安全
- 响应式设计：适配各种屏幕尺寸
📦 安装指南
环境设置
使用 uv 进行 Python 环境管理，确保已安装 uv，并按以下步骤操作：
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建新的虚拟环境
uv venv
# 激活虚拟环境
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
安装依赖
# 使用 uv 安装依赖
uv pip install -r requirements.txt
# 同步依赖（推荐）
uv sync
设置环境变量（可选）
若有自己的高德地图 API 密钥，可设置环境变量：
# 设置环境变量
export AMAP_API_KEY="你的高德地图API密钥"
export AMAP_SECURITY_CODE="你的高德地图安全密钥"
启动服务器
# 直接运行
python main.py
# 或者使用 uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000
💻 使用示例
基础用法
以下是使用 MCP tool 创建会话和发送导航命令的基本示例：
# 假设这里有创建会话的代码示例
# 例如：使用 MCP tool 'create_session' 创建会话
# session = mcp_tool.create_session()
# 假设这里有发送导航命令的代码示例
# 例如：使用 MCP tool 'send_navigation_to_map' 发送导航命令
# mcp_tool.send_navigation_to_map(session, "目的地信息")
高级用法
在实际应用中，可结合环境变量和会话管理进行更灵活的操作：
import os
# 设置环境变量
os.environ["AMAP_API_KEY"] = "你的高德地图API密钥"
os.environ["AMAP_SECURITY_CODE"] = "你的高德地图安全密钥"
# 创建会话
# session = mcp_tool.create_session()
# 发送导航命令
# mcp_tool.send_navigation_to_map(session, "目的地信息")
📚 详细文档
🔌 API 接口
主要端点
| 属性 | 详情 |
|---|---|
| 端点 | /、/ws/{session_id}、/sessions、/queue-status、/health、/mcp、/static |
| 方法 | GET、WebSocket |
| 说明 | 获取地图页面（需要 sessionid 参数）、WebSocket 连接端点、查看所有活跃会话、查看命令队列状态、健康检查、MCP 协议端点、静态文件服务 |
查看系统状态
# 查看所有会话
curl "http://localhost:8000/sessions"
# 查看命令队列状态
curl "http://localhost:8000/queue-status"
# 健康检查
curl "http://localhost:8000/health"
🗝️ 获取高德地图 API Key
- 访问 高德开放平台
- 注册账号并登录
- 创建应用并获取 API Key
- 在 Web 服务中启用 JavaScript API
🎬 使用流程
- 设置环境变量 → （可选）设置
AMAP_API_KEY和AMAP_SECURITY_CODE - 启动服务 → 运行
python main.py - 创建会话 → 使用 MCP tool
create_session - 访问地图 → 使用返回的完整链接访问地图页面（包含密钥参数）
- 发送导航命令 → 使用 MCP tool
send_navigation_to_map - 查看结果 → 地图通过 WebSocket 实时显示导航路线
🔧 技术细节
🏗️ 架构设计
- 会话管理：基于 sessionid 的多用户会话隔离系统
- 地图页面：FastAPI 提供的交互式 HTML 页面，需要有效的 sessionid 才能访问
- WebSocket 通信：实时双向通信，支持导航命令的即时推送
- MCP Tools：
create_session创建会话，send_navigation_to_map发送导航命令 - 多种导航类型：支持驾车、骑行、步行三种导航模式
- 混合输入：支持经纬度坐标和关键字地点混合使用
🛠️ 技术栈
- FastAPI：现代、快速的 Web 框架，支持 WebSocket
- fastmcp：MCP (Model Context Protocol) 实现
- uvicorn：ASGI 服务器
- WebSocket：实时双向通信协议
- 高德地图 JavaScript API：地图、驾车、骑行、步行导航服务
⚠️ 重要提示
⚠️ 重要提示
本服务仅用于学习和开发测试目的，严禁在生产环境中使用！API 密钥通过 URL 参数传递，存在暴露风险；未实施密钥加密和访问控制，不得部署到公网；密钥可能被记录在服务器访问日志中；缺乏 HTTPS、密钥加密、访问限制等安全措施。
💡 使用建议
仅在本地开发环境使用，使用测试用的 API 密钥，确保防火墙阻止外部访问，禁止使用生产环境密钥，禁止部署到公网服务器。
⚠️ 注意事项
- 🔐 安全第一：本服务仅用于学习测试，严禁生产环境使用！
- 🔑 密钥安全：API 密钥通过 URL 参数传递，存在泄露风险，仅限本地使用
- 🌐 网络要求：需要网络连接加载地图资源
- 🔒 会话管理：必须先创建会话才能访问地图页面
- 💻 浏览器兼容：建议在现代浏览器中使用（支持 WebSocket）
- 📍 坐标系统：坐标使用 WGS84 坐标系统
- 🚲 导航限制：骑行和步行导航不支持 policy 参数
- 🔍 搜索要求：关键字搜索时必须提供城市信息
- 📝 日志风险：密钥可能被记录在各级日志中，注意清理
- 🔒 访问控制：确保服务只在可信网络中运行
📂 项目结构
08.amap/
├── main.py # 主程序文件
├── main.js # 客户端JavaScript文件
├── main.html # 地图页面HTML文件
├── pyproject.toml # 项目配置文件
├── README.md # 项目说明文档（中文）
├── README_EN.md # Project documentation (English)
├── README_JA.md # プロジェクトドキュメント（日本語）
└── uv.lock # 依赖锁定文件
🤝 贡献
欢迎提交 Issues 和 Pull Requests！
📄 许可证
MIT License
免责声明： 本项目仅用于学习和技术研究目的。使用者应当：
- 遵守高德地图API使用条款
- 不得将本项目用于商业生产环境
- 自行承担API密钥泄露等安全风险
- 确保符合当地法律法规要求
作者不承担因使用本项目而产生的任何直接或间接损失。