io.github.sgdev279/utility-network-mcp

Give Claude and other AI agents working knowledge of the Esri ArcGIS Utility Network.

Utility Network questions are hard for general-purpose AI: the answer depends on the dataset version, the deployment, which API you're in, and a long list of ordering rules and gotchas. This project packages that knowledge as a Claude Agent Skill so an agent answers like an experienced UN implementer.

The skill is 29 curated reference files, answer templates, helper scripts and evals. It works in Claude.ai, Claude Code and any agent that reads Agent Skills.

See it in action

Real questions with the details a consultant would be given. Full walk-throughs with captured output are in docs/EXAMPLES.md.

1. Apply Asset Package fails when adding gas to a water UN

Pro 3.5, Enterprise 11.3. WaterUN already has the Water domain network. Two maps open, connected as gis_editor (owner is wateradmin), portal login jsmith, version wateradmin.crew1, topology enabled for dispatch.

Finds five violated prerequisites at once (maps open, topology enabled, wrong database user, wrong portal user, not on DEFAULT), gives the fix order, and confirms that applying Gas does not wipe Water because the tool is additive.

2. Isolation trace at the midpoint of main {8F2A6C1E-...} on branch crew1.outage

Stop at operable Isolating valves, domain Water, tier Pressure, someone else has the version open.

Produces a complete request (percentAlong: 0.5, filterBarriers, string values, no sessionId), and a validator checks it. On a request with typical mistakes the validator reports seven problems, such as a percent along of 50, a start with no terminal or percent, and a misspelled tierNam.

3. Dirty areas: Status 1 x 41,220, 9 x 312, 8 x 5, 40 x 18, and validate "succeeded"

$ python scripts/decode_dirty_status.py 9 8 40
9: feature inserted or updated; feature error  [edit + error]  ->  Validate will evaluate it. ...
8: feature error  [error only]  ->  Validate will IGNORE this row. ... fix it by EDITING the feature ...
40: feature error; subnetwork error  [error only]  ->  Validate will IGNORE this row. ... run Update Subnetwork ...

Rows 8 and 40 have no edit bit, so validate ignores them: edit the feature, then validate.

How these were tested, and where they fell short, is in docs/TESTING.md.

Quick start

Claude Code

claude plugin marketplace add sgdev279/esri-utility-network-skill
claude plugin install utility-network@esri-utility-network

Claude.ai / Claude desktop app — download utility-network.skill from the latest release and add it to your skills.

Any skills-aware agent — copy plugins/utility-network/skills/utility-network into its skills folder.

What the skill knows

Every answer follows a defined format (how-to, troubleshooting, code, concept, cross-API translation), states which versions it applies to, and flags anything unverified.

How it's built

flowchart LR
    Q[User question] --> S[SKILL.md<br/>workflow · disambiguation · answer formats]
    S -->|loads only what's needed| R[(references/<br/>pro-help · rest-api · js-api<br/>pro-sdk · arcpy)]
    S -->|runs instead of guessing| T[scripts/<br/>status decoder · association codes<br/>trace request checker]
    S --> A[Structured answer<br/>with version caveats]

The skill uses progressive disclosure: Claude reads the short SKILL.md first, then pulls in only the reference files a question needs, so broad coverage doesn't cost context on every question.

Help improve it

The skill is designed to grow. You can contribute without writing code:

• Share knowledge — a gotcha you hit, a fix from Esri Community, a doc page the skill should know → open an "Add UN knowledge" issue
• Report something wrong or outdated → open a correction
• Write a reference file → python tools/new_reference.py scaffolds one in the house format; CI checks it

Details in CONTRIBUTING.md. Planned content is tracked in the roadmap, and content freshness in docs/FRESHNESS.md.

Repository layout

plugins/utility-network/skills/utility-network/   the skill
  SKILL.md                                         entry point: workflow, routing, answer formats
  references/                                      topic files (pro-help, rest-api, js-api, pro-sdk, arcpy …)
  scripts/                                         helper scripts
  evals/                                           test prompts and trigger tests
tests/                                             tests for the helper scripts
examples/                                          sample trace requests
tools/                                             maintainer tools (scaffold, lint, freshness)
knowledge-inbox/                                   raw notes waiting to be turned into references
docs/                                              roadmap, freshness report, assets
.github/                                           CI, release, issue forms

Disclaimer

Independent community project — not affiliated with or endorsed by Esri. ArcGIS and ArcGIS Utility Network are trademarks of Esri. Reference content is written in our own words from public Esri documentation; each file lists its sources and review date. Always confirm version-specific behaviour against Esri's documentation before production changes.

Author

Built by Sayanta Ghosh (@sgdev279). If this helps your utility GIS work, a ⭐ helps others find it.

Licensed under the MIT License.