readme.md•7.5 kB
# TMB Bus Arrival Times MCP Server
A Model Context Protocol (MCP) server that provides real-time bus arrival information for TMB (Transports Metropolitans de Barcelona) bus stops.
## 🚀 Features
- **Real-time bus arrivals**: Get up-to-date information about when buses will arrive
- **Multiple lines support**: See all bus lines serving a stop
- **Time in minutes**: Arrival times shown in minutes for easy understanding
- **Detailed information**: Line numbers, destinations, directions, and bus IDs
- **MCP compliant**: Works with any MCP client including Claude Desktop
## 📋 Prerequisites
- Node.js 18+
- npm or yarn
- TMB API credentials (get them at https://developer.tmb.cat/)
## 🔧 Installation
1. **Clone or create the project:**
```bash
mkdir tmb-bus-mcp
cd tmb-bus-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Set up your TMB API credentials:**
```bash
# Copy the example environment file
cp .env.example .env
# Edit .env and add your credentials
# TMB_APP_ID=your_app_id
# TMB_APP_KEY=your_app_key
```
4. **Build the project:**
```bash
npm run build
```
## 🎯 Usage
### Option 1: Using the Client (Testing)
The client is perfect for testing and development:
```bash
# Set environment variables
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
# Query a specific bus stop
npm run client 2775
# List available tools
npm run client -- list
```
**Example output:**
```
🚌 Bus Stop: Pl Espanya - FGC (108)
📅 Query Time: 11/6/2025, 10:30:00 AM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚍 Line H12 (212) → Gornal
Direction: return
Next arrivals:
• ⏱️ 2 min (at 10:32:00) - Bus #3673
• ⏱️ 16 min (at 10:46:00) - Bus #8531
```
### Option 2: Using with Claude Desktop
Add the server to your Claude Desktop configuration:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"tmb-bus": {
"command": "node",
"args": ["/absolute/path/to/tmb-bus-mcp/dist/server.js"],
"env": {
"TMB_APP_ID": "your_app_id",
"TMB_APP_KEY": "your_app_key"
}
}
}
}
```
Then restart Claude Desktop. You can now ask Claude things like:
- "What buses are coming to stop 2775?"
- "When is the next bus at Pl Espanya?"
- "Show me all bus arrivals for stop 108"
### Option 3: Using the Host (Standalone)
Run the server independently:
```bash
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
npm run host
```
## 🛠️ Architecture Explained
### MCP Server (`src/server.ts`)
The core component that:
- Exposes the `get_bus_arrivals` tool via MCP protocol
- Handles communication with TMB's iBus API
- Transforms raw API responses into user-friendly formats
- Runs on stdio transport for easy integration
**Key responsibilities:**
- Tool registration and discovery
- Request validation
- API communication with error handling
- Data transformation and formatting
### Host Application (`src/host.ts`)
A simple wrapper that:
- Starts the MCP server as a child process
- Manages environment variables
- Handles graceful shutdown
**When to use:** For standalone deployment or testing without an MCP client.
### Client Application (`src/client.ts`)
A demonstration client that:
- Connects to the MCP server via stdio
- Lists available tools
- Calls tools with parameters
- Displays formatted results
**When to use:** For testing, development, or as a reference implementation.
## 🔌 API Integration Details
The server connects to TMB's iBus API:
**Endpoint:** `https://api.tmb.cat/v1/itransit/bus/parades/{stopCode}`
**Parameters:**
- `app_id`: Your TMB application ID
- `app_key`: Your TMB application key
**Response structure:**
```javascript
{
timestamp: number, // Query timestamp
parades: [{
codi_parada: string, // Stop code
nom_parada: string, // Stop name
linies_trajectes: [{ // Lines serving this stop
codi_linia: string, // Line code
nom_linia: string, // Line name
desti_trajecte: string, // Destination
id_sentit: number, // 1=Outbound, 2=Return
propers_busos: [{ // Upcoming buses
temps_arribada: number, // Arrival timestamp
id_bus: number // Bus identifier
}]
}]
}]
}
```
## 📝 Type Safety
The project uses TypeScript with strict type checking. All API responses are properly typed in `src/types.ts`:
- `TMBApiResponse`: Raw API response structure
- `BusStopInfo`: Transformed, user-friendly format
- `FormattedBusArrival`: Individual line information
## 🧪 Testing Different Bus Stops
Try these Barcelona bus stops:
- `2775`: Random stop
- `108`: Pl Espanya - FGC
- `1`: Pl Catalunya
- `2554`: Sagrada Família
## 🔍 How It Works
1. **Client Request**: An MCP client (like Claude) calls the `get_bus_arrivals` tool with a stop code
2. **Server Processing**: The MCP server receives the request via stdio transport
3. **API Query**: Server makes an authenticated request to TMB's iBus API
4. **Data Transformation**: Raw API response is transformed into a readable format
5. **Time Calculation**: Arrival timestamps are converted to "minutes until arrival"
6. **Response**: Formatted text is returned to the client
```
┌─────────┐ ┌──────────┐ ┌─────────┐
│ Client │────────▶│ MCP │────────▶│ TMB │
│ (Claude)│ │ Server │ │ API │
└─────────┘ └──────────┘ └─────────┘
▲ │ │
│ ▼ │
│ Transform Data │
│ │ │
└────────────────────┴────────────────────┘
```
## 🚦 Error Handling
The server handles various error scenarios:
- **Missing credentials**: Exits with clear error message
- **Invalid stop code**: Returns user-friendly error
- **API errors**: Catches and formats API error responses
- **Network issues**: Handles timeout and connection errors
## 🔐 Security Notes
- Never commit your `.env` file or API credentials
- The `.env.example` file shows the format without real credentials
- Credentials are passed via environment variables, not hardcoded
- Use MCP's built-in transport security for production deployments
## 📚 MCP Protocol Details
This server implements MCP (Model Context Protocol):
- **Transport**: stdio (standard input/output)
- **Capabilities**: Tools
- **Tool Name**: `get_bus_arrivals`
- **Input**: `{ stopCode: string }`
- **Output**: Formatted text with bus arrival information
## 🤝 Contributing
To extend this server:
1. Add new tools in `server.ts` `getTools()` method
2. Implement handlers in `handleToolCall()`
3. Update types in `types.ts` as needed
4. Test with the client application
## 📄 License
MIT
## 🙏 Credits
- TMB API: https://developer.tmb.cat/
- MCP SDK: https://github.com/anthropics/modelcontextprotocol
---
**Questions?** Check the MCP documentation at https://modelcontextprotocol.io/