{"_id":"@cyanheads/transitland-mcp-server","_rev":"3-13c9f03ab854a6b17cc6589e3af118d6","name":"@cyanheads/transitland-mcp-server","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@cyanheads/transitland-mcp-server","version":"0.1.0","keywords":["transit","transitland","gtfs","gtfs-realtime","gbfs","public-transit","departures","transit-feeds","mcp","mcp-server","model-context-protocol","typescript","bun","stdio","streamable-http","ai-agent"],"license":"Apache-2.0","_id":"@cyanheads/transitland-mcp-server@0.1.0","maintainers":[{"name":"cyanheads","email":"casey@caseyjhand.com"}],"homepage":"https://github.com/cyanheads/transitland-mcp-server#readme","bugs":{"url":"https://github.com/cyanheads/transitland-mcp-server/issues"},"bin":{"transitland-mcp-server":"dist/index.js"},"dist":{"shasum":"f8bbb66c41cc97ae6bb4ca367a7426d9a650ee4c","tarball":"https://registry.npmjs.org/@cyanheads/transitland-mcp-server/-/transitland-mcp-server-0.1.0.tgz","fileCount":65,"integrity":"sha512-TRu+XYqBFIZFfzRHOXZ147yy8nEm4oqA6NsXXlonkBchYjfPcefq7VXZavxAR1tun1pxyPnBxjDLcs+xr0gUFw==","signatures":[{"sig":"MEQCIGjXAIX0iA0F7+DZf3w1+mlCdYTPMTNGnbOSn7pLa2tBAiBrGrsm9p3Jks0ufC9auiFvpeBtq7z/JthbX2Td+zGXUA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":336000},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"bun":">=1.3.0","node":">=24.0.0"},"gitHead":"cc68f52e2f2e0c3856479a1eba8547e773d45dd4","mcpName":"io.github.cyanheads/transitland-mcp-server","scripts":{"test":"vitest run","tree":"bun run scripts/tree.ts","build":"bun run scripts/build.ts","clean":"bun run scripts/clean.ts","start":"node dist/index.js","bundle":"bun run build && npx -y @anthropic-ai/mcpb pack . dist/transitland-mcp-server.mcpb && bun run scripts/clean-mcpb.ts dist/transitland-mcp-server.mcpb","format":"biome check --write .","rebuild":"bun run scripts/clean.ts && bun run scripts/build.ts","devcheck":"bun run scripts/devcheck.ts","lint:mcp":"bun run scripts/lint-mcp.ts","start:http":"MCP_TRANSPORT_TYPE=http node dist/index.js","list-skills":"bun run scripts/list-skills.ts","publish-mcp":"mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish","start:stdio":"MCP_TRANSPORT_TYPE=stdio node dist/index.js","audit:refresh":"rm -f bun.lock && bun install && bun audit","format:unsafe":"biome check --write --unsafe .","lint:packaging":"bun run scripts/lint-packaging.ts","release:github":"bun run scripts/release-github.ts","changelog:build":"bun run scripts/build-changelog.ts","changelog:check":"bun run scripts/build-changelog.ts --check"},"_npmUser":{"name":"cyanheads","email":"casey@caseyjhand.com"},"repository":{"url":"git+https://github.com/cyanheads/transitland-mcp-server.git","type":"git"},"_npmVersion":"11.12.1","description":"Global transit data via the Transitland v2 registry — operators, GTFS/GTFS-RT/GBFS feeds with license terms, routes, stops, and real-time-aware departures via MCP. STDIO or Streamable HTTP.","directories":{},"_nodeVersion":"26.0.0","dependencies":{"zod":"^4.4.3","pino-pretty":"^13.1.3","@cyanheads/mcp-ts-core":"^0.10.6"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.0","devDependencies":{"ignore":"^7.0.5","vitest":"^4.1.8","depcheck":"^1.4.7","tsc-alias":"^1.8.17","typescript":"^6.0.3","@types/node":"25.9.3","@biomejs/biome":"2.5.0"},"_npmOperationalInternal":{"tmp":"tmp/transitland-mcp-server_0.1.0_1781427580618_0.8682456798802036","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cyanheads/transitland-mcp-server","version":"0.1.1","keywords":["transit","transitland","gtfs","gtfs-realtime","gbfs","public-transit","departures","transit-feeds","mcp","mcp-server","model-context-protocol","typescript","bun","stdio","streamable-http","ai-agent"],"author":"Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)","license":"Apache-2.0","_id":"@cyanheads/transitland-mcp-server@0.1.1","maintainers":[{"name":"cyanheads","email":"casey@caseyjhand.com"}],"homepage":"https://github.com/cyanheads/transitland-mcp-server#readme","bugs":{"url":"https://github.com/cyanheads/transitland-mcp-server/issues"},"bin":{"transitland-mcp-server":"dist/index.js"},"dist":{"shasum":"1c5b84bea1cb2f93a68715628ae050179d765616","tarball":"https://registry.npmjs.org/@cyanheads/transitland-mcp-server/-/transitland-mcp-server-0.1.1.tgz","fileCount":66,"integrity":"sha512-KVZc7WjQ95qWwCqGMcac8Md6t/hD63lqWKa32F7I2rm4nYvd0yConKyuGGWDfjNzRPPwoXEg9SFbT0U+P6mnsw==","signatures":[{"sig":"MEUCIB4izUbum6n7G9EIjmdHt6PeCxqsFdVemixZa1Nc4jhtAiEAiJLsHwwu3+ERbtQ1OvIvWOKoSRS36JSFmvzOGXcDaL0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":346872},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","shasum":"1c5b84bea1cb2f93a68715628ae050179d765616","engines":{"bun":">=1.3.0","node":">=24.0.0"},"mcpName":"io.github.cyanheads/transitland-mcp-server","scripts":{"test":"vitest run","tree":"bun run scripts/tree.ts","build":"bun run scripts/build.ts","clean":"bun run scripts/clean.ts","start":"node dist/index.js","bundle":"bun run build && npx -y @anthropic-ai/mcpb pack . dist/transitland-mcp-server.mcpb && bun run scripts/clean-mcpb.ts dist/transitland-mcp-server.mcpb","format":"biome check --write .","rebuild":"bun run scripts/clean.ts && bun run scripts/build.ts","devcheck":"bun run scripts/devcheck.ts","lint:mcp":"bun run scripts/lint-mcp.ts","start:http":"MCP_TRANSPORT_TYPE=http node dist/index.js","list-skills":"bun run scripts/list-skills.ts","publish-mcp":"mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish","start:stdio":"MCP_TRANSPORT_TYPE=stdio node dist/index.js","audit:refresh":"rm -f bun.lock && bun install && bun audit","format:unsafe":"biome check --write --unsafe .","test:coverage":"vitest run --coverage","lint:packaging":"bun run scripts/lint-packaging.ts","release:github":"bun run scripts/release-github.ts","changelog:build":"bun run scripts/build-changelog.ts","changelog:check":"bun run scripts/build-changelog.ts --check"},"_npmUser":{"name":"cyanheads","email":"casey@caseyjhand.com"},"_integrity":"sha512-KVZc7WjQ95qWwCqGMcac8Md6t/hD63lqWKa32F7I2rm4nYvd0yConKyuGGWDfjNzRPPwoXEg9SFbT0U+P6mnsw==","repository":{"url":"git+https://github.com/cyanheads/transitland-mcp-server.git","type":"git"},"_npmVersion":"10.8.3","description":"Global transit data via the Transitland v2 registry — operators, GTFS/GTFS-RT/GBFS feeds with license terms, routes, stops, and real-time-aware departures via MCP. STDIO or Streamable HTTP.","directories":{},"_nodeVersion":"26.3.0","dependencies":{"zod":"^4.4.3","pino-pretty":"^13.1.3","@cyanheads/mcp-ts-core":"^0.12.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.4.0","devDependencies":{"ignore":"^7.0.6","vitest":"^4.1.11","depcheck":"^1.4.7","tsc-alias":"^1.9.2","fast-check":"^4.9.0","typescript":"^7.0.2","@types/node":"^26.2.0","@biomejs/biome":"2.5.9","@vitest/coverage-istanbul":"4.1.11","@socketsecurity/bun-security-scanner":"^1.1.2"},"_npmOperationalInternal":{"tmp":"tmp/transitland-mcp-server_0.1.1_1787328033085_0.14893552901512064","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"_id":"@cyanheads/transitland-mcp-server@0.1.2","bin":{"transitland-mcp-server":"dist/index.js"},"bugs":{"url":"https://github.com/cyanheads/transitland-mcp-server/issues"},"dist":{"shasum":"27b3ce45dc24dc2433e6d68355db846a25c91c3e","tarball":"https://registry.npmjs.org/@cyanheads/transitland-mcp-server/-/transitland-mcp-server-0.1.2.tgz","fileCount":67,"integrity":"sha512-UA+jTiLUO76+kMUGsLq+TIO7PO82iW38Eth6FpkMW7HDkJcXocP4zzCV8JhBrnizA3CQStbBRGvK3zEAQc/uVQ==","signatures":[{"sig":"MEUCIEk5eYknKWec2LIySlWeghNoF/QfAoK74w/QUiGXaNkoAiEA3D7ehbKBULyJ+Wyxvr0qZJkFVEcxNRpdNAEUARHrk5Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCMsaRLA3eWxr+2F3b0Z5ByjRhydB5Gv3SkkPWsAUVmSQIhANAmzCF0IMi89kiTZy+hN0A92oyZuUSQLauyc3gBFcZ6"}],"unpackedSize":360904},"main":"dist/index.js","name":"@cyanheads/transitland-mcp-server","type":"module","types":"dist/index.d.ts","author":"Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)","shasum":"27b3ce45dc24dc2433e6d68355db846a25c91c3e","engines":{"bun":">=1.4.0","node":">=24.0.0"},"funding":[{"url":"https://github.com/sponsors/cyanheads","type":"github"},{"url":"https://www.buymeacoffee.com/cyanheads","type":"buy_me_a_coffee"}],"license":"Apache-2.0","mcpName":"io.github.cyanheads/transitland-mcp-server","scripts":{"test":"vitest run","tree":"bun run scripts/tree.ts","build":"bun run scripts/build.ts","clean":"bun run scripts/clean.ts","start":"node dist/index.js","bundle":"bun run build && npx -y @anthropic-ai/mcpb pack . dist/transitland-mcp-server.mcpb && bun run scripts/clean-mcpb.ts dist/transitland-mcp-server.mcpb","format":"biome check --write .","rebuild":"bun run scripts/clean.ts && bun run scripts/build.ts","devcheck":"bun run scripts/devcheck.ts","lint:mcp":"bun run scripts/lint-mcp.ts","audit:fix":"bun audit fix","start:http":"MCP_TRANSPORT_TYPE=http node dist/index.js","list-skills":"bun run scripts/list-skills.ts","publish-mcp":"mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish","start:stdio":"MCP_TRANSPORT_TYPE=stdio node dist/index.js","audit:refresh":"rm -f bun.lock && bun install && bun audit","format:unsafe":"biome check --write --unsafe .","test:coverage":"vitest run --coverage","lint:packaging":"bun run scripts/lint-packaging.ts","release:github":"bun run scripts/release-github.ts","changelog:build":"bun run scripts/build-changelog.ts","changelog:check":"bun run scripts/build-changelog.ts --check"},"version":"0.1.2","_npmUser":{"name":"cyanheads","email":"casey@caseyjhand.com"},"homepage":"https://github.com/cyanheads/transitland-mcp-server#readme","keywords":["transit","transitland","gtfs","gtfs-realtime","gbfs","public-transit","departures","transit-feeds","mcp","mcp-server","model-context-protocol","typescript","bun","stdio","streamable-http","ai-agent"],"_integrity":"sha512-UA+jTiLUO76+kMUGsLq+TIO7PO82iW38Eth6FpkMW7HDkJcXocP4zzCV8JhBrnizA3CQStbBRGvK3zEAQc/uVQ==","repository":{"url":"git+https://github.com/cyanheads/transitland-mcp-server.git","type":"git"},"_npmVersion":"10.8.3","description":"Global transit data via the Transitland v2 registry — operators, GTFS/GTFS-RT/GBFS feeds with license terms, routes, stops, and real-time-aware departures via MCP. STDIO or Streamable HTTP.","directories":{},"maintainers":[{"name":"cyanheads","email":"casey@caseyjhand.com"}],"_nodeVersion":"26.3.0","dependencies":{"zod":"^4.6.5","pino-pretty":"^13.1.3","@cyanheads/mcp-ts-core":"^0.13.6"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.4.0","devDependencies":{"ignore":"^7.0.9","vitest":"^5.0.1","depcheck":"^1.4.7","tsc-alias":"^1.9.5","fast-check":"^4.10.1","typescript":"^7.0.2","@types/node":"^26.6.1","@biomejs/biome":"2.5.14","@vitest/coverage-istanbul":"5.0.1","@socketsecurity/bun-security-scanner":"^1.1.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/transitland-mcp-server_0.1.2_1789938330241_0.5062409060192956"}}},"time":{"created":"2026-06-14T08:59:40.448Z","modified":"2026-09-20T21:05:30.498Z","0.1.0":"2026-06-14T08:59:40.790Z","0.1.1":"2026-08-21T16:00:33.261Z","0.1.2":"2026-09-20T21:05:30.341Z"},"bugs":{"url":"https://github.com/cyanheads/transitland-mcp-server/issues"},"author":"Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)","license":"Apache-2.0","homepage":"https://github.com/cyanheads/transitland-mcp-server#readme","keywords":["transit","transitland","gtfs","gtfs-realtime","gbfs","public-transit","departures","transit-feeds","mcp","mcp-server","model-context-protocol","typescript","bun","stdio","streamable-http","ai-agent"],"repository":{"url":"git+https://github.com/cyanheads/transitland-mcp-server.git","type":"git"},"description":"Global transit data via the Transitland v2 registry — operators, GTFS/GTFS-RT/GBFS feeds with license terms, routes, stops, and real-time-aware departures via MCP. STDIO or Streamable HTTP.","maintainers":[{"name":"cyanheads","email":"casey@caseyjhand.com"}],"readme":"<div align=\"center\">\n  <h1>@cyanheads/transitland-mcp-server</h1>\n  <p><b>Global transit data via the Transitland v2 registry — operators, GTFS/GTFS-RT/GBFS feeds with license terms, routes, stops, and real-time-aware departures via MCP. STDIO or Streamable HTTP.</b>\n  <div>6 Tools • 2 Resources</div>\n  </p>\n</div>\n\n<div align=\"center\">\n\n[![Version](https://img.shields.io/badge/Version-0.1.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/transitland-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/transitland-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/transitland-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n</div>\n\n<div align=\"center\">\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/transitland-mcp-server/releases/latest/download/transitland-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=transitland-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdHJhbnNpdGxhbmQtbWNwLXNlcnZlciJdLCJlbnYiOnsiVFJBTlNJVExBTkRfQVBJX0tFWSI6InlvdXItYXBpLWtleSJ9fQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22transitland-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ftransitland-mcp-server%22%5D%2C%22env%22%3A%7B%22TRANSITLAND_API_KEY%22%3A%22your-api-key%22%7D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n</div>\n\n---\n\n## Overview\n\nTransit data from the Transitland v2 registry — the open aggregator of GTFS, GTFS-Realtime, and GBFS feeds from thousands of transit operators worldwide. Find operators, discover feeds and their license terms, and look up routes, stops, and real-time-aware departures from any MCP client. Runs as a stdio process or a local Streamable HTTP server.\n\n### Tools\n\n| Tool | Description |\n|:---|:---|\n| `transitland_find_operators` | Find transit operators/agencies by name, point/radius, bounding box, country/region, or Onestop ID |\n| `transitland_get_operator` | Fetch the full operator record by Onestop ID — agencies, feeds, and source tags |\n| `transitland_find_feeds` | Discover GTFS, GTFS-Realtime, and GBFS feeds — fetch URLs, license terms, and freshness |\n| `transitland_find_routes` | Find routes by point/radius, bounding box, operator, Onestop ID, or GTFS mode |\n| `transitland_find_stops` | Find stops/stations by point/radius, bounding box, Onestop ID, or operator network |\n| `transitland_get_departures` | Departures from a stop, each flagged `realtime` true/false |\n\nTransitland does not geocode place names — resolve a location to coordinates with a geocoding MCP server (e.g. [`openstreetmap-mcp-server`](https://github.com/cyanheads/openstreetmap-mcp-server)'s `openstreetmap_geocode`) before calling a geography-filtered tool.\n\n### Resources\n\n| Resource | Description |\n|:---|:---|\n| `transitland://operator/{onestop_id}` | Operator record by Onestop ID — agencies, places served, published feeds, and source tags |\n| `transitland://feed/{onestop_id}` | Feed record by Onestop ID — spec, fetch URL, license terms, and freshness |\n\nAll resource data is also reachable via tools (`transitland_get_operator`, `transitland_find_feeds`).\n\n## Capability reference\n\n### `transitland_find_operators` <sub>tool</sub>\n\n- Filter by `search` (name), `lat`+`lon`+`radius` (max 100,000m, default 1,000m), `bbox`, `onestop_id`, or `adm0_name`/`adm1_name` (country/region) — at least one required, or the call fails as `no_filter`\n- Returns each operator's Onestop ID, name, places served, published feeds (a `GTFS_RT` entry signals real-time departures may be available), and Wikidata QID\n- `lat` requires `lon` and vice versa, or the call fails as `incomplete_point`\n- `limit` caps at 100 (default 20), paginated via the `after` cursor\n\n---\n\n### `transitland_get_operator` <sub>tool</sub>\n\n- Accepts an Onestop ID (e.g. `o-9q9-bart`) or an internal integer ID\n- Returns agencies (each with places served), published feeds, and source tags: Wikidata QID, US NTD ID, general Twitter/X handle\n- Idempotent single-record lookup; mirrored by the `transitland://operator/{onestop_id}` resource\n- `operator_not_found` when the ID doesn't resolve\n\n---\n\n### `transitland_find_feeds` <sub>tool</sub>\n\n- Filter by `operator_onestop_id` (from `transitland_find_operators` — the reliable path to one agency's feeds), `spec` (`gtfs`/`gtfs-rt`/`gbfs`/`mds`), `search`, or `fetch_error` — at least one required\n- Each feed returns its fetch URL, real-time endpoints when present, and license terms — redistribution, commercial use, derived products, and attribution as explicit `yes`/`no`/`unknown` (never inferred from a blank field), plus SPDX identifier and attribution text where known\n- Freshness: last-fetch timestamp, content hash, and the calendar window the current data covers\n- `authorizationRequired` flags feeds whose download needs a separate key/registration\n- `limit` caps at 100 (default 20), paginated via `after`\n\n---\n\n### `transitland_find_routes` <sub>tool</sub>\n\n- Filter by `lat`+`lon`+`radius` (max 50,000m, default 1,000m), `bbox`, `operator_onestop_id`, `onestop_id`, `route_type` (GTFS mode integer), or `search` — at least one required\n- Returns short/long name, `route_type` mapped to a human-readable mode (bus, subway, rail, ferry, tram, …), brand color, operating agency's Onestop ID, and source feed's Onestop ID\n- Scheduled (GTFS static) route definitions, not live vehicle positions\n- `lat` requires `lon` and vice versa, or the call fails as `incomplete_point`\n- `limit` caps at 100 (default 20), paginated via `after`\n\n---\n\n### `transitland_find_stops` <sub>tool</sub>\n\n- Filter by `lat`+`lon`+`radius` (max 10,000m, default 500m), `bbox`, `onestop_id`, or `served_by_onestop_ids` (comma-separated operator/route Onestop IDs) — at least one required\n- Returns coordinates, `location_type` with a label (stop, station, entrance, node, boarding area), wheelchair accessibility, timezone, and the parent station's Onestop ID for child platforms\n- Departures attach to platform-level stops (`location_type` 0) — a station may return none; use its child platforms\n- `limit` caps at 100 (default 20), paginated via `after`\n\n---\n\n### `transitland_get_departures` <sub>tool</sub>\n\n- Resolve a stop to its Onestop ID with `transitland_find_stops` first\n- Every departure carries a `realtime` flag — `true` for a live GTFS-Realtime prediction, `false` for a static scheduled time — plus a `scheduleRelationship` (`STATIC`, `SCHEDULED`, `ADDED`, `CANCELED`, `UNSCHEDULED`, `DUPLICATED`)\n- Returns scheduled and (when real-time) estimated times with delay in seconds, route, headsign, mode, trip, direction, and accessibility\n- Top-level `realtimeAvailable` reports whether the stop's feed publishes GTFS-RT at all\n- `next_seconds` look-ahead window: 60–86,400 (default 3,600); widen it or set `use_service_window: true` when a stop returns nothing\n- `stop_not_found` when the stop doesn't resolve — detected from an empty upstream array, not an HTTP 404\n\n---\n\n### `transitland://operator/{onestop_id}` <sub>resource</sub>\n\n- Mirrors `transitland_get_operator` — agencies, places served, published feeds, and source tags (Wikidata QID, US NTD ID, Twitter/X handle)\n- `onestop_id` param accepts an Onestop ID (e.g. `o-9q9-bart`) or internal integer ID\n- `operator_not_found` when the ID doesn't resolve\n\n---\n\n### `transitland://feed/{onestop_id}` <sub>resource</sub>\n\n- Mirrors a single-feed result from `transitland_find_feeds` — spec, fetch URL, real-time endpoints, license terms, and latest-fetch freshness\n- `onestop_id` param accepts a feed Onestop ID (e.g. `f-9q9-bart`) or internal integer ID\n- License fields normalize blank registry values to `unknown`/null — never inferred as permissive\n- `feed_not_found` when the ID doesn't resolve\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.\n\nTransitland-specific:\n\n- Direct HTTP client for the Transitland v2 REST API — no SDK dependency, a flat query-param contract over a handful of GET endpoints\n- Onestop IDs (`o-`/`f-`/`r-`/`s-`) are the identifier spine — surfaced in every result, accepted on input alongside internal integer IDs\n- Feed-version history sliced to the latest version (the raw endpoint returns the entire fetch log — 167 entries for BART), so a feed lookup returns current freshness, not a multi-year history\n- Coverage polygons and route/stop geometry omitted by default — a compact country/region/city place summary instead\n\nAgent-friendly output:\n\n- The real-time distinction is structural — a per-departure `realtime` boolean and `scheduleRelationship`, plus a top-level `realtimeAvailable`, so an agent branches on data, never on parsing a timestamp\n- License terms surfaced honestly — blank registry fields normalize to `unknown`/null and are never inferred as permissive; the schema descriptions tell agents to confirm against the license URL before redistributing\n- The pagination `meta.next` URL embeds the API key in plaintext; the service discards it and surfaces only the opaque integer `after` cursor, so the key never reaches tool output or logs\n- Empty results return data plus an actionable notice (geocode-first, widen the window, try a child platform) rather than an error\n\n## Getting started\n\nAdd the following to your MCP client configuration file. A Transitland API key is required — see [Prerequisites](#prerequisites) for how to get one.\n\n```json\n{\n  \"mcpServers\": {\n    \"transitland-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"bunx\",\n      \"args\": [\"@cyanheads/transitland-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"MCP_LOG_LEVEL\": \"info\",\n        \"TRANSITLAND_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n  \"mcpServers\": {\n    \"transitland-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cyanheads/transitland-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"MCP_LOG_LEVEL\": \"info\",\n        \"TRANSITLAND_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\nOr with Docker:\n\n```json\n{\n  \"mcpServers\": {\n    \"transitland-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n        \"-e\", \"TRANSITLAND_API_KEY=your-api-key\",\n        \"ghcr.io/cyanheads/transitland-mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TRANSITLAND_API_KEY=your-api-key bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).\n- A Transitland v2 API key — register at the [Transitland developer portal](https://www.transit.land/documentation). The free tier is rate-limited; the Pro tier raises the quota.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/transitland-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd transitland-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set TRANSITLAND_API_KEY\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. A missing `TRANSITLAND_API_KEY` fails at startup with a banner naming the variable, not at the first tool call.\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `TRANSITLAND_API_KEY` | **Required.** Transitland v2 API key, sent as the `apikey` query parameter. | — |\n| `TRANSITLAND_BASE_URL` | Transitland REST API base URL. Override to pin a specific deployment or a self-hosted instance. | `https://transit.land/api/v2/rest` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted. | `/mcp` |\n| `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `notice`, `warning`, `error`). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n  ```sh\n  # One-time build\n  bun run rebuild\n\n  # Run the built server\n  bun run start:stdio\n  # or\n  bun run start:http\n  ```\n\n- **Run checks and tests:**\n\n  ```sh\n  bun run devcheck   # Lint, format, typecheck, security, changelog sync\n  bun run test       # Vitest test suite\n  bun run lint:mcp   # Validate MCP definitions against spec\n  ```\n\n### Docker\n\n```sh\ndocker build -t transitland-mcp-server .\ndocker run --rm -e TRANSITLAND_API_KEY=your-key -p 3010:3010 transitland-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/transitland-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/index.ts` | `createApp()` entry point — registers tools and resources, inits the Transitland service. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Six tools across operators, feeds, routes, stops, and departures. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Operator and feed records. |\n| `src/services/transitland` | Transitland v2 REST client — HTTP, `apikey` injection, cursor normalization, error classification, and per-endpoint typed methods. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) / [`AGENTS.md`](./AGENTS.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`\n- Wrap the Transitland API: validate raw → normalize to domain type → return output schema; never fabricate missing fields (especially license terms — blanks are `unknown`, not permissive)\n\n## Data & licensing\n\nTransit data is provided by [Transitland](https://www.transit.land/terms) — an open registry aggregating GTFS, GTFS-Realtime, and GBFS feeds from thousands of operators worldwide. Products built on Transitland data must display the name \"Transitland\" with a link to [transit.land/terms](https://www.transit.land/terms), clearly visible to end users.\n\nTransitland aggregates feeds from thousands of operators, each of which may carry its own license and attribution requirements. Review the per-feed license terms at [transit.land/terms](https://www.transit.land/terms) and comply with each source feed's requirements before redistributing or publishing data obtained through this server.\n\n## Contributing\n\nIssues are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md"}