Live DataModel Tools

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.

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

< Back to Home

---

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).

---