EPLAN MCP Server (EPlanMCPServer, eplan-mcp-server)

Source-preserving EPLAN export, electrical report and drawing analysis for MCP

Standalone Codex plugin, shared Python service and CLI. Version 26.1026.164643. The main purpose is to extract device names/descriptions, network addresses, PLC I/O points, and the power or compressed-air supplies feeding each device. The repository uses EPlanMCPServer; the Python distribution uses the normalized package name eplan-mcp-server and imports as eplan_mcp.

Table of Contents

• Background

• Local readers

• Install

• Usage

• Features

• Optional app-owned framework

• Development

• Maintainers

• Contributing

• License

Related MCP server: Design MCP

Background

Built using the AutoCAD MCP Server architecture. This release analyzes exported evidence without changing engineering sources. It does not require EPLAN for offline analysis. It does not yet provide native EPLAN project access or editing.

Local readers

The standalone route uses bounded lightweight metadata frontdoors. Idle chats do not reserve analysis or parser/ODA workers. Work is admitted lazily in owned ephemeral processes; an exhausted analysis pool returns a meaningful busy error while discovery and guidance stay usable. See multi-chat readiness for independent budgets, measured acceptance requirements and MSIX path handling. The finite metadata capacity is twenty connections, each metadata process limited to 128 MiB. Analysis keeps separate admission and full-tree limits. Validate the actual loaded-chat and reconnect demand before publishing a deployment; a small pilot does not establish general host availability.

Packed-source preparation is experimental and opt-in. Its deterministic container, logical hash checks, verified source/resource loader and Windows read leases are available for source validation; existing launchers still use the expanded layout. It does not select a runtime or establish deployment readiness. See packed runtime preparation.

The explicit direct-standalone-local-readers profile enables the existing ODA DWG/DWT/DWS-to-DXF adapter. Configure oda_executable as an explicit .exe path and oda_sha256 as its reviewed SHA-256. No executable discovery or environment opt-in is used. Default configurations stay direct-standalone-offline.

Conversion runs only against a private staged copy, through the existing bounded, job-contained and durably recorded worker ownership layer. Executable and source hashes are checked around conversion; changed evidence is discarded. The direct stdio and pinned ODA paths have synthetic read, preview and descendant-cleanup coverage. Revalidate changed runtime/vendor bytes before activation. Existing offline deployments need no change. Access/ACE provider execution remains gated; semantic EPLAN project APIs and native editing are not implemented.

Install

Published connections use an app-owned Start-Mcp.py, stable working directory, retained Python engine and immutable versioned runtimes. Atomic selection changes apply to new connections; live peers keep their original runtime. Launch verifies the selected inventory and never installs, discovers a newer directory or falls back after failure. Plugin-cache removal does not remove this entry point.

Prepare a reviewed deployment through the root installer (Windows Python 3.13):

.\Install.cmd --stable-deploy --help
.\Install.cmd --stable-deploy --root "C:\Apps\EPlanMCPServer" --runtime "C:\Reviewed\runtime" --wheel "C:\Packages\eplan_mcp_server-RELEASE-py3-none-any.whl" --wheel-sha256 REVIEWED_SHA256 --config "C:\Reviewed\config.json" --dependencies "C:\Reviewed\dependencies.json"

Updates require --expected-current with the prior selection's SHA-256. Keep old runtime generations and receipts. Prepare plugin bindings separately with scripts/install_plugin.py --prepare-only --stable-root and the matching --config. Source plugin templates retain the standalone skill but publish no implicit HTTP route. Host settings publication is a separate serialized operation; no installer edits global Codex TOML or immutable plugin caches. See the stable deployment guide.

Install.cmd and the retained InstallAndRun.cmd install only: neither starts a server/native application, enables a plugin, installs the manager, or writes global Codex settings. Use --help before setup. Existing configuration is preserved. With no first-time --root, setup creates an empty private .local/workspace. See implementation and developer guide.

Dependencies

