How do I use TwinCAT Validator MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TwinCAT Validator MCP Server validate MotorControl.TcPOU and suggest safe fixes" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

TwinCAT Validator MCP Server

Python Version License: MIT MCP Compatible Code style: black

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:

pip install twincat-validator-mcp
Download the .dxt file from the latest release
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
    }
  }
}

Replace "command": "twincat-validator-mcp" with:

"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:

Tabs → 2 spaces (runs before indentation)
File ending — fixes truncated ]]> after </TcPlcObject>
Property newlines — normalizes declaration line breaks
CDATA formatting — corrects CDATA section structure
Property VAR blocks — inserts missing VAR/END_VAR in getters
Excessive blank lines — reduces to max 2 consecutive
Indentation — normalizes to 2-space multiples
GUID case — uppercases hex to canonical lowercase
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).

TwinCAT Validator MCP Server

TwinCAT Validator MCP Server

Supported File Types

Installation

From Source

Claude Desktop Extension

Connecting to an LLM Client

Cursor — `.cursor/mcp.json`

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

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

Cline (VS Code Extension)

MCP Tools

Validation

Auto-fix

Orchestration

Validation Checks

Structure & Format (critical — blocks import)

Style (warning — advisory)

OOP — IEC 61131-3 (21 checks)

Auto-fix Capabilities

Intent-Aware OOP Enforcement

Health Score

MCP Resources

MCP Prompts

Agent Guide

Recommended Workflow

Configuration

Development

License

Authors

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

TwinCAT Validator MCP Server

Supported File Types

Installation

From Source

Claude Desktop Extension

Connecting to an LLM Client

Cursor — .cursor/mcp.json

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

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

Cline (VS Code Extension)

MCP Tools

Validation

Auto-fix

Orchestration

Validation Checks

Structure & Format (critical — blocks import)

Style (warning — advisory)

OOP — IEC 61131-3 (21 checks)

Auto-fix Capabilities

Intent-Aware OOP Enforcement

Health Score

MCP Resources

MCP Prompts

Agent Guide

Recommended Workflow

Configuration

Development

License

Authors

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

Cursor — `.cursor/mcp.json`

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

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