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 0.1.0. The repository uses EPlanMCPServer; the Python distribution uses the normalized package name eplan-mcp-server and imports as eplan_mcp.

Table of Contents

• Background

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

Install

Dependencies

Python 3.11+; Windows is the primary target. Python 3.13 is used for validation. ODA File Converter is optional and required only for DWG/DWT/DWS. DXF, PDF and report analysis work without it.

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.17.0-py3-none-any.whl
SHA-256 6387265e9353f69f2dd767e4431ab2c7f6df40dd090118592a01daa3b5946c6b
Source commit 87157f88de4a5320d2712224216b1e6f18a0ec8d

.\InstallAndRun.cmd --framework-wheel C:\Packages\universal_codex_tools-0.17.0-py3-none-any.whl --root "engineering=C:\Engineering\EPLAN-Exports" --install-only

Dependencies install into .venv; roots, caches, receipts, artifacts and plugin bindings stay under ignored .local. Existing configuration and explicit integration preferences are preserved. The initial setup refreshes the standalone Codex plugin by default. To skip that integration use --codex-integration none. No customer directories are automatically selected.

After first setup, double-click InstallAndRun.cmd for loopback HTTP at port 8816, or:

.\InstallAndRun.cmd --stdio
.\.venv\Scripts\python.exe scripts\install_plugin.py --mode standalone

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. Native project 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 → 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. 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.

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

• 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, previews, literal project search and drawing comparisons.

• 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 38 direct MCP tools, or the optional app-owned shared-framework host. No universal daemon required.

Boundaries: ELK/EDB/ZW1/ZW9/macros are inventory only. Arbitrary native EPJ schemas are not decoded; only declared flat XML rows can be read. 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

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

See VERIFICATION.md for repeatable checks 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.