Python 3.11+; Windows is the primary target. Python 3.13 is used for validation. The selected direct-standalone-offline profile supports DXF, PDF, explicit reports and local byte/XML readers. The explicit local-reader profile also supports ODA-converted DWG/DWT/DWS. No vendor discovery or environment opt-in selects it. Access/ACE provider reads remain refused.

The shared framework is a separately supplied local wheel, not fetched from an unverified public package with the same name. The installer verifies SHA-256 and every wheel RECORD member:

universal_codex_tools-0.20.0-py3-none-any.whl
SHA-256 a1b3777f8e8c1900e136a514d89ddb485a6bf4d69a525e3d24e1d04cd040efb3
Source commit 5b2cac50ca24d21a15b732e0424bb02fd794e1fb

.\Install.cmd --help
.\Install.cmd --framework-wheel "C:\Packages\universal_codex_tools-0.20.0-py3-none-any.whl" --root "engineering=C:\Engineering\EPLAN Exports"

Dependencies install into .venv; roots, caches, receipts, artifacts and plugin bindings stay under ignored .local. Existing configuration and explicit integration preferences are preserved. --offline uses cached dependencies/build wheels only. Stable plugin preparation requires an explicitly reviewed installation; source setup alone does not publish a checkout-based server connection. No customer roots are inferred. Exit codes and quoted arguments propagate through both CMD wrappers.

Start an explicitly selected configuration through the app-owned entry point:

.\.venv\Scripts\python.exe -m eplan_mcp --config .local/config.json serve

HTTP, shared-host and automatic plugin-install entry points remain unavailable. The plugin is eplan@eplan-local. Its generated stdio binding starts this application's own environment. Reconnect Codex or open a fresh chat after installation. Package/protocol checks do not prove activation in an already-open chat.

Usage

Start with eplan_status and eplan_capabilities. Select named roots using eplan_list_files. Local data files can be included with supported_only=false; drawing extraction filters do not enumerate report formats as supported drawings. Reports are imported through their own tool.

Example eplan_import_reports arguments:

{
  "root_id": "engineering",
  "reports": [
    {"relative_path": "devices.csv", "kind": "devices",
     "field_map": {"tag": "Device designation", "description": "Function text"}},
    {"relative_path": "connections.csv", "kind": "connections",
     "field_map": {"source_tag": "Source DT", "source_terminal": "Source terminal",
                   "target_tag": "Target DT", "target_terminal": "Target terminal"}}
  ],
  "request_id": "import-reviewed-exports-001"
}

Mappings are canonical name to exact exported column/property. No localized labels, numeric property IDs or export scheme are guessed. Exact canonical headers can omit field_map. CSV uses comma by default; TSV uses tab. Set delimiter explicitly for semicolon or pipe exports. UTF-8/BOM and BOM-marked UTF-16 are supported. XML requires exact row_tag (Clark notation for namespaces). Limits: 16 MiB/report, 32 declarations, 100000 combined rows, 200 properties/row, 16000 chars/property. Input XML must have flat rows with unique child properties; DTD/entities are rejected.

The result supplies snapshot_id:

Kinds: devices, connections, plc_io, terminals, cables, parts, network, pages, supplies, supply_links, bridges. Use full structured device tags. Different terminals on a device are not internally bridged. Findings are review observations: repeated tags can represent legitimate multi-function devices. Historical snapshots remain readable when sources change or disappear; always inspect freshness.

For drawings, index bounded batches with eplan_index_project, then use eplan_search_project. Inspect failures and coverage. Use eplan_get_text, eplan_get_entities, eplan_get_pdf_tables and eplan_render_preview for source detail. Drawing-derived electrical snapshots use their own project_id and eplan_build_electrical_project workflow, separate from EPLAN snapshot_id.

Device information and supply feeds

Use eplan_get_device_profile for exact-tag names/descriptions, IP/interface facts, PLC I/O and power/air supply summaries. Use eplan_trace_device_supply to follow explicitly declared terminal relationships upstream to reported source outputs. Electrical and pneumatic domains stay separate. Connections require explicit media and flow direction; internal terminal bridges are never invented. Ambiguity, multiple feeds, conflicting facts, missing ports and incomplete paths remain explicit.

