Live DataModel Tools

Read/edit the open project’s live object model via runtime reflection, working around a script-engine limitation on static using directives.

5 tools (all prefixed eplan_ when registered as MCP tools).

`eplan_live_query_functions`

eplan_live_query_functions(contains: str=None, limit: int=100, timeout_seconds: float=60.0)

List the functions (devices) of the project currently open in EPLAN.

Reads the live object model, so it sees the project as it stands in the session - including unsaved changes - which the file-based export_functions and the action-based search_devices do not.

Args: contains: Optional case-insensitive substring filter on the function’s identifying name (e.g. “-K” for contactors). Omit for all. limit: Max functions to return (default 100). “matched” in the result reports how many passed the filter before this cap. timeout_seconds: Max seconds to wait for the script (default 60). A full walk of a large project can exceed the standard 30s.

Returns: dict with “functions” (list of {“name”: …}), “matched”, “returned”.

`eplan_live_query_pages`

eplan_live_query_pages(contains: str=None, limit: int=100, timeout_seconds: float=60.0)

List the pages of the project currently open in EPLAN.

Reads the live object model, so unlike export_pages it reflects unsaved session state and needs no export file.

Args: contains: Optional case-insensitive substring filter on the page name. limit: Max pages to return (default 100). timeout_seconds: Max seconds to wait for the script (default 60).

Returns: dict with “pages” (list of {“name”: …, “pageType”: …}), “matched”, “returned”.

`eplan_live_set_function_text`

eplan_live_set_function_text(name: str, text: str, limit: int=1, timeout_seconds: float=60.0)

Set the function text (FUNC_TEXT) of functions whose identifying name exactly equals name, in the project currently open in EPLAN.

This is a WRITE to the live object model. The change lands on EPLAN’s normal undo stack and is not persisted until the project is saved. Each modified function’s previous text is returned so the edit is reversible.

Args: name: Exact identifying name of the target function, e.g. “+TEST-K1”. Matching is exact, not substring - use live_query_functions first to find the name you want. text: New function text. limit: Max functions to modify (default 1). “matched” reports how many functions carry the name; anything beyond limit is left alone, so a mistaken name cannot mass-edit the project. timeout_seconds: Max seconds to wait for the script (default 60).

Returns: dict with “matched”, “modified”, and “details” (per-function {“name”, “previous”, “new”}).

Note: FUNC_TEXT (property 20011) is backed by MultiLangString. “previous” is EPLAN’s internal MultiLangString encoding (language markers + text), not clean display text - a faithful but opaque snapshot, good for detecting “was empty”, less so for reading. Beware round-tripping it: writing a plain string stores it under the “no language set” key, so a value read back can carry a literal “??_??@” prefix. Restoring an empty value is clean; restoring a previously-set one may need that prefix stripped.

`eplan_live_set_connection_designations`

eplan_live_set_connection_designations(name: str, designations: list, limit: int=1, timeout_seconds: float=60.0)

Set the connection point designations of a function in the project currently open in EPLAN.

These are the connection point numbers shown on the multi-line schematic (e.g. “Y09” and “Y10” on a two-point function). EPLAN’s dialogs show the whole set joined with a pilcrow separator - “Y09Y10” - but the API stores one designation PER INDEX, so pass them as a list and this tool writes index 1, 2, … in order. Do NOT pass a pre-joined string; it would land entirely in index 1.

This is a WRITE to the live object model. The change lands on EPLAN’s normal undo stack and is not persisted until the project is saved. The previous designations are returned so the edit is reversible.

Note this changes the connection point NUMBERS, not their geometry. Connection point position and direction (PinBase.Location / .Direction) are read-only in the object model; moving a connection point means authoring the symbol itself, or swapping the function’s SymbolVariant.

Args: name: Exact identifying name of the target function, e.g. “+-TEST”. Matching is exact, not substring - use live_query_functions first. designations: Designations in connection point order, e.g. [“Y11”, “Y12”]. Written to indices 1..N. Passing fewer than the function has leaves the remaining points untouched. limit: Max functions to modify (default 1). “matched” reports how many functions carry the name; anything beyond limit is left alone. timeout_seconds: Max seconds to wait for the script (default 60).

Returns: dict with “matched”, “modified”, and “details” (per-function {“name”, “page”, “previous”, “new”}, previous/new being lists in index order).

`eplan_live_read_check_messages`

eplan_live_read_check_messages(start_index: int=1, limit: int=50, contains: str=None, timeout_seconds: float=60.0)

Read itemized messages from EPLAN’s “Message management” dialog (Tools > Review > Messages, action XMsgManagementShowAction) - the per-item results of the last check run (eplan_check_project / eplan_check_pages / ribbon “Check project”).

get_system_messages CANNOT see these: a check run only ever appends two summary lines (“N messages appeared…”) to the general system message tree. The actual N itemized entries live in a separate store, Eplan.EplApi.EServices.PrjMessagesCollection - “Collection of project messages of the last check run” per the API docs - which is what this reads.

That namespace is Eplan.EplApi.EServices, one of the ones that does NOT compile with using inside the EPLAN script engine (CS0234 - same trap as Eplan.EplApi.DataModel/HEServices, see api-data-access.md). This tool reaches it the same way live_query_functions reaches DataModel: by runtime reflection over the already-loaded assemblies (FindType + Activator + MethodInfo.Invoke), never by referencing the namespace at compile time.

Indexing is 1-based and matches the order EPLAN’s own Message management dialog lists items in, so “message number 71 in the dialog” is start_index=71, limit=1.

Args: start_index: 1-based position of the first message to return (default 1). Use this to page through a large check run, or to jump straight to one position to compare against what the user sees on screen (“is message #1940 the same as what I see?”). limit: How many consecutive messages to return from start_index (default 50, hard-capped at 500 - the collection can hold thousands of entries and this is a read tool, not a full dump). contains: Optional case-insensitive substring filter on the message text. Applied together with the start_index/limit window (i.e. this narrows what’s returned FROM that window, it does not search the whole collection) - pass a wide limit if you need to search broadly. Omit to return every message in the window. timeout_seconds: Max seconds to wait for the script (default 60). Raise it for very large projects - the whole collection is enumerated once regardless of the window requested.

Returns: dict with “total” (Count of the full collection, read directly - not by walking), “enumerated” (how many entries the enumerator actually walked before stopping at end_index; less than total whenever the window ends before the collection does), “matched” (how many in-window messages passed the contains filter), and “messages”: a list of {“index” (1-based), “id” (message number), “text” (full substituted message text), “object1Type” (.NET type name of the first object the message is attached to, e.g. “Terminal”, “Function”, or “” if none)}.

This page is generated from the docstrings in Canary-ECAD/eplan-mcp.