PCM MCP

An MCP server for ABB / Hitachi Energy PCM600 (Protection and Control IED Manager).

No such server exists publicly — this is a from-scratch build. Status: Phases 1-4 complete, 24 tools working end-to-end over stdio against PCM600 2.14.

Tier 0 — offline analysis (no PCM600 install needed)

Reads and reasons about IEC 61850 SCL files (.scd, .icd, .iid, .cid, .ssd) already exported from PCM600, and .apcmp project archives.

Tool	Purpose
scl_summary	Header, substation/voltage-level/bay tree, inventory counts
scl_list_ieds	Every IED with manufacturer, type, config version, IP addressing
scl_get_ied	One IED in detail: logical devices, logical nodes, datasets, control blocks
scl_list_datasets	Datasets and their FCDA members
scl_list_goose	GOOSE publishers + addressing; flags publishers with no GSE address
scl_list_reports	Report control blocks: buffering, trigger options, timing
scl_list_addresses	IP addressing per access point; flags duplicate IPs / APPIDs / MACs
scl_check_goose_bindings	Traces publishers → subscribers; catches unsubscribed publishers, unknown IEDs/control blocks, and subscriptions to signals the dataset doesn't carry
scl_validate	Referential integrity — dangling dataset refs, FCDAs pointing at missing logical nodes, Communication/IED mismatches, duplicates. Optional xsd_path for schema validation
scl_diff	Structural, model-level diff of two SCL files across 11 categories
apcmp_summary	Inspect a .apcmp project archive without importing it — project name, IED inventory, and whether the required connectivity packages are installed
apcmp_logic	Recover ACT application logic from a .apcmp without importing it — worksheets, signals, blocks; flags naming clashes and device groups where one member lacks what its siblings have
pcm_probe_archive	Characterise any PCM600 archive without assuming its layout — for file kinds not yet verified against a real sample (.apcmi, .apcmt)

scl_diff compares the parsed model, not the text. PCM600 reorders elements and rewrites attributes on every export, so a text diff of two SCDs is unusable — a one-setting change can look like a thousand-line rewrite.

scl_validate's XSD support is opt-in: the IEC 61850-6 schema is a licensed IEC deliverable and isn't bundled here (nor shipped with PCM600), so pass your own copy via xsd_path if you want it. The rule-based checks are the primary value — XSD only catches syntax.

apcmp_logic reads the ACT logic sheets, which PCM600 stores as XML inside the project database and which survive as recoverable text. That means application logic can be reviewed even when the connectivity package needed for an import is missing.

Its asymmetry checks are the useful part, because they find the defects that are invisible when reading sheet by sheet — each sheet looks self-consistent:

• Device groups — a concept present for some members and not others (on a real 3-breaker scheme: B3 lacked the fail-to-open/close and breaker-failure supervision B1 and B2 both had).
• Source pairs — an A-side signal with no B-side counterpart, and vice versa. In a two-source transfer scheme this is where inconsistent failure handling hides.
• Transfer direction — concepts tagged for one direction only. Where one direction carries an explicit _BA/_AB suffix and the other reuses untagged names, the second direction was typically added as a parallel copy rather than the original logic being generalised.
• Letter-transposition typos — SRCA_AVAIL vs SCRB_AVAIL, where SRC silently became SCR. Deliberately narrow: it will not flag FTC/FTO (different concepts) or BA1/BA4 (legitimate numbering), because a noisy detector is worse than none in a safety review. Limits are reported in every result — block-to-block wiring and setting values are not recoverable, so absence in the output is not proof of absence in the project.

apcmp_summary is the import pre-flight. PCM600's import silently ignores IEDs whose object type it does not recognise, so importing a project whose connectivity package is missing can discard IEDs with no error. Run it first. Note the archive's project name (what -p takes) is not the database name — the tool reports both.

Resource pcm600://config reports resolved config and which tiers are available.

Tier 1 — drives the PCM600 CLI (needs PCM600 installed)

All read-only with respect to the PCM600 project database.

Tool	Purpose
pcm_cli_info	Detected install, SQL version, connectivity packages, and a live reachability check
pcm_export_scd	Export a project's SCD
pcm_export_parameters	One IED's parameters to .csv / .xrio (by technical key)
pcm_export_bulk_parameters	Every IED's .xrio into a directory — needs no technical key
pcm_export_ied	One IED as .apcmi
pcm_export_project	Whole project as .apcmp
pcm_validate_parameters	List deviations a parameter import would make. Validates only

Tier 1 degrades cleanly: if PCM600 isn't detected, these report why and the offline tools keep working.

It will never talk to a physical relay. PCM600Cmd does expose eight commands that open a connection to a live IED — write-ied, read-ied, and their -under-bay / -under-voltage-level / -under-substation variants. All eight are on a hard denylist in cli.py: the wrapper refuses to build the argv, and no setting enables them. --allow-unsigned-file is refused too. See DESIGN.md §6.

Success is never inferred from the exit code. PCM600Cmd returns 0 even on failure. Outcome comes from parsing its log output and verifying the output artifact exists and is non-empty.

Existing export files are never silently overwritten — pass overwrite=true deliberately.

Tier 1 — mutating (off by default)

Tool	Purpose
pcm_import_scd	Import an SCD. Counts IEDs before, re-exports after, and reports any that vanished
pcm_import_parameters	Import one IED's settings. Runs validate-parameters first and aborts if it fails
pcm_import_bulk_parameters	Bulk .xrio import. States that no per-file pre-flight exists
pcm_import_ied	Import an .apcmi/.apcmt into a bay, voltage level or substation

All four require PCM_MCP_ALLOW_WRITES=1 and confirm=true — two independent gates — and snapshot the project before touching it.