Use eplan_collect_device_evidence to find device text, IP literals, I/O labels and nearby power/air context in indexed drawings. These are candidates with hashes and positions; text proximity does not establish device ownership or feed connectivity. Counts are occurrences, not unique devices.

See device information for the report contract, synthetic example, scope handling and coverage limits.

Independent local readers

These tools work without starting EPLAN or checking out an EPLAN license. They read isolated copies; every response identifies the original source hash. Access/ACE provider operations and archive-member Access reads are disabled before worker dispatch and at the low-level worker. Raw byte/text evidence from MDB files remains available without loading a provider.

For binary reads, byte offsets refer to the source file unless stream_offset selects an inflated stream. Inflated results include the stream's source offset, consumed byte length and inflated hash. Follow scan continuation and result pagination separately. Binary matches can include incidental strings, stale data or window-edge fragments; they are not verified devices, pages, connections or active objects. See local reader details.

For non-ASCII descriptions, explicitly select text_encoding (utf-8, utf-16-le, utf-16-be or cp1252) on eplan_read_binary_text, including inflated streams. Results preserve exact byte offsets and lengths; invalid units split candidates. No character encoding or device ownership is guessed.

CLI

The CLI uses the same service:

.\.venv\Scripts\python.exe -m eplan_mcp --config .local/config.json status
.\.venv\Scripts\python.exe -m eplan_mcp --config .local/config.json import-reports engineering declarations.json
.\.venv\Scripts\python.exe -m eplan_mcp --config .local/config.json snapshot-query ep_HASH devices --limit 20

Synthetic examples are in examples/synthetic; these are custom test reports, not authenticated vendor-generated exports. Configure that directory as a source root to try reports.json.

Python

The Python API uses the same service as the CLI and MCP adapters:

from eplan_mcp.config import Config
from eplan_mcp.exports import ExportService
from eplan_mcp.service import DrawingService

drawings = DrawingService(Config.load(".local/config.json"))
exports = ExportService(drawings)
snapshot = exports.import_reports(
    "engineering",
    [{"relative_path": "devices.csv", "kind": "devices", "field_map": {"tag": "Device designation"}}],
)
devices = exports.query(snapshot["snapshot_id"], "devices", limit=20)

For every state-writing MCP call retain a unique request_id. Inspect eplan_get_transaction after a lost response. Never automatically replace an uncertain request with a new ID or switch routes. Sources and state directories must not overlap. Tool arguments cannot select executables or output paths.

Features

• Independently inspect nested XML records, ELK/ELL project links, ordinary ZIP members, raw binary byte ranges and offset-bound text candidates.

• Discover and inflate checksum-valid zlib streams in binary data with strict resource budgets. Experimental EOD slot partitioning exposes raw headers; it does not infer native object status.

• Import explicitly mapped CSV/TSV/TXT, JSON and flat XML report rows for devices, connections, PLC I/O, terminals, cables, parts, network inventory and pages.

• Keep raw properties, canonical mappings, source SHA-256, row provenance and source freshness.

• Query immutable snapshots, review potential duplicate tags/addresses, trace explicit connection endpoints, compare revisions including duplicate multiplicity, and export verified JSON evidence.

• Inspect PDF/DXF and ODA-converted DWG/DWT/DWS: text, attributes, layers, blocks, dimensions, references, PDF pages/tables with cell coordinates, previews, literal project search and drawing comparisons. Drawing I/O candidates include I/Q and bracketed DI/DO, AI/AO, GI/GO and UI/UO address text. Air candidates include plant-air, feed, preparation, manifold and dump-valve labels. Reviewed drawing records retain original PDF hashes, page quotes and reviewer notes in device facts and supply traces, with original-source freshness checks. Device answers also retain reported feed/sheet references when terminal connectivity is unresolved.

• Analyze derivative drawing electrical devices, PLC I/O, equipment groups and connection evidence. WDP and AutoCAD Electrical reports remain a separate compatibility workflow.

