# 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:
   ```bash
   npm install
   ```
2. Build the TypeScript code:
   ```bash
   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:
```json
{
  "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):
```bash
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:
```bash
npx @modelcontextprotocol/inspector node build/index.js
```

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