The snapshot is not rollback. PCM600 has no CLI command to restore a project; an .apcmp can only be re-imported by hand in the GUI. Every mutating tool says so in its own output.

The IED-loss verification on pcm_import_scd exists because PCM600's import silently ignores IEDs whose object type it does not recognise. A missing connectivity package makes IEDs disappear with no error, so the tool round-trips the SCD back out and compares rather than trusting silence.

Setup

Requires Python ≥3.12 (built and tested on 3.14).

cd C:\theWork\pcm-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

PCM_MCP_WORKSPACE is required — it is the allowlist root for every path argument, so there is no safe default and the server refuses to start without it.

Var	Meaning	Default
PCM_MCP_WORKSPACE	Allowlisted root for all file access	required
PCM600_BIN	PCM600 bin dir containing PCM600Cmd.exe	auto-detected
PCM_MCP_ALLOW_WRITES	1 enables mutating tools (none exist yet — Phase 4)	0
PCM_MCP_CLI_TIMEOUT	Seconds per PCM600Cmd call	600
PCM_MCP_AUDIT_LOG	JSONL audit path	$WORKSPACE/.pcm-mcp-audit.jsonl

Register with Claude Code

{
  "mcpServers": {
    "pcm600": {
      "command": "C:\\theWork\\pcm-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "pcm600_mcp.server"],
      "env": { "PCM_MCP_WORKSPACE": "C:\\theWork\\pcm-mcp" }
    }
  }
}

Tests

.\.venv\Scripts\python.exe -m pytest -q            # 203 passed, 13 skipped
.\.venv\Scripts\python.exe scripts\smoke_stdio.py  # live stdio handshake

Most skips are the integration suite (below) plus the symlink-escape test, which needs Windows Developer Mode. The smoke script drives the real transport: initialize → tools/list → tools/call → path-confinement refusal.

Integration tests against a real PCM600

tests/test_integration_cli.py drives the installed PCM600Cmd.exe for real. It skips cleanly when prerequisites are absent, so it is safe to run anywhere.

Three tests need only PCM600 installed and run automatically — CLI reachability, the IED-communication denylist against the real binary, and the regression guard for exit-code-0-on-failure. The rest need a project:

$env:PCM_MCP_TEST_PROJECT = "SCRATCH_MCP_TEST"          # a SCRATCH project, never production
$env:PCM_MCP_TEST_TECHNICAL_KEY = "AA1J1Q01A1"          # optional; unlocks per-IED tests
.\.venv\Scripts\python.exe -m pytest tests/test_integration_cli.py -v -rs

Mutating tests additionally require PCM_MCP_ALLOW_WRITES=1. Point these at a scratch project only — a bad import can only be undone by a manual GUI import of the snapshot.

test_export_ied_then_probe_the_format is the one to run first once a project exists: it produces a real .apcmi and prints its structure, which settles whether the .apcmp readers can be reused for IED exports and templates.

Layout

src/pcm600_mcp/
  server.py        MCP wiring, the twenty-four tools
  cli.py           PCM600Cmd wrapper: denylist, log parsing, artifact verification
  config.py        env resolution, PCM600 + connectivity-pack detection, tier availability
  safety.py        path confinement, write gating, audit log
  apcmp.py         .apcmp project-archive reader (ZIP + metadata sidecars)
  act.py           ACT logic recovery from the project database inside a .apcmp
  scl/model.py     dataclass model of an SCL document
  scl/parse.py     namespace-agnostic lxml reader
  scl/checks.py    binding tracing + referential-integrity rules
  scl/diff.py      structural diff
tests/
  fixtures/synthetic.scd           clean-ish 2-IED substation
  fixtures/synthetic_modified.scd  one change per diff category
  fixtures/problems.scd            duplicate IPs/APPIDs/MACs, orphan address
  fixtures/bindings.scd            all four GOOSE binding failure modes
  fixtures/invalid.scd             eleven referential-integrity failures
  test_integration_cli.py          live PCM600 round-trips; skips without a project
scripts/smoke_stdio.py     end-to-end transport check
docs/                      DESIGN.md, PLAN.md, DISCOVERY.md, cli-help.txt

Documents

File	What
docs/DESIGN.md	Design, tool surface, safety model, ~30 cited references
docs/PLAN.md	Phased plan and status
docs/DISCOVERY.md	Phase 0 results: real CLI contract, .apcmp format, traps
docs/cli-help.txt	Verbatim PCM600Cmd help, captured from the install

Current state

Phase 0  Discovery ............ MOSTLY DONE - CLI captured; scratch project needs GUI
Phase 1  Scaffold + SCL core .. DONE
Phase 2  Analysis / diff ...... SCL half DONE; parameter CSV/XRIO readers deferred (no sample)
Phase 3  CLI wrapper .......... DONE - cli_info verified live; 6 tools await a project to test
Phase 4  Mutating tools ....... DONE - 4 import tools, two gates, snapshot + verify
Phase 5  Packaging ............ partial (pyproject + .mcp.json snippet done)
Phase 6  Test & harden ........ partial (203 tests + stdio smoke + live integration suite)

Next action

Two things are blocked on data, not code:

1. A project in the local PCM600 database. Six of the seven Tier 1 tools need one to be tested end-to-end (pcm_cli_info is already verified live, since export-system-info needs no project). There is no create-project CLI command, so this needs the GUI.
2. A parameter .csv / .xrio sample to build the deferred params_* tools against. One read-only command supplies it and needs no technical key: export-bulk-parameters -p "<project>" -d "<dir>".

Also still untested: whether PCM600Cmd works with the PCM600 GUI open (DISCOVERY.md §0.7).