# Underground Utility Permit Review — MCP Server

An MCP server that gives Claude direct, read-only access to a portfolio of pending
excavation permit reviews and the underground utility lines near each one.

The [permit review dashboard](https://erincheong.github.io/permit-review-dashboard/) answers
these questions for a human looking at a screen. This answers them for an agent — same data,
same scoring rules, no interface.

**Zero dependencies.** `node server.js` is the entire install.

---

## Why build this

A dashboard assumes a person sits down and browses. That works until the question is
*"across every permit I have open, what's about to hurt someone?"* — at which point browsing
twenty-four cases is the wrong shape of work.

The interesting shift is that **the tools aren't a mirror of the database.** There is no
"conflicts" table; `find_utility_conflicts` exists because triage across a portfolio is a real
question a reviewer asks and a screen answers badly. Designing the tool boundaries around
questions rather than tables is most of the product work here.

## What Claude can do with it

```
You:    Which pending permits have unverified gas lines within 5 feet of the dig?

Claude: [find_utility_conflicts · utility_types=["Gas line"] · max_distance_ft=5]

        Two, and both are high risk:

        Firestone Blvd. & Studebaker Rd. — 2 in gas main, 2.4 ft from the excavation,
        Level D. That's a county record with no independent verification, so the
        position is approximate and the line is well inside strike range.

        Artesia Blvd. & Carpintero Ave. — 2 in gas line at 4 ft, Level C. The county
        record and the independent detection disagree on diameter, so neither can be
        relied on until someone confirms it.

        I'd pothole both before either permit is signed.
```

Other things it handles well:

- *"Summarise my permit portfolio risk by city."*
- *"I have one crew for one day. What should they pothole?"*
- *"Walk me through PRM-1001 and tell me what's unresolved."*
- *"How much of the county record have we actually corroborated?"*

## Install

Requires Node 18+. Nothing to `npm install`.

**1. Point Claude Desktop at it.** Edit the config file:

- macOS `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "utility-permits": {
      "command": "node",
      "args": ["/absolute/path/to/utility-mcp-server/server.js"]
    }
  }
}
```

The path must be absolute — Claude Desktop doesn't run from your project directory.

**2. Restart Claude Desktop.** Fully quit it; closing the window isn't enough.

**3. Confirm.** The tools appear in the tool menu. Ask *"what permit tools do you have?"*

## The tools

| Tool | The question it answers |
|---|---|
| `search_permits` | Which cases match this filter? |
| `get_permit` | What's the full review for this one case? |
| `find_utility_conflicts` | Across everything, what's dangerous to dig near? |
| `portfolio_summary` | How are we doing overall, and where is risk concentrated? |
| `recommend_verification` | Given a limited field budget, what do we pothole first? |

Every tool is annotated `readOnlyHint: true`. **Nothing here can approve a permit or dispatch
a crew.** That's a deliberate boundary, not an unfinished feature: an agent that can sign off
on an excavation without a human in the loop is a liability, and the fastest way to lose a
utility customer's trust is to build one.

### Results link back into the dashboard

Every result carries a deep link to the human UI — down to the specific utility line that
triggered it:

```
https://erincheong.github.io/permit-review-dashboard/#permit=PRM-1001&line=4&set=PRM-2008,PRM-1001&label=Gas+lines+within+5+ft
```

That opens the permit with the offending line already expanded and highlighted, and **Back**
returns to the permits from the query rather than the full portfolio.

The agent is a second door onto the same data, not a replacement for it. It's good at "across
everything, what's dangerous." It's bad at "let me see the county record with my own eyes." So
it hands off to the thing that's good at that, and remembers where you came from.

Hash routing rather than query strings, so the links also work against a copy opened straight
off the filesystem. Point them elsewhere with `UTILITY_DASHBOARD_URL`.

### Provenance travels with every result

Every utility line comes back carrying its ASCE 38-02 quality grade, what that grade means in
plain language, and where the record came from. The server's `instructions` tell the model to
keep them attached:

> A Level D record is not a known position — it is a decades-old drawing whose source
> disclaims any guarantee of accuracy, and treating it as fact is how people get hurt.

This matters more for an agent than for a dashboard. A human looking at a red badge infers
uncertainty. A model summarising into prose will flatten "county record, unverified, position
approximate" into "there's a gas line at 4 feet" unless the data fights back.

### One scoring module, two surfaces

`src/scoring.js` holds the risk rules, and the dashboard uses the same ones. If they diverged,
a reviewer and an agent could look at the same permit and disagree about whether it's safe to
approve — which is worse than either being wrong alone. The test suite asserts the server's
numbers for the shared corridors match what the dashboard displays.

## Protocol notes

This is a **dual-era** server, written directly against the spec rather than an SDK.

MCP changed its negotiation model in revision `2026-07-28`: instead of an `initialize`
handshake establishing a session, every request carries its own protocol version in `_meta`
and the server accepts or rejects each one independently. Older clients still open with
`initialize`. This server speaks both:

| Client | Flow |
|---|---|
| Modern (`2026-07-28`) | `server/discover` → `tools/call` with `_meta` on every request |
| Legacy (`2025-11-25`, `2025-06-18`) | `initialize` → `notifications/initialized` → `tools/call` |

An unsupported version gets `UnsupportedProtocolVersionError` (`-32022`) listing what the
server does support, so the client can retry instead of guessing.

**Transport rule worth knowing:** stdio MCP is newline-delimited JSON, and the server must
write *nothing* to stdout that isn't a valid MCP message. A stray `console.log` corrupts the
stream and the server appears to hang — it's the single most common way these break. All
logging here goes to stderr, and there's a test asserting stdout stayed clean.

Writing the protocol by hand instead of importing the SDK was a deliberate choice: it's about
250 lines, and it means there's nothing in this repo I can't explain.

## Tests

122 checks, run against a **real spawned server process** speaking actual JSON-RPC over stdio —
nothing stubbed.

```bash
npm test          # or: node tests/verify_server.js
```

Covers both handshakes, version rejection, every tool's behaviour and schema conformance,
error handling for unknown tools and bad arguments, malformed-JSON resilience, the rule that
notifications are never answered, stdout hygiene, determinism across processes, and
cross-artifact agreement with the dashboard.

The schema validator is hand-written (~30 lines) so the test suite has no dependencies either.

## Data

The first six permit cases are real corridors from the **LA County Substructure Grid Map**
(County of Los Angeles Open Data), carried over verbatim from the dashboard. The other
eighteen are **synthetic**, generated from a fixed seed so the portfolio is big enough for
search and filtering to mean something.

Every case carries a `dataSource` field saying which it is. An agent answering questions about
this data should never have to guess whether a record is real — and neither should anyone
watching a demo.

Per the county's own disclaimer, it makes no warranty as to the accuracy, timeliness, or
completeness of the data, and recommends utility research be conducted under the supervision
of a licensed civil engineer. That disclaimer is why county-only records are graded Level D
by default.

## Known limitations

- **No spatial geometry.** Distances are precomputed scalars, not a real GIS layer. A
  production version sits on PostGIS and takes a bore path, not a permit ID.
- **Read-only by design**, so there's no write path to argue about yet. When there is, it
  should require explicit human confirmation rather than a tool annotation.
- **No auth.** stdio means it runs as the local user with their file permissions. A hosted
  version needs real per-customer access control, since permit and utility data is
  commercially sensitive and sometimes security-sensitive.
- **Consequence weights are asserted, not derived.** Gas at 10× and fiber at 1× is a judgment.
  In a real deployment those come from the customer's own liability exposure and would differ
  between a gas utility and a fiber contractor.