TwinCAT Validator MCP Server

An MCP server that validates, auto-fixes, and scaffolds TwinCAT 3 XML files (.TcPOU, .TcIO, .TcDUT, .TcGVL). Connect it to any LLM client to give your AI assistant reliable, deterministic TwinCAT code quality tooling — structural checks, 21 IEC 61131-3 OOP checks, auto-fix pipelines, and canonical skeleton generation.

Supported File Types

| Extension | Description | |-----------|-------------| | .TcPOU | Program Organization Units — Function Blocks, Programs, Functions | | .TcIO | I/O configurations — Interfaces | | .TcDUT | Data Unit Types — Structures, Enums, Type Aliases | | .TcGVL | Global Variable Lists |

Installation

pip install twincat-validator-mcp

From Source

git clone https://github.com/agenticcontrolio/twincat-validator-mcp.git
cd twincat-validator-mcp
pip install -e .

Claude Desktop Extension

The easiest way to use this server with Claude Desktop is via the one-click .dxt extension:

1. pip install twincat-validator-mcp
2. Download the .dxt file from the latest release
3. Open Claude Desktop → Settings → Extensions → Install Extension

See dxt/README.md for full instructions and troubleshooting.

Connecting to an LLM Client

For other clients (Cursor, VS Code, Windsurf, Cline), the server uses stdio transport. Add the following to your client's MCP config file:

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "twincat-validator": {
      "command": "twincat-validator-mcp",
      "args": []
    }
  }
}

VS Code (Copilot / Continue) — .vscode/mcp.json

{
  "servers": {
    "twincat-validator": {
      "type": "stdio",
      "command": "twincat-validator-mcp",
      "args": []
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "twincat-validator": {
      "command": "twincat-validator-mcp",
      "args": []
    }
  }
}

Cline (VS Code Extension)

{
  "mcpServers": {
    "twincat-validator": {
      "command": "twincat-validator-mcp",
      "args": [],
      "disabled": false
    }
  }
}

"command": "python",
"args": ["-m", "twincat_validator"],
"cwd": "/path/to/twincat-validator-mcp"

MCP Tools

Validation

| Tool | Description | |------|-------------| | validate_file | Full validation of a single file — returns all issues with severity, location, code snippet, and explanation | | validate_batch | Validate multiple files matching glob patterns (e.g. ["**/*.TcPOU"]) | | validate_for_import | Quick critical-only check to confirm a file is safe to import into TwinCAT | | check_specific | Run a named subset of validation checks on a file | | get_validation_summary | Return a 0–100 health score with issue counts by severity | | suggest_fixes | Generate prioritized fix recommendations from a validation result |

Auto-fix

| Tool | Description | |------|-------------| | autofix_file | Apply all safe auto-fixes to a single file in deterministic order | | autofix_batch | Apply auto-fixes to multiple files matching glob patterns | | generate_skeleton | Generate a canonical, deterministic XML skeleton for a given file type and subtype | | extract_methods_to_xml | Promote inline METHOD blocks from the main ST declaration into proper <Method> XML elements |

Orchestration

| Tool | Description | |------|-------------| | process_twincat_single | Full enforced pipeline for one file: validate → autofix → validate → suggest fixes if still unsafe | | process_twincat_batch | Full enforced pipeline across multiple files with summary or full response modes | | verify_determinism_batch | Run the strict pipeline twice and report per-file idempotence stability | | get_effective_oop_policy | Resolve the active OOP validation policy for a file or directory (walks ancestor dirs for .twincat-validator.json) | | lint_oop_policy | Validate the nearest .twincat-validator.json config file — checks key names, types, and value ranges | | get_context_pack | Return curated knowledge-base entries and OOP policy scoped to a workflow stage (pre_generation or troubleshooting) |

Validation Checks

Structure & Format (critical — blocks import)

• XML structure validity
• GUID format ({xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx})
• GUID uniqueness across elements
• Property getter VAR blocks (missing VAR/END_VAR)
• LineIds count consistency
• File ending format

Style (warning — advisory)

• Tab characters (TwinCAT requires spaces)
• 2-space indentation
• Element ordering
• Naming conventions (FB_, PRG_, FUNC_, E_, ST_, I_, GVL_)
• Excessive blank lines
• CDATA formatting

OOP — IEC 61131-3 (21 checks)

Runs automatically when EXTENDS or IMPLEMENTS is detected. Skipped for procedural code.

| Category | Checks | |----------|--------| | Inheritance safety | Extends visibility, extends cycle detection, diamond inheritance warning | | Override correctness | Override marker, override signature match, override super call | | Interface compliance | Interface contract, inheritance property contract, interface segregation | | FB lifecycle | FB_init signature, FB_init super call, FB_exit contract | | Memory safety | Dynamic creation attribute, pointer/delete pairing | | Design quality | THIS^ pointer consistency, abstract contract, abstract instantiation, composition depth | | Property/method | Property accessor pairing, method visibility consistency, method count |

Auto-fix Capabilities

Fixes are applied in a deterministic, dependency-aware order:

1. Tabs → 2 spaces (runs before indentation)
2. File ending — fixes truncated ]]> after </TcPlcObject>
3. Property newlines — normalizes declaration line breaks
4. CDATA formatting — corrects CDATA section structure
5. Property VAR blocks — inserts missing VAR/END_VAR in getters
6. Excessive blank lines — reduces to max 2 consecutive
7. Indentation — normalizes to 2-space multiples
8. GUID case — uppercases hex to canonical lowercase
9. LineIds — experimental generation (marked unsafe, opt-in only)

Running autofix twice on the same file produces byte-identical output (idempotency guaranteed).

Intent-Aware OOP Enforcement

All tools accept an intent_profile parameter:

