# MBTA Worcester Line MCP Server

An MCP (Model Context Protocol) server that provides real-time train schedule information for the MBTA Worcester Line. Built with Next.js and deployable on Vercel.

## Features

- Real-time train departures from any Worcester Line station
- Merges scheduled times with live predictions
- Supports all 18 Worcester Line stops
- Works with Gemini CLI and other MCP clients

## Quick Start

### 1. Get an MBTA API Key

Get a free API key at: https://api-v3.mbta.com

### 2. Install Dependencies

```bash
npm install
```

### 3. Configure Environment

Copy `.env.example` to `.env.local` and add your MBTA API key:

```bash
MBTA_API_KEY=your-mbta-api-key-here
MCP_API_KEY=your-secret-token  # Optional: for authentication
```

### 4. Run Locally

```bash
npm run dev
```

### 5. Test the MCP Server

```bash
npm run test:mcp
```

## Deployment

### Deploy to Vercel

1. Push to GitHub
2. Import to Vercel
3. Add environment variables:
   - `MBTA_API_KEY`: Your MBTA API key
   - `MCP_API_KEY`: Secret token for authentication (optional)

## Client Configuration

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "mbta": {
      "httpUrl": "https://your-app.vercel.app/api",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      },
      "timeout": 30000
    }
  }
}
```

Or via CLI:
```bash
gemini mcp add --transport http mbta https://your-app.vercel.app/api
```

### Claude Desktop (via mcp-remote)

```json
{
  "mcpServers": {
    "mbta": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-app.vercel.app/api/mcp"]
    }
  }
}
```

## Available Tools

### get_worcester_departures

Get upcoming train departures from any Worcester Line station.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `stop` | string | Yes | Stop name or ID (e.g., "South Station", "framingham") |
| `direction` | string | No | "outbound" (toward Worcester) or "inbound" (toward Boston). Default: "outbound" |
| `date` | string | No | Date in YYYY-MM-DD format. Default: today |
| `limit` | number | No | Number of departures (1-20). Default: 5 |

**Example queries:**
- "What trains leave South Station for Worcester?"
- "Get next trains from Framingham to Boston"
- "What trains leave Westborough tomorrow morning?"

## Worcester Line Stops

South Station, Back Bay, Lansdowne, Boston Landing, Newtonville, West Newton, Auburndale, Wellesley Farms, Wellesley Hills, Wellesley Square, Natick Center, West Natick, Framingham, Ashland, Southborough, Westborough, Grafton, Worcester

## Project Structure

```
src/
├── app/
│   ├── api/[transport]/route.ts  # MCP handler
│   └── page.tsx                   # Status page
├── lib/
│   ├── mbta/
│   │   ├── client.ts             # MBTA API client
│   │   ├── types.ts              # TypeScript types
│   │   └── stops.ts              # Stop ID mappings
│   └── mcp/
│       ├── auth.ts               # Authentication
│       └── tools/                # MCP tools
│           ├── get-departures.ts
│           └── index.ts
```

## License

MIT