Amapmcp

🚀 高德地圖導航 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 接口

主要端點

查看系統狀態

# 查看所有會話
curl "http://localhost:8000/sessions"

# 查看命令隊列狀態
curl "http://localhost:8000/queue-status"

# 健康檢查
curl "http://localhost:8000/health"

🗝️ 獲取高德地圖 API Key

1. 訪問 高德開放平臺
2. 註冊賬號並登錄
3. 創建應用並獲取 API Key
4. 在 Web 服務中啟用 JavaScript API

🎬 使用流程

1. 設置環境變量 → （可選）設置 AMAP_API_KEY 和 AMAP_SECURITY_CODE
2. 啟動服務 → 運行 python main.py
3. 創建會話 → 使用 MCP tool create_session
4. 訪問地圖 → 使用返回的完整鏈接訪問地圖頁面（包含密鑰參數）
5. 發送導航命令 → 使用 MCP tool send_navigation_to_map
6. 查看結果 → 地圖通過 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 密鑰，確保防火牆阻止外部訪問，禁止使用生產環境密鑰，禁止部署到公網服務器。

⚠️ 注意事項

1. 🔐 安全第一：本服務僅用於學習測試，嚴禁生產環境使用！
2. 🔑 密鑰安全：API 密鑰通過 URL 參數傳遞，存在洩露風險，僅限本地使用
3. 🌐 網絡要求：需要網絡連接加載地圖資源
4. 🔒 會話管理：必須先創建會話才能訪問地圖頁面
5. 💻 瀏覽器兼容：建議在現代瀏覽器中使用（支持 WebSocket）
6. 📍 座標系統：座標使用 WGS84 座標系統
7. 🚲 導航限制：騎行和步行導航不支持 policy 參數
8. 🔍 搜索要求：關鍵字搜索時必須提供城市信息
9. 📝 日誌風險：密鑰可能被記錄在各級日誌中，注意清理
10. 🔒 訪問控制：確保服務只在可信網絡中運行

📂 項目結構

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密鑰洩露等安全風險
• 確保符合當地法律法規要求

作者不承擔因使用本項目而產生的任何直接或間接損失。