README.md
Validate, auto-fix, and scaffold TwinCAT 3 XML files.
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:
pip install twincat-validator-mcp- Download the
.dxtfile 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
}
}
}
From-source config (all clients)
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-xxx
Tools (5)
validate_fileFull validation of a single file returning issues with severity and location.validate_batchValidate multiple files matching glob patterns.autofix_fileApply all safe auto-fixes to a single file in deterministic order.generate_skeletonGenerate a canonical, deterministic XML skeleton for a given file type.process_twincat_batchFull enforced pipeline across multiple files with summary or full response modes.Configuration
claude_desktop_config.json
{"mcpServers": {"twincat-validator": {"command": "twincat-validator-mcp", "args": []}}}Try it
→Validate the file 'Main.TcPOU' and list all critical structural issues.
→Run a batch validation on all files in the project matching '**/*.TcPOU' and provide a health summary.
→Apply all safe auto-fixes to the file 'SensorModule.TcPOU' and verify the changes.
→Generate a canonical XML skeleton for a new Function Block named 'MotorControl'.
→Process all files in the current directory using the enforced pipeline and report any remaining issues.