JinDaGe - mcp_hkbus MCP Details

article

README

🚀 香港九龍巴士及龍運巴士 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 的速率限制，在生产环境中实施适当的错误处理。

mcp_hkbus