• Bound responses and worker concurrency; coordinate shared state across processes; record durable write receipts and recover lost replies without silently repeating effects.

• Use 50 direct MCP tools. No universal plugin or daemon is required.

Boundaries: ZW1/ZW9/macros remain inventory only. ELK/ELL links and raw/decompressed EOD/EOX evidence can be read independently; full semantic project decoding is not provided. Nested XML can be inspected, while canonical report imports still require flat explicitly mapped rows. No native project editing, save/upgrade, restore, UI highlighting, controller access, network scanning or automatic OCR exists. Export completeness, native check-run results and physical continuity are not established.

Optional app-owned framework

CodexMCPBroker provides the shared Python framework and a separate Windows MCP Service Manager application. The manager is optional and installed independently. EPLAN retains its standalone MCP server, eplan@eplan-local plugin and eplan-analysis skill. No universal plugin or shared-host migration is required. The Python names universal-codex-tools and universal_tools identify the shared library, not a universal plugin selection.

Serving and proxy startup are currently blocked pending backend-tree and shared-owner lifetime acceptance. The following describes the retained design; it is not permission to start the profile.

The direct standalone endpoint is the default. To prepare a dedicated host:

.\.venv\Scripts\python.exe -m eplan_mcp --config .local/config.json framework-prepare --host-state .local/framework-host
.\.venv\Scripts\python.exe -m eplan_mcp --config .local/config.json framework-serve --host-state .local/framework-host

Use --frontend framework --host-state .local/framework-host with scripts/install_plugin.py only after preparing and starting that host. It pins immutable backend bytes and configuration, uses independent host/app receipts, and exposes the current workflow through eplan_get_workflow. Tasks, remote access, OAuth, replication and native UI integration are not enabled by this app.

Development

Releases use one fixed America/New_York YY.MMDD.HHmmss timestamp. Python/plugin package identities remove component leading zeroes; human displays retain the fully padded value. See release stamping and verification. Runtime startup and builds never restamp.

The standalone entry point sets numerical-library pool limits to one before importing NumPy or ezdxf, including in parser workers. A preloaded native-library host is refused. This changes only the app process environment, not user/system settings. Configured limits and measured OS thread/ commit counts are separate evidence; changed runtimes still require validation.

eplan_capabilities.feature_profiles reports enabled/tested features and concrete blockers. Feature profiles cover progress, cooperative cancellation, private report resources, bounded modern discovery caching and the unchanged transient legacy backend.

The stable packaged skill reads the current workflow and supporting references through eplan_get_workflow on the selected route. Both compatible endpoints also publish the same data through Skills-over-MCP. Runtime guidance describes explicit live publication, stale-reference checks and the separate native host reload boundary.

The direct server and optional app-owned framework host report to the existing Windows MCP Service Manager through framework 0.20.0. No manager installation or broker registration is performed here. Status uses cached package/plugin metadata and per-instance activity; availability remains unknown without an update source. Restart stays disabled: EPLAN has no surviving process supervisor or cross-chat quiescence fence for pending operations and uncertain receipts. New server processes report automatically; existing chat processes require their normal reconnect to load this integration. See service management for the restart boundary and verification.

See implementation and developer guide, VERIFICATION.md and native integration boundaries. Run tests before committing; packages use an explicit source allowlist and byte manifest. Keep private engineering content and runtime state out of Git and distributable artifacts.

Maintainers

votecoffee. Issues and contributions: use this repository's GitHub issues.

Contributing

Questions and bug reports are welcome in GitHub issues. Pull requests are accepted. Keep operations in the shared service layer, add relevant synthetic tests, run the checks in VERIFICATION.md, and update documentation and the byte manifest. Never submit customer projects, real reports, private paths, credentials or local setup receipts. Keep organization-specific standards, validation rules and project interpretations in the corresponding engineering service, using this server's generic source-bound evidence. Use repository-root .local/ for private working material; it is ignored by Git and excluded from release packages. Public examples and fixtures must be synthetic or explicitly redistributable.

License

MIT © 2026 votecoffee. See NOTICE.md for attribution.