# adancurusul/serial-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/adancurusul/serial-mcp-server
- Repository: https://github.com/adancurusul/serial-mcp-server
- Video tour (about a minute): https://gitdiagram.com/adancurusul/serial-mcp-server/video

## Overview

Serial MCP Server exposes serial-device operations through both an MCP stdio server and a scriptable CLI. Users discover ports, open connections, exchange data or control lines, and close connections; bounded capture reads extend ordinary reads. Its macro workflow validates and loads or accepts a JSON pack, plans macros or assemblies, then runs the plan against a connection or simulated input. The graph includes session management and configuration as supporting layers. README documents CLI capabilities beyond the sampled CLI implementation, so those links are limited to documented dispatch and behavior.

Main entry points: [`src/tools/serial_handler.rs`](https://github.com/adancurusul/serial-mcp-server/blob/main/src/tools/serial_handler.rs) (MCP tools), [`src/main.rs`](https://github.com/adancurusul/serial-mcp-server/blob/main/src/main.rs) (Command dispatch), [`src/cli.rs`](https://github.com/adancurusul/serial-mcp-server/blob/main/src/cli.rs) (CLI commands), [`src/serial/mod.rs`](https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/mod.rs) (Connection manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main["Command dispatch<br/>[main.rs]"]
  node_cli["CLI commands<br/>[cli.rs]"]
  node_handler["MCP tools<br/>[serial_handler.rs]"]
  node_tool_types["Tool inputs<br/>[types.rs]"]
end

subgraph group_serial["Serial access"]
  node_ports["Port discovery<br/>[port.rs]"]
  node_connections["Connection manager<br/>[mod.rs]"]
  node_connection["Serial connection<br/>[connection.rs]"]
  node_capture["Capture reads<br/>[capture.rs]"]
end

subgraph group_automation["Macro automation"]
  node_dsl["Macro DSL<br/>[dsl.rs]"]
  node_validation["Pack validation<br/>[validation.rs]"]
  node_registry["Pack registry<br/>[registry.rs]"]
  node_planner["Plan expansion<br/>[planner.rs]"]
  node_executor["Macro execution<br/>[executor.rs]"]
  node_transport["Macro transports<br/>[transport.rs]"]
end

subgraph group_support["Runtime support"]
  node_config["Configuration<br/>[config.rs]"]
  node_sessions["Session lifecycle<br/>[manager.rs]"]
  node_session_state["Session state<br/>[serial_session.rs]"]
end

node_cli_user(("CLI user"))
node_mcp_client(("MCP client"))
node_device(("Serial device"))

node_cli_user -->|"invokes"| node_main
node_main -->|"loads config"| node_config
node_main -->|"dispatches CLI"| node_cli
node_main -->|"serves MCP"| node_handler
node_mcp_client -->|"calls tools"| node_handler
node_handler -->|"uses inputs"| node_tool_types
node_cli -->|"lists ports"| node_ports
node_cli -->|"serial commands"| node_connections
node_handler -->|"lists ports"| node_ports
node_handler -->|"manages connections"| node_connections
node_connections -->|"opens and retrieves"| node_connection
node_connection -->|"reads and writes"| node_device
node_handler -->|"captures reads"| node_capture
node_cli -->|"capture options"| node_capture
node_sessions -->|"tracks sessions"| node_session_state
node_sessions -->|"creates connections"| node_connections
node_handler -->|"validates packs"| node_validation
node_validation -->|"checks definitions"| node_dsl
node_handler -->|"loads and lists"| node_registry
node_handler -->|"requests plans"| node_planner
node_planner -->|"expands targets"| node_dsl
node_handler -->|"runs plans"| node_executor
node_executor -->|"dispatches steps"| node_transport
node_transport -->|"uses connection"| node_connection
node_transport -.->|"simulates reads"| node_device

click node_main "https://github.com/adancurusul/serial-mcp-server/blob/main/src/main.rs"
click node_cli "https://github.com/adancurusul/serial-mcp-server/blob/main/src/cli.rs"
click node_handler "https://github.com/adancurusul/serial-mcp-server/blob/main/src/tools/serial_handler.rs"
click node_tool_types "https://github.com/adancurusul/serial-mcp-server/blob/main/src/tools/types.rs"
click node_config "https://github.com/adancurusul/serial-mcp-server/blob/main/src/config.rs"
click node_ports "https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/port.rs"
click node_connections "https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/mod.rs"
click node_connection "https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/connection.rs"
click node_capture "https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/capture.rs"
click node_sessions "https://github.com/adancurusul/serial-mcp-server/blob/main/src/session/manager.rs"
click node_session_state "https://github.com/adancurusul/serial-mcp-server/blob/main/src/session/serial_session.rs"
click node_dsl "https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/dsl.rs"
click node_validation "https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/validation.rs"
click node_registry "https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/registry.rs"
click node_planner "https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/planner.rs"
click node_executor "https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/executor.rs"
click node_transport "https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/transport.rs"

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_main,node_cli,node_handler,node_tool_types,node_cli_user,node_mcp_client toneBlue
class node_ports,node_connections,node_connection,node_capture toneAmber
class node_dsl,node_validation,node_registry,node_planner,node_executor,node_transport toneMint
class node_config,node_sessions,node_session_state toneRose
class node_device toneIndigo
```

## Components

### Entry points

- [Command dispatch](https://github.com/adancurusul/serial-mcp-server/blob/main/src/main.rs): `src/main.rs`
- [CLI commands](https://github.com/adancurusul/serial-mcp-server/blob/main/src/cli.rs): `src/cli.rs`
- [MCP tools](https://github.com/adancurusul/serial-mcp-server/blob/main/src/tools/serial_handler.rs): `src/tools/serial_handler.rs`
- [Tool inputs](https://github.com/adancurusul/serial-mcp-server/blob/main/src/tools/types.rs): `src/tools/types.rs`

### Serial access

- [Port discovery](https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/port.rs): `src/serial/port.rs`
- [Connection manager](https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/mod.rs): `src/serial/mod.rs`
- [Serial connection](https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/connection.rs): `src/serial/connection.rs`
- [Capture reads](https://github.com/adancurusul/serial-mcp-server/blob/main/src/serial/capture.rs): `src/serial/capture.rs`

### Macro automation

- [Macro DSL](https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/dsl.rs): `src/automation/dsl.rs`
- [Pack validation](https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/validation.rs): `src/automation/validation.rs`
- [Pack registry](https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/registry.rs): `src/automation/registry.rs`
- [Plan expansion](https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/planner.rs): `src/automation/planner.rs`
- [Macro execution](https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/executor.rs): `src/automation/executor.rs`
- [Macro transports](https://github.com/adancurusul/serial-mcp-server/blob/main/src/automation/transport.rs): `src/automation/transport.rs`

### Runtime support

- [Configuration](https://github.com/adancurusul/serial-mcp-server/blob/main/src/config.rs): `src/config.rs`
- [Session lifecycle](https://github.com/adancurusul/serial-mcp-server/blob/main/src/session/manager.rs): `src/session/manager.rs`
- [Session state](https://github.com/adancurusul/serial-mcp-server/blob/main/src/session/serial_session.rs): `src/session/serial_session.rs`

### Other components

- **CLI user**
- **MCP client**
- **Serial device**

## Connections

- CLI user → Command dispatch: invokes
- Command dispatch → Configuration: loads config
- Command dispatch → CLI commands: dispatches CLI
- Command dispatch → MCP tools: serves MCP
- MCP client → MCP tools: calls tools
- MCP tools → Tool inputs: uses inputs
- CLI commands → Port discovery: lists ports
- CLI commands → Connection manager: serial commands
- MCP tools → Port discovery: lists ports
- MCP tools → Connection manager: manages connections
- Connection manager → Serial connection: opens and retrieves
- Serial connection → Serial device: reads and writes
- MCP tools → Capture reads: captures reads
- CLI commands → Capture reads: capture options
- Session lifecycle → Session state: tracks sessions
- Session lifecycle → Connection manager: creates connections
- MCP tools → Pack validation: validates packs
- Pack validation → Macro DSL: checks definitions
- MCP tools → Pack registry: loads and lists
- MCP tools → Plan expansion: requests plans
- Plan expansion → Macro DSL: expands targets
- MCP tools → Macro execution: runs plans
- Macro execution → Macro transports: dispatches steps
- Macro transports → Serial connection: uses connection
- Macro transports → Serial device: simulates reads