ztm-mcp-server
poznan-ai-transit/ztm-mcp-server
MCP integration for AI agents with public transport schedules and real-time vehicle location system in Poznań (ZTM). Built on GTFS & GTFS-Realtime open data.
Instalação
npx convez-ai poznan-ai-transit/ztm-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
ztm-mcp-server
Example scripts for the ZTM Poznań Open Data API — public transport feeds (GTFS + GTFS-RT) published by Zarząd Transportu Miejskiego w Poznaniu.
Requirements
- Python 3.10+
requests— HTTP clientgtfs-realtime-bindings— Protocol Buffer parser for GTFS-RT feeds (pulls inprotobufas a transitive dependency)
Setup
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
Examples
| Script | What it does |
|---|---|
| examples/01_static_gtfs.py | Download the latest GTFS archive and print stops & routes |
| examples/02_vehicle_positions.py | Fetch live vehicle positions (lat/lon, bearing, trip, route) |
| examples/03_trip_updates.py | Fetch real-time delays and compute predicted departure times |
| examples/04_service_alerts.py | List active service disruptions, detours, and notices |
| examples/05_vehicle_dictionary.py | Join the vehicle catalog (accessibility flags) with live positions |
Run any example:
python examples/01_static_gtfs.py
python examples/02_vehicle_positions.py
python examples/03_trip_updates.py
python examples/04_service_alerts.py
python examples/05_vehicle_dictionary.py
API overview
| Feed | Format | File |
|---|---|---|
| Static schedule | GTFS ZIP | getGTFSFile |
| Service alerts | GTFS-RT protobuf | feeds.pb |
| Trip delays | GTFS-RT protobuf | trip_updates.pb |
| Vehicle positions | GTFS-RT protobuf | vehicle_positions.pb |
| Vehicle catalog | CSV | vehicle_dictionary.csv |
Base URL: https://www.ztm.poznan.pl/pl/dla-deweloperow/
Data source: ZTM Poznań developer portal
Tests
pip install -r requirements-dev.txt
pytest # full suite
pytest -m "not slow" # skip the tests that parse/freeze the full mock dataset
Linting & formatting
Code style is enforced with Ruff (configured in pyproject.toml):
ruff check src tests # lint
ruff format src tests # auto-format
ruff check --fix src tests # lint + apply safe fixes
Both linting and the test suite run in CI on every push and pull request (.github/workflows/ci.yml).
Tests live in tests/ and cover the in-memory schedule store (test_ztm_static_schedule.py), the ZTM data service (test_ztm_service.py), and the MCP tool and resource callables (test_mcp_server.py). They run entirely against the bundled mock data — no network access required.
Documentation map
| Document | Purpose |
|---|---|
| docs/01-product-goal.md | Project description and product goal |
| docs/02-mvp.md | MVP boundaries, mock phase, and core behavior |
| docs/03-requirements.md | Functional and non-functional requirements for the MVP |