bus-tracker-mcp

MCP (Model Context Protocol) server that exposes a small set of tools to fetch scheduled bus departures for two directions: home→bar and bar→home.

This repository contains a tiny MCP server that can be run from the CLI (stdin/stdout transport) or started programmatically from other Node code. It normalizes remote departure JSON into a tolerant, predictable shape and exposes both machine-friendly structured results and short human-readable text.

Key files

• package.json — project scripts & dependencies
• tsconfig.json — TypeScript config
• src/cli.ts — CLI entrypoint that starts the MCP server via stdin/stdout
• src/server.ts — implementation of the MCP tools (exports createServer and fetchDepartures)

What it does

• Starts an MCP server named bus-tracker-mcp.
• Registers a primary tool bus_departures which accepts an enum input (homeToBar or barToHome) and returns structured departure data.
• Registers two convenience alias tools: home_to_bar_departures and bar_to_home_departures.

Install & run

Prerequisites

• Node.js (LTS recommended) and npm installed.

Development (no build)

# install deps
npm ci

# run in dev mode (uses tsx to run src/cli.ts)
npm run dev

Build and run

# build TypeScript to dist/
npm run build

# run the built CLI directly
node dist/cli.js

# or install locally and run the CLI globally
npm link
bus-tracker-mcp

Using in VS Code

Add the below to the mcp.json config file.

"bus-tracker": {
    "command": "npx",
    "args": ["-y", "@chrislaughlin/bus-tracker-mcp@latest"]
}

You can run and debug the server easily from Visual Studio Code. Here are a few recommended steps and a sample launch configuration.

1. Open the project folder in VS Code (File → Open...).
2. Make sure Node.js is installed and npm ci has been run once to install dependencies.
3. Use the integrated terminal to run the dev script:

npm run dev

4. (Optional) Add a debug launch configuration so you can start the server from the Run view and see output in the integrated terminal. Create a .vscode/launch.json with the following configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run bus-tracker-mcp (dev)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}"
    }
  ]
}

5. Start the configuration from the Run and Debug panel (select Run bus-tracker-mcp (dev) and press the green play button). Your server will start in the integrated terminal and communicate over stdin/stdout.

Notes about VS Code environment:

• You don't need special VS Code extensions to run the server, but extensions that improve Node.js/TypeScript editing (ESLint, TypeScript Hero, npm scripts) can help.
• If you prefer to run the built JS, change the launch configuration to run node against dist/cli.js after npm run build.

Programmatic usage

You can import and start the server programmatically via the exported factory in src/server.ts:

import { createServer } from './src/server.js';

const server = createServer();
// attach an MCP transport (the CLI uses stdio) and start sending requests

Examples

1. Dev run (stdin/stdout transport)

• Start the server:

npm run dev

• The server uses the stdio transport (see src/cli.ts) and communicates over stdin/stdout using MCP.

2. Example tool response (structured)

The tools return a result object with both human-readable content and structuredContent. The structuredContent looks like:

{
  "departures": [
    {
      "scheduled": "2025-11-06T18:30:00.000Z",
      "dueMinutes": 12,
      "raw": { "departureTimePlanned": "...", "departureTimeBaseTimetable": "...", "runningLate": false }
    }
  ],
  "meta": { "count": 1 }
}

3. Example human-readable text returned inside content (simplified)

Departures (homeToBar) — 2 result(s)
 @ 18:30 (due in 12 min)
 @ 19:05 (due in 47 min)

Notes

• The network fetch logic lives in fetchDepartures (src/server.ts) and normalizes incoming JSON into a tolerant shape (see normalizeDepartures in src/server.ts).
• The MCP server is implemented using @modelcontextprotocol/sdk (see src/server.ts).

If you need a client example that talks MCP to this server, pick any MCP-compatible client transport and connect to the CLI/stdin-stdout process started with bus-tracker-mcp (or run the server programmatically with createServer and attach your transport).