Utility Network MCP README

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 so an agent answers like an experienced UN implementer — and connects agents to a live network through MCP.

See it in action

Ask the questions you'd ask a senior UN consultant:

"Apply Asset Package keeps failing when I add gas to our water UN. Pro 3.5, Enterprise 11.3."

→ Troubleshooting answer walking the four prerequisites that cause most failures (maps closed, topology disabled, Pro/UN version match, both owners on DEFAULT), and why the tool is additive.

"Write the REST request for an isolation trace from this main at the midpoint, stopping at operable valves, on version crew1.outage."

→ Complete request with percentAlong, filter barriers and gdbVersion, checked by a validator for the mistakes that make traces silently return nothing.

"Our dirty areas show Status 1, 9 and 40 — which ones matter?"

→ Decoded bitmask: 1 is a pending edit, 9 and 40 carry feature and subnetwork errors, with the next action for each.

"Hook Claude up to our electric UN so dispatch can ask what's downstream of a breaker."

→ Route recommendation (Esri's MCP beta vs. custom GP tools vs. this MCP server), tool list, auth, write-safety rails and licensing.

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.

MCP server — see mcp-server/README.md:

pip install utility-network-mcp

What the skill knows

Every answer follows a defined format (how-to, troubleshooting, code, MCP design, 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 · mcp)]
    S -->|runs instead of guessing| T[scripts/<br/>status decoder · association codes<br/>trace request checker]
    S --> A[Structured answer<br/>with version caveats]
    M[utility-network-mcp] -->|REST| U[(Your ArcGIS Enterprise<br/>Utility Network)]
    A -. "connect an agent" .-> M

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, mcp …)
  scripts/                                         helpers + MCP server template
  evals/                                           test prompts and trigger tests
mcp-server/                                        utility-network-mcp Python package
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.