io.github.efranceschetti/festo-codesys-mcp

Generate a CODESYS data type: ENUM (E_*) or STRUCT (ST_*), with .st + PLCopen XML output. USE WHEN: you need an ENUM (state/mode) or STRUCT (config/record) to back FB, GVL, or program declarations. Name auto-corrected to E_ (enum) or ST_ (struct) prefix if missing.

Generate a CODESYS Function Block (.st + PLCopen XML) with the standard interface built in. USE WHEN: the user asks for a new FB and plc_library returned no reusable match. ALWAYS BEFORE: (1) plc_library action=search — never create what already exists; (2) plc_knowledge topics 'conventions' + 'abbreviations'. Standard pattern: bEnable/bExecute inputs, bDone/bBusy/bErr/nErrId outputs, nState state machine. Name auto-corrected to FB_ prefix. DO NOT: use this for servo motion logic — motion uses MC_*_Festo blocks (topic 'festo-ptp'), not custom FBs.

Generate a Global Variable List (.st + PLCopen XML) with {attribute 'qualified_only'}. USE WHEN: you need globals shared across POUs — I/O map, system flags, HMI tags (GVL_HMI), config. Name auto-corrected to GVL_ prefix if missing. Common: GVL_Sys, GVL_IO, GVL_HMI, GVL_Cfg.

Generate a CODESYS Program (.st + PLCopen XML) for cyclic control logic. USE WHEN: you need a cyclic PRG (runs once per scan) — PRG_Main, PRG_Auto, sequence orchestration — and no reusable one exists. Programs run once per PLC scan (PRG_Main, PRG_Auto, etc.). Name auto-corrected to PRG_ prefix if missing.

Scaffold a standard CODESYS project directory for Festo CPX-E. USE WHEN: starting a new CODESYS project and you need the standard folder scaffold before creating POUs. Creates: src/0_Types, src/1_Globals, src/2_Programs, src/3_FunctionBlocks, src/4_Functions, src/5_Library, export/xml, docs. Set includeExamples=true to pre-populate with E_MachState, GVL_Sys, and PRG_Main stubs. After scaffolding, create files in order: Types → GVLs → FBs → Programs → generate XML.

Static analysis for Structured Text bugs — run BEFORE deploying to a real PLC. USE WHEN: ST code is convention-clean and you need runtime-bug analysis, or the user reports misbehavior. Catches: WHILE/REPEAT loops (watchdog risk), missing error handling (bErr/nErrId), CiA 402 safety gaps (MC_Power without MC_Stop), state machine issues (missing IDLE/ERROR), Hungarian notation violations, REAL-INT type mismatches, unused timer outputs. Returns categorized Critical/Warning/Suggestion results.

Decode Festo/CODESYS/EtherCAT error codes using ALL embedded references. USE WHEN: any Festo/CODESYS/EtherCAT error code appears — 0x…, 16#…, drive fault, AL status. Never guess meanings. Accepts hex (0x7500), IEC (16#8011), or decimal formats. Searches: CiA 402, Festo PtP, CODESYS ground truth, ALL embedded topics, and all device manuals. If not found locally, search the web — then save useful findings to knowledge/manuals/ for future use.

Batch-convert a directory of .st files into a single PLCopen TC6 0200 XML for CODESYS import. USE WHEN: .st sources are final and reviewed, and the user wants a CODESYS-importable file. ALWAYS BEFORE: plc_knowledge topic 'ground-truth' (anti-hallucination XML rules) if you have not loaded it this session. ALWAYS AFTER: validate_plcopen_xml -> validate_plcopen_xsd -> validate_plcopen_semantic. Never hand the XML to the user before the chain passes. DO NOT: hand-write PLCopen XML — always generate it from .st sources with this tool.

Load embedded PLC reference documentation — the source of truth for Festo/CODESYS/EtherCAT/PLCopen. USE WHEN: before writing ANY Structured Text (load 'conventions' + 'abbreviations' first), before generating XML (load 'ground-truth'), before motion code (load 'festo-ptp' + 'ethercat-cia402'), or whenever a technical fact is needed — never answer from memory. Actions: 'topic' (load by name), 'search' (BM25 full-text across ALL topics + manuals), 'list_manuals', 'read_manual'. Topics (27): conventions, abbreviations, hungarian-notation, state-machines, engineering-discipline, ground-truth, xml-rules, plcopen-schema, plcopen-example, plcopen-extensions, festo-cpx, festo-ptp, festo-cdpx-hmi, festo-vtux-terminal, festo-cmmt-st, festo-mqtt, motion-patterns, ethercat-cia402, eplan, hmi-web-architecture, opcua-websocket-gateway, hmi-embedded-deploy, plc-architecture-patterns, plc-alarm-patterns, codesys-recipe-manager, codesys-gotchas, plc-testing-twin. Covers: Festo CPX/PtP/CMMT/MQTT, CODESYS, EtherCAT CiA 402, PLCopen XML, naming conventions, engineering discipline & quality gates, custom Web HMI + OPC-UA gateway, PLC program architecture + alarm design, recipes, testing without hardware, CODESYS gotchas, 19 device manuals. If information is not found here, you may search the web — but suggest saving useful findings to knowledge/manuals/ for future use.

