Skip to main content
Glama
wheelstransit

wheels-router-mcp

Official
by wheelstransit
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Wheels Router MCP Server

Built with MatthewDailey/mcp-starter

A Model Context Protocol server for Hong Kong public transit routing. Provides tools to search locations and plan trips using the Wheels Router API.

Features

  • Location Search: Find places in Hong Kong using OpenStreetMap Nominatim

  • Trip Planning: Get public transit routes with MTR, bus, ferry, and walking directions

Related MCP server: Hong Kong Government Data MCP Server

Installation

With npm

npm install -g wheels-router-mcp

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wheels-router": {
      "command": "wheels-router-mcp"
    }
  }
}

OpenCode

Add to your OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wheels-router": {
      "type": "local",
      "command": ["npx", "-y", "wheels-router-mcp"],
      "enabled": true
    }
  }
}

From Source

  1. Clone and build:

git clone https://github.com/wheelstransit/wheels-router-mcp
cd wheels-router-mcp
npm install
npm run build

  1. Add to your preferred tool's config:

Claude Desktop:

{
  "mcpServers": {
    "wheels-router": {
      "command": "node",
      "args": ["/absolute/path/to/wheels-router-mcp/dist/index.cjs"]
    }
  }
}

OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wheels-router": {
      "type": "local",
      "command": ["node", "/absolute/path/to/wheels-router-mcp/dist/index.cjs"],
      "enabled": true
    }
  }
}

  1. Restart your application

Available Tools

search_location

Search for places in Hong Kong.

Parameters:

  • query (string, required): Place name (e.g., "Yau Tong MTR Exit A2")

  • limit (number, optional): Max results (1-10, default: 5)

Example:

Find "Tsim Sha Tsui"

plan_trip

Plan a public transit trip in Hong Kong.

Parameters:

  • origin (string, required): Starting point as lat,lon or stop:ID

  • destination (string, required): Destination as lat,lon or stop:ID

  • depart_at (string, optional): ISO 8601 departure time

  • arrive_by (string, optional): ISO 8601 arrival deadline

  • modes (string, optional): Comma-separated modes (e.g., mtr,bus,ferry)

  • max_results (number, optional): Max route plans (1-5)

Example:

Plan a trip from 22.3193,114.2644 to 22.2783,114.1747

Development

Run with Inspector for testing:

npm run dev

This starts both the file watcher and MCP Inspector.

License

See LICENSE

Available Tools

3 tools
hello_toolD

Hello tool

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the person to greet

TDQS

D1.7/5.0
Behavior1/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Hello tool' discloses nothing about side effects, return values, or operational behavior, leaving the agent completely uninformed beyond the tool's name.

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

Conciseness2/5

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

The description is extremely short, but this is under-specification rather than effective conciseness. It is a two-word tautology that provides no informative structure or front-loaded value.

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

Completeness2/5

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

While the tool is simple and the schema fully documents its one parameter, the description still fails to state the tool's purpose or expected behavior. An agent may infer from the name and parameter that it greets a person, but the description itself is incomplete.

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

Parameters3/5

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

Schema description coverage is 100%: the only parameter, 'name', is described as 'The name of the person to greet'. This meets the baseline where the schema does the heavy lifting. The description itself adds no additional parameter meaning.

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

Purpose1/5

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

The description 'Hello tool' simply restates the tool name without a verb, resource, or outcome. It does not specify that the tool greets a person or what action it performs, and it fails to distinguish itself from siblings like plan_trip or search_location.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool or when to prefer an alternative. There are no exclusions, conditions, or context clues to help an agent decide between hello_tool and its siblings.

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

plan_tripA

Plan a transit trip. Uses Wheels Router for Hong Kong and Transitous for other regions. IMPORTANT: fares_min/fares_max are fare ranges, NOT interchange discounts. Interchange discounts (轉乘優惠) only apply when FareDiscountRules are explicitly present in the API response, and IT ONLY APPLIES TO CERTAIN ROUTES.

