🚌 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
| 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
- 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
🎯 Roadmap
✅ Manual Acceptance Checklist
Version: 0.1.0
Status: Production Ready
Last Updated: 2024