cats-mcp 1.0.0__tar.gz

cats_mcp-1.0.0/.env.example

@@ -0,0 +1,23 @@
+# HTTP transport with Google OAuth. Copy to .env and fill in; .env is gitignored.
+# Not needed for the stdio transport.
+
+CATS_TRANSPORT=http
+
+# From an OAuth 2.0 "Web application" client at
+# https://console.cloud.google.com/apis/credentials
+# Its authorized redirect URI must be exactly <CATS_PUBLIC_URL>/auth/google/callback
+CATS_GOOGLE_CLIENT_ID=
+CATS_GOOGLE_CLIENT_SECRET=
+
+# Who may use the server. At least one of these three is required; without one
+# the server refuses to start rather than admitting every Google account.
+CATS_ALLOWED_EMAILS=you@example.com
+# CATS_ALLOWED_DOMAINS=example.com
+# CATS_ALLOW_ANY_GOOGLE_ACCOUNT=false
+
+# The externally reachable origin: what clients dial, and this server's OAuth
+# issuer. Must be https unless it is loopback.
+CATS_PUBLIC_URL=https://cats.example.com
+
+# CATS_HTTP_HOST=127.0.0.1
+# CATS_HTTP_PORT=8000

cats_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  # So the release workflow can gate a publish on this same suite.
+  workflow_call:
+
+permissions:
+  contents: read
+
+# A newer push to the same branch makes an in-flight run redundant.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          # The version pyproject targets for ruff and mypy.
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - run: ruff check
+      - run: ruff format --check
+      - run: mypy

cats_mcp-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Release
+
+# Cutting a version means pushing a tag: `git tag v1.0.1 && git push origin v1.0.1`.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # PyPI refuses a re-upload, so a version mismatch is unrecoverable under that
+  # tag. Catch it before anything is built.
+  check-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          # tomllib needs 3.11+; don't depend on the runner's default.
+          python-version: "3.11"
+      - name: Tag must match pyproject.toml and server.json
+        run: |
+          python - <<'PY'
+          import json, os, sys, tomllib
+
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          server = json.load(open("server.json"))
+          found = {
+              "pyproject.toml": tomllib.load(open("pyproject.toml", "rb"))["project"]["version"],
+              "server.json (version)": server["version"],
+              "server.json (packages[0].version)": server["packages"][0]["version"],
+          }
+          bad = {where: got for where, got in found.items() if got != tag}
+          for where, got in bad.items():
+              print(f"::error::tag is {tag} but {where} is {got}")
+          sys.exit(1 if bad else 0)
+          PY
+
+  test:
+    needs: check-version
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    # Must match the environment named in the PyPI trusted publisher.
+    environment: pypi
+    permissions:
+      # Mints the short-lived OIDC token PyPI trusts. No API token to store.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - name: Check the built distributions
+        run: pipx run twine check --strict dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-registry:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      # mcp-publisher trades this for a registry token; no secret to store.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - name: Wait for the release to be visible on PyPI
+        # The registry verifies the mcp-name marker by reading the package
+        # description off PyPI, so it has to be able to see this version.
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          for attempt in $(seq 1 20); do
+            if curl -sf "https://pypi.org/pypi/cats-mcp/$version/json" > /dev/null; then
+              echo "cats-mcp $version is on PyPI"
+              exit 0
+            fi
+            echo "attempt $attempt: not visible yet, retrying in 15s"
+            sleep 15
+          done
+          echo "::error::cats-mcp $version never appeared on PyPI"
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Authenticate to the MCP Registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish to the MCP Registry
+        run: ./mcp-publisher publish
+
+  github-release:
+    needs: [publish, publish-registry]
+    runs-on: ubuntu-latest
+    permissions:
+      # Creating the release writes to the repo.
+      contents: write
+    steps:
+      # Only so gh infers the repository; the notes come from the API.
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes

cats_mcp-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.log
+.env

cats_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.5
+Name: cats-mcp
+Version: 1.0.0
+Summary: MCP server for Charlotte Area Transit System (CATS) realtime bus and light rail data
+Requires-Python: >=3.11
+Requires-Dist: gtfs-realtime-bindings<3,>=2.2
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: pyjwt[crypto]<3,>=2.10
+Requires-Dist: starlette<2,>=0.48
+Requires-Dist: uvicorn<1,>=0.34
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: types-protobuf; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.ajwann/cats-mcp -->
+
+# cats-mcp
+
+[![CI](https://github.com/ajwann/cats-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ajwann/cats-mcp/actions/workflows/ci.yml)
+
+An MCP server for live **Charlotte Area Transit System (CATS)** bus and light rail data,
+built on the agency's public GTFS-Realtime feeds. It runs over **stdio**, launched by
+the MCP client that uses it, or over **HTTP** with Google OAuth in front of it, for a
+hosted server. Both transports serve the same three tools.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `find_vehicle` | Locate one bus/train by vehicle number, or every vehicle on a route, and return GPS coordinates. |
+| `list_vehicles` | Current GPS coordinates of every bus and train in service. |
+| `get_arrivals` | Estimated arrival times at a specific stop or station. |
+
+### `find_vehicle`
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `vehicle` | string | Vehicle number as shown on the bus/train, e.g. `2301`, `LRV307`. |
+| `route` | string | Route to locate: `9`, `501`, `Blue Line`, `Mt. Holly Road`. |
+| `mode` | `bus` \| `train` | Optional filter. |
+
+At least one of `vehicle` or `route` is required. Returns position, heading, speed,
+occupancy, headsign, and the next scheduled stop.
+
+### `list_vehicles`
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `mode` | `bus` \| `train` | Optional filter. |
+| `route` | string | Optional single-route filter. |
+| `limit` | integer | Max vehicles to return (default and cap: 250). |
+
+Includes `countsByMode` and `totalInService` so the total is visible even when the
+list is truncated.
+
+### `get_arrivals`
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `stop` | string | **Required.** Stop id (`02400`), stop code, or part of a stop name (`CTC Station`). |
+| `route` | string | Optional route filter. |
+| `mode` | `bus` \| `train` | Optional filter. |
+| `limit` | integer | Max arrivals (default 10, cap 50). |
+
+Returns minutes away, predicted and scheduled times, schedule deviation, the vehicle
+number, and that vehicle's live position. When a name query is ambiguous, the best
+match is used and the runners-up are listed under `otherStopsMatchingQuery`. Service
+alerts affecting the stop or its routes are attached when present.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install .
+```
+
+## Transports
+
+Pick one with `--transport` or `CATS_TRANSPORT`; the default is `stdio`.
+
+```bash
+cats-mcp                                  # stdio (default)
+cats-mcp --transport http --port 8000     # streamable HTTP + Google OAuth
+```
+
+### stdio
+
+For a server the client launches itself. No authentication: the client already owns
+the process.
+
+Register it with Claude Code:
+
+```bash
+claude mcp add cats -- /absolute/path/to/cats-mcp/.venv/bin/cats-mcp
+```
+
+Or in an MCP client config file:
+
+```json
+{
+  "mcpServers": {
+    "cats": {
+      "command": "/absolute/path/to/cats-mcp/.venv/bin/cats-mcp"
+    }
+  }
+}
+```
+
+`python -m cats_mcp` runs the same server, so any interpreter with the package
+installed works as the command.
+
+stdout carries MCP protocol traffic only; all diagnostics go to stderr.
+
+### HTTP with Google OAuth
+
+For a hosted server anyone with the URL can reach. Every request to `/mcp` needs a
+bearer token, and the only way to get one is to sign in with a Google account that is
+on the allow list.
+
+**How the sign-in works.** MCP clients register themselves dynamically and expect an
+authorization server at the MCP server's own origin. Google offers neither dynamic
+registration nor tokens audience-restricted to a third-party resource, so this server
+is its own OAuth 2.1 authorization server and delegates only the login to Google:
+
+```
+MCP client  <--OAuth-->  cats-mcp  <--OAuth-->  Google
+```
+
+Google's answer is used exactly once, to learn which account signed in. That email is
+checked against the allow list, and only then does this server mint its own tokens.
+Google's tokens are never handed to the client.
+
+**One-time setup in Google Cloud.** At
+[console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials),
+create an **OAuth client ID** of type **Web application** and add one authorized
+redirect URI:
+
+```
+https://your-public-url/auth/google/callback
+```
+
+It must match `CATS_PUBLIC_URL` exactly. The server logs the URI it expects at startup.
+Copy the client ID and secret into the environment below.
+
+**Run it.** `.env.example` lists every setting; the shell form is:
+
+```bash
+export CATS_GOOGLE_CLIENT_ID=...apps.googleusercontent.com
+export CATS_GOOGLE_CLIENT_SECRET=...
+export CATS_ALLOWED_EMAILS=you@example.com
+export CATS_PUBLIC_URL=https://cats.example.com
+
+cats-mcp --transport http --port 8000
+```
+
+Then point a client at `https://cats.example.com/mcp`; it discovers the rest and opens
+a browser for the Google sign-in. In Claude Code:
+
+```bash
+claude mcp add --transport http cats https://cats.example.com/mcp
+```
+
+**Access is denied by default.** Startup fails unless `CATS_ALLOWED_EMAILS`,
+`CATS_ALLOWED_DOMAINS`, or an explicit `CATS_ALLOW_ANY_GOOGLE_ACCOUNT=true` says who
+may get in, so a misconfigured deployment is unreachable rather than open to every
+Google account on the internet. Unverified Google addresses are always refused.
+
+**Endpoints.**
+
+| Path | Purpose |
+| --- | --- |
+| `/mcp` | The MCP endpoint. Requires `Authorization: Bearer <token>`. |
+| `/.well-known/oauth-protected-resource/mcp` | Points clients at the authorization server. |
+| `/.well-known/oauth-authorization-server` | This server's OAuth metadata. |
+| `/register` | Dynamic client registration (RFC 7591). |
+| `/authorize`, `/token`, `/revoke` | The OAuth endpoints. |
+| `/auth/google/callback` | Where Google returns the user. |
+
+[`scripts/install.sh`](scripts/install.sh) does a whole deployment: a system
+user under `/opt`, a Cloudflare tunnel and its DNS record created over the API,
+both systemd units, and a verification pass. No port forwarding, so it works
+behind CGNAT or a locked router. See [`deploy/`](deploy/README.md).
+
+**Deployment notes.**
+
+- By default the server speaks plain HTTP and expects a tunnel or proxy to
+  terminate TLS, which is what the install script sets up. Setting
+  `CATS_TLS_CERT` and `CATS_TLS_KEY` instead makes it serve HTTPS itself, for a
+  deployment with nothing in front of it.
+- `CATS_PUBLIC_URL` is what clients dial and is this server's OAuth issuer
+  identifier, so it must be the external URL, not the bind address.
+- Token state is in memory and therefore per-process: restarting invalidates
+  outstanding tokens, and running several replicas behind one hostname would need a
+  shared store instead.
+- Access tokens last an hour and refresh tokens 30 days, both rotated on refresh.
+
+## Data sources
+
+Realtime (GTFS-Realtime protobuf, refreshed every 20s):
+
+- `https://gtfsrealtime.ridetransit.org/GTFSRealTime/Vehicle/VehiclePositions.pb`
+- `https://gtfsrealtime.ridetransit.org/GTFSRealTime/TripUpdate/TripUpdates.pb`
+- `https://gtfsrealtime.ridetransit.org/GTFSRealTime/Alert/Alerts.pb`
+
+Static schedule (cached 6h), used to turn feed identifiers into route names, stop
+names, and coordinates:
+
+- `https://gtfsrealtime.ridetransit.org/GTFSStatic/api/GTFSDownload/GTFS.zip`
+
+Only `routes.txt`, `stops.txt`, and `trips.txt` are read; `stop_times.txt` and
+`shapes.txt` are the bulk of the archive and are not needed.
+
+## Feed quirks this server works around
+
+Verified against live feed captures:
+
+- **`VehiclePosition.stop_id` and `current_stop_sequence` are unusable.** None of the
+  158 vehicle stop ids in a sample capture matched any stop in the published schedule,
+  and reported sequence numbers exceeded the trip's own stop count (e.g. sequence 192
+  on a 52-stop trip). This server never surfaces them; next-stop data comes from the
+  TripUpdates feed instead, whose stop ids resolve 100%.
+- **`StopTimeEvent.delay` is never populated.** Schedule deviation is computed from
+  `time` minus `scheduled_time`, which are both present.
+- **TripUpdates cover ~83% of active vehicles**, so `nextStop` is omitted rather than
+  guessed for the remainder.
+- **Route matching is exact-first**, so a query of `5` returns route 5, not 501 or 510.
+
+## Behavior notes
+
+- Arrival predictions already in the past are filtered out; no negative ETAs.
+- Feed responses are capped in size and time-bounded; one slow feed cannot hang a call.
+- Concurrent calls share a single in-flight fetch per feed, and one call giving up does
+  not abort a fetch the others are awaiting.
+- If a refresh fails but cached data exists, the last good data is served rather than
+  an error. `feedAgeSeconds` on every response shows how stale it is.
+- The alerts feed is supplementary: if it fails, `get_arrivals` still returns arrivals.
+- Times are ISO 8601 UTC; coordinates are WGS84 decimal degrees.
+
+## Configuration
+
+### Feeds (both transports)
+
+All optional; defaults target the CATS feeds above. Durations are in milliseconds.
+
+| Variable | Default |
+| --- | --- |
+| `CATS_VEHICLE_POSITIONS_URL` | CATS vehicle positions feed |
+| `CATS_TRIP_UPDATES_URL` | CATS trip updates feed |
+| `CATS_ALERTS_URL` | CATS alerts feed |
+| `CATS_STATIC_GTFS_URL` | CATS static GTFS zip |
+| `CATS_REALTIME_TTL_MS` | `20000` |
+| `CATS_STATIC_TTL_MS` | `21600000` |
+| `CATS_REQUEST_TIMEOUT_MS` | `30000` |
+| `CATS_MAX_FEED_BYTES` | `33554432` |
+| `CATS_MAX_STATIC_BYTES` | `268435456` |
+
+Feed URLs must be `http` or `https`; anything else is rejected at startup.
+
+### Transport
+
+| Variable | CLI | Default |
+| --- | --- | --- |
+| `CATS_TRANSPORT` | `--transport` | `stdio` |
+
+### HTTP transport
+
+Read only when `--transport http` is selected.
+
+| Variable | CLI | Default | Notes |
+| --- | --- | --- | --- |
+| `CATS_HTTP_HOST` | `--host` | `127.0.0.1` | Bind address. |
+| `CATS_HTTP_PORT` | `--port` | `8000` | Bind port. |
+| `CATS_PUBLIC_URL` | `--public-url` | `http://localhost:<port>` | External origin; the OAuth issuer. |
+| `CATS_GOOGLE_CLIENT_ID` | | **required** | From Google Cloud credentials. |
+| `CATS_GOOGLE_CLIENT_SECRET` | | **required** | From Google Cloud credentials. |
+| `CATS_ALLOWED_EMAILS` | | — | Allowed addresses, comma- or space-separated. |
+| `CATS_ALLOWED_DOMAINS` | | — | Allowed bare domains, e.g. `example.com`. |
+| `CATS_ALLOW_ANY_GOOGLE_ACCOUNT` | | `false` | Opt in to admitting every Google account. |
+| `CATS_TLS_CERT` | `--tls-cert` | — | PEM chain, to serve HTTPS directly. |
+| `CATS_TLS_KEY` | `--tls-key` | — | PEM private key. Required with the above. |
+| `CATS_ACCESS_TOKEN_TTL_MS` | | `3600000` | Access token lifetime. |
+| `CATS_REFRESH_TOKEN_TTL_MS` | | `2592000000` | Refresh token lifetime. |
+
+One of the three allow-list settings is required; see above.
+
+## Layout
+
+| Module | Role |
+| --- | --- |
+| `config.py` | Environment parsing and validation |
+| `feed_http.py` | Bounded, time-limited HTTP fetch |
+| `cache.py` | TTL cache with single-flight refresh |
+| `gtfs_csv.py` | GTFS-flavored CSV reading |
+| `static_gtfs.py` | Static schedule: routes, stops, trips |
+| `realtime.py` | GTFS-Realtime protobuf decoding |
+| `transit.py` | Domain layer: joins realtime to schedule, resolves queries |
+| `tools.py` | The three tools' behavior and JSON payloads |
+| `server.py` | MCP tool registration and schemas |
+| `oauth.py` | OAuth authorization server, with Google as the login |
+| `http.py` | Streamable HTTP transport and the Google callback route |
+| `main.py` | CLI entry point and transport selection |
+
+Plus [`scripts/install.sh`](scripts/install.sh), which deploys the HTTP
+transport onto a Debian host.
+
+## Development
+
+```bash
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest        # 130 tests, offline against recorded feed fixtures
+.venv/bin/mypy          # strict
+.venv/bin/ruff check .
+.venv/bin/ruff format .
+```
+
+Tests run against protobuf and GTFS fixtures captured from the live feeds, so they are
+deterministic and make no network calls. `tests/test_feed_http.py` is the exception: it
+serves canned responses from a loopback socket so the byte cap and timeout are exercised
+for real.
+
+`tests/test_http.py` drives the whole OAuth handshake against the real ASGI app -
+registration, `/authorize`, the Google callback, `/token`, then an authenticated
+`tools/list` - with Google's token endpoint replaced by a stub, so no account or network
+is needed.