# nxt-tronic/winols-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/nxt-tronic/winols-mcp
- Repository: https://github.com/nxt-tronic/winols-mcp

## Overview

winols-mcp is an MCP-to-WinOLS control bridge, not a standalone ECU editor. An MCP client invokes a tool; the Python server validates and marshals the request into a ticket, the Lua script running inside WinOLS polls for it and calls WinOLS, then returns a response ticket for the server to deliver. The catalog covers the documented project, calibration, checksum, map, import/export, and context operations. The README documents this flow; the Lua implementation was not excerpted, so its internal behavior is represented only where explicitly documented.

Main entry points: [`server/winols_mcp_server.py`](https://github.com/nxt-tronic/winols-mcp/blob/main/server/winols_mcp_server.py) (Python MCP Server), [`lua/winols_mcp_bridge.lua`](https://github.com/nxt-tronic/winols-mcp/blob/main/lua/winols_mcp_bridge.lua) (Lua Bridge), [`server/tool_specs.py`](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py) (Tool Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Interface"]
  node_server["Python MCP Server"]
  node_catalog["Tool Catalog<br/>[tool_specs.py]"]
end

subgraph group_bridge["Ticket Bridge"]
  node_tickets["Ticket Files"]
  node_lua["Lua Bridge"]
end

subgraph group_capabilities["WinOLS Capabilities"]
  node_session["Session Control<br/>[tool_specs.py]"]
  node_project["Project Lifecycle<br/>[tool_specs.py]"]
  node_calibration["Calibration Data<br/>[tool_specs.py]"]
  node_checksums["Checksum Operations<br/>[tool_specs.py]"]
  node_maps["Map Management<br/>[tool_specs.py]"]
  node_importexport["Import Export<br/>[tool_specs.py]"]
  node_context["Vehicle and Version Data<br/>[tool_specs.py]"]
  node_search["Search and Addressing<br/>[tool_specs.py]"]
  node_extras["Filesystem and Diagnostics<br/>[tool_specs.py]"]
end

node_client(("MCP Client"))
node_winols["WinOLS"]

node_client -->|"calls tools"| node_server
node_server -->|"builds tools"| node_catalog
node_server -->|"writes requests"| node_tickets
node_lua -->|"polls requests"| node_tickets
node_lua -->|"calls API"| node_winols
node_lua -->|"writes responses"| node_tickets
node_server -->|"polls responses"| node_tickets
node_server -.->|"dispatches tools"| node_session
node_server -.->|"dispatches tools"| node_project
node_server -.->|"dispatches tools"| node_calibration
node_server -.->|"dispatches tools"| node_checksums
node_server -.->|"dispatches tools"| node_maps
node_server -.->|"dispatches tools"| node_importexport
node_server -.->|"dispatches tools"| node_context
node_server -.->|"dispatches tools"| node_search
node_server -.->|"dispatches tools"| node_extras

click node_server "https://github.com/nxt-tronic/winols-mcp/blob/main/server/winols_mcp_server.py"
click node_catalog "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_lua "https://github.com/nxt-tronic/winols-mcp/blob/main/lua/winols_mcp_bridge.lua"
click node_session "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_project "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_calibration "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_checksums "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_maps "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_importexport "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_context "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_search "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py"
click node_extras "https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.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,node_catalog,node_client toneBlue
class node_tickets,node_lua toneAmber
class node_session,node_project,node_calibration,node_checksums,node_maps,node_importexport,node_context,node_search,node_extras toneMint
class node_winols toneIndigo
```

## Components

### MCP Interface

- [Python MCP Server](https://github.com/nxt-tronic/winols-mcp/blob/main/server/winols_mcp_server.py): `server/winols_mcp_server.py`
- [Tool Catalog](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`

### Ticket Bridge

- **Ticket Files**
- [Lua Bridge](https://github.com/nxt-tronic/winols-mcp/blob/main/lua/winols_mcp_bridge.lua): `lua/winols_mcp_bridge.lua`

### WinOLS Capabilities

- [Session Control](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Project Lifecycle](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Calibration Data](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Checksum Operations](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Map Management](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Import Export](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Vehicle and Version Data](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Search and Addressing](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`
- [Filesystem and Diagnostics](https://github.com/nxt-tronic/winols-mcp/blob/main/server/tool_specs.py): `server/tool_specs.py`

### Other components

- **MCP Client**
- **WinOLS**

## Connections

- MCP Client → Python MCP Server: calls tools (evidence: `README.md`)
- Python MCP Server → Tool Catalog: builds tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Ticket Files: writes requests (evidence: `README.md`)
- Lua Bridge → Ticket Files: polls requests (evidence: `README.md`)
- Lua Bridge → WinOLS: calls API (evidence: `README.md`)
- Lua Bridge → Ticket Files: writes responses (evidence: `README.md`)
- Python MCP Server → Ticket Files: polls responses (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Session Control: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Project Lifecycle: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Calibration Data: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Checksum Operations: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Map Management: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Import Export: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Vehicle and Version Data: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Search and Addressing: dispatches tools (evidence: `server/winols_mcp_server.py`)
- Python MCP Server → Filesystem and Diagnostics: dispatches tools (evidence: `server/winols_mcp_server.py`)