Access the 38-block reusable ST library (30 Function Blocks + 8 shared DUTs) — ALWAYS check here BEFORE creating new FBs. USE WHEN: about to create any FB, or looking for ready-made motor/valve/PID/sensor/safety logic. Actions: 'search' (keyword match), 'list' (browse by category), 'get' (full source code). Categories: types (8), motion (4), actuators (5), sensors (4), safety (2), system (5), utilities (10). Contains ready-to-use blocks for motors, valves, PID, sensors, safety, and more. DO NOT create a new FB if a similar one already exists here.

Quick lookup for PLC conventions and error codes — instant answers without loading full knowledge topics. USE WHEN: you need a single fact — prefix, state number, error code — without loading a full topic. Try this BEFORE plc_knowledge for point lookups. Actions: 'hungarian' (type→prefix), 'type_prefix' (POU→prefix), 'state' (state number→name), 'error_code' (decode Festo/CiA402/CODESYS error), 'fb_interface' (standard FB pattern), 'list_standard' (full reference).

Validate PLC code against conventions — composable validators with consistent results. USE WHEN: you need to check ST against conventions programmatically — naming, FB interface, or state machine — without a full review. Actions: 'naming' (check variable names + Hungarian notation), 'fb_interface' (check FB pattern), 'state_machine' (check nState pattern), 'batch' (validate multiple items at once). Returns {valid, message, details} for each check.

Validate ST code against naming conventions — returns ONLY violations, not reference dumps. USE WHEN: immediately after writing or editing any ST code. Checks: Hungarian notation (b=BOOL, n=INT, r=REAL, t=TIME, fb=FB instance), POU prefixes (FB_, PRG_, FC_), FB interface pattern (bEnable/bDone/bBusy/bErr/nErrId), state machine (0=IDLE, 90=DONE, 99=ERROR), snake_case detection. Includes quick-reference table when violations are found.

Find all references (usages) of an ST identifier across a directory of .st files — token-aware and comment/string-safe (unlike grep: ignores comments, strings, typed literals, and substring matches). USE WHEN: you need every usage of an ST identifier across files before renaming or refactoring. Each reference carries file, line/column, the line text, the containing POU, whether it is the declaration site, and disambiguation hints (e.g. resolves E_X.MEMBER member access via the qualifier). Note: sourceDir must be inside the workspace unless FESTO_MCP_ALLOW_OUTSIDE_WORKSPACE=1.

Index a directory of .st files and navigate symbols across files — dialect-aware (CODESYS V3.5), comment/string-safe, better than grep. USE WHEN: you need to navigate an existing .st project — outline symbols or resolve a definition across files (better than grep). Actions: 'outline' — project map. Returns top-level symbols (functionBlock/program/function/enum/struct/gvl) by default; pass kindFilter to include vars/members (e.g. ["inputVar","globalVar"]). 'definition' — resolve a name (case-insensitive) to its definition(s); requires 'name'. Notes: sourceDir must be inside the workspace unless FESTO_MCP_ALLOW_OUTSIDE_WORKSPACE=1. Line numbers and find-references arrive in a later version (this version returns file + container).

Compares variable/initializer counts between source .st files and generated PLCopen XML. USE WHEN: after validate_plcopen_xsd passes, to confirm no variables/initializers were silently dropped vs the .st sources. Detects bugs where the generator silently drops variables or initializers: - VARS_MISSING — ST has more vars than XML (Bugs A/B/F) - INITS_MISSING — ST has more initializers than XML (Bug E) - AT_ADDR_LOST — ST has vars with AT %IX/QX, XML has 0 <address> tags (Bug A) - POU_MISSING_IN_XML — POU declared in .st but absent in XML Use AFTER validate_plcopen_xsd. If XSD passes but semantic fails, the XML is structurally valid but missing content — exactly the silent-failure scenario that caused the 2026-05-22 incident (203 CODESYS errors). Tolerances are configurable; defaults are permissive (-25% vars, -30% inits). Output: { gate, valid, summary, errors[{line, location, code, message}], counts }

Fast smoke check for PLCopen XML — XML well-formedness + 13 structural regex heuristics. USE WHEN: immediately after generate_plcopen_xml, as the fast first gate before the XSD/semantic validators. Use AFTER generate_plcopen_xml as a quick gate before the heavier validators. Checks: XML well-formedness, PLCopen namespace, XHTML namespace, fileHeader, contentHeader, coordinateInfo (fbd/ld/sfc), mandatory instances footer, zero-ID rule on connectionPoints, ST code wrapping in xhtml, inOutVariables on blocks, structural hierarchy. Returns: PASSED/ISSUES counts and VALID/FIX verdict. NOTE: this is a sanity check only. For full validation use: - validate_plcopen_xsd — XSD official PLCopen TC6 v2.00 (catches structural issues) - validate_plcopen_semantic — count vars/inits source ST vs XML (catches Bugs A/B/E/F: missing vars/inits)

Strict schema validation against the official PLCopen TC6 v2.00 XSD (embedded). USE WHEN: after validate_plcopen_xml passes and you need strict schema conformance before import. Catches structural issues that the fast sanity check misses: malformed elements, required attributes missing, type mismatches, etc. Use AFTER generate_plcopen_xml for full structural validation before CODESYS import. Output: { gate, valid, summary, errors[{line, location, code, message}], counts } Codes: FILE_NOT_FOUND, XSD_NOT_FOUND, XSD_PARSE_ERROR, XML_PARSE_ERROR, XSD_VIOLATION. NOTE: requires lxml in the MCP python venv. Pair with validate_plcopen_semantic for end-to-end coverage (XSD catches structure, semantic catches missing vars/inits).