Skip to main content
Glama
Sign In

onebusaway-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Get Block Schedule

onebusaway_get_block
Read-only

Fetch block trip sequences with their stop times and service-calendar conditions. Top-level fields describe the first returned configuration; every remaining alternative is included without choosing a calendar date. Optionally select an exact tripId or complete trips having any departure in a half-open GTFS-seconds interval, independently in every configuration; selection counts trip occurrences before and after filtering. Without selectors, returns all trips with no default cap. Block IDs appear as blockId in onebusaway_get_trip responses; obtain a tripId from onebusaway_get_arrivals first.

Input Schema

NameRequiredDescriptionDefault
tripIdNoExact trip ID; omit or leave blank for no trip selector. Mutually exclusive with departure bounds.
blockIdYesBlock ID from a trip record. Obtain a tripId from onebusaway_get_arrivals, then call onebusaway_get_trip to get the blockId.
departureFromSecNoInclusive departure lower bound in GTFS seconds from midnight; values beyond 86400 are valid.
departureBeforeSecNoExclusive departure upper bound in GTFS seconds from midnight; must exceed departureFromSec when both are supplied.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
tripsNoAll trips in the first returned configuration, in order.
noticeNoAlternative-configuration guidance or an aggregate empty-selection notice.
blockIdNoBlock ID.
selectionNoApplied selectors and aggregate trip occurrence counts across every configuration; absent without selectors.
activeServiceIdsNoService IDs required active for the first returned configuration.
inactiveServiceIdsNoService IDs required inactive for the first returned configuration.
alternateConfigurationsNoRemaining configurations in upstream order; empty when none exist.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changed
    • addedInput schema / properties / departureBeforeSec
      Added value: +{
+  "description": "Exclusive departure upper bound in GTFS seconds from midnight; must exceed departureFromSec when both are supplied.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / departureFromSec
      Added value: +{
+  "description": "Inclusive departure lower bound in GTFS seconds from midnight; values beyond 86400 are valid.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / tripId
      Added value: +{
+  "description": "Exact trip ID; omit or leave blank for no trip selector. Mutually exclusive with departure bounds.",
+  "type": "string"
+}
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "blockId",
-      "activeServiceIds",
-      "inactiveServiceIds",
-      "trips"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "blockId",
+      "activeServiceIds",
+      "inactiveServiceIds",
+      "trips",
+      "alternateConfigurations"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • changedOutput schema / properties / activeServiceIds / description
      Previous value: -"Service calendar IDs active for this block today."New value: +"Service IDs required active for the first returned configuration."
    • addedOutput schema / properties / alternateConfigurations
      Added value: +{
+  "description": "Remaining configurations in upstream order; empty when none exist.",
+  "items": {
+    "additionalProperties": false,
+    "description": "An alternative block configuration.",
+    "properties": {
+      "activeServiceIds": {
+        "description": "Service IDs required active for this configuration.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "inactiveServiceIds": {
+        "description": "Service IDs required inactive for this configuration.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "trips": {
+        "description": "Ordered trips in this configuration.",
+        "items": {
+          "additionalProperties": false,
+          "description": "A block trip.",
+          "properties": {
+            "accumulatedSlackTime": {
+              "description": "Accumulated layover/slack time (seconds) before this trip starts.",
+              "type": "number"
+            },
+            "blockStopTimes": {
+              "description": "Ordered stop times.",
+              "items": {
+                "additionalProperties": false,
+                "description": "A stop time.",
+                "properties": {
+                  "arrivalTime": {
+                    "description": "Arrival in GTFS seconds from midnight.",
+                    "type": "number"
+                  },
+                  "departureTime": {
+                    "description": "Departure in GTFS seconds from midnight.",
+                    "type": "number"
+                  },
+                  "dropOffType": {
+                    "description": "GTFS drop-off type (0=regular, 1=no dropoff, 2=phone agency, 3=coordinate with driver).",
+                    "type": "number"
+                  },
+                  "pickupType": {
+                    "description": "GTFS pickup type (0=regular, 1=no pickup, 2=phone agency, 3=coordinate with driver).",
+                    "type": "number"
+                  },
+                  "stopId": {
+                    "description": "Stop ID.",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "stopId",
+                  "arrivalTime",
+                  "departureTime"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "distanceAlongBlock": {
+              "description": "Cumulative distance (meters) from block start to the first stop of this trip.",
+              "type": "number"
+            },
+            "tripId": {
+              "description": "Trip ID for follow-up onebusaway_get_trip calls.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tripId",
+            "distanceAlongBlock",
+            "accumulatedSlackTime",
+            "blockStopTimes"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "activeServiceIds",
+      "inactiveServiceIds",
+      "trips"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / inactiveServiceIds / description
      Previous value: -"Service calendar IDs not active for this block today."New value: +"Service IDs required inactive for the first returned configuration."
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Alternative-configuration guidance or an aggregate empty-selection notice.",
+  "type": "string"
+}
    • addedOutput schema / properties / selection
      Added value: +{
+  "additionalProperties": false,
+  "description": "Applied selectors and aggregate trip occurrence counts across every configuration; absent without selectors.",
+  "properties": {
+    "configurationCounts": {
+      "description": "Preserved slot order: index 0 is the top-level first configuration; index 1 is alternateConfigurations[0], and so on, including empty slots.",
+      "items": {
+        "additionalProperties": false,
+        "description": "Trip occurrence counts for one configuration.",
+        "properties": {
+          "returned": {
+            "description": "Count after local selection.",
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "total": {
+            "description": "Count before local selection.",
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "total",
+          "returned"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "departureBeforeSec": {
+      "description": "Exclusive departure upper bound in GTFS seconds from midnight; must exceed departureFromSec when both are supplied.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "departureFromSec": {
+      "description": "Inclusive departure lower bound in GTFS seconds from midnight; values beyond 86400 are valid.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "returned": {
+      "description": "Count after local selection.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "total": {
+      "description": "Count before local selection.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "tripId": {
+      "description": "Exact trip ID; omit or leave blank for no trip selector. Mutually exclusive with departure bounds.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "total",
+    "returned",
+    "configurationCounts"
+  ],
+  "type": "object"
+}
    • changedOutput schema / properties / trips / description
      Previous value: -"All trips in this block in order."New value: +"All trips in the first returned configuration, in order."
    • changedOutput schema / properties / trips / items / description
      Previous value: -"A trip in this vehicle block."New value: +"A block trip."
    • changedOutput schema / properties / trips / items / properties / blockStopTimes / description
      Previous value: -"Ordered stop times for this trip."New value: +"Ordered stop times."
    • changedOutput schema / properties / trips / items / properties / blockStopTimes / items / description
      Previous value: -"A scheduled stop time within this trip."New value: +"A stop time."
    • changedOutput schema / properties / trips / items / properties / blockStopTimes / items / properties / arrivalTime / description
      Previous value: -"Scheduled arrival time as seconds from midnight (GTFS format)."New value: +"Arrival in GTFS seconds from midnight."
    • changedOutput schema / properties / trips / items / properties / blockStopTimes / items / properties / departureTime / description
      Previous value: -"Scheduled departure time as seconds from midnight (GTFS format)."New value: +"Departure in GTFS seconds from midnight."
  2. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `block_not_found`: Block ID does not exist on this instance. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `block_not_found`: Block ID does not exist on this instance. `rate_limited`: No upstream request slot opened within the queue wait cap, or OneBusAway returned a rate limit response. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "block_not_found"
-]New value: +[
+  "block_not_found",
+  "rate_limited"
+]
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "blockId",
+      "activeServiceIds",
+      "inactiveServiceIds",
+      "trips"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `block_not_found`: Block ID does not exist on this instance. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "block_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "blockId",
-  "activeServiceIds",
-  "inactiveServiceIds",
-  "trips"
-]
  4. Added

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint already covers safety, so the description is free to add real behavior. It does: top-level fields describe the first returned configuration, alternatives are returned without choosing a calendar date, and selection counts trip occurrences before and after filtering. It also discloses that there is no default cap on results. That is meaningful context beyond the annotations, though return size or ordering is still unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and contains no filler, but the middle sentences are densely nested ('independently in every configuration; selection counts trip occurrences before and after filtering') and hard to parse on first read. The closing sentence about blockId also largely repeats what the blockId schema field already says.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and readOnlyHint is set, so return values and safety do not need to be explained. The description covers the ambiguous parts: multi-configuration results, defaults, and selector interaction. What is missing is any note on result size or pagination when no cap applies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description still adds value by explaining that selection applies independently in every configuration and by clarifying the half-open interval semantics and the counting behavior. It also reinforces the tripId/departure-bounds mutual exclusivity that the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Fetch block trip sequences with their stop times and service-calendar conditions.' That is clearly distinct from get_trip or get_arrivals. It never explains in one clause what a 'block' is or why this differs from get_schedule_for_route, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It describes the two selection modes (tripId or departure interval) and notes that no selectors means all trips with no cap, which implies usage. It also gives a workflow hint ('obtain a tripId from onebusaway_get_arrivals first'). However, it never says when to use this tool rather than get_trip or get_schedule_for_route, so the guidance remains implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All onebusaway-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources