mbta-mpc-server

# MBTA MCP Server Specification ## Overview The MBTA MCP Server is a Machine Learning Control Protocol (MCP) server that integrates with the Massachusetts Bay Transportation Authority (MBTA) API to provide Boston-area transit information. This server allows AI assistants to access real-time and scheduled transit data for the MBTA system, enabling users to query for transit information through conversational interfaces. ## Goals - Provide a seamless interface between AI assistants and the MBTA API - Enable transit information queries through natural language - Support trip planning and route finding, including alternatives during delays - Deliver real-time service updates and alerts ## Technical Architecture ### Core Components 1. **MCP Server Implementation** - Built with Go programming language - Uses the mcp-go module (https://github.com/mark3labs/mcp-go) - Implements stdio protocol for local usage 2. **MBTA API Integration** - Connects to the MBTA API v3 (https://api-v3.mbta.com/) - Uses API key authentication - Handles rate limiting and API errors according to MCP best practices 3. **Data Processing** - Simplifies complex MBTA API data structures for easier consumption by AI assistants - Formats responses as JSON - Processes real-time updates for service disruptions, delays, and schedule changes ### Features & Capabilities #### Core Features - **Transit Information Retrieval** - Routes and schedules - Real-time arrival/departure predictions - Service alerts and disruptions - Station and stop information - Vehicle locations - Accessibility information (elevator status, accessible stations) - Available fare information (with limitations based on API) #### Use Cases - **Trip Planning** - Find optimal routes between locations - Calculate estimated travel times - Identify transfer points - **Service Disruption Handling** - Identify alternate routes during delays - Provide real-time updates on service status - Explain reasons for delays when available - **Accessibility Information** - Check accessibility status of stations - Find accessible routes and alternatives - **Geographic Queries** - Find nearest stations to locations - Identify routes serving specific areas or destinations ### Data Model The server will expose simplified versions of the following MBTA API resources: - Routes - Stops - Trips - Schedules - Predictions - Vehicles - Alerts - Facilities (for accessibility information) - Available fare information ### Error Handling Following MCP community best practices: - Return standardized error response objects with proper HTTP status codes - Include descriptive error messages and error codes - Implement graceful degradation when the MBTA API is unavailable - Log detailed error information for troubleshooting - Include retry mechanisms for transient errors ### Logging Implement standard logging with multiple levels: - Error: Critical issues that prevent operation - Warning: Problems that don't prevent operation but require attention - Info: General operational information - Debug: Detailed information for troubleshooting - Trace: Very detailed diagnostic information ## Deployment Options ### Docker Container - Build using a minimal "FROM scratch" approach - Include the Go binary directly - Provide Docker Compose configuration for easy setup ### Standalone Binary - Cross-compile for major platforms (Linux, macOS, Windows) - Provide installation and setup documentation ## Documentation ### End-User Documentation - Installation instructions for both Docker and standalone approaches - Configuration options - Examples of common queries and interactions - Troubleshooting guide ### Developer Documentation - API reference - Architecture overview - Contribution guidelines - Testing instructions ## Testing Strategy Implement a thorough test suite including: - Unit tests for core functionality - Integration tests with the MBTA API - End-to-end tests simulating assistant interactions - Mocked API responses for testing error conditions ## Future Considerations - Data caching to improve performance and reduce API calls - Enhanced historical data analysis for route recommendations - Expanded fare information if API support improves - User preferences and personalization if MCP protocol supports it ## Implementation Timeline - Immediate development with focus on core functionality first - Iterative releases with expanding feature set - Prioritize reliability and accuracy over comprehensive coverage initially ## Development Practices - Follow Go best practices and idiomatic code patterns - Implement continuous integration for automated testing - Maintain comprehensive documentation - Use semantic versioning for releases