Tool Reference

This chapter describes every tool the IronPLC MCP server exposes. Tools are grouped by purpose: analysis tools validate source, context tools summarise a project, and execution tools produce artifacts.

Every tool that takes source files shares two input fields:

sources (array, required)

One or more source files. Each entry has a name (logical file name — non-empty, at most 256 bytes of printable ASCII, unique within the array) and a content string with the full source text.

options (object, required)

Compiler options. Must include a dialect field set to one of the identifiers returned by list_options (for example, iec61131-3-ed2, iec61131-3-ed3, rusty). May also include boolean feature-flag overrides (such as allow_c_style_comments). Call list_options for the authoritative list.

All tools return diagnostics as an array of objects with code, message, file, start, end, and severity fields. code is a problem code documented in Problem Codes.

Analysis Tools

list_options

Enumerates the dialects and feature flags accepted in the options object of the source-accepting tools. Call this once at the start of a session to learn what your build of ironplcmcp supports; the set of flags evolves with the compiler.

Inputs: none.

Returns: an object listing each dialect and each feature flag with its option key and default value.

explain_diagnostic

Looks up the human-readable explanation for a compiler problem code. Call this before editing code in response to a diagnostic you do not fully understand — the explanation often names the exact construct to change.

Inputs:

• code (string, required) — Problem code to look up (e.g. "P0042"). Case-insensitive; whitespace is trimmed.

Returns: an object with found, code, title, description, and an optional suggested_fix pulled from the same documentation rendered at Problem Codes.

parse

Syntax check only. Confirms that the supplied sources tokenize and parse. Use while drafting to catch missing keywords, unbalanced brackets, and similar mistakes quickly. Do not use parse to validate a change — it does not catch type errors, undeclared symbols, or any other semantic rule. Call check for that.

Inputs: sources, options.

Returns: an object with ok, a structure array listing the top-level declarations found in each file, and diagnostics.

check

Primary validator. Runs the full pipeline through semantic analysis and returns structured diagnostics. Always call check before reporting a change as complete and before calling compile. To self-heal, read the returned diagnostics, fix the source, and call check again — use explain_diagnostic to clarify any unfamiliar problem code before editing.

Inputs: sources, options.

Returns: an object with ok and diagnostics.

symbols

Extracts the full symbol table for the supplied sources: programs, functions, function blocks, their variables, and user-defined types. Large responses are capped at 256 KiB; when the cap is reached the response is empty with truncated set to true. Use the pou filter or one of the context tools below when you only need part of the answer.

Inputs:

• sources (required)

• options (required)

• pou (string, optional) — Restrict the response to a single program, function, or function block by name. Matching is case-insensitive. Referenced user-defined types are still included.

Returns: an object with ok, arrays programs, functions, function_blocks, types, a truncated flag, and diagnostics. When pou is supplied, found indicates whether a matching POU existed.

Context Tools

project_manifest

Flat summary of what is declared across the supplied sources: file names, program / function / function-block names, and user-defined types grouped by kind (enumerations, structures, arrays, subranges, aliases, strings, references). Use this to orient yourself in an unfamiliar project before calling symbols or a more targeted context tool.

Inputs: sources, options.

Returns: an object with ok, files, programs, functions, function_blocks, grouped types, and diagnostics.

project_io

Lists the inputs the caller can drive and the outputs the caller can observe. This is the right tool to call before planning an execution run — for example, to decide which variables to supply as stimuli or which to trace.

Inputs: sources, options.

Returns: an object with ok, inputs, outputs, and diagnostics.

Execution Tools

compile

Runs the full pipeline (parse → semantic analysis → code generation) and stores the resulting bytecode container in the server’s in-memory cache. Only call compile when you need a compiled artifact — for validation, use check, which is faster and produces the same diagnostics.

Inputs:

• sources (required)

• options (required)

• include_bytes (boolean, optional, default false) — When true, the response includes the compiled container as a base64-encoded string.

Returns: an object with ok, a container_id string for later reference, an optional container_base64 when include_bytes is true, arrays tasks and programs describing the compiled configuration, and diagnostics.

run

Executes a previously compiled container in the IronPLC virtual machine for a span of simulated time, returning a time-ordered trace of the variables you name. Use it to check that a program behaves correctly, not merely that it compiles.

Inputs:

• container_id (string, required) — The identifier returned by a prior compile call.

• duration_ms (number, required) — How much simulated time to run. The number of scan cycles follows from each task’s cycle time.

• freewheeling_interval_ms (number) — The cycle time to run a task that declares no INTERVAL at. Required when the container has such a task. See Programs with no task interval below.

• variables (array of strings, optional) — Fully-qualified names to trace, such as Main.Counter.

• trace_outputs (boolean, optional, default false) — Trace every observable output in addition to variables.

• limits (object, optional) — Tightens the server’s resource limits for this call. It cannot loosen them.

Returns: an object with ok, a trace array, a truncated flag, a terminated_reason, a summary (final values, completed cycles per task, and interval_ms — the cycle time the run executed at), and diagnostics.

Programs with no task interval

A task that declares no INTERVAL — including the task the compiler supplies for a program with no CONFIGURATION — is freewheeling: it runs as fast as the hardware allows. That rate is a property of the machine, not of the program, so under simulated time there is nothing to advance the clock by.

run will not choose a rate for you — a scan time belongs to the hardware the program would run on, and a trace built on a number you never chose reads as fact. Running such a container without freewheeling_interval_ms returns ok: false and a diagnostic naming the task. Supply the scan time you want to simulate, and the response reports what it used as summary.interval_ms, because every timestamp in the trace — and every timer in the program — depends on it.

The debugger is deliberately more forgiving: it assumes 100 ms and says so on the console, because a debug session that refuses to start is a poor answer to a missing setting. See ironplcvmd.

compile reports these tasks with kind: "freewheeling", which is how you can tell in advance that the assumption applies. Declare a CONFIGURATION with TASK plc_task(INTERVAL := T#100ms) when you want the program itself to fix the rate.

container_drop

Explicitly releases a compiled container from the server cache. Not usually necessary — the cache evicts on LRU pressure automatically — but useful for long-running connections that have finished with a particular build.

Inputs:

• container_id (string, required) — The identifier returned by a prior compile call.

Returns: an object with ok, removed (true when the entry existed and was evicted), and diagnostics.

See Also

• Overview — MCP server overview

• ironplcmcp — Command-line reference

• Problem Codes — Problem code index used by the diagnostics field and by explain_diagnostic