Dragonmcp

---

🌟 什么是 DragonMCP？

一个 MCP 服务，为 AI Agent 提供香港及中国内地边境地区真实、可验证的公共数据。

此服务中的每个工具都会调用实时 API，不使用任何模拟数据。 如果上游数据源不可用，工具会如实说明，绝不会编造看似可信的答案。你可以随时使用内置的 system_run_selftest 工具自行验证：它会 ping 每个上游，并报告实际可访问的服务。

选择这一细分领域的原因：香港的公共数据确实开放（data.gov.hk，无需密钥，也无需填写限流申请），但分散在各个机构，格式也不统一。而跨境出行中，单次旅程可能涉及 MTR、中国内地铁路网络以及两个不同的天气机构，这正是没有任何单一机构有动力提供服务的场景。

---

🔥 实时示例

MTR 实时到站信息——无需 API 密钥：

> When is the next train from Admiralty to Central?

Next Island Line train from Admiralty to Central (towards Kennedy Town):
- Arriving in: 0 min(s) (14:02:27)
Subsequent trains:
- 4 min(s) (14:06:27)
- 7 min(s) (14:09:27)

香港天文台——无需 API 密钥，包含生效中的警告：

> What's the weather in Hong Kong?

Current Weather in Hong Kong (Updated: 2026-08-04T13:02:00+08:00):
- Temperature: 30°C
- Humidity: 75%
- UV Index: 8 (very high)

Warnings:
The Thunderstorm Warning has been issued. It will remain effective until
3:00 p.m. today. Isolated thunderstorms are expected to occur over New
Territories West.

---

🛠️ 工具

工具	来源	API 密钥	功能
search_mtr_schedule	通过 data.gov.hk 获取的 MTR 数据	—	含换乘的行程规划 + 实时到站信息；覆盖全部 10 条线路和 98 个车站
hk_weather_current	香港天文台	—	当前天气状况 + 生效中的警告
hk_typhoon_signal	香港天文台	—	以结构化格式提供台风、暴雨及其他生效中的警告状态
search_transit_route	MTR / Amap	仅限中国内地	统一的香港/中国内地路线规划；自动选择合适的服务商
system_run_selftest	以上所有来源	—	实时检查每个上游服务的可访问性
amap_search_poi	Amap（高德）	✅	搜索中国内地 POI
amap_walking_direction	Amap（高德）	✅	步行路线
amap_driving_direction	Amap（高德）	✅	驾车路线
amap_transit_direction	Amap（高德）	✅	公共交通路线
amap_bicycling_direction	Amap（高德）	✅	骑行路线

MTR 覆盖范围——覆盖全部 10 条线路，车站名称可使用英文或中文：

港岛线（港岛线）· 荃湾线（荃湾线）· 观塘线（观塘线）· 将军澳线（将军澳线）· 东铁线（东铁线，可前往罗湖 Lo Wu 和落马洲 Lok Ma Chau）· 屯马线（屯马线）· 南港岛线（南港岛线）· 东涌线（东涌线）· 机场快线（机场快线）· 迪士尼线（迪士尼线）

---

⚠️ 局限

先说明这一点，因为隐瞒局限的工具就是在欺骗你的 Agent：

• 路线优化的是换乘次数，而非出行时间。 没有公布站间行车时间，因此我们只能针对实际可测的指标进行优化。有时，返回的路线只有 1 次换乘，但实际耗时可能比换乘 2 次的路线更长。
• 实时到站信息仅覆盖上车路段。 由于没有行车时间，我们无法判断你何时到达换乘站，因此提供后续路段的到站信息只是凭空捏造。
• 有 2 个车站没有实时数据。 上游 API 不提供天后或太子站的到站信息。路线可以经过这两个车站；系统会报告它们的到站信息不可用，而不会伪造数据。
• 高德工具需要你自己的密钥，且仅覆盖中国大陆。
• 跨境行程规划尚未实现。 东铁线可到达边境车站，但整合完整的香港→深圳行程属于路线图中的第 2 阶段。

---

🚀 快速开始

先决条件： Node.js >= 18

git clone https://github.com/arthurpanhku/DragonMCP.git
cd DragonMCP
npm install
npm run build

香港工具无需 .env。对于高德工具，请复制模板并添加密钥：

cp .env.example .env

连接到 Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "DragonMCP": {
      "command": "node",
      "args": ["/absolute/path/to/DragonMCP/dist/stdio.js"]
    }
  }
}

仅当你想使用中国大陆工具时，才添加 "env": { "AMAP_API_KEY": "your_key" }。

其他运行方式

npm run dev:stdio   # stdio transport, for local MCP clients
npm run dev         # HTTP server: Streamable HTTP at /mcp, legacy SSE at /mcp/sse
docker-compose up -d --build

在 stdio 模式下，stdin/stdout 承载 MCP JSON-RPC；诊断信息会输出到 stderr，以保持协议流干净。

---

🏗️ 架构

graph TD
    A[AI Agent Client] -->|MCP: stdio or HTTP| B[DragonMCP Server]
    B --> C[Tool Registry]

    C --> D["Hong Kong (no key)"]
    C --> E["Mainland China (Amap key)"]
    C --> F["Cross-border aggregator"]

    D -.-> G[data.gov.hk: MTR real-time]
    D -.-> H[HK Observatory]
    E -.-> I[Amap Web Service API]
    F -.-> D
    F -.-> E

---

🗺️ 路线图

第 1 阶段 — 来源溯源与零配置

• 每个工具响应都包含 source、fetched_at、freshness
• 发布到 npm，让 npx dragon-mcp 无需克隆项目或密钥即可运行
• 每日 CI 自测并提供状态徽章，公开验证“数据源今天仍在运行”

第 2 阶段 — 跨境

• MTR 换乘规划
• 边境检查站、广州—深圳—香港高速铁路、机场快线集成
• plan_cross_border_trip：一次调用即可规划跨越边境两侧的行程

第 3 阶段 — 覆盖范围

• 更多 data.gov.hk 数据源（巴士／渡轮预计到达时间、台风信号、空气质量）
• 澳门

---

🧪 测试

npm test          # unit + integration; hermetic, no network required
npm run check     # typecheck
npm run lint

如需改为验证实时上游服务，可通过任意 MCP 客户端调用 system_run_selftest 工具。

---

🤝 贡献

请参阅 CONTRIBUTING.md。

一条铁律：不要使用模拟工具。 返回伪造数据的工具比缺少工具更糟糕，因为 Agent 无法分辨两者。如果上游 API 不可用，正确做法不是注册该工具。

不错的起点：MTR 换乘规划、更多 data.gov.hk 数据源、东铁线和将军澳线的支线处理。

---

🙏 致谢

• Anthropic — 感谢其推出 Model Context Protocol
• MTR Corporation 和 data.gov.hk — 感谢提供开放的实时交通 API
• 香港天文台 — 感谢提供开放的天气 API
• 高德（Amap） — 感谢提供地图和路线规划服务

---

📄 许可证

MIT — 请参阅 LICENSE。