ParametersJSON Schema
NameRequiredDescriptionDefault
modesNoOptional comma-separated modes (e.g. 'mtr,bus,ferry'). Only set if needed.
originYesRequired. Starting point as 'lat,lon' or 'stop:ID'. Use coordinates or stop IDs only.
arrive_byNoOptional ISO 8601 arrival deadline (UTC preferred).
depart_atNoOptional ISO 8601 departure time (UTC preferred).
destinationYesRequired. Destination as 'lat,lon' or 'stop:ID'. Use coordinates or stop IDs only.
max_resultsNoOptional cap on returned plans (1-5). Defaults to API behavior.

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations provided, the description carries a heavier burden, and it does well by disclosing important behavioral nuances: backends differ by region, and fares_min/fares_max must not be misinterpreted as interchange discounts. It doesn't cover every possible output or error behavior, but the key caveat is prominently surfaced.

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

Conciseness5/5

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

The description is tight and well-structured: the core action first, followed by regional routing scope, then a critical warning. Each sentence adds distinct value and there is no filler or repetition.

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?

For a moderate-complexity tool, the description covers the most important context: router selection and a non-obvious fare/discount caveat. A minor gap is that there is no explicit return-shape description despite no output schema, but the warning about response fields partly mitigates this.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional input-parameter meaning; the fares_min/fares_max warning relates to response semantics rather than the schema parameters themselves.

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

Purpose5/5

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

The description clearly states the tool's core function with a specific verb and resource: 'Plan a transit trip.' It adds concrete distinction by naming the routing backends for different regions, which separates it from sibling tools like search_location and hello_tool without ambiguity.

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

Usage Guidelines4/5

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

The description provides clear context that this tool is for trip planning and explains regional routing behavior: Wheels Router for Hong Kong and Transitous for other regions. It does not explicitly name sibling alternatives or when-not-to-use conditions, but the action and routing scope make the intended usage apparent.

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

search_locationA

Search locations via Nominatim (use for origin/destination lookup).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoHow many results to return (1-10).
queryYesFree-text place search. Example: 'Yau Tong MTR Exit A2' or 'Tokyo Station'.

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It names the external backend (Nominatim) and implies a read-only search operation, which adds some context. However, it does not disclose potential limitations such as rate limits, network dependence, or approximate result behavior.

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

Conciseness5/5

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

A single, direct sentence with no filler. The action is front-loaded, and the parenthetical use-case earns its place by clarifying when to invoke the tool.

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

Completeness3/5

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

The tool is simple with only two parameters and no output schema, so the description is mostly adequate. However, without an output schema, it does not explain what a result looks like (e.g., matched place names, coordinates), which an agent might need to properly consume the response.

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

Parameters3/5

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

Schema description coverage is 100%: both 'query' and 'limit' already have descriptive text and constraints. The description adds no additional parameter meaning, so baseline score of 3 is appropriate.

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

Purpose5/5

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

The description states a specific action ('Search locations'), identifies the resource ('via Nominatim'), and adds the intended use case ('for origin/destination lookup'). This clearly distinguishes it from the sibling tools plan_trip and hello_tool.

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

Usage Guidelines4/5

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

The phrase 'use for origin/destination lookup' gives a clear when-to-use context. It does not explicitly mention alternatives or exclusions, but the intended use case is enough to guide an agent away from the unrelated siblings.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.5.0
    • First observedhello_tool
    • First observedplan_trip
    • First observedsearch_location
Deploy Server
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

TDQS

B3/5.0

Scored across 3 tools

Disambiguation4/5

plan_trip and search_location have clear, non-overlapping purposes, and hello_tool is obviously set apart. However, hello_tool is a vague stub that doesn't fit the travel domain, so there is a slight coherence cost.

Naming Consistency4/5

plan_trip and search_location both follow a verb_noun snake_case pattern. hello_tool breaks the pattern with a greeting-style verb, but since only one of three tools deviates, the naming is mostly consistent.

Tool Count3/5

Three tools is borderline for a transit router, and only two are actually useful. hello_tool is filler, which makes the effective functional surface feel thin for the stated purpose.

Completeness4/5

The core workflow is covered: search_location for origin/destination lookup and plan_trip for routing. Minor gaps exist, such as route/fare rule inspection or provider metadata, but agents can complete basic trip planning without dead ends.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers