Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@festo-codesys-mcp Create a conveyor jam detection FB and export as validated PLCopen XML"
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.
An MCP server that turns AI assistants into competent Festo/CODESYS PLC engineers.
LLMs are strong general programmers but unreliable PLC engineers: they invent Function Block signatures, hand-write PLCopen XML that CODESYS rejects, and guess at error codes. This server fixes that by grounding the model in curated, manufacturer-accurate knowledge and forcing every artifact through a machine-checked validation pipeline — so what reaches the CODESYS IDE actually imports, compiles, and follows one consistent engineering standard.
IEC 61131-3 ST ──► conventions enforced ──► PLCopen TC6 XML ──► 3-stage validation ──► CODESYS import
▲ ▲ │
│ │ ▼
38-block library 27 knowledge topics + 19 manuals official TC6 v2.00 XSD18 core tools — lookup, knowledge search (BM25), library reuse, ST/DUT/GVL generation, static analysis, convention review, PLCopen XML generation and a three-stage validation chain, ST code intelligence (symbols & where-used).
Embedded knowledge base — 27 curated topics (Festo PtP motion, EtherCAT CiA 402, CPX-E, VTUX, CMMT-ST, MQTT/IIoT, PLCopen ground truth, naming conventions…) plus 19 reference manuals, all searchable full-text.
Teaching modules that go beyond datasheets: PLC program architecture (Input-Process-Output, status-bus coordination), alarm design patterns, testing ST without hardware (digital-twin methodology), CODESYS Recipe Manager, hard-won CODESYS gotchas, and a complete custom web HMI + OPC-UA gateway curriculum (three-layer architecture, embedded-panel deployment).
38-block reusable ST library — 30 vendor-neutral Function Blocks plus 8 shared DUTs (motors, valves, PID, sensors, safety, logging, MQTT), all following one strict interface convention.
Built for AI agents — always-on server instructions, prescriptive
USE WHEN tool descriptions, next-step hints appended to every tool result,
and an engineering-discipline topic that encodes non-negotiable quality
gates (verify before delivering, no regressions, no hardcoded secrets).
Optional live surfaces — 12 ide_* tools drive a running CODESYS V3.5
IDE (create/patch POUs, compile, browse the device tree), and 8 hardware
tools commission Festo CPX-AP I/O and CMMT drives on the bench.
Trustworthy by construction — ~690 automated tests (676 node:test + 15 pytest); the generator's output is validated against the official PLCopen XSD (v2.01 release, namespace-patched to the tc6_0200 namespace CODESYS emits).
Related MCP server: TwinCAT Validator MCP Server
Requires Node.js ≥ 20. No API keys, no accounts, fully offline.
Claude Code — add to .mcp.json in your project:
{
"mcpServers": {
"festo-codesys-mcp": {
"command": "npx",
"args": ["-y", "festo-codesys-mcp"]
}
}
}Claude Desktop — add the same block to claude_desktop_config.json.
On Windows, wrap the command with cmd /c:
{
"mcpServers": {
"festo-codesys-mcp": {
"command": "cmd",
"args": ["/c", "npx", "-y", "festo-codesys-mcp"]
}
}
}From source:
git clone https://github.com/efranceschetti/festo-codesys-mcp.git
cd festo-codesys-mcp
npm ci && npm run build && npm test
# point your MCP client at: node build/index.jsThen just ask your assistant:
"Create a function block for a conveyor with jam detection, export it as PLCopen XML and validate it for CODESYS import."
The server steers the model through the full pipeline: load conventions → check the library for an existing block → generate → static-analyse → review naming → generate XML → validate (heuristics → XSD → semantics) → hand over an import-ready file.
Component | Technology |
PLC | Festo CPX-E-CEC (CODESYS V3.5) |
Motion | EtherCAT CiA 402 — CMMT-AS / CMMT-ST drives, Festo PtP library |
Pneumatics | VTUX valve terminals via CPX-AP-A/AP-I |
HMI | Festo CDPX (native WebVisu/TargetVisu) or custom web HMI + OPC-UA gateway |
Fieldbus | EtherCAT (master), Profinet (device), EtherNet/IP, Modbus/TCP |
Standards | IEC 61131-3, PLCopen XML TC6 v2.00 |
Much of the knowledge (IEC 61131-3 conventions, PLCopen XML, CiA 402, program architecture, alarm patterns, twin testing) applies to any CODESYS V3.5 target, not only Festo hardware.
Tool | What it does |
| Instant facts: Hungarian prefixes, POU prefixes, state numbers, error codes, FB patterns |
| Load any of the 27 topics, or BM25 full-text search across all topics + 19 manuals |
| Browse, search, and retrieve the 38-block ST library (30 FBs + 8 DUTs) |
| Validate ST: naming conventions, FB interface pattern, state machine, batch mode |
| Generate an FB (.st + PLCopen XML) with the standard interface built in |
| Generate a cyclic PRG |
| Generate ENUM / STRUCT data types (incl. |
| Generate Global Variable Lists (CONSTANT / PERSISTENT RETAIN aware) |
| Scaffold a standard project layout |
| Batch-convert an .st directory into one PLCopen TC6 XML file |
| Fast sanity gate: well-formedness + 13 structural heuristics (no Python required) |
| Strict validation against the official PLCopen XSD (v2.01, tc6_0200-namespace patched) |
| Diff source ST vs XML — catches silent variable/initializer loss |
| Static analysis: unbounded loops, missing error handling, state-machine gaps |
| Convention review with quick-reference output |
| Decode Festo / CODESYS / EtherCAT error codes with fix suggestions |
| Cross-file ST code intelligence: definitions, types, members |
| Where-used analysis for any symbol across the project |
Enabled by setting FESTO_MCP_CODESYS_PATH to your CODESYS.exe and
FESTO_MCP_CODESYS_PROFILE to the profile name shown in the CODESYS version
selector. Drives a live CODESYS V3.5 instance through its scripting engine:
open/create projects, create POUs/methods/properties, read and atomically patch
POU code, compile and surface errors, and walk the project & hardware device
tree as JSON. Use it after the offline pipeline produced validated XML — IDE
changes are irreversible.
Enabled by FESTO_MCP_ENABLE_HARDWARE=1 (plus Python with the official
festo-cpx-io / festo-edcon packages). Discover CPX-AP modules, read/write
I/O channels, control CMMT drives (enable, ack faults, position tasks) and
read/write raw PNU/SDO parameters. These tools bypass the PLC and write
directly to devices — never use them on a machine in production.
new-function-block · new-motion-fb · new-project · new-ethercat-slave ·
debug-axis · decode-error-code · audit-naming · validate-st-batch ·
audit-plcopen-xml · convert-manual
Area | Topics |
Conventions & discipline |
|
CODESYS / PLCopen |
|
Festo hardware |
|
EtherCAT |
|
Architecture & testing |
|
Web HMI curriculum |
|
EPLAN |
|
Plus 19 auto-discovered manuals (CPX-E system/IO/EtherCAT/Profinet, CMMT
servo & CiA 402 protocol reference, motion library, module catalog, CoE
dictionary, data logging/FTP, OPC-DA, safety relay, VFD reference…). Drop your
own converted manuals into knowledge/manuals/ and they are indexed
automatically at runtime — no rebuild needed.
A distinctive part of this knowledge base: a complete, generic curriculum for building a custom web HMI for CODESYS PLCs — the three-layer architecture (SPA ↔ WebSocket ↔ Python gateway ↔ OPC-UA ↔ PLC), a tag manifest as single source of truth with five access modes (read/write/pulse/dead-man hold/ heartbeat), hosting the SPA on the PLC's own web server, and deploying to resource-constrained embedded panels (Chromium 69 on ARMv7) including the unified panel-installer pattern. Ask your assistant "how do I show PLC data in a browser?" and it will find its way here.
This server is designed so the model cannot quietly go off the rails:
Server instructions (always in the client's context) pin the mandatory workflow — lookup → learn → reuse → create → verify → export — and five hard NEVERs (never invent FB signatures, never hand-write PLCopen XML, …).
Prescriptive tool descriptions (USE WHEN / ALWAYS BEFORE / DO NOT)
make the right next call obvious.
Next-step hints: every successful tool result ends with a one-line
Next: pointing to the next stage of the pipeline.
engineering-discipline topic: non-negotiable quality gates — verify
before delivering, re-validate the whole affected set after any edit, zero
deferred warnings, no hardcoded credentials or network addresses, and human
review before anything runs on a machine.
For Claude Code users, the repo ships ready-made skills (ST writing,
PLCopen pipeline, error diagnosis, motion control, HMI/gateway), review
subagents, and a project-memory scaffold under .claude/.
Environment variable | Default | Effect |
| unset | Path to |
| unset | CODESYS profile name (as shown in the version selector) — required for |
| unset |
|
| bundled venv | Python interpreter used by the XSD/semantic validators and hardware tools (needs |
| unset |
|
npm ci
npm run build # tsc → build/
npm test # node:test
npm run lint # eslint, zero warnings
npm run inspect # MCP Inspector against the built server
cd python # PLCopen XSD + semantic validation gates
uv sync && uv run pytest -qThe synthetic test fixture (python/tests/fixtures/synthetic-project-valid.xml,
~200 KB, 29 POUs) is generated by the server's own pipeline
(scripts/gen-synthetic-fixture.mjs) and must always validate against the
official TC6 v2.00 schema — regenerate it after generator changes and re-run the XSD gate to catch regressions.
See CONTRIBUTING.md for style rules and known future work (MCP SDK v2 migration, PLCopen ObjectId round-trip identity).
This project generates logic that can command real machinery. It is a reference implementation and engineering assistant — generated code must be reviewed by a qualified automation engineer before it runs on any machine that can cause physical harm, and safety functions must be implemented and validated per the applicable standards. See SECURITY.md.
This project stands on the shoulders of excellent open work, and is grateful to:
codesys-mcp-toolkit
by Johannes Pettersson (MIT) — the foundation for the ide_* CODESYS
Scripting-Engine driving tools and their script templates.
Festo SE & Co. KG — the official
festo-cpx-io and
festo-edcon Python SDKs, which the
cpx_* / edcon_* commissioning tools wrap.
PLCopen — the TC6 XML interchange standard and the reference schema/example that the generator and validators are built against.
Model Context Protocol and the
@modelcontextprotocol/sdk
— the protocol and TypeScript SDK this server is built on.
Full third-party copyright and license notices are preserved in NOTICE.md.
MIT — © 2026 E3 Engenharia Industrial · Eduardo Franceschetti.
Built from real-world Festo/CODESYS machine engineering practice.
Festo® and CODESYS® are trademarks of their respective owners. This is an independent open-source project, not affiliated with or endorsed by Festo SE & Co. KG or CODESYS GmbH.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Error source platform | |
| errorCode | Yes | The error code (e.g., "0x7500", "16#8011", "MC error 4357") |
| Name | Required | Description |
|---|---|---|
| found | Yes | |
| source | Yes | |
| message | Yes | |
| errorCode | Yes | |
| manualHits | Yes | |
| snippetCount | Yes | |
| sourcesMatched | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description claims the tool saves findings to knowledge/manuals for future use, implying a write operation. However, annotations declare readOnlyHint=true, indicating no state modification. This is a direct contradiction, significantly reducing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with front-loaded main purpose. Every sentence adds value without redundancy, achieving clarity in few words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-platform error decoding), the description covers input formats, search sources, fallback web search, and saving behavior. With an output schema present and thorough annotations, this is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining acceptable input formats for errorCode (hex, IEC, decimal) and describing search sources (CiA 402, Festo PtP, etc.), which enriches the meaning of both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool decodes Festo/CODESYS/EtherCAT error codes using all embedded references. It specifies the verb 'decode' and resource 'error codes', distinguishing it from sibling tools like review_st_code or plc_lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'USE WHEN: any Festo/CODESYS/EtherCAT error code appears' with examples like 0x..., 16#..., drive fault, AL status. It also warns against guessing, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Block name for action=get (e.g., "FB_StandardMotor", "E_AxisState") | |
| query | No | Search term for action=search (e.g., "motor", "temperature", "pid") | |
| action | Yes | 'search': find blocks by keyword | 'list': browse all blocks (optionally by category) | 'get': retrieve full .st source code | |
| category | No | Filter by category for action=list, or category hint for action=get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by detailing the actions (search, list, get) and that it provides source code, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and front-loaded with the main purpose. Each sentence adds value, though it could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 4 parameters with enums, rich annotations, and no output schema, the description covers actions, categories, usage guidance, and what to expect, making it fully informative for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage. Description adds examples (e.g., 'FB_StandardMotor' for name) and explains the actions and categories in more detail than schema, enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Access the 38-block reusable ST library' and lists specific actions (search, list, get) and categories. This distinguishes it from sibling tools like 'review_st_code' and 'plc_lookup'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'ALWAYS check here BEFORE creating new FBs' and 'DO NOT create a new FB if a similar one already exists.' It lacks explicit alternatives, but the context strongly implies when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| value | No | The value to look up (type name, POU type, state number, or error code) | |
| action | Yes | 'hungarian': get prefix for a type | 'type_prefix': get prefix for POU type | 'state': decode state number | 'error_code': decode error | 'fb_interface': show standard FB pattern | 'list_standard': full convention reference |
| Name | Required | Description |
|---|---|---|
| found | Yes | |
| action | Yes | |
| details | Yes | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by noting 'instant answers without loading full knowledge topics', which implies no side effects and fast response. Annotations already indicate readOnly, idempotent, non-destructive behavior, and the description complements this well without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with a clear 'USE WHEN' block and action list. Every sentence adds value, and it is front-loaded with the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to detail return values. It covers usage context and actions comprehensively. Minor gap: no mention of error handling for invalid lookup values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters well. The description lists actions but does not add significant new meaning beyond what is in the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: quick lookup for PLC conventions and error codes. It lists specific actions, which helps distinguish from siblings, though it does not explicitly differentiate from all listed sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: 'USE WHEN: you need a single fact' and suggests trying this tool before a related tool (plc_knowledge) for point lookups. However, it does not mention when not to use it relative to the listed sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The Structured Text code to review |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show read-only, idempotent, non-destructive. Description adds value: returns only violations, not reference dumps, includes quick-reference table. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Succinct multi-line description with front-loaded purpose and bullet-like list of checks. Some redundancy (e.g., 'immediately after writing' could be concise).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one input and no output schema; description covers purpose, usage, checks, and output behavior. Could clarify what happens with no violations (likely empty result) but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter 'code' is fully described in schema (100% coverage). Description adds no extra parameter depth beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it validates ST code against naming conventions and lists specific checks (Hungarian notation, POU prefixes, etc.), distinguishing it from siblings like explain_error_code or st_find_references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'USE WHEN: immediately after writing or editing any ST code' provides clear context. Does not explicitly mention when not to use or alternatives, but the sibling list is provided separately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Identifier to search for (whole token) | |
| sourceDir | Yes | Directory containing .st files (recursive scan) | |
| caseInsensitive | No | IEC is case-insensitive (default true) | |
| includeDeclaration | No | Include the declaration site (default false) |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| sourceDir | Yes | |
| references | Yes | |
| definitions | Yes | |
| referenceCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rich behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It details token-awareness, ignoring comments/strings/substrings, and specifies the output fields (file, line/col, line text, containing POU, declaration flag, disambiguation hints). It also notes the workspace constraint for sourceDir.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 3 sentences, with a clear 'USE WHEN' callout and a final note on workspace restrictions. No wasted words, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, full schema coverage, existing output schema, rich annotations), the description covers all necessary aspects: behavior, usage context, constraints, and output details. It is complete without needing to repeat output schema information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 4 parameters with descriptions (100% coverage). The description does not add new parameter-specific semantic details beyond the schema; it provides tool-level context but no extra per-parameter elaboration. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Find all references (usages) of an ST identifier across a directory of .st files'. It distinguishes itself from grep by being token-aware and safe, and differentiates from sibling tools like plc_lookup or st_symbols by focusing on references for renaming/refactoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an explicit 'USE WHEN' statement: 'USE WHEN: you need every usage of an ST identifier across files before renaming or refactoring.' This provides clear context for when to use the tool, though it does not explicitly state when not to use it or name specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Symbol name (required for action=definition) | |
| action | Yes | 'outline' = project map | 'definition' = resolve a name | |
| sourceDir | Yes | Directory containing .st files (recursive scan) | |
| kindFilter | No | Filter by SymbolKind (e.g. ["functionBlock","globalVar"]) |
| Name | Required | Description |
|---|---|---|
| action | Yes | |
| symbols | Yes | |
| fileCount | Yes | |
| sourceDir | Yes | |
| symbolCount | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable behavioral context: dialect-aware (CODESYS V3.5), comment/string-safe, workspace restriction with env var override, and return format (file + container). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, bullet points, and clear language. It is somewhat lengthy but every sentence adds value. Could be slightly more concise, but overall efficient for the information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description appropriately focuses on usage and constraints. It covers workspace restrictions, different actions, and explicitly mentions limitations (no line numbers/find-references). The description is complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented. The description adds actionable nuance: explains default behavior of outline (top-level symbols) and how kindFilter extends it, and notes that definition is case-insensitive. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('index', 'navigate') and clearly distinguishes the tool from siblings by noting it is dialect-aware and better than grep. It explicitly mentions the two actions and the resource (.st files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'USE WHEN' guidance: to navigate an existing .st project for outlining or resolving definitions. It also clarifies what the tool does NOT do (line numbers, find-references), directing agents to future updates or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1explain_error_codeplc_libraryplc_lookupreview_st_codest_find_referencesst_symbolsScored across 6 tools
Most tools have distinct purposes: review_st_code for validation, explain_error_code for error decoding, plc_library for library access, st_symbols for symbol navigation, st_find_references for reference finding. However, plc_lookup overlaps with explain_error_code by also decoding error codes, though descriptions differentiate them as quick lookup vs. comprehensive search.
Tool names use snake_case but follow inconsistent patterns: some start with verbs (review_st_code, explain_error_code), others with nouns (plc_library, plc_lookup, st_symbols) or a verb phrase (st_find_references). This mix reduces predictability.
With 6 tools for PLC development, the set is well-scoped. Each tool addresses a clear need: code validation, error handling, library access, quick lookup, symbol navigation, and reference finding. No tool is redundant.
The tool set covers the essential tasks for ST coding assistance: code style validation, error code resolution, reusable block library, quick references, project navigation, and refactoring support. There are no obvious gaps for the intended use case.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Official DevSpeak MCP server — translate technical text into formal specs from any AI IDE or agent
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
