feat: add bike-share and transit tools

Add get_bike_share over the public GBFS systems and get_transit_vehicles
over the GTFS-Realtime feeds. Each finds the systems or feeds whose
coverage reaches the area, reads up to three, and reports any that were
unavailable instead of failing the whole answer. Transit results carry
each feed's attribution and license.

src/tools/index.js

@@ -10,6 +10,7 @@ import {
   getAircraftTrack,
 } from './queries/aviation.js';
 import { getActiveFires, getEarthquakes } from './queries/hazards.js';
+import { getBikeShare, getTransitVehicles } from './queries/mobility.js';
 import { placesNearby, planRoute, searchPlaces } from './queries/places.js';
 import {
   findCctvCameras,
@@ -60,4 +61,6 @@ export const coreTools = Object.freeze([
   searchPlaces,
   placesNearby,
   planRoute,
+  getBikeShare,
+  getTransitVehicles,
 ]);

src/tools/localServer.test.mjs

@@ -84,6 +84,8 @@ test('the stdio server answers newline-delimited requests using only its data so
       'search_places',
       'places_nearby',
       'plan_route',
+      'get_bike_share',
+      'get_transit_vehicles',
     ],
   );
   assert.equal(

src/tools/queries/mobility.js

@@ -0,0 +1,224 @@
+/** Bike-share and public transit queries. */
+
+import {
+  parseStationInformation,
+  parseStationStatus,
+} from '../../sources/gbfsStations.js';
+import { defineTool, ToolError } from '../catalog.js';
+import {
+  AREA_SCHEMA,
+  areaCenter,
+  areaContains,
+  areaRadiusKm,
+  distanceKm,
+  resolveArea,
+} from '../area.js';
+import { LIMIT_SCHEMA, capRows, countNoun, isoTime } from '../results.js';
+
+const MAX_SYSTEMS = 3;
+
+const round = (value, digits) =>
+  Number.isFinite(value) ? Number(value.toFixed(digits)) : null;
+
+/** Systems or feeds whose coverage reaches the area, nearest first. */
+function covering(area, entries, centerOf, radiusOf) {
+  const center = areaCenter(area);
+  const reach = areaRadiusKm(area);
+  return entries
+    .map((entry) => ({ entry, distance: distanceKm(center, centerOf(entry)) }))
+    .filter(({ entry, distance }) => distance <= reach + radiusOf(entry))
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, MAX_SYSTEMS)
+    .map(({ entry }) => entry);
+}
+
+export const getBikeShare = defineTool({
+  name: 'get_bike_share',
+  title: 'Bike-share stations',
+  description:
+    'Live bike-share stations in an area from public GBFS feeds, nearest the ' +
+    'center first, with bikes and docks available.',
+  inputSchema: {
+    type: 'object',
+    properties: { area: AREA_SCHEMA, limit: LIMIT_SCHEMA },
+    required: ['area'],
+    additionalProperties: false,
+  },
+  requires: ['bikeshare'],
+  async run(args, { services, signal }) {
+    const area = await resolveArea(args.area, { services, signal });
+    const { bikeshare } = services;
+    const systems = covering(
+      area,
+      bikeshare.systems,
+      (system) => ({ lat: system.centerLat, lon: system.centerLon }),
+      (system) => system.loadRadiusKm,
+    );
+    if (!systems.length)
+      return {
+        summary: `No supported bike-share system covers ${area.label}.`,
+        data: { ...capRows([], args.limit), systems: [] },
+      };
+    const center = areaCenter(area);
+    const results = await Promise.allSettled(
+      systems.map(async (system) => {
+        const [information, status] = await Promise.all([
+          bikeshare.getStations(system.stationInformationUrl, { signal }),
+          bikeshare.getStations(system.stationStatusUrl, { signal }),
+        ]);
+        const live = parseStationStatus(status);
+        return [...parseStationInformation(information).values()].map(
+          (station) => ({ system, station, live: live.get(station.stationId) }),
+        );
+      }),
+    );
+    signal?.throwIfAborted();
+    if (results.every((result) => result.status === 'rejected'))
+      throw new ToolError(
+        'unavailable',
+        'Bike-share feeds are unavailable right now',
+      );
+    const rows = results
+      .flatMap((result) => (result.status === 'fulfilled' ? result.value : []))
+      .filter(({ station }) => areaContains(area, station))
+      .map(({ system, station, live }) => ({
+        system: system.city,
+        provider: system.provider ?? null,
+        station_id: station.stationId,
+        name: station.name || null,
+        lat: round(station.lat, 6),
+        lon: round(station.lon, 6),
+        bikes_available: live?.bikesAvailable ?? null,
+        docks_available: live?.docksAvailable ?? null,
+        capacity: station.capacity,
+        renting: (live?.isRenting ?? station.isRenting) === true,
+        returning: (live?.isReturning ?? station.isReturning) === true,
+        last_reported: Number.isFinite(live?.lastReported)
+          ? isoTime(live.lastReported * 1000)
+          : null,
+        distance_km: round(distanceKm(center, station), 2),
+      }))
+      .sort((a, b) => a.distance_km - b.distance_km);
+    const bikes = rows.reduce(
+      (sum, row) => sum + (row.bikes_available ?? 0),
+      0,
+    );
+    const failed = results.filter(
+      (result) => result.status === 'rejected',
+    ).length;
+    return {
+      summary:
+        `${countNoun(rows.length, 'bike-share station')} in ${area.label} with ` +
+        `${countNoun(bikes, 'bike')} available` +
+        (failed ? ` (${countNoun(failed, 'system')} unavailable).` : '.'),
+      data: {
+        ...capRows(rows, args.limit),
+        systems: systems.map((system) => system.city),
+        bikes_available: bikes,
+      },
+    };
+  },
+});
+
+export const getTransitVehicles = defineTool({
+  name: 'get_transit_vehicles',
+  title: 'Transit vehicles',
+  description:
+    'Live positions of buses, trains and other transit vehicles in an area ' +
+    'from public GTFS-Realtime feeds, optionally for one route.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      area: AREA_SCHEMA,
+      route: {
+        type: 'string',
+        minLength: 1,
+        maxLength: 64,
+        description:
+          'Route id or vehicle label to match, such as "1" or "Red".',
+      },
+      limit: LIMIT_SCHEMA,
+    },
+    required: ['area'],
+    additionalProperties: false,
+  },
+  requires: ['transit'],
+  async run(args, { services, signal }) {
+    const area = await resolveArea(args.area, { services, signal });
+    const feeds = covering(
+      area,
+      await services.transit.getFeeds({ signal }),
+      (feed) => feed.center,
+      (feed) => feed.loadRadiusKm ?? 0,
+    );
+    if (!feeds.length)
+      return {
+        summary: `No supported transit feed covers ${area.label}.`,
+        data: { ...capRows([], args.limit), feeds: [] },
+      };
+    const center = areaCenter(area);
+    const results = await Promise.allSettled(
+      feeds.map(async (feed) => {
+        const response = await services.transit.requestSnapshot(feed.id, {
+          signal,
+        });
+        if (!response.ok) throw new Error(`Transit HTTP ${response.status}`);
+        const snapshot = await response.json();
+        return (snapshot.vehicles || []).map((vehicle) => ({ feed, vehicle }));
+      }),
+    );
+    signal?.throwIfAborted();
+    if (results.every((result) => result.status === 'rejected'))
+      throw new ToolError(
+        'unavailable',
+        'Transit feeds are unavailable right now',
+      );
+    const wanted = args.route?.trim().toLowerCase();
+    const rows = results
+      .flatMap((result) => (result.status === 'fulfilled' ? result.value : []))
+      .filter(({ vehicle }) => areaContains(area, vehicle))
+      .filter(
+        ({ vehicle }) =>
+          !wanted ||
+          [vehicle.routeId, vehicle.label].some(
+            (value) => String(value || '').toLowerCase() === wanted,
+          ),
+      )
+      .map(({ feed, vehicle }) => ({
+        feed: feed.name,
+        id: vehicle.id,
+        label: vehicle.label ?? null,
+        route_id: vehicle.routeId ?? null,
+        trip_id: vehicle.tripId ?? null,
+        lat: vehicle.lat,
+        lon: vehicle.lon,
+        bearing_deg: round(vehicle.bearing, 0),
+        speed_mps: round(vehicle.speedMps, 1),
+        status: vehicle.status ?? null,
+        occupancy: vehicle.occupancy ?? null,
+        updated: Number.isFinite(vehicle.timestamp)
+          ? isoTime(vehicle.timestamp * 1000)
+          : null,
+        distance_km: round(distanceKm(center, vehicle), 2),
+      }))
+      .sort((a, b) => a.distance_km - b.distance_km);
+    const failed = results.filter(
+      (result) => result.status === 'rejected',
+    ).length;
+    const what = args.route ? ` on route ${args.route}` : '';
+    return {
+      summary:
+        `${countNoun(rows.length, 'transit vehicle')}${what} in ${area.label}` +
+        (failed ? ` (${countNoun(failed, 'feed')} unavailable).` : '.'),
+      data: {
+        ...capRows(rows, args.limit),
+        feeds: feeds.map((feed) => ({
+          name: feed.name,
+          operator: feed.operator ?? null,
+          attribution: feed.attribution ?? null,
+          license: feed.license ?? null,
+        })),
+      },
+    };
+  },
+});

