# tods-mcp 🚌

> **Transit Operational Data Standard (TODS v2.1.0)** Model Context Protocol (MCP) server, validator, supplement merge engine, and interactive CLI.

Standardized by [MobilityData](https://tods.mobilitydata.org), **TODS** extends public GTFS to represent the internal operational reality of transit systems: **crew run cuts, pieces of work, driver reliefs, deadheads / yard moves, and dated vehicle block rosters**.

`tods-mcp` connects LLMs (Antigravity, Claude Desktop, Cursor, Claude Code) and developers directly to transit operations datasets.

---

## 🚀 Features

- **⚡ Official Supplement Merge Engine:** Executes the TODS v2.1.0 supplement overlay algorithm (`_supplement.txt` on GTFS files) with support for row updates, insertions, and `TODS_delete=1` removals.
- **🩺 Automated Validator:** Checks primary key uniqueness, foreign key consistency against supplemented tables, temporal continuity (`start_time <= end_time`), and ensures operators are never scheduled for overlapping trips.
- **🧑‍✈️ Crew Run Inspector:** Decodes `run_events.txt` into chronological duties (report, clear, deadhead, trips, breaks, reliefs) with duty hour calculations.
- **🚍 Fleet & Block Assignments:** Queries physical fleet rosters and vehicle assignments to blocks by service date.
- **🤖 Built-in Agent Skill (`SKILL.md`):** Complete agent guide included for authoring and reasoning about TODS feeds.
- **🖥️ Dual Mode:** Runs as an MCP server via stdio or as an interactive CLI utility (`inspect`, `validate`, `merge`, `runs`).

---

## 📦 Installation & CLI Usage

### Build from source
```bash
git clone https://github.com/amin/tods-mcp.git # or local folder
cd tods-mcp
npm install
npm run build
```

### Inspect a feed
```bash
node dist/index.js inspect ./test/fixtures/sample-tods-feed
# Or if installed globally / linked:
tods inspect ./path/to/feed.zip
```

### Validate a feed
```bash
node dist/index.js validate ./test/fixtures/sample-tods-feed
```

### View effective supplement merge diffs
```bash
node dist/index.js merge ./test/fixtures/sample-tods-feed --table stops.txt
```

### List crew runs
```bash
node dist/index.js runs ./test/fixtures/sample-tods-feed
```

---

## 🛠️ MCP Tools Reference

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `tods_inspect_feed` | `feed_path` | High-level audit of GTFS base rows, supplement tables, crew runs, and vehicle counts. |
| `tods_merge_supplements` | `feed_path`, `table_name?`, `sample_limit?` | Merges supplement files onto GTFS base tables and provides diffs of added, modified, and deleted rows. |
| `tods_validate_feed` | `feed_path` | Validates primary/foreign keys, non-overlapping trip assignments, and time integrity. |
| `tods_get_runs` | `feed_path`, `run_id?`, `service_id?`, `piece_id?` | Returns chronological events for crew runs including duty durations and relief handoffs. |
| `tods_get_vehicle_assignments`| `feed_path`, `date?`, `block_id?`, `vehicle_id?` | Returns fleet vehicle assignments mapped to vehicle blocks. |
| `tods_get_deadheads` | `feed_path` | Lists non-revenue positioning trips, yard pulls, and depot moves. |

---

## ⚙️ MCP Configuration

Add to your `mcp_config.json` (Claude Desktop, Antigravity, Cursor, etc.):

```json
{
  "mcpServers": {
    "tods-mcp": {
      "command": "node",
      "args": ["E:/development/tods-mcp/dist/index.js", "serve"]
    }
  }
}
```

---

## 📄 License

MIT © Amin