twincat-validator-mcp

WHAT IT DOES

Six deterministic capabilities that no amount of prompt engineering can reliably replace.

SUPPORTED FILE TYPES

All four Beckhoff TwinCAT 3 XML formats — the server understands full XML schema, CDATA-embedded ST declarations, method/property XML elements, GUID structures, and LineIds metadata.

LAYERED ARCHITECTURE

Six clean layers — each with a single responsibility. The LLM client only ever touches the MCP Interface Layer. Data flows strictly top-down; no layer skips.

graph LR
    CLIENT["LLM Client"]
    MCP["MCP Interface"]
    ENGINE["Engine Layer"]
    CHECKFIX["Check / Fix Layer"]
    DOMAIN["Domain Layer"]
    CONFIG["Config Layer"]

    CLIENT -->|"stdio JSON-RPC"| MCP
    MCP --> ENGINE
    ENGINE --> CHECKFIX
    CHECKFIX --> DOMAIN
    DOMAIN --> CONFIG

    style CLIENT fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style MCP fill:#1a1a1e,stroke:#9e4aff,color:#e2e8f0
    style ENGINE fill:#1a1a1e,stroke:#fec20b,color:#e2e8f0
    style CHECKFIX fill:#1a1a1e,stroke:#ff4fd8,color:#e2e8f0
    style DOMAIN fill:#1a1a1e,stroke:#00ff7f,color:#e2e8f0
    style CONFIG fill:#1a1a1e,stroke:#1f75ff,color:#e2e8f0

Each arrow represents a strict dependency boundary. The MCP Interface Layer is the only public API — all LLM tool calls, resource reads, and prompt fetches go through it. The Domain Layer owns the TwinCATFile value object and never writes to disk.

DATA FLOW

Every tool call follows the same two-phase pattern: a request phase that loads and processes the file, and a response phase that assembles the result envelope.

graph LR
    PROMPT["User Prompt"] --> LLM["LLM Client"]
    LLM -->|"Tool Call"| HANDLER["Tool Handler"]
    HANDLER --> FILE["TwinCATFile"]
    HANDLER --> VENGINE["ValidationEngine"]
    HANDLER --> FENGINE["FixEngine"]
    FILE --> VENGINE
    FILE --> FENGINE

    style PROMPT fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style LLM fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style HANDLER fill:#1a1a1e,stroke:#9e4aff,color:#e2e8f0
    style FILE fill:#1a1a1e,stroke:#00ff7f,color:#e2e8f0
    style VENGINE fill:#1a1a1e,stroke:#ff4fd8,color:#e2e8f0
    style FENGINE fill:#1a1a1e,stroke:#ff4fd8,color:#e2e8f0

graph LR
    VENGINE["ValidationEngine"] --> CONTRACT["ContractState"]
    FENGINE["FixEngine"] --> CONTRACT
    CONTRACT --> ENVELOPE["Response Envelope"]
    ENVELOPE --> LLM["LLM Client"]
    LLM --> USER["User"]

    style VENGINE fill:#1a1a1e,stroke:#ff4fd8,color:#e2e8f0
    style FENGINE fill:#1a1a1e,stroke:#ff4fd8,color:#e2e8f0
    style CONTRACT fill:#1a1a1e,stroke:#00ff7f,color:#e2e8f0
    style ENVELOPE fill:#1a1a1e,stroke:#9e4aff,color:#e2e8f0
    style LLM fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style USER fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0

MCP INTERFACE

16 tools · 11 resources · 8 prompt templates — the complete surface area exposed to any LLM client.

CORE DESIGN PATTERNS

Nine engineering patterns that make the server deterministic, reliable, and LLM-friendly.

@CheckRegistry.register
class GuidFormatCheck(BaseCheck):
    check_id = "guid_format"
    def run(self, file: TwinCATFile) -> list[ValidationIssue]: ...

@FixRegistry.register
class TabsFix(BaseFix):
    fix_id = "tabs"
    def apply(self, file: TwinCATFile) -> bool: ...

safe_to_import  = (error_count == 0)
safe_to_compile = (error_count == 0)  # warnings do NOT block
blocking_count  = count(unfixable issues where severity in ["error", "critical"])
done            = safe_to_import and safe_to_compile and blocking_count == 0
status          = "done" if done else "blocked"

VALIDATION CHECK CATALOG

34 checks across three severity categories. Critical checks block import; style checks are advisory.

AUTO-FIX PIPELINE

9 fix operations executed in a strict dependency-aware order defined by fix_capabilities.json. The order field ensures fixes never conflict with each other.

LLM WORKFLOW INTEGRATION

The recommended end-to-end flow has three distinct phases: setup, correction loop, and determinism verification. Each phase is a separate concern.

graph LR
    PROMPT["User Prompt"] --> CTX["get_context_pack"]
    CTX --> SKEL["generate_skeleton"]
    SKEL --> WRITE["LLM writes ST"]
    WRITE --> PROC["process_twincat"]

    style PROMPT fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style CTX fill:#1a1a1e,stroke:#9e4aff,color:#e2e8f0
    style SKEL fill:#1a1a1e,stroke:#9e4aff,color:#e2e8f0
    style WRITE fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style PROC fill:#1a1a1e,stroke:#00ff7f,color:#e2e8f0

graph LR
    PROC["process_twincat"] --> SAFE["Safe to import?"]
    SAFE -->|Yes| VERIFY["verify_determinism"]
    SAFE -->|No| FIX["LLM correction"]
    FIX -->|"next pass"| BLOCKED["Blocked / done"]

    style PROC fill:#1a1a1e,stroke:#00ff7f,color:#e2e8f0
    style SAFE fill:#fec20b,stroke:#fec20b,color:#0d0d0f
    style VERIFY fill:#1a1a1e,stroke:#fec20b,color:#e2e8f0
    style FIX fill:#1a1a1e,stroke:#04d9ff,color:#e2e8f0
    style BLOCKED fill:#ff4fd8,stroke:#ff4fd8,color:#0d0d0f

graph LR
    VERIFY["verify_determinism"] --> HASH["SHA-256 compare"]
    HASH -->|"Match"| DONE["Done ✓"]
    HASH -->|"Mismatch"| RETRY["Re-process"]

    style VERIFY fill:#1a1a1e,stroke:#fec20b,color:#e2e8f0
    style HASH fill:#fec20b,stroke:#fec20b,color:#0d0d0f
    style DONE fill:#00ff7f,stroke:#00ff7f,color:#0d0d0f
    style RETRY fill:#1a1a1e,stroke:#00ff7f,color:#e2e8f0

HEALTH SCORE SYSTEM

Every file gets a 0–100 score. Warnings don't block import — only errors do.

TECH STACK & METRICS

Zero external dependencies beyond the MCP SDK. The entire validator uses only Python standard library.

CLIENT INTEGRATION

Works with any MCP client via stdio transport. One install, any editor.