CATA Bus MCP Server

by pranav-karra-3301

開発ツール

Provides real-time and scheduled bus data for the Centre Area Transportation Authority (CATA) in State College, PA. Enables users to track live bus positions, get arrival predictions, search stops, view routes, and receive service alerts through natural language queries.

GitHubで見る

🚌 CATA Bus MCP Server

A Model Context Protocol (MCP) server that provides live and static schedule data for the Centre Area Transportation Authority (CATA) bus system in State College, PA.

🌟 Features

Real-time vehicle positions - Track buses live on their routes
Trip updates - Get delay information and predicted arrivals
Service alerts - Stay informed about detours and disruptions
Static schedule data - Access routes, stops, and scheduled times
Fast in-memory storage - No database required, pure Python performance

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/catabus-mcp.git
cd catabus-mcp

# Install dependencies
pip install -e .

Running the Server

# Run in stdio mode (for MCP clients)
python -m catabus_mcp.server

# Run in HTTP mode (for testing)
python -m catabus_mcp.server --http

The HTTP server will be available at http://localhost:7000

🛠️ Available Tools

Tool	Description	Parameters
`list_routes`	Get all bus routes	None
`search_stops`	Find stops by name/ID	`query: string`
`next_arrivals`	Get upcoming arrivals at a stop	`stop_id: string`, `horizon_minutes?: int`
`vehicle_positions`	Track buses on a route	`route_id: string`
`trip_alerts`	Get service alerts	`route_id?: string`

💻 API Examples

Using with cURL (HTTP mode)

# List all routes
curl -X POST http://localhost:7000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"list_routes_tool","params":{}}'

# Search for stops
curl -X POST http://localhost:7000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"search_stops_tool","params":{"query":"HUB"}}'

# Get next arrivals
curl -X POST http://localhost:7000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"next_arrivals_tool","params":{"stop_id":"PSU_HUB","horizon_minutes":30}}'

Integration with ChatGPT

Install the MCP client in ChatGPT
Add this server configuration:

{
  "name": "catabus",
  "command": "python",
  "args": ["-m", "catabus_mcp.server"],
  "description": "CATA bus schedule and realtime data"
}

Ask questions like:
- "When is the next N route bus from the HUB?"
- "Are there any service alerts for the V route?"
- "Show me all buses currently on the W route"

Integration with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "catabus": {
      "command": "python",
      "args": ["-m", "catabus_mcp.server"]
    }
  }
}

🧪 Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=catabus_mcp

Code Quality

# Format code
black src/

# Lint
ruff check src/

# Type checking
mypy src/catabus_mcp/

📊 Data Sources

This server uses official CATA data feeds:

Static GTFS: https://catabus.com/wp-content/uploads/google_transit.zip
GTFS-Realtime Vehicle Positions: https://realtime.catabus.com/InfoPoint/GTFS-Realtime.ashx?Type=VehiclePosition
GTFS-Realtime Trip Updates: https://realtime.catabus.com/InfoPoint/GTFS-Realtime.ashx?Type=TripUpdate
GTFS-Realtime Alerts: https://realtime.catabus.com/InfoPoint/GTFS-Realtime.ashx?Type=Alert

Data is cached locally and updated:

Static GTFS: Daily
Realtime feeds: Every 15 seconds

🏗️ Architecture

catabus-mcp/
├── src/catabus_mcp/
│   ├── ingest/          # Data loading and polling
│   │   ├── static_loader.py
│   │   └── realtime_poll.py
│   ├── tools/           # MCP tool implementations
│   │   ├── list_routes.py
│   │   ├── search_stops.py
│   │   ├── next_arrivals.py
│   │   ├── vehicle_positions.py
│   │   └── trip_alerts.py
│   └── server.py        # FastMCP server
└── tests/               # Test suite

⚡ Performance

Warm cache response time: < 100ms for all queries
Memory usage: ~50MB with full GTFS data loaded
Rate limiting: Respects CATA's 10-second minimum between requests

📝 License

MIT License - See LICENSE file

🙏 Attribution

Transit data provided by Centre Area Transportation Authority (CATA). This project is not affiliated with or endorsed by CATA.

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass
Submit a pull request

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

🎯 Roadmap

Add trip planning capabilities
Support for accessibility features
Historical data analysis
Geospatial queries (nearest stop)
Multi-agency support

✅ Manual Acceptance Checklist

Version: 0.1.0
Status: Production Ready
Last Updated: 2024