# metrotransit-mcp

[![npm version](https://img.shields.io/npm/v/metrotransit-mcp.svg)](https://www.npmjs.com/package/metrotransit-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A unified **Model Context Protocol (MCP)**, **Command Line Interface (CLI)**, and **Agent Capabilities Protocol (ACP)** toolkit for **Metro Transit** in the Minneapolis–Saint Paul metropolitan area.

Connect your AI assistants (Claude Desktop, Cursor, Antigravity, custom agents) or query directly from your terminal for real-time bus & light rail departures, station search, route schedules, and live alerts.

**Zero API keys or signups required** — built on Metro Transit's open public REST API.

---

## What's Included

* 🔌 **MCP Server:** Stdio server implementing the official Model Context Protocol for Claude, Cursor, Antigravity, and other MCP clients.
* 💻 **Interactive CLI:** Beautiful terminal tool for departures, routes, directions, stops, and incident reports.
* 🤖 **ACP (Agent Capabilities Protocol):** Ready-to-use function calling declarations and execution handlers for OpenAI, Anthropic Claude, and Google Gemini agents.
* 📜 **Downloaded OpenAPI / Swagger Specs:** Full OpenAPI 3.0.4 definitions for NexTrip v2, Alerts v1, Trip Planner v1, and Schedule v1 included in `spec/`.

---

## 1. CLI Usage

You can run commands directly using `npx metrotransit-mcp <command>` or by installing globally (`npm i -g metrotransit-mcp`).

```bash
# List all routes or search by name/number
metrotransit routes
metrotransit routes green
metrotransit routes 94

# Show route travel directions
metrotransit directions 902

# List stops for a route in a specific direction (0 = EB/NB, 1 = WB/SB)
metrotransit stops 902 0

# Search for a station on a route
metrotransit search 902 "U.S. Bank"
metrotransit search 902 "Nicollet"

# Live countdown departure board by Stop ID (posted at bus stops & platforms)
metrotransit departures 51408

# Live countdown departure board by Route + Direction + Place Code
metrotransit departures 902 0 5SNI

# Check active detours, service advisories, and closures
metrotransit alerts
metrotransit alerts 902
metrotransit alerts 94 --keyword detour

# Inspect downloaded OpenAPI / Swagger specs
metrotransit spec
```

---

## 2. Model Context Protocol (MCP) Setup

### Run via NPX
```bash
npx metrotransit-mcp
```
*(When launched by an MCP client or without arguments on a piped stdio, it automatically starts the MCP server).*

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

#### macOS / Linux
```json
{
  "mcpServers": {
    "metrotransit": {
      "command": "npx",
      "args": ["-y", "metrotransit-mcp"]
    }
  }
}
```

#### Windows
```json
{
  "mcpServers": {
    "metrotransit": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "-y", "metrotransit-mcp"]
    }
  }
}
```

### Cursor / Antigravity / Other MCP Clients
```json
{
  "mcpServers": {
    "metrotransit": {
      "command": "node",
      "args": ["/path/to/metrotransit-mcp/dist/index.js", "mcp"]
    }
  }
}
```

### MCP Tools Provided
1. `list_routes` – List or search all Twin Cities transit routes.
2. `get_route_directions` – Get directional travel options (Eastbound/Westbound, Northbound/Southbound).
3. `get_route_stops` – Get all stations/stops and place codes for a route.
4. `search_stops` – Fuzzy search stations along a route.
5. `get_departures` – Live GPS countdowns, departure times, and stop alerts by 4–5 digit Stop ID or Route + Place Code.
6. `get_service_alerts` – Check active detours, stop closures, or incident advisories.

---

## 3. Agent Capabilities Protocol (ACP)

Need to equip a custom agent with Metro Transit tools without MCP?

Run:
```bash
# Output OpenAI function definitions
metrotransit acp --format openai

# Output Anthropic tool definitions
metrotransit acp --format anthropic

# Output Google Gemini tool declarations
metrotransit acp --format gemini
```

Or import directly in TypeScript / JavaScript:
```typescript
import {
  getOpenAITools,
  getAnthropicTools,
  getGeminiTools,
  executeAgentTool,
} from "metrotransit-mcp";

// 1. Pass tool definitions to your model
const tools = getOpenAITools();

// 2. Execute when tool is called
const result = await executeAgentTool("metrotransit_get_departures", {
  stop_id: 51408,
});
```

---

## 4. OpenAPI / Swagger Specs

The repository includes the official OpenAPI 3.0.4 schemas directly in the `spec/` folder:

* [`spec/nextrip-v2.json`](./spec/nextrip-v2.json): Real-time vehicle positions, arrival countdowns, and routes.
* [`spec/alerts-v1.json`](./spec/alerts-v1.json): Incident alerts, construction reroutes, and detours.
* [`spec/tripplanner-v1.json`](./spec/tripplanner-v1.json): Transit itinerary planning and geocoding.
* [`spec/schedule-v1.json`](./spec/schedule-v1.json): Static timetable schedules and planned stop details.

---

## Development & Testing

```bash
# Install dependencies
npm install

# Build
npm run build

# Run unit tests
npm test

# Test CLI
node dist/index.js departures 51408
```

---

## License

MIT © [Amin](https://github.com/aminamos)