Transport NSW

🚀 Transport NSW API Client (MCP Implementation)

This is a Model Context Protocol (MCP) service implementation that interacts with the Transport NSW API using direct HTTP requests.

📚 About

This project implements a Model Context Protocol service for the Transport NSW API.

📦 Installation

1. Clone this repository.
2. Install dependencies using uv (a fast Python package manager):

   uv venv
   uv sync
   

3. Create a .env file and add your API key:

   OPEN_TRANSPORT_API_KEY=your_api_key_here
   

4. (Optional) Run the MCP checker tool:

   uv run mcp dev api.py
   

   And access the server at http://localhost:5173 (the port may vary).

✨ Features

• Stop Finder API: Find transport stops by name or coordinates.
• Alerts API: Get information on transport disruptions and alerts.
• Departure Monitor API: Get real - time departure information for transport stops.
• MCP Implementation: Structured as a Model Context Protocol service.

💻 Usage Examples

MCP examples are coming soon. Here are standard Python examples:

Basic Usage

Find Transport Stops

from api import find_transport_stops

# Search by name
stops = find_transport_stops(stop_name="Central Station")

# Search by coordinates (Central Station area)
central_station = '151.206290:-33.884080:EPSG:4326'
stops = find_transport_stops(coord=central_station, radius=500)

Get Transport Alerts

from api import get_transport_alerts

# Get all current alerts
alerts = get_transport_alerts()

# Get alerts for a specific date
date_alerts = get_transport_alerts(date='22-03-2025')

# Get train alerts (mot_type=1)
train_alerts = get_transport_alerts(mot_type=1)

Monitor Real - Time Departure Information

from api import get_departure_monitor

# Get departure information for Central Station
departures = get_departure_monitor("200060")  # Central Station ID

# Get departure information for a specific time
from datetime import datetime
time_departures = get_departure_monitor("200060", time="15:30")

# Get only train departures
train_departures = get_departure_monitor("200060", mot_type=1)  # 1 = Train

🎬 Demo Script

This project includes a comprehensive demo script that demonstrates all API features:

# Run the full demo
python demo.py

# Run specific parts
python demo.py --stops       # Stop finder demo
python demo.py --alerts      # Transport alerts demo
python demo.py --departures  # Departure monitor demo

🧪 Testing

Local Testing

Run the full test suite using pytest:

uv run pytest

Tests with coverage report:

uv run pytest --cov=api

Continuous Integration

GitHub Actions automatically run tests for each push to the main branch and for pull requests. The workflow is as follows:

1. Set up a Python 3.10 environment.
2. Install uv and project dependencies.
3. Run tests with a coverage report.

To use this feature:

1. Add OPEN_TRANSPORT_API_KEY as a GitHub repository secret.
2. Push your code to GitHub.

🔗 MCP Integration

This project follows the Model Context Protocol specification, allowing AI models to access Transport NSW data through a standardized interface.

📦 Package Management

This project uses uv, a modern Python package manager written in Rust. Dependencies are managed as follows:

• pyproject.toml: Defines project dependencies.
• uv.lock: Locks dependency versions to ensure a reproducible environment.