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.

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.

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)

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.

Related MCP server: Semantic Model MCP Server

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.

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

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