src/tools/queries/mobility.test.mjs

@@ -0,0 +1,262 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { composeCatalog, coreTools } from '../index.js';
+
+const system = (id, city, centerLat, centerLon) => ({
+  id,
+  city,
+  centerLat,
+  centerLon,
+  loadRadiusKm: 30,
+  provider: 'Test Bikes',
+  stationInformationUrl: `https://gbfs.example/${id}/station_information.json`,
+  stationStatusUrl: `https://gbfs.example/${id}/station_status.json`,
+});
+const documents = {
+  'https://gbfs.example/austin/station_information.json': {
+    data: {
+      stations: [
+        {
+          station_id: 's1',
+          name: 'Congress & 2nd',
+          lat: 30.2645,
+          lon: -97.7445,
+          capacity: 12,
+        },
+        {
+          station_id: 's2',
+          name: 'Far Station',
+          lat: 30.4,
+          lon: -97.9,
+          capacity: 8,
+        },
+        {
+          station_id: 's3',
+          name: 'Lamar & 5th',
+          lat: 30.268,
+          lon: -97.753,
+          capacity: '10',
+        },
+      ],
+    },
+  },
+  'https://gbfs.example/austin/station_status.json': {
+    data: {
+      stations: [
+        {
+          station_id: 's1',
+          num_bikes_available: 4,
+          num_docks_available: 8,
+          is_renting: 1,
+          last_reported: 1767225600,
+        },
+        {
+          station_id: 's3',
+          num_bikes_available: 0,
+          num_docks_available: 10,
+          is_renting: 0,
+        },
+      ],
+    },
+  },
+};
+const bikeshare = (systems, failing = new Set()) => ({
+  systems,
+  async getStations(url) {
+    if ([...failing].some((id) => url.includes(`/${id}/`)))
+      throw new Error('GBFS HTTP 502');
+    return documents[url];
+  },
+});
+const downtown = { lat: 30.2672, lon: -97.7431, radius_km: 2 };
+
+test('bike share joins station information with live status inside the area', async () => {
+  const catalog = composeCatalog({
+    tools: coreTools,
+    services: {
+      bikeshare: bikeshare([
+        system('austin', 'Austin, TX', 30.27, -97.74),
+        system('oslo', 'Oslo', 59.9, 10.7),
+      ]),
+    },
+  });
+  const result = await catalog.call('get_bike_share', { area: downtown });
+  assert.equal(
+    result.summary,
+    '2 bike-share stations in 2 km around 30.267, -97.743 with 4 bikes available.',
+  );
+  assert.deepEqual(result.data.systems, ['Austin, TX']);
+  assert.deepEqual(result.data.rows[0], {
+    system: 'Austin, TX',
+    provider: 'Test Bikes',
+    station_id: 's1',
+    name: 'Congress & 2nd',
+    lat: 30.2645,
+    lon: -97.7445,
+    bikes_available: 4,
+    docks_available: 8,
+    capacity: 12,
+    renting: true,
+    returning: true,
+    last_reported: '2026-01-01T00:00:00.000Z',
+    distance_km: 0.33,
+  });
+  assert.equal(result.data.rows[1].renting, false);
+  assert.equal(result.data.rows[1].capacity, 10);
+});
+
+test('bike share reports uncovered areas and failed systems honestly', async () => {
+  const none = composeCatalog({
+    tools: coreTools,
+    services: { bikeshare: bikeshare([system('oslo', 'Oslo', 59.9, 10.7)]) },
+  });
+  const empty = await none.call('get_bike_share', { area: downtown });
+  assert.equal(
+    empty.summary,
+    'No supported bike-share system covers 2 km around 30.267, -97.743.',
+  );
+  assert.equal(empty.data.total, 0);
+  const both = [
+    system('austin', 'Austin, TX', 30.27, -97.74),
+    system('round-rock', 'Round Rock', 30.5, -97.68),
+  ];
+  const partial = composeCatalog({
+    tools: coreTools,
+    services: { bikeshare: bikeshare(both, new Set(['round-rock'])) },
+  });
+  assert.match(
+    (
+      await partial.call('get_bike_share', {
+        area: { lat: 30.4, lon: -97.7, radius_km: 20 },
+      })
+    ).summary,
+    /\(1 system unavailable\)\.$/,
+  );
+  const down = composeCatalog({
+    tools: coreTools,
+    services: { bikeshare: bikeshare(both, new Set(['austin', 'round-rock'])) },
+  });
+  await assert.rejects(
+    down.call('get_bike_share', { area: downtown }),
+    (error) => error.code === 'unavailable',
+  );
+});
+
+const feed = {
+  id: 'capmetro',
+  name: 'CapMetro',
+  operator: 'Capital Metro',
+  center: { lat: 30.27, lon: -97.74 },
+  loadRadiusKm: 50,
+  attribution: 'Capital Metro',
+  license: 'Open data',
+};
+const vehicles = [
+  {
+    id: 'v1',
+    lat: 30.2675,
+    lon: -97.7425,
+    bearing: 91.6,
+    speedMps: 8.23,
+    timestamp: 1767225600,
+    routeId: '1',
+    tripId: 't1',
+    label: '1 North',
+    status: 'IN_TRANSIT_TO',
+    occupancy: 'FEW_SEATS_AVAILABLE',
+  },
+  {
+    id: 'v2',
+    lat: 30.268,
+    lon: -97.745,
+    bearing: null,
+    speedMps: null,
+    timestamp: null,
+    routeId: '801',
+    label: 'Rapid',
+  },
+  { id: 'v3', lat: 30.5, lon: -97.6, routeId: '1' },
+];
+const transit = (
+  snapshot = { ok: true, status: 200, json: async () => ({ vehicles }) },
+) => ({
+  requested: [],
+  async getFeeds() {
+    return [
+      feed,
+      { ...feed, id: 'far', name: 'Far Away', center: { lat: 0, lon: 0 } },
+    ];
+  },
+  async requestSnapshot(id) {
+    this.requested.push(id);
+    return snapshot;
+  },
+});
+
+test('transit vehicles come from nearby feeds and can be limited to a route', async () => {
+  const source = transit();
+  const catalog = composeCatalog({
+    tools: coreTools,
+    services: { transit: source },
+  });
+  const all = await catalog.call('get_transit_vehicles', { area: downtown });
+  assert.equal(
+    all.summary,
+    '2 transit vehicles in 2 km around 30.267, -97.743.',
+  );
+  assert.deepEqual(source.requested, ['capmetro']);
+  assert.deepEqual(all.data.rows[0], {
+    feed: 'CapMetro',
+    id: 'v1',
+    label: '1 North',
+    route_id: '1',
+    trip_id: 't1',
+    lat: 30.2675,
+    lon: -97.7425,
+    bearing_deg: 92,
+    speed_mps: 8.2,
+    status: 'IN_TRANSIT_TO',
+    occupancy: 'FEW_SEATS_AVAILABLE',
+    updated: '2026-01-01T00:00:00.000Z',
+    distance_km: 0.07,
+  });
+  assert.deepEqual(all.data.feeds, [
+    {
+      name: 'CapMetro',
+      operator: 'Capital Metro',
+      attribution: 'Capital Metro',
+      license: 'Open data',
+    },
+  ]);
+  const rapid = await catalog.call('get_transit_vehicles', {
+    area: downtown,
+    route: 'rapid',
+  });
+  assert.equal(
+    rapid.summary,
+    '1 transit vehicle on route rapid in 2 km around 30.267, -97.743.',
+  );
+  assert.equal(rapid.data.rows[0].id, 'v2');
+});
+
+test('transit reports uncovered areas and unavailable feeds', async () => {
+  const catalog = composeCatalog({
+    tools: coreTools,
+    services: { transit: transit() },
+  });
+  const oslo = await catalog.call('get_transit_vehicles', {
+    area: { lat: 59.9, lon: 10.7, radius_km: 5 },
+  });
+  assert.equal(
+    oslo.summary,
+    'No supported transit feed covers 5 km around 59.900, 10.700.',
+  );
+  const down = composeCatalog({
+    tools: coreTools,
+    services: { transit: transit({ ok: false, status: 503 }) },
+  });
+  await assert.rejects(
+    down.call('get_transit_vehicles', { area: downtown }),
+    (error) => error.code === 'unavailable',
+  );
+});