# xrds76354/sumo-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/xrds76354/sumo-mcp-server
- Repository: https://github.com/xrds76354/sumo-mcp-server

## Overview

SUMO-MCP exposes SUMO traffic-simulation capabilities as MCP tools. The primary user workflow is the documented sim-gen/eval pipeline: create a network, generate demand, compute routes, run simulation, and analyze FCD output. Separate branches provide network-format conversion, signal optimization, online TraCI control/state queries, and reinforcement-learning training. The graph reflects README-documented workflows and source-index references; several modules were not sampled, so their internal calls are not inferred.

Main entry points: [`src/server.py`](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/server.py) (MCP Tool Server), [`src/mcp_tools/network.py`](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/network.py) (Network Tools), [`src/mcp_tools/simulation.py`](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/simulation.py) (Simulation Runner), [`src/workflows/sim_gen.py`](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/sim_gen.py) (Sim Gen Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_server["MCP Tool Server<br/>[server.py]"]
end

subgraph group_offline["Offline Simulation"]
  node_network["Network Tools<br/>[network.py]"]
  node_ezdesignx["ezdesignX Conversion<br/>[ezdesignx.py]"]
  node_demand["Demand Tools<br/>[route.py]"]
  node_signal["Signal Optimization Tools<br/>[signal.py]"]
  node_simulation["Simulation Runner<br/>[simulation.py]"]
  node_analysis["FCD Analysis<br/>[analysis.py]"]
  node_simgen["Sim Gen Workflow<br/>[sim_gen.py]"]
  node_signalworkflow["Signal Workflow<br/>[signal_opt.py]"]
  node_rlworkflow["RL Training Workflow<br/>[rl_train.py]"]
  node_rl["RL Training Engine<br/>[rl.py]"]
end

subgraph group_control["Online Control"]
  node_vehicle["Vehicle Queries<br/>[vehicle.py]"]
  node_connection["TraCI Connection<br/>[connection.py]"]
  node_traci["TraCI Helpers<br/>[traci.py]"]
end

subgraph group_support["Runtime Support"]
  node_sumo["SUMO Discovery<br/>[sumo.py]"]
  node_timeout["Timeout Handling<br/>[timeout.py]"]
  node_output["Output Formatting<br/>[output.py]"]
end

node_client(("AI Agent"))
node_sumoexternal["Eclipse SUMO"]
node_osm["OpenStreetMap"]

node_client -->|"invokes tools"| node_server
node_server -->|"dispatches network tools"| node_network
node_server -->|"dispatches conversion"| node_ezdesignx
node_server -->|"dispatches demand tools"| node_demand
node_server -->|"dispatches signal tools"| node_signal
node_server -->|"dispatches simulation"| node_simulation
node_server -->|"dispatches analysis"| node_analysis
node_server -->|"dispatches queries"| node_vehicle
node_server -->|"dispatches RL tasks"| node_rl
node_server -->|"starts workflow"| node_simgen
node_server -->|"starts workflow"| node_signalworkflow
node_server -->|"starts workflow"| node_rlworkflow
node_simgen -->|"generates network"| node_network
node_simgen -->|"generates demand and routes"| node_demand
node_simgen -->|"runs simulation"| node_simulation
node_simgen -->|"analyzes results"| node_analysis
node_signalworkflow -->|"runs baseline and optimized"| node_simulation
node_signalworkflow -->|"optimizes signals"| node_signal
node_signalworkflow -->|"compares results"| node_analysis
node_rlworkflow -->|"delegates training"| node_rl
node_network -->|"downloads map data"| node_osm
node_network -->|"runs SUMO tools"| node_sumoexternal
node_demand -->|"runs SUMO tools"| node_sumoexternal
node_signal -->|"runs SUMO tools"| node_sumoexternal
node_simulation -->|"runs simulation"| node_sumoexternal
node_vehicle -->|"uses connection"| node_connection
node_connection -->|"locates binary"| node_sumo
node_connection -->|"controls session"| node_traci
node_simulation -->|"closes session"| node_traci
node_network -->|"truncates output"| node_output
node_demand -->|"truncates output"| node_output
node_signal -->|"truncates output"| node_output
node_network -->|"runs with timeout"| node_timeout
node_demand -->|"runs with timeout"| node_timeout
node_signal -->|"runs with timeout"| node_timeout
node_simulation -->|"runs with adaptive timeout"| node_timeout

click node_server "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/server.py"
click node_network "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/network.py"
click node_ezdesignx "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/ezdesignx.py"
click node_demand "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/route.py"
click node_signal "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/signal.py"
click node_simulation "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/simulation.py"
click node_analysis "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/analysis.py"
click node_simgen "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/sim_gen.py"
click node_signalworkflow "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/signal_opt.py"
click node_rlworkflow "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/rl_train.py"
click node_rl "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/rl.py"
click node_vehicle "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/vehicle.py"
click node_connection "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/connection.py"
click node_traci "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/traci.py"
click node_sumo "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/sumo.py"
click node_timeout "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/timeout.py"
click node_output "https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/output.py"

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_server toneBlue
class node_network,node_ezdesignx,node_demand,node_signal,node_simulation,node_analysis,node_simgen,node_signalworkflow,node_rlworkflow,node_rl toneAmber
class node_vehicle,node_connection,node_traci toneMint
class node_sumo,node_timeout,node_output toneRose
class node_client,node_sumoexternal,node_osm toneIndigo
```

## Components

### MCP Interface

- [MCP Tool Server](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/server.py): `src/server.py`

### Offline Simulation

- [Network Tools](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/network.py): `src/mcp_tools/network.py`
- [ezdesignX Conversion](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/ezdesignx.py): `src/mcp_tools/ezdesignx.py`
- [Demand Tools](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/route.py): `src/mcp_tools/route.py`
- [Signal Optimization Tools](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/signal.py): `src/mcp_tools/signal.py`
- [Simulation Runner](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/simulation.py): `src/mcp_tools/simulation.py`
- [FCD Analysis](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/analysis.py): `src/mcp_tools/analysis.py`
- [Sim Gen Workflow](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/sim_gen.py): `src/workflows/sim_gen.py`
- [Signal Workflow](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/signal_opt.py): `src/workflows/signal_opt.py`
- [RL Training Workflow](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/workflows/rl_train.py): `src/workflows/rl_train.py`
- [RL Training Engine](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/rl.py): `src/mcp_tools/rl.py`

### Online Control

- [Vehicle Queries](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/mcp_tools/vehicle.py): `src/mcp_tools/vehicle.py`
- [TraCI Connection](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/connection.py): `src/utils/connection.py`
- [TraCI Helpers](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/traci.py): `src/utils/traci.py`

### Runtime Support

- [SUMO Discovery](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/sumo.py): `src/utils/sumo.py`
- [Timeout Handling](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/timeout.py): `src/utils/timeout.py`
- [Output Formatting](https://github.com/xrds76354/sumo-mcp-server/blob/main/src/utils/output.py): `src/utils/output.py`

### Other components

- **AI Agent**
- **Eclipse SUMO**
- **OpenStreetMap**

## Connections

- AI Agent → MCP Tool Server: invokes tools (evidence: `README.md`)
- MCP Tool Server → Network Tools: dispatches network tools (evidence: `src/server.py`)
- MCP Tool Server → ezdesignX Conversion: dispatches conversion (evidence: `src/server.py`)
- MCP Tool Server → Demand Tools: dispatches demand tools (evidence: `src/server.py`)
- MCP Tool Server → Signal Optimization Tools: dispatches signal tools (evidence: `src/server.py`)
- MCP Tool Server → Simulation Runner: dispatches simulation (evidence: `src/server.py`)
- MCP Tool Server → FCD Analysis: dispatches analysis (evidence: `src/server.py`)
- MCP Tool Server → Vehicle Queries: dispatches queries (evidence: `src/server.py`)
- MCP Tool Server → RL Training Engine: dispatches RL tasks (evidence: `src/server.py`)
- MCP Tool Server → Sim Gen Workflow: starts workflow (evidence: `src/server.py`)
- MCP Tool Server → Signal Workflow: starts workflow (evidence: `src/server.py`)
- MCP Tool Server → RL Training Workflow: starts workflow (evidence: `src/server.py`)
- Sim Gen Workflow → Network Tools: generates network (evidence: `src/workflows/sim_gen.py`)
- Sim Gen Workflow → Demand Tools: generates demand and routes (evidence: `src/workflows/sim_gen.py`)
- Sim Gen Workflow → Simulation Runner: runs simulation (evidence: `src/workflows/sim_gen.py`)
- Sim Gen Workflow → FCD Analysis: analyzes results (evidence: `src/workflows/sim_gen.py`)
- Signal Workflow → Simulation Runner: runs baseline and optimized (evidence: `src/workflows/signal_opt.py`)
- Signal Workflow → Signal Optimization Tools: optimizes signals (evidence: `src/workflows/signal_opt.py`)
- Signal Workflow → FCD Analysis: compares results (evidence: `src/workflows/signal_opt.py`)
- RL Training Workflow → RL Training Engine: delegates training (evidence: `src/workflows/rl_train.py`)
- Network Tools → OpenStreetMap: downloads map data (evidence: `README.md`)
- Network Tools → Eclipse SUMO: runs SUMO tools (evidence: `src/mcp_tools/network.py`)
- Demand Tools → Eclipse SUMO: runs SUMO tools (evidence: `src/mcp_tools/route.py`)
- Signal Optimization Tools → Eclipse SUMO: runs SUMO tools (evidence: `src/mcp_tools/signal.py`)
- Simulation Runner → Eclipse SUMO: runs simulation (evidence: `src/mcp_tools/simulation.py`)
- Vehicle Queries → TraCI Connection: uses connection (evidence: `src/mcp_tools/vehicle.py`)
- TraCI Connection → SUMO Discovery: locates binary (evidence: `src/utils/connection.py`)
- TraCI Connection → TraCI Helpers: controls session (evidence: `src/utils/connection.py`)
- Simulation Runner → TraCI Helpers: closes session (evidence: `src/mcp_tools/simulation.py`)
- Network Tools → Output Formatting: truncates output (evidence: `src/mcp_tools/network.py`)
- Demand Tools → Output Formatting: truncates output (evidence: `src/mcp_tools/route.py`)
- Signal Optimization Tools → Output Formatting: truncates output (evidence: `src/mcp_tools/signal.py`)
- Network Tools → Timeout Handling: runs with timeout (evidence: `src/mcp_tools/network.py`)
- Demand Tools → Timeout Handling: runs with timeout (evidence: `src/mcp_tools/route.py`)
- Signal Optimization Tools → Timeout Handling: runs with timeout (evidence: `src/mcp_tools/signal.py`)
- Simulation Runner → Timeout Handling: runs with adaptive timeout (evidence: `src/mcp_tools/simulation.py`)
