Transport NSW API 客户端 (MCP 实现)

一个使用直接 HTTP 请求与 Transport NSW API 交互的 Claude MCP。

关于

本项目为 Transport NSW 的 API 实现了一个模型上下文协议 (MCP) 服务。

设置

1. 克隆此仓库
2. 使用 uv (快速 Python 包管理器) 安装依赖项:

   uv venv
   uv sync
   

3. 创建一个包含您的 API 密钥的 .env 文件:

   OPEN_TRANSPORT_API_KEY=your_api_key_here
   

4. (可选) 运行 MCP Inspector:

   uv run mcp dev api.py
   

   并访问 http://localhost:5173 (端口可能不同)。

功能

• Stop Finder API: 通过名称或坐标查找交通站点
• Alerts API: 获取有关交通警报和中断的信息
• Departure Monitor API: 获取交通站点的实时出发信息
• MCP 实现: 结构化为模型上下文协议服务

使用示例

MCP 示例即将推出。 以下是标准 Python 示例：

查找交通站点

from api import find_transport_stops

# 按名称搜索
stops = find_transport_stops(stop_name="Central Station")

# 按坐标搜索 (中央车站区域)
central_station = '151.206290:-33.884080:EPSG:4326'
stops = find_transport_stops(coord=central_station, radius=500)

获取交通警报

from api import get_transport_alerts

# 获取所有当前警报
alerts = get_transport_alerts()

# 获取特定日期的警报
date_alerts = get_transport_alerts(date='22-03-2025')

# 仅获取火车警报 (mot_type=1)
train_alerts = get_transport_alerts(mot_type=1)

监控实时出发

from api import get_departure_monitor

# 获取从中央车站出发的班次
departures = get_departure_monitor("200060")  # 中央车站 ID

# 获取特定时间的出发班次
from datetime import datetime
time_departures = get_departure_monitor("200060", time="15:30")

# 仅获取火车出发班次
train_departures = get_departure_monitor("200060", mot_type=1)  # 1 = 火车

演示脚本

该项目包含一个全面的演示脚本，展示了所有 API 功能：

# 运行完整演示
python demo.py

# 运行特定部分
python demo.py --stops       # 站点查找演示
python demo.py --alerts      # 交通警报演示
python demo.py --departures  # 出发监控演示

测试

本地测试

使用 pytest 运行完整的测试套件：

uv run pytest

运行并生成覆盖率报告：

uv run pytest --cov=api

持续集成

测试会在每次推送和拉取请求到主分支时自动在 GitHub Actions 上运行。 工作流程：

1. 设置 Python 3.10
2. 安装 uv 和项目依赖项
3. 运行测试并生成覆盖率报告

要使用此功能：

1. 将您的 OPEN_TRANSPORT_API_KEY 添加为 GitHub 仓库密钥
2. 将您的代码推送到 GitHub

MCP 集成

本项目遵循模型上下文协议规范，允许 AI 模型通过标准化接口访问 Transport NSW 数据。

包管理

本项目使用 uv，一种用 Rust 编写的现代 Python 包管理器。 依赖项通过以下方式管理：

• pyproject.toml: 定义项目依赖项
• uv.lock: 锁定依赖项版本以实现可重现的环境