Scope

Current implementation

The project is an experimental MCP server for local OpenPLC engineering operations. Its research-release delivery scope is frozen to the thirteen tools in release contract revision 1. That contract also defines platform support and completion criteria; freezing the scope does not assert that release qualification is complete.

Project, execution-configuration, physical-I/O, data-type, POU, variable, and diagnostic inspection is read-only. The only local write-capable operations are update_pou, which atomically replaces one existing Structured Text POU file, and compilation, which is delegated to the authoritative openplc-cli.

Project format

The MCP supports only the current OpenPLC Editor project format.

Supported:

  • current OpenPLC Editor projects;
  • current POU source files under pous/;
  • current data.configuration execution/resource representation;
  • current datatypes/*.dt project-defined data types;
  • current devices/configuration.json board selection;
  • current per-board devices/pin-mapping.json local physical I/O mappings.

Intentionally unsupported:

  • legacy OpenPLC project formats;
  • historical JSON POU representations;
  • historical project representations such as data.configurations and embedded data.dataTypes data-type definitions;
  • historical flat pin-mapping arrays and legacy pin name fields;
  • automatic migration or backward-compatibility parsing.

The MCP does not detect, convert, or normalize historical project versions. A legacy representation may be ignored when it is outside a tool's recognized current layout or rejected when it would otherwise make the result ambiguous.

OpenPLC Editor compatibility

The research-release environment fixes OpenPLC Editor/CLI to commit f0bb418b9c3419e573dece4222558570f6a31378 (source version 4.2.12). It includes native POU files, .dt persistence, and the headless CLI required by the server. The validation environment defines how to install and verify that exact source revision.

Detailed project-format behavior remains in OpenPLC projects.

Current boundary

The implementation currently covers:

  • local current-format OpenPLC Editor project paths;
  • basic project.json metadata preconditions;
  • concise engineering overview and recognized physical project-file inspection;
  • configured execution Tasks and Program Instances;
  • selected device board and active local DevicePin mapping inspection;
  • project-defined data-type inspection from datatypes/*.dt files;
  • POU discovery;
  • POU content reading;
  • Structured Text POU content replacement;
  • POU variable/interface discovery;
  • resource-level global variable inspection;
  • CLI compilation;
  • process-local compiler diagnostics;
  • stdio MCP transport.

Not implemented yet

The current server does not provide:

  • POU creation, deletion, renaming, type conversion, or language conversion;
  • writes to POUs in languages other than Structured Text;
  • project, execution, device, data-type, or resource-level configuration modification;
  • data-type creation, modification, deletion, or recursive resolution;
  • built-in IEC or OpenPLC library data-type discovery;
  • standalone variable creation or modification tools (POU-local declarations can change through complete ST POU replacement);
  • project-wide variable or reference search;
  • vendor-specific VPP configuration inspection or reinterpretation;
  • communication configuration or protocol-specific device inspection;
  • remote-device inspection;
  • deployment or upload;
  • controller start/stop;
  • runtime or debug sessions;
  • live runtime execution or I/O state;
  • runtime variable reads;
  • variable forcing or releasing;
  • dependency analysis;
  • authentication;
  • HTTP transport.

These capabilities are outside the frozen research-release scope. A later scope revision may add them when a concrete requirement exists and the smallest useful domain-level contract can be defined.

Architectural non-goals

The MCP should not become:

  • a generic filesystem API;
  • a generic shell execution API;
  • a duplicate implementation of the OpenPLC project schema;
  • a project-format migration or compatibility layer;
  • a complete IEC 61131-3 parser;
  • a replacement for the OpenPLC Editor, CLI, compiler, or runtime;
  • a framework of abstractions created only for possible future features.

Expansion rule

Changing the frozen tool set, supported project representation, or mutation boundary requires an explicit revision of the release contract. Compatible fixes and validation work within that boundary do not expand the scope.

Before adding a capability, ask:

  1. Is this required by a real engineering workflow or experiment?
  2. Can the operation be expressed as a PLC engineering concept rather than a low-level implementation detail?
  3. Can existing OpenPLC behavior remain authoritative?
  4. Can it be implemented without adding unnecessary layers?
  5. Is it required to correctly support a project created by the current OpenPLC Editor?

If the answer is not clear, keep the current boundary unchanged.