MCP Hkbus

🚀 香港九龍巴士及龍運巴士 MCP 伺服器

本項目是一個提供香港九龍巴士（KMB）及龍運巴士（LWB）即時路線信息及到站時間的模型上下文協議（MCP）伺服器。藉助該伺服器，語言模型能夠查詢香港巴士服務信息，精準回答用戶關於路線、站點和預計到站時間（estimated arrival times）的問題。

✨ 主要特性

• 🌐 即時公交到站信息 (ETA)：讓您隨時掌握巴士的預計到站時間。
• 🚍 全面的巴士路線檢索：可查詢所有巴士路線。
• 🚍 巴士站信息及搜索：輕鬆獲取巴士站點信息並進行搜索。
• 🗺️ 路線至站點的映射：清晰瞭解每條路線對應的站點。
• 💾 緩存系統以優化 API 調用：提升 API 調用效率。
• 🌏 雙語支持（英文和繁體中文）：滿足不同語言需求。

📦 安裝指南

安裝 uv

如果尚未安裝 uv，可使用以下命令進行安裝：

curl -LsSf https://astral.sh/uv/install.sh | sh

克隆倉庫

克隆項目倉庫並進入項目目錄：

git clone git@github.com:kennyckk/mcp_hkbus.git
cd mcp_hkbus

處理 Python 包

使用 uv 處理 Python 包：

uv sync # 使用 uv.lock

💻 使用示例

基礎用法

編輯 MCP 客戶端配置

編輯您的 MCP 客戶端（例如 Claude 桌面版）的 Config：

{
  "mcpServers": {
    "bus_service": {
      "command": "path/to/uv.exe",
      "args": ["--directory", "path/to/kmb_bus", "run", "kmb_mcp.py"],
      "background": true
    }
  }
}

調用工具查詢公交信息

伺服器提供了一些工具，可用於語言模型查詢公交信息：

# 獲取所有巴士路線列表
get_route_list()
# 獲取所有巴士站點列表
get_stop_list()
# 獲取特定路線的站點
get_route_stops()
# 根據名稱搜索巴士站點
find_stops_by_name()
# 獲取為特定站點服務的所有路線
get_all_routes_at_stop()
# 獲取 estimated arrival times
get_eta()

📚 詳細文檔

數據源

此專案使用官方 KMB/LWB 開放數據 API：

• 基礎 URL: https://data.etabus.gov.hk/v1/transport/kmb
• KMB 開放數據 API 文件

依存條件

• Python 3.10 或更高版本
• uv 包管理器

測試

使用 pytest 運行測試套件：

pytest test/kmb-mcp-tests.py

依存項

• httpx: 用於 async HTTP 請求
• fastmcp: 用於 MCP 伺服器實現
• pytest: 用於測試（開發環境）

參與貢獻

歡迎任何人的參與！請隨意提交 Pull Request。

特別鳴謝

• KMB/LWB 提供開放數據 API
• MCP 協議的 developers

注意事項

⚠️ 重要提示

本服務依賴於 KMB/LWB 開放數據 API。請注意 API 的速率限制，在生產環境中實施適當的錯誤處理。