AMapMCP

# 高徳地図ナビゲーション MCP Tool [简体中文](README.md) | [日本語](README_JA.md) | [English](README_EN.md) これは 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` がインストールされていることを確認してください： ```bash # uvのインストール（未インストールの場合） curl -LsSf https://astral.sh/uv/install.sh | sh # 新しい仮想環境の作成 uv venv # 仮想環境の有効化 source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows ``` ### 2. 依存関係のインストール ```bash # uvを使用して依存関係をインストール uv pip install -r requirements.txt # 依存関係の同期（推奨） uv sync ``` ### 3. 環境変数の設定（オプション） 独自の高徳地図 API キーがある場合、環境変数を設定できます： ```bash # 環境変数の設定 export AMAP_API_KEY="あなたの高徳地図APIキー" export AMAP_SECURITY_CODE="あなたの高徳地図セキュリティコード" ``` ### 4. サーバーの起動 ```bash # 直接実行 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 インターフェース ### 主要エンドポイント | エンドポイント | メソッド | 説明 | |----------------|----------|------| | `/` | GET | 地図ページの取得（sessionid パラメータが必要） | | `/ws/{session_id}` | WebSocket | WebSocket 接続エンドポイント | | `/sessions` | GET | アクティブなセッションの表示 | | `/queue-status` | GET | コマンドキューのステータス確認 | | `/health` | GET | ヘルスチェック | | `/mcp` | - | MCP プロトコルエンドポイント | | `/static` | GET | 静的ファイルサービス | ### システムステータスの確認 ```bash # すべてのセッションを表示 curl "http://localhost:8000/sessions" # コマンドキューのステータスを確認 curl "http://localhost:8000/queue-status" # ヘルスチェック curl "http://localhost:8000/health" ``` ## 🗝️ 高徳地図 API キーの取得 1. [高徳開放プラットフォーム](https://lbs.amap.com/) にアクセス 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 キー漏洩などのセキュリティリスクは自己責任 - 現地の法律規制要件への準拠 作者は本プロジェクトの使用により生じるいかなる直接的または間接的な損失に対して責任を負いません。