Skip to main content
Glama
Sign In
tods-mcp

tods-mcp

by aminamos
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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, 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).

Related MCP server: bus-scheduling-mcp

📦 Installation & CLI Usage

Build from source

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

Inspect a feed

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

Validate a feed

node dist/index.js validate ./test/fixtures/sample-tods-feed

View effective supplement merge diffs

node dist/index.js merge ./test/fixtures/sample-tods-feed --table stops.txt

List crew runs

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.):

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

📄 License

MIT © Amin

Available Tools

6 tools
tods_get_deadheadsC

Extracts deadheads, yard pulls, non-revenue positioning trips, and depot movements identified in trips_supplement.txt or run_events.txt.

Inputs: feed_path (required).

tods_get_runsA

Queries operational crew runs from run_events.txt. Returns chronological duty events, report/clear times, pieces of work, and total duty duration.

Inputs: feed_path (required), run_id, piece_id, service_id.

tods_get_vehicle_assignmentsC

Queries fleet vehicle assignments to blocks and dates from vehicle_assignments.txt and vehicles.txt.

Inputs: feed_path (required), date, block_id, vehicle_id.

tods_inspect_feedA

Inspects a TODS (Transit Operational Data Standard) directory or .zip feed. Returns high-level statistics, table list, supplement counts, crew runs, and fleet totals.

Inputs: feed_path (required).

tods_merge_supplementsC

Applies the official TODS v2.1.0 supplement merge algorithm (_supplement.txt files onto base GTFS files). Returns merge summary, additions, deletions, updates, and diffs.

Inputs: feed_path (required), table_name, sample_limit.

tods_validate_feedB

Runs comprehensive TODS v2.1.0 validation against the dataset: primary key uniqueness, foreign key consistency (run_events -> supplemented calendar/trips/stops), non-overlapping trip runs, time format/chronology, and TODS_delete rules.

Inputs: feed_path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct operation: inspection, merging, validation, and entity-specific queries for runs, vehicle assignments, and deadheads. There is no meaningful overlap because inspect/validate/merge have clearly different outputs and each get_ tool is scoped to a different TODS entity.

    Naming Consistency5/5

    All tools consistently use the tods_ prefix followed by a verb_noun pattern: inspect_feed, merge_supplements, validate_feed, get_runs, get_vehicle_assignments, get_deadheads. No mixed casing, inconsistent verbs, or irregular naming conventions are present.

    Tool Count5/5

    Six tools is a well-scoped count for a TODS-specific server. The set covers feed-level operations and targeted queries without redundancy or unnecessary bloat.

    Completeness4/5

    The surface covers the main TODS workflows: inspect, merge supplements, validate, and query core operational entities. Minor conveniences like a dedicated vehicle-only query or raw table access are missing, but these are workaroundable and do not create dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers