# dkawale499/railway-mcp-server architecture

> Architecture diagram of the GitHub repository dkawale499/railway-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dkawale499/railway-mcp-server
- Repository: https://github.com/dkawale499/railway-mcp-server

## Overview

This is a Spring Boot MCP adapter that exposes Railway Reservation backend operations as tools for Copilot and other MCP clients. The main workflow is MCP tool invocation, domain-specific tool delegation, authenticated HTTP request, and backend response. Authentication maintains a shared active account and refreshes a cached JWT after a 401; passenger booking and lookup, wallet access, and administrator reporting and schedule management are separate capabilities. The excerpts show the tool-to-client calls and client HTTP behavior; README documents the Streamable HTTP entry point and additional capabilities.

Main entry points: [`src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java`](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java) (Railway API client), [`src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java) (Railway tools), [`src/main/java/com/sts/Railway_mcp_server/config/RailwayApiConfiguration.java`](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/config/RailwayApiConfiguration.java) (Tool registration), [`src/main/java/com/sts/Railway_mcp_server/tools/CoachConfig.java`](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/CoachConfig.java) (Coach configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_tool_registration["Tool registration"]
  node_railway_tools["Railway tools<br/>[RailwayTools.java]"]
end

subgraph group_passenger["Passenger tools"]
  node_auth_tools["Account tools<br/>[RailwayTools.java]"]
  node_travel_tools["Travel tools<br/>[RailwayTools.java]"]
  node_account_tools["Wallet and tickets<br/>[RailwayTools.java]"]
end

subgraph group_admin["Administration"]
  node_admin_ticket_tools["Ticket and user admin<br/>[RailwayTools.java]"]
  node_schedule_tools["Schedule admin<br/>[RailwayTools.java]"]
  node_coach_config["Coach configuration<br/>[CoachConfig.java]"]
end

subgraph group_backend["Backend access"]
  node_api_client["Railway API client"]
  node_api_config["API settings"]
end

node_mcp_client(("MCP client"))
node_railway_api["Railway Reservation API"]

node_mcp_client -->|"invokes tools"| node_railway_tools
node_tool_registration -->|"registers callbacks"| node_railway_tools
node_railway_tools -->|"exposes"| node_auth_tools
node_auth_tools -->|"delegates auth"| node_api_client
node_travel_tools -->|"delegates travel"| node_api_client
node_account_tools -->|"delegates account"| node_api_client
node_admin_ticket_tools -->|"delegates reports"| node_api_client
node_schedule_tools -->|"delegates schedules"| node_api_client
node_schedule_tools -->|"accepts typed coaches"| node_coach_config
node_api_client -->|"reads settings"| node_api_config
node_api_client -->|"sends HTTP requests"| node_railway_api

click node_tool_registration "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/config/RailwayApiConfiguration.java"
click node_railway_tools "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java"
click node_auth_tools "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java"
click node_travel_tools "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java"
click node_account_tools "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java"
click node_admin_ticket_tools "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java"
click node_schedule_tools "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java"
click node_api_client "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java"
click node_api_config "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/config/RailwayApiProperties.java"
click node_coach_config "https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/CoachConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tool_registration,node_railway_tools,node_mcp_client toneBlue
class node_auth_tools,node_travel_tools,node_account_tools toneAmber
class node_admin_ticket_tools,node_schedule_tools,node_coach_config,node_railway_api toneMint
class node_api_client,node_api_config toneRose
```

## Components

### MCP entry

- [Tool registration](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/config/RailwayApiConfiguration.java): `src/main/java/com/sts/Railway_mcp_server/config/RailwayApiConfiguration.java`
- [Railway tools](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java): `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`

### Passenger tools

- [Account tools](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java): `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`
- [Travel tools](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java): `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`
- [Wallet and tickets](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java): `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`

### Administration

- [Ticket and user admin](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java): `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`
- [Schedule admin](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java): `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`
- [Coach configuration](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/tools/CoachConfig.java): `src/main/java/com/sts/Railway_mcp_server/tools/CoachConfig.java`

### Backend access

- [Railway API client](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java): `src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java`
- [API settings](https://github.com/dkawale499/railway-mcp-server/blob/main/src/main/java/com/sts/Railway_mcp_server/config/RailwayApiProperties.java): `src/main/java/com/sts/Railway_mcp_server/config/RailwayApiProperties.java`

### Other components

- **MCP client**
- **Railway Reservation API**

## Connections

- MCP client → Railway tools: invokes tools (evidence: `README.md`)
- Tool registration → Railway tools: registers callbacks (evidence: `src/main/java/com/sts/Railway_mcp_server/config/RailwayApiConfiguration.java`)
- Railway tools → Account tools: exposes (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Account tools → Railway API client: delegates auth (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Travel tools → Railway API client: delegates travel (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Wallet and tickets → Railway API client: delegates account (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Ticket and user admin → Railway API client: delegates reports (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Schedule admin → Railway API client: delegates schedules (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Schedule admin → Coach configuration: accepts typed coaches (evidence: `src/main/java/com/sts/Railway_mcp_server/tools/RailwayTools.java`)
- Railway API client → API settings: reads settings (evidence: `src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java`)
- Railway API client → Railway Reservation API: sends HTTP requests (evidence: `src/main/java/com/sts/Railway_mcp_server/service/RailwayApiClient.java`)