| Value | Behavior | |-------|----------| | "auto" (default) | Detects OOP patterns (EXTENDS/IMPLEMENTS) automatically; runs OOP checks only when found | | "procedural" | Skips all 21 OOP checks regardless of file content | | "oop" | Always runs OOP checks |

Batch tools scan all .TcPOU files to resolve "auto" once at the batch level.

Health Score

Files are scored 0–100 based on issue counts:

| Deduction | Severity | |-----------|----------| | −25 pts | Critical / error | | −5 pts | Warning | | −1 pt | Info |

| Score | Rating | |-------|--------| | 90–100 | Excellent — production ready | | 70–89 | Good — minor issues | | 50–69 | Needs work | | 0–49 | Critical issues present |

Target ≥ 90 for all production files.

MCP Resources

| URI | Description | |-----|-------------| | validation-rules:// | All 34 check definitions | | fix-capabilities:// | All 9 fix definitions with complexity and risk level | | naming-conventions:// | TwinCAT naming patterns by file type | | config://server-info | Server metadata and capability summary | | knowledge-base:// | Full LLM-friendly knowledge base | | knowledge-base://checks/{check_id} | Explanation, examples, and common mistakes for one check | | knowledge-base://fixes/{fix_id} | Algorithm and examples for one fix | | generation-contract:// | Deterministic generation contracts for all file types | | generation-contract://types/{file_type} | Contract for TcPOU, TcDUT, TcGVL, or TcIO | | oop-policy://defaults | Default OOP policy values | | oop-policy://effective/{target_path} | Resolved OOP policy for a path |

MCP Prompts

8 reusable prompt templates for canonical LLM workflows — covering single-file generation, batch validation, OOP scaffolding, determinism verification, and troubleshooting flows. Accessible via your MCP client's prompt interface.

Agent Guide

AGENT.md is an example guide prompt that tells your LLM agent exactly how to use this server — which tools to call, in what order, how to route intent (procedural vs OOP), stop conditions, and the reporting contract. Copy it into your system prompt or agent instructions and customise it to match your workflow.

Recommended Workflow

The pattern for any TwinCAT generation task — no code is written until the user has approved the plan.

flowchart LR
    A([User Prompt]) --> B[📋 Plan\nLLM produces plan file\nand stops]
    B --> C{User reviews\nand approves?}
    C -- No --> B
    C -- Yes --> D[⚙️ Implement\nLLM generates\nTwinCAT artifacts]
    D --> E[✅ Validate\nMCP server validates,\nauto-fixes, confirms safety]
    E --> F([Done])

    style A fill:#4a90d9,color:#fff,stroke:none
    style F fill:#27ae60,color:#fff,stroke:none
    style C fill:#f39c12,color:#fff,stroke:none

After approval, the LLM follows this MCP tool sequence:

flowchart TD
    START([Plan approved by user]) --> CTX

    CTX["get_context_pack\n(stage=pre_generation)"]
    CTX --> POLICY["get_effective_oop_policy\n(if OOP task)"]
    POLICY --> SKE
    CTX --> SKE

    SKE["generate_skeleton\nfor each artifact"]
    SKE --> WRITE["LLM writes\nST content into files"]

    WRITE --> ORCH

    subgraph ORCH_LOOP ["Orchestration loop (max 3 iterations)"]
        ORCH["process_twincat_single\nor process_twincat_batch"]
        ORCH --> SAFE{safe_to_import\n&& safe_to_compile?}
        SAFE -- Yes --> DET
        SAFE -- No --> BLOCKED{no_progress\nor iter >= 3?}
        BLOCKED -- No --> KB["get_context_pack\n(stage=troubleshooting,\ncheck_ids=blockers)"]
        KB --> FIX["LLM applies\none focused correction"]
        FIX --> ORCH
        BLOCKED -- Yes --> FAIL([Report blocked —\nstop])
    end

    DET["verify_determinism_batch\n(second pass — no changes expected)"]
    DET --> STABLE{stable?}
    STABLE -- No --> ORCH
    STABLE -- Yes --> DONE([Report done ✅\nsafe_to_import, safe_to_compile,\nblocking_count=0, content_changed=false])

    style START fill:#4a90d9,color:#fff,stroke:none
    style DONE fill:#27ae60,color:#fff,stroke:none
    style FAIL fill:#e74c3c,color:#fff,stroke:none
    style BLOCKED fill:#f39c12,color:#fff,stroke:none
    style SAFE fill:#f39c12,color:#fff,stroke:none
    style STABLE fill:#f39c12,color:#fff,stroke:none

See EXAMPLE_PROMPT.md for a complete worked prompt using this pattern.

Configuration

Config files live in twincat_validator/config/ inside the installed package. To locate them:

import twincat_validator, os
print(os.path.join(os.path.dirname(twincat_validator.__file__), "config"))

| File | Purpose | |------|---------| | validation_rules.json | Check definitions — severity, category, auto_fixable flag | | fix_capabilities.json | Fix definitions — complexity, risk level, deterministic order | | naming_conventions.json | Naming patterns by file type and subtype | | knowledge_base.json | LLM-friendly explanations and examples for all checks and fixes | | generation_contract.json | Canonical XML generation rules and forbidden patterns |

Restart the server after editing config files to reload.

Development

pip install -e ".[dev]"

# Run tests
pytest tests/

# Format
black --line-length=100 .

# Lint
ruff check .

# Type check
mypy twincat_validator/server.py --ignore-missing-imports

# Full CI suite (py311 + py312, lint, type check)
tox

License

MIT — see LICENSE for details.

Authors

Agentic Control - Jaime Calvente Mieres: design, architecture, and domain expertise

Built with the assistance of Claude (Anthropic) and Codex (OpenAI).