Amapmcp

🚀 高德地图ナビゲーション MCP Tool

このツールは、FastAPI と fastmcp に基づく、高德地図ナビゲーションの MCP (Model Context Protocol) ツールです。インタラクティブな地図ページを提供し、車、自転車、徒歩の3種類のナビゲーションタイプをサポートしています。MCP インターフェースを通じてナビゲーションコマンドを送信し、リアルタイムのルート計画を行うことができます。システムは WebSocket を使用したリアルタイム通信と、sessionid に基づくセッション管理を採用しており、多ユーザー使用時の安全性と独立性を確保しています。

⚠️ 重要なセキュリティ声明

本サービスは学習と開発テスト目的のみに使用され、本番環境での使用は厳禁です！

• 🔒 APIキーの暴露リスク：高德地図 API キーは URL パラメータで渡されるため、暴露のリスクがあります。
• 🌐 公開ネットワークへのアクセスの危険性：キーの暗号化やアクセス制御が実装されていないため、公開ネットワークにデプロイしてはいけません。
• 📊 ログの漏洩リスク：キーがサーバーのアクセスログに記録される可能性があります。
• 🔐 セキュリティ対策の不足：HTTPS、キーの暗号化、アクセス制限などのセキュリティ対策がありません。

使用上の推奨事項：

• ✅ ローカル開発環境でのみ使用してください。
• ✅ テスト用の API キーを使用してください。
• ✅ ファイアウォールで外部からのアクセスをブロックするようにしてください。
• ❌ 本番環境のキーを使用しないでください。
• ❌ 公開ネットワークのサーバーにデプロイしないでください。

🏗️ アーキテクチャ設計

• セッション管理：sessionid に基づく多ユーザーセッション分離システム
• 地図ページ：FastAPI が提供するインタラクティブな HTML ページで、有効な sessionid が必要です。
• WebSocket 通信：リアルタイムの双方向通信をサポートし、ナビゲーションコマンドの即時送信が可能です。
• MCP Tools：create_session でセッションを作成し、send_navigation_to_map でナビゲーションコマンドを送信します。
• 複数のナビゲーションタイプ：車、自転車、徒歩の3種類のナビゲーションモードをサポートしています。
• 混合入力：緯度経度座標とキーワード地点の混合使用をサポートしています。

🚀 クイックスタート

1. 環境設定

Python 環境管理に uv を使用します。まず、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`を使用してナビゲーションコマンドを送信します。

🔌 APIインターフェース

主要エンドポイント

システム状態の確認

# すべてのセッションを確認する
curl "http://localhost:8000/sessions"

# コマンドキューの状態を確認する
curl "http://localhost:8000/queue-status"

# ヘルスチェック
curl "http://localhost:8000/health"

🗝️ 高德地図APIキーの取得

1. 高德開放プラットフォームにアクセスします。
2. アカウントを登録し、ログインします。
3. アプリケーションを作成し、APIキーを取得します。
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を通じてリアルタイムにナビゲーションルートを表示します。

🌟 特徴機能

• WebSocketリアルタイム通信：地図ページがWebSocketを通じてリアルタイムにナビゲーションコマンドを受信します。
• セッション分離：各ユーザーに独立した地図セッションと接続があります。
• 複数のナビゲーションタイプ：車、自転車、徒歩のナビゲーションをサポートしています。
• 混合入力：緯度経度座標とキーワードの混合使用をサポートしています。
• 自動再接続：WebSocket接続が切断された場合、自動的に再接続します。
• 安全なアクセス：sessionidに基づくアクセス制御があります。
• 環境変数のサポート：環境変数を使用してカスタムAPIキーを設定できます。
• URLパラメータの送信：キーがURLパラメータを通じて動的に送信され、柔軟で安全です。
• レスポンシブデザイン：すべての画面サイズに適合します。

📂 プロジェクト構造

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              # 依存関係ロックファイル

🛠️ 技術スタック

• FastAPI: 現代的で高速なWebフレームワークで、WebSocketをサポートしています。
• fastmcp: MCP (Model Context Protocol) の実装
• uvicorn: ASGIサーバー
• WebSocket: リアルタイム双方向通信プロトコル
• 高德地図JavaScript API: 地図、車、自転車、徒歩のナビゲーションサービス

⚠️ 注意事項

1. 🔐 安全第一：本サービスは学習テスト用であり、本番環境での使用は厳禁です！
2. 🔑 キーの安全性：APIキーはURLパラメータを通じて渡されるため、漏洩のリスクがあり、ローカルでの使用に限定してください。
3. 🌐 ネットワーク要件：地図リソースをロードするためにネットワーク接続が必要です。
4. 🔒 セッション管理：地図ページにアクセスする前に、セッションを作成する必要があります。
5. 💻 ブラウザ互換性：WebSocketをサポートする最新のブラウザで使用することをお勧めします。
6. 📍 座標系：座標はWGS84座標系を使用しています。
7. 🚲 ナビゲーション制限：自転車と徒歩のナビゲーションではpolicyパラメータをサポートしていません。
8. 🔍 検索要件：キーワード検索時には、都市情報を提供する必要があります。
9. 📝 ログのリスク：キーが各レベルのログに記録される可能性があるため、定期的に削除するようにしてください。
10. 🔒 アクセス制御：サービスが信頼できるネットワーク内でのみ実行されるようにしてください。

🤝 貢献

Issues と Pull Requests の投稿を歓迎します！

📄 ライセンス

MIT License

免責事項： 本プロジェクトは学習と技術研究目的のみに使用されます。ユーザーは以下のことを行う必要があります。

• 高德地図APIの使用規約を遵守する。
• 本プロジェクトを商用本番環境で使用しない。
• APIキーの漏洩などのセキュリティリスクを自己責任で負う。
• 現地の法令要件を満たすことを確認する。

作者は、本プロジェクトの使用によって生じる直接的または間接的な損失について一切の責任を負いません。