Transport NSW

🚀 运输 NSW API 客户端（MCP 实现）

使用直接 HTTP 请求与运输 NSW API 交互的 Model Context Protocol (MCP) 服务实现。本项目可助力开发者便捷地与运输 NSW 的 API 进行交互，获取各类运输信息。

🚀 快速开始

设置步骤

1. 克隆此仓库。
2. 使用 uv（快速 Python 包管理器）安装依赖项：

   uv venv
   uv sync
   

3. 创建一个 .env 文件并添加您的 API 密钥：

   OPEN_TRANSPORT_API_KEY=your_api_key_here
   

4. （可选）运行 MCP 检查工具：

   uv run mcp dev api.py
   

   并访问服务器 http://localhost:5173（端口可能不同）。

✨ 主要特性

• 停靠站查找 API：通过名称或坐标查找运输停靠站。
• 警报 API：获取运输中断和警报信息。
• 出发监控 API：获取运输停靠站的实时出发信息。
• MCP 实现：作为 Model Context Protocol 服务结构化，允许 AI 模型通过标准化接口访问运输 NSW 数据。

📦 安装指南

依赖安装

使用 uv 安装依赖：

uv venv
uv sync

配置 API 密钥

创建 .env 文件并添加 API 密钥：

OPEN_TRANSPORT_API_KEY=your_api_key_here

💻 使用示例

基础用法

查找运输停靠站

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")  # Central Station ID

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

# 只获取火车出发信息
train_departures = get_departure_monitor("200060", mot_type=1)  # 1 = 火车

高级用法

MCP 示例即将推出。

📚 详细文档

演示脚本

该项目包含一个全面的演示脚本，展示所有 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。

包管理

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

• pyproject.toml：定义项目依赖。
• uv.lock：锁定依赖版本以确保可重复环境。