GTFS Pilot

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Skill for ~/.claude/skills/

Drop this into ~/.claude/skills/flowmcp-gtfs-pilot/SKILL.md:

---
name: flowmcp-gtfs-pilot
description: Help a user reproduce the FlowMCP v4.1 GTFS pilot — download a feed, build local SQLite, query from FlowMCP
---

# FlowMCP GTFS Pilot

Use this skill when a user wants to set up local mobility databases (VBB Berlin, DELFI Germany) from a GTFS feed and query them through FlowMCP. Guide them from raw feed to running transit-routing queries.

## Steps

1. Pick the feed: VBB Berlin (~30 MB) for a small demo, DELFI (~245 MB) for nationwide coverage
2. Download the GTFS ZIP and unpack it into a working directory
3. Convert the GTFS files to SQLite with the quality-seal converter from the tutorial
4. Activate the FlowMCP GTFS schema: `flowmcp add gtfs-de`
5. Point the schema at the local SQLite via its required server param
6. Run a transit-routing query end-to-end (e.g. stops near a coordinate, departures within 30 min)
7. Reference the full tutorial: https://flowmcp.github.io/guides/gtfs-pilot/

## References

- Tutorial: https://flowmcp.github.io/guides/gtfs-pilot/
- FlowMCP CLI: https://github.com/FlowMCP/flowmcp-cli

This guide reproduces the FlowMCP v4.1 GTFS pilot. By the end, you have two queryable mobility databases (VBB Berlin, DELFI Germany) and can ask transit-routing questions in seconds.

📖 Background: Blog — FlowMCP v4.1 GTFS Add-on (Phase 3 pilot results).

What you set up

DELFI feed (Germany-wide, ~245 MB ZIP, CC-BY 4.0)
VBB feed (Berlin / Brandenburg, ~83 MB ZIP, CC-BY 4.0)
gtfs-sqlite-toolkit for conversion
A FlowMCP schema (sqlite-gtfs) that auto-injects routing tools

Total time: 20–30 minutes (mostly waiting for downloads + conversion).

Prerequisites

Node.js 22+ with --max-old-space-size=8192 for the DELFI conversion (default 4 GB heap is too small)
~3 GB free disk space
FlowMCP CLI installed
gtfs-sqlite-toolkit cloned or installed from github:FlowMCP/gtfs-sqlite-toolkit

Step 0 — Install the FlowMCP CLI

npm install -g github:FlowMCP/flowmcp-cli
flowmcp --version
flowmcp list

The CLI is needed to register the GTFS schema in Step 5. If you only want the SQLite files for direct queries, you can skip the CLI install — but the recommended hackathon flow uses it.

Step 1 — Download both feeds

mkdir -p ~/.flowmcp/resources/gtfs
cd ~/.flowmcp/resources/gtfs

# Germany-wide (~245 MB)
curl -L -o gtfs-delfi.zip https://download.gtfs.de/germany/free/latest.zip

# Berlin / Brandenburg (~83 MB)
curl -L -o gtfs-vbb.zip https://www.vbb.de/vbbgtfs

# Verify hashes for reproducibility
shasum -a 256 *.zip

The DELFI feed is regenerated daily — pin the hash + date if you need exact reproducibility.

Step 2 — Convert to SQLite

import { GtfsSqliteConverter } from 'gtfs-sqlite-toolkit'

// VBB — passes validation, gets quality seal
const vbb = await GtfsSqliteConverter.start( {
    input:     '/Users/you/.flowmcp/resources/gtfs/gtfs-vbb.zip',
    inputType: 'zip',
    dbPath:    '/Users/you/.flowmcp/resources/gtfs/gtfs-vbb.db',
    sourceUrl: 'https://www.vbb.de/vbbgtfs'
} )

// DELFI — needs force mode (97k validation errors in pilot)
const delfi = await GtfsSqliteConverter.start( {
    input:     '/Users/you/.flowmcp/resources/gtfs/gtfs-delfi.zip',
    inputType: 'zip',
    dbPath:    '/Users/you/.flowmcp/resources/gtfs/gtfs-delfi.db',
    sourceUrl: 'https://download.gtfs.de/germany/free/latest.zip',
    force:     true
} )

console.log( 'VBB seal:',  vbb.seal )      // 'sqlite-gtfs'
console.log( 'DELFI seal:', delfi.seal )   // null (no seal in force mode)
console.log( 'DELFI caps:', delfi.capabilities ) // routing: false → no findRoute injected

Run with node --max-old-space-size=8192 convert.mjs.

Step 3 — Query the database

Direct SQLite:

sqlite3 ~/.flowmcp/resources/gtfs/gtfs-vbb.db <<EOF
SELECT r.route_short_name, t.trip_headsign,
       st1.departure_time AS dep, st2.arrival_time AS arr
  FROM stop_times st1
  JOIN trips t ON st1.trip_id = t.trip_id
  JOIN routes r ON t.route_id = r.route_id
  JOIN stop_times st2 ON st2.trip_id = t.trip_id
  JOIN stops s1 ON st1.stop_id = s1.stop_id
  JOIN stops s2 ON st2.stop_id = s2.stop_id
 WHERE s1.stop_name LIKE 'S+U Berlin Hauptbahnhof%'
   AND s2.stop_name = 'S Spandau Bhf (Berlin)'
   AND st2.stop_sequence > st1.stop_sequence
 ORDER BY dep LIMIT 5;
EOF

Or via FlowMCP (when the schema is active):

flowmcp call gtfsvbb.findRoute '{"origin":"Berlin Hbf","destination":"Spandau"}'

Step 4 — Read the capability matrix

The DB has a meta table with the seal, capabilities, and validation report:

sqlite3 ~/.flowmcp/resources/gtfs/gtfs-vbb.db \
  "SELECT key, substr(value, 1, 100) FROM meta;"

The FlowMCP-CLI reads capabilities and only injects tools that the feed can answer. DELFI without routing capability sees searchStops and findStopsByGeo, but not findRoute — no 404, no hallucination, the tool simply does not exist in the agent’s tool set.

License attribution

CC-BY 4.0 requires attribution in every response that uses the data:

{
    "data": { "route_id": "ICE793", "dep_time": "09:34" },
    "licenseAttribution": "Daten: DELFI e.V. / VBB GmbH, CC-BY 4.0",
    "source": "gtfs-de | gtfs-vbb"
}

FlowMCP carries this in the output object — your downstream code must surface it to end users.

Blog — FlowMCP v4.1 GTFS Add-on — full pilot results, 5 use cases, performance
Specification → Resources — source: 'sqlite-gtfs' semantics
gtfs-sqlite-toolkit README — converter API