PlantUML CSA Server

Generate Control System Architecture (CSA) diagrams using PlantUML via the Model Context Protocol (MCP).

Features

• ISA-95 Purdue Model - Zone packages with color-coded levels (0-4)
• Industrial Symbols - 36+ component types (10 controllers, 26 devices)
• Protocol Visualization - 12 protocols with distinct line colors
• Architecture Templates - 5 pre-defined templates for common configurations
• Bootstrap from Skills - Generate topology from equipment-list + instrument-io skills
• Multiple Layout Engines - Graphviz, Smetana, ELK
• Shareable URLs - Generate PlantUML server links
• Same Schema as FreeCAD - Interoperable YAML topology format

Project Structure

plantuml-csa-mcp-server/
├── src/
│   ├── __init__.py              # Package entry point
│   ├── __main__.py              # Module runner (python -m src)
│   ├── server.py                # FastMCP server with 8 MCP tools
│   ├── models/
│   │   └── csa_topology.py      # Pydantic models (same as FreeCAD CSA)
│   ├── converter/
│   │   ├── topology_to_puml.py  # YAML topology → PlantUML source
│   │   ├── sprites.py           # ISA symbol definitions (36+ types)
│   │   └── layout_hints.py      # Purdue-aware layout directives
│   ├── renderer/
│   │   └── plantuml_runner.py   # PlantUML CLI wrapper (JAR/native/Docker)
│   ├── encoder/
│   │   └── plantuml_encoder.py  # Text encoding for shareable URLs
│   ├── templates/
│   │   └── architecture_templates.py  # 5 architecture templates
│   └── bootstrap/
│       └── csa_bootstrap.py     # Bootstrap from equipment/IO lists
├── tests/                       # 56 tests
├── docs/
│   └── completed-plans/         # Implementation plan
├── pyproject.toml
├── CLAUDE.md                    # Development guide
└── README.md

Installation

# Clone and install
cd plantuml-csa-mcp-server
uv sync

# Verify PlantUML is available
uv run python -c "from src.renderer import PlantUMLRunner; print(PlantUMLRunner().check_available())"

Quick Start

1. Add to MCP Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "plantuml-csa-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/plantuml-csa-mcp-server", "run", "python", "-m", "src"],
      "description": "PlantUML CSA diagram generation (ISA-95 Purdue model)"
    }
  }
}

2. Generate a Diagram

# topology.yaml
schema_version: "1.0"
metadata:
  project_name: "Sample WWTP CSA"
zones:
  - id: "level_0"
    purdue_level: 0
  - id: "level_1"
    purdue_level: 1
controllers:
  - id: "PLC-101"
    type: PLC
    zone: "level_1"
devices:
  - id: "RIO-101"
    type: RemoteIO
    parent_controller: "PLC-101"
    zone: "level_0"
links:
  - source: "PLC-101"
    target: "RIO-101"
    protocol: "Ethernet_IP"

Then use the MCP tools:

# Get PlantUML source for version control
csa_get_plantuml_source(topology_yaml=yaml_content)

# Generate SVG diagram
csa_generate_diagram(topology_yaml=yaml_content, format="svg")

# Get shareable URL
csa_encode_plantuml(plantuml_source=puml_source)

MCP Tools Reference

Tool	Purpose
csa_generate_diagram	Render topology YAML to SVG/PNG
csa_get_plantuml_source	Get .puml source for version control
csa_validate_topology	Validate YAML against schema
csa_list_symbols	List available ISA-style symbols
csa_encode_plantuml	Generate shareable PlantUML URLs
csa_list_templates	List architecture templates
csa_render_preview	Quick preview for iteration
csa_check_plantuml	Check PlantUML availability
csa_bootstrap_from_io	Bootstrap topology from equipment/IO lists

Architecture Templates

Pre-defined templates for common control system configurations:

Template	Description	Use Case
centralized	Central MCC + Central PLC	Small plants (<5 MLD)
central_mcc_distributed_io	Central MCC + Distributed IO	Medium plants (5-20 MLD)
fully_distributed	Remote panels per area	Large plants (>20 MLD)
hybrid_safety	Central Safety + Distributed Process	SIL/SIS requirements
vendor_package_integration	OEM packages via OPC-UA	Multiple vendor packages

Bootstrap from Skill Outputs

Generate CSA topology from equipment-list-skill and instrument-io-skill outputs:

csa_bootstrap_from_io(
    equipment_list_qmd=equipment_qmd_content,
    instrument_database_yaml=io_database_yaml,
    project_name="WWTP Control System",
    architecture_template="fully_distributed"
)
# Returns: {topology_yaml, suggestions, io_summary, equipment_mapping}

Supported Components

Controllers (10 types)

PLC, DCS, PAC, Safety_PLC, Soft_PLC, Edge_Controller, Motion_Controller, Redundant_PLC, RTU, SIS

Devices (26 types)

RemoteIO, HMI, SCADA, Historian, OPC_UA_Server, Gateway, VFD, Soft_Starter, MCC, Industrial_PC, Switch, Managed_Switch, Router, Firewall, Wireless_AP, Media_Converter, Network_TAP, Motor_Starter, Engineering_WS, Panel_PC, Data_Logger, Junction_Box, Marshalling_Cabinet, Local_Panel, Remote_Panel, Instrument_Rack

Protocols (12 types)

Ethernet_IP, Profinet, Modbus_TCP, Modbus_RTU, Profibus, DeviceNet, ControlNet, HART, Foundation_Fieldbus, OPC_UA, MQTT, BACnet

Testing

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src

vs FreeCAD CSA

Aspect	PlantUML CSA	FreeCAD CSA
Output	SVG/PNG	TechDraw PDF
Version Control	Plain text .puml	Binary .FCStd
Dependencies	Java/PlantUML	FreeCAD runtime
Best For	Documentation	CAD deliverables

Use Both: Same YAML topology works with both renderers. Use PlantUML for rapid iteration and documentation, FreeCAD for final engineering drawings.

Workflow Integration

This server is part of the puran-water control system architecture workflow:

┌─────────────────────────┐     ┌──────────────────────────┐     ┌─────────────────────┐
│  equipment-list-skill   │ ──► │  instrument-io-skill     │ ──► │  csa-diagram-skill  │
│  (equipment + feeder)   │     │  (IO lists, patterns)    │     │  (CSA generation)   │
└─────────────────────────┘     └──────────────────────────┘     └─────────────────────┘
                                                                            │
                                                                            ▼
                                                                 ┌─────────────────────┐
                                                                 │ plantuml-csa-mcp    │
                                                                 │ (this server)       │
                                                                 └─────────────────────┘
                                                                            │
                                                                            ▼
                                                                 ┌─────────────────────┐
                                                                 │ CSA Topology YAML   │
                                                                 │ PlantUML PNG/SVG    │
                                                                 │ Shareable URLs      │
                                                                 └─────────────────────┘

Related Projects

Upstream (Data Sources)

• equipment-list-skill - Equipment lists with feeder types
• instrument-io-skill - IO lists with DI/DO/AI/AO patterns

Companion Skill

• csa-diagram-skill - Claude Code skill that orchestrates this MCP server

Similar Pattern (Electrical)

• plantuml-sld-mcp-server - Single-Line Diagram generation (same YAML → PlantUML pattern)
• electrical-distribution-skill - SLD skill using plantuml-sld-mcp-server

Alternative Renderer

• freecad-csa-workbench - Same YAML topology rendered in FreeCAD for CAD deliverables

License

MIT