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：鎖定依賴版本以確保可重複環境。