# TrainTrack AI Agent Setup Instructions

This document provides instructions for AI agents and developer tools to configure and register the **TrainTrack MCP (Model Context Protocol) Server**.

---

## 1. Quick Overview

- **Server URL**: `https://api.traintrack.hu/mcp`
- **Protocol Version**: `2026-07-28` (Streamable HTTP / SSE transport, JSON-RPC 2.0)
- **Authentication**: `X-API-Key: <YOUR_API_KEY>` or `Authorization: Bearer <YOUR_API_KEY>`
- **Capabilities**: Live train coordinates, delay predictions, station departure/arrival boards, delay toplists, network status, and journey route calculations across Hungary.

---

## 2. Automatic Setup Instructions for Agents

If you are an AI agent configuring tools for the user, determine the user's environment and add the MCP server configuration accordingly:

### A. Antigravity / Gemini CLI (`.gemini/config.json` or CLI)

Add to the user's MCP configuration:
```json
{
  "mcpServers": {
    "traintrack": {
      "url": "https://api.traintrack.hu/mcp",
      "headers": {
        "X-API-Key": "$TRAINTRACK_API_KEY"
      }
    }
  }
}
```

Or via command line:
```bash
agy mcp add traintrack --url https://api.traintrack.hu/mcp --header "X-API-Key=$TRAINTRACK_API_KEY"
```

### B. Claude Desktop (`claude_desktop_config.json`)

File locations:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

Add the following block under `mcpServers`:
```json
{
  "mcpServers": {
    "traintrack": {
      "url": "https://api.traintrack.hu/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### C. Cursor (`.cursor/mcp.json` or Global Settings)

File location: `.cursor/mcp.json` in project root or Cursor Settings > Features > MCP:
```json
{
  "mcpServers": {
    "traintrack": {
      "url": "https://api.traintrack.hu/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### D. Windsurf / Codeium (`~/.codeium/windsurf/mcp_config.json`)

```json
{
  "mcpServers": {
    "traintrack": {
      "url": "https://api.traintrack.hu/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

### E. Cline / Roo-Code (`cline_mcp_settings.json`)

```json
{
  "mcpServers": {
    "traintrack": {
      "url": "https://api.traintrack.hu/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

---

## 3. Available MCP Tools Reference

Once connected, the following tools are available:

1. **`search_trains`**:
   - Query trains by number (e.g. `IC 910`, `S50 2824`), station name (`Budapest-Keleti`, `Győr`), or destination.
   - Parameters: `query` (string, required), `delayed_only` (boolean, optional).

2. **`get_train_details`**:
   - Fetch real-time GPS position, speed, delay in minutes, complete stop schedule with scheduled vs estimated times.
   - Parameters: `train_id` (string, required).

3. **`get_station_schedule`**:
   - Fetch live departure and arrival boards for any Hungarian railway station with platform and delay information.
   - Parameters: `station_name` (string, required), `direction` (enum: `arrivals` | `departures` | `both`).

4. **`get_delay_toplist`**:
   - Ranked list of currently most delayed trains on the network and system punctuality metrics.
   - Parameters: `limit` (number, default: 10, max: 50).

5. **`get_network_status`**:
   - High-level Hungarian railway network operational health, total active train count, average network delay.
   - Parameters: none.

6. **`calculate_route`**:
   - Route and connection planner between origin and destination stations with transfer times.
   - Parameters: `from_station` (string, required), `to_station` (string, required).

---

## 4. Verification & Testing

To test if the MCP connection is working, ask the agent:
> *"What is the current delay of train IC 910?"* or *"Show me the most delayed trains in Hungary right now."*

The agent should invoke `search_trains` or `get_delay_toplist` via the TrainTrack MCP server and return real-time data.