Metadata-Version: 2.5
Name: yyc-transit-mcp
Version: 0.1.0
Summary: MCP server for Calgary Transit: live arrivals, alerts, and historical route reliability from GTFS + GTFS-Realtime.
Project-URL: Homepage, https://github.com/Abiolr/calgary-transit-MCP
Project-URL: Repository, https://github.com/Abiolr/calgary-transit-MCP
Project-URL: Issues, https://github.com/Abiolr/calgary-transit-MCP/issues
Project-URL: Changelog, https://github.com/Abiolr/calgary-transit-MCP/blob/main/CHANGELOG.md
Author: Abiola Raji
License-Expression: MIT
License-File: LICENSE
Keywords: calgary,gtfs,gtfs-realtime,mcp,model-context-protocol,transit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: alembic>=1.13
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: gtfs-realtime-bindings>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.3
Requires-Dist: psycopg[binary,pool]>=3.2
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: structlog>=24.1
Requires-Dist: tzdata>=2026.5
Provides-Extra: agent
Requires-Dist: anthropic>=0.40; extra == 'agent'
Description-Content-Type: text/markdown

# yyc-transit-mcp

[![CI](https://github.com/Abiolr/calgary-transit-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Abiolr/calgary-transit-MCP/actions/workflows/ci.yml)

<!-- mcp-name: io.github.Abiolr/yyc-transit-mcp -->

An [MCP](https://modelcontextprotocol.io) server that lets AI assistants answer
**"when's my bus, and can I trust it?"** with Calgary Transit data:
- live arrivals;
- service alerts;
- bus positions;
- **historical on-time reliability**, which it measures itself from the live feeds.

> **When's the next 3 at Centre St and 16 Ave?**
> The next Route 3 at Centre St and 16 Ave is the northbound one at **11:52 PM** tonight,
> but that time is scheduled only, with no live tracking. The next live-tracked northbound
> buses are at 12:26 AM and 12:51 AM.
>
> **How reliable is route 1?**
> About 85.8% of observed trips were on time (within 1 minute early to 5 minutes late)…
> However, this is based on only 1 day of data (239 observations), so the history is too
> short to be a solid measure.
>
> **Plan me a trip from Tuscany to the airport with two transfers.**
> I can't plan multi-leg trips with transfers… Calgary Transit's trip planner or app can do that.

<sub>These are real answers from the [eval suite](#evals) (Claude Haiku 5.5), lightly trimmed.</sub>

## Tools

| Tool | What it answers |
|---|---|
| `find_stops` | Stops by name ("Centre St and 16 Ave"), stop number ("#4585") or location, with the routes serving each |
| `next_arrivals` | Next arrivals at a stop in the next 3 hours: live, scheduled or cancelled |
| `route_alerts` | Active detours, closures and delays for a route or stop |
| `vehicles_on_route` | Live bus positions on a route, with headsign and delay |
| `route_reliability` | Historical on-time %, median and 90th-percentile delay, by time of day |
| `compare_routes` | Reliability for two routes side by side |

- **Route names:** riders can name routes the way they say them: "3", "route 3", "MAX Teal", "Red Line".
- **Times:** all times are Calgary local time.
- **Freshness:** every response says how fresh its data is (`meta.data_as_of`, `meta.is_stale`). Live predictions are withheld when the City's feed is stale.
- **Read-only:** every tool only reads data.

**Limitations**
- Calgary Transit only.
- Direct routes only; no trip planning with transfers.
- The City doesn't publish CTrain positions; CTrain arrivals and alerts work.
- CTrain reliability isn't measured yet: the City's CTrain predictions are an hour off, and
  live arrivals correct for it, but the history waits until the correction is verified.
- Reliability is computed from history the worker collects, so it needs a few days of running before the numbers mean much. Until then, results say `enough_data: false`.

## How it fits together

```
City of Calgary open data            your machine / server
───────────────────────────          ───────────────────────────────────────────
static GTFS (nightly)  ──▶  worker ──▶  Postgres + PostGIS  ◀──  MCP server  ◀──  Claude
GTFS-Realtime (30 s)   ──▶           (schedule, live state,       (6 tools)
                                      delay history)
```

The **worker** has to run all the time: it keeps the live state current and writes the delay
history that reliability is computed from. The **MCP server** only reads the database.

## Quick start (Docker)

Needs Docker. This starts the database, runs the migrations, loads the schedule (about a
minute) and starts polling the live feeds:

```bash
git clone https://github.com/Abiolr/calgary-transit-MCP.git
cd calgary-transit-MCP
docker compose up -d
docker compose logs -f worker    # wait for "rt_poll.done" lines
```

The MCP server is now at `http://localhost:8000/mcp`.

### Connect your assistant

**Claude Code:**
```bash
claude mcp add --transport http yyc-transit http://localhost:8000/mcp
```

**Claude Desktop**, or any client that launches servers over stdio: run the server with
[uv](https://docs.astral.sh/uv/) and point it at the database:

```json
{
  "mcpServers": {
    "yyc-transit": {
      "command": "uvx",
      "args": ["yyc-transit-mcp"],
      "env": { "DATABASE_URL": "postgresql://transit:transit@localhost:5432/transit" }
    }
  }
}
```

To try it without a client, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
`npx @modelcontextprotocol/inspector`, then connect to `http://localhost:8000/mcp`.

## Install without Docker

You need Postgres 16 with PostGIS 3.

```bash
pip install yyc-transit-mcp            # or: uv tool install yyc-transit-mcp
export DATABASE_URL=postgresql://user:pass@host:5432/transit
yyc-transit-migrate                     # create or upgrade the schema
yyc-transit-worker                      # load the schedule, then poll; keep it running
yyc-transit-mcp                         # MCP server over stdio (default)
yyc-transit-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

| Command | What it does |
|---|---|
| `yyc-transit-migrate` | Creates or upgrades the database schema |
| `yyc-transit-worker` | Always-on: loads the schedule nightly and polls the live feeds every 30 s |
| `yyc-transit-ingest --download` | Loads the latest schedule once (the worker does this for you) |
| `yyc-transit-mcp` | The MCP server (`--transport stdio` or `streamable-http`) |
| `yyc-transit-agent "question"` | Asks Claude a question through the tools. Needs `pip install "yyc-transit-mcp[agent]"` and `ANTHROPIC_API_KEY` |

### Configuration

Set these as environment variables, or in a `.env` file in the working directory:

| Variable | Default | |
|---|---|---|
| `DATABASE_URL` | `postgresql://transit:transit@localhost:5432/transit` | Postgres + PostGIS |
| `RT_POLL_SECONDS` | `30` | How often the worker polls the live feeds |
| `RT_STALE_AFTER_SECONDS` | `120` | Live data older than this is reported as stale |
| `GTFS_STATIC_URL`, `GTFS_RT_*_URL` | City of Calgary open data | Feed locations |
| `ANTHROPIC_API_KEY` | | Only for `yyc-transit-agent` |
| `AGENT_MODEL` | `claude-haiku-5-5` | Model used by `yyc-transit-agent` |

### Hosting

Run the worker on an always-on host; if it sleeps, the reliability history gets gaps.
- **Resource use:** about 70 MB of RAM for the worker and about 300 MB for Postgres.
- **History growth:** tens of MB a day.
- **Railway:** a PostGIS template plus this repo's `Dockerfile` (start command
  `yyc-transit-worker`, pre-deploy `yyc-transit-migrate`) works as is.

## Evals

The repo includes an eval suite that measures how well an LLM uses the tools: 40 rider
questions covering:
- stops, arrivals, alerts, vehicles, reliability and comparisons;
- questions out of scope that it should decline;
- questions it should answer with honest uncertainty.

Ground truth comes from SQL against a frozen database snapshot, never from an LLM.

Claude Haiku 5.5, 40 cases × 3 runs:

| | Baseline | Now |
|---|---|---|
| Answer correct | 94.2% (95% CI 88–97%) | **100%** (95% CI 97–100%) |
| Right tools called | 100% | **100%** |
| Latency p50 / p95 | 2.6 s / 6.1 s | 2.2 s / 4.3 s |
| Tool calls per question | 1.2 | 1.2 |
| Cost of a full run | about $0.08 | about $0.08 |

All 7 baseline failures were arrival questions, caused by the tools rather than the model:
- **City Hall:** a bus stop named "City Hall LRT Station" ranked above the CTrain platforms,
  which were listed as routes "201" and "202".
- **MAX Teal:** results showed the route code "MT" without the name "MAX Teal".

The fixes:
- CTrain and MAX lines are shown by name (`Red Line (201)`, `MAX Teal (MT)`);
- station searches list CTrain platforms first;
- `find_stops` takes a `route`, so a station's many bays narrow to the ones that route serves.

The suite is small, so 100% means these 40 questions pass, not that every question will.

Results are in [`.claude/hillclimb/transit-agent/`](https://github.com/Abiolr/calgary-transit-MCP/tree/main/.claude/hillclimb/transit-agent)
(`baseline/`, then `v1/` and `v2/`);
how to run the suite is in [CONTRIBUTING.md](https://github.com/Abiolr/calgary-transit-MCP/blob/main/CONTRIBUTING.md#evals).

## More

- [How it works](https://github.com/Abiolr/calgary-transit-MCP/blob/main/docs/how-it-works.md): schema, the live feed's quirks and how they're cleaned, measurements
- [CONTRIBUTING.md](https://github.com/Abiolr/calgary-transit-MCP/blob/main/CONTRIBUTING.md): development setup, tests, evals
- [CHANGELOG.md](https://github.com/Abiolr/calgary-transit-MCP/blob/main/CHANGELOG.md)

## Data & licence

Contains information licensed under the
Open Government Licence – City of Calgary
([City of Calgary open data](https://data.calgary.ca)).
Every tool response carries this attribution. The data is fetched from the City at run time
and isn't included in this package.

The code is MIT licensed; see [LICENSE](https://github.com/Abiolr/calgary-transit-MCP/blob/main/LICENSE). This project is not affiliated with
Calgary Transit or the City of Calgary.
