Bus Scheduling MCP Server

This is a Model Context Protocol (MCP) server designed to interface with the Bus Scheduling Backend system. It allows MCP-compatible LLM clients (like Claude Desktop, Cursor, Cline, etc.) to access scheduling data, read KPIs, list routes, and trigger/monitor optimization algorithms.

Prerequisites

• Node.js (v18 or higher recommended)

• The accompanying Python backend must be running (by default on http://127.0.0.1:8000).

Installation

1. Install dependencies:

   npm install

2. Build the TypeScript code:

   npm run build

Configuration

If your backend is running on a different URL, you can configure it via a .env file in the root of this /mcp-server directory.

Example .env:

API_BASE_URL=http://localhost:8000/api

Running the Server

For standard usage as an MCP Server:

Point your MCP client configuration (e.g. cline_mcp_settings.json or equivalent) to the built index.js file.

Example Cursor/Claude config:

{
  "mcpServers": {
    "bus-scheduling": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"]
    }
  }
}

For development:

Run the development watcher (useful if you are actively modifying the MCP server code):

npm run dev

Available Tools

The server exposes the following tools directly to the AI:

• Dashboard & Metrics

  • scheduling_get_kpi: Fetch KPIs (vehicle status, departures, punctuality).

  • scheduling_get_trends: Get passenger flow trends.

• Routes & Data

  • scheduling_list_routes: List active bus routes.

  • scheduling_get_route_details: Fetch stations and departures for a specific route.

• Plans & Gantt

  • scheduling_list_plans: List all saved scheduling plans.

  • scheduling_get_gantt_data: Get task formats for Gantt charts.

• Optimization

  • scheduling_get_optimization_algorithms: List available optimization scripts.

  • scheduling_run_optimization: Trigger an algorithm task.

  • scheduling_get_optimization_status: Check the status of a running algorithm task.

Testing & Evaluations

You can inspect the capabilities of this server directly using the official MCP inspector:

npx @modelcontextprotocol/inspector node build/index.js

10 comprehensive use cases and checks are available in evaluations.xml in this project's root folder.