ugrc-mcp
CLAUDE.md0 starsChanged 6 months agoMITView on GitHub
v0.2 (released 2026-05). 33-tool MCP server: 20 SGID list_<category> discovery tools, 3 generic discovery/search tools (list_capabilities, describe_layer, find_layer), 3 query primitives (arcgis_query, arcgis_aggregate, arcgis_raw), and 7 mapserv wrappers. docs/plan.md is the authoritative design doc — read it end-to-end before making non-trivial changes. docs/epic-v0.2.md + docs/stories/* track the rollout. spec.md is the v0.1 contract; superseded by plan.md for tool shapes, but still useful for the geometry/error invariants. The 33-tool surface splits cleanly into discovery and action, layered over three coverage tiers.
- Reads credentials
- Installs packages
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
No auth required for any SGID FeatureServer.
- Very specific: line 55
Every discovery tool's description ends with: *"Pair with arcgis_query / arcgis_aggregate to pull data.
- Very specific: line 77
Write ops (applyEdits), image rendering (export), other vendors (PVWatts/NSRDB/CropScape/HIFLD/SSURGO — each is its own MCP), feature-data …
- Distinctive: line 97
No test suite yet. When tests land, document the runner and how to run a single test here.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Repository state
v0.2 (released 2026-05). 33-tool MCP server: 20 SGID list_<category> discovery tools, 3 generic discovery/search tools (list_capabilities, describe_layer, find_layer), 3 query primitives (arcgis_query, arcgis_aggregate, arcgis_raw), and 7 mapserv wrappers. docs/plan.md is the authoritative design doc — read it end-to-end before making non-trivial changes. docs/epic-v0.2.md + docs/stories/* track the rollout. spec.md is the v0.1 contract; superseded by plan.md for tool shapes, but still useful for the geometry/error invariants.
Stack
- TypeScript on Cloudflare Workers.
@modelcontextprotocol/sdk+ Cloudflare Agents SDK (agents/mcp) for streamable HTTP transport. TheMcpAgentbase class puts MCP session state in a Durable Object — that's transparent; the business logic stays stateless. - HTTP: native
fetchwrapped withAbortSignal.timeout(30_000)and a 5xx retry helper (src/arcgis-client.ts,src/tools/hub-search.ts,src/tools/mapserv.tseach share the same shape). Nohttpx/axios. - Geometry: hand-rolled GeoJSON↔esriJSON for Polygon/MultiPolygon in
src/geometry.ts. Don't reach for@turf/turf. describe_layercache: module-levelMap<string, unknown>insrc/tools/generic.tskeyed by resolved layer URL. Per-isolate, best-effort. Promote to KV/Cache API only if measured latency calls for it.- mapserv auth:
UGRC_API_KEYis a Worker secret (wrangler secret put), not avar. The 7 mapserv tools short-circuit with a clear "set UGRC_API_KEY" message if it's unset. Mapserv keys are issued with a Referer allow-list — the Worker sendsUGRC_API_REFERER(a regularvarinwrangler.jsonc) on every mapserv call. - No auth required for any SGID FeatureServer. If the server ever ships outside the Watts-for-Water context, gate the endpoint behind Cloudflare Access rather than baking auth into individual tools.
Layout:
src/
index.ts # Worker entrypoint — /mcp + /sse routes
mcp.ts # McpAgent + registration wiring + INSTRUCTIONS string
arcgis-client.ts # shared arcgisJson() + applySpatialFilter()
geometry.ts # GeoJSON ↔ esriJSON
env.d.ts # ambient augmentations for Cloudflare.Env (secrets)
registry/
types.ts # SgidRegistry / SgidLayer / Org shapes
orgs.ts # hand-maintained — org handle → AGOL ID + url_base
sgid.ts # AUTOGENERATED by scripts/sync-sgid-registry.ts
tools/
generic.ts # describe_layer + list_capabilities + per-isolate cache
sgid.ts # factory — emits one list_<category> per SGID category
hub-search.ts # find_layer (live ArcGIS Hub Search v1)
arcgis.ts # arcgis_query / arcgis_aggregate / arcgis_raw
mapserv.ts # 7 mapserv wrappers
scripts/
sync-sgid-registry.ts # one-shot fetch + transform of agrc/sgid-index
enrichment.ts # hand-curated per-layer gaps/caveats/useful_fields
docs/
plan.md # authoritative v0.2 design doc
epic-v0.2.md # epic-level scope
stories/ # per-story rollout notesArchitecture: what to internalize before writing code
The 33-tool surface splits cleanly into discovery and action, layered over three coverage tiers.
Discovery / action split
- Discovery tools are catalog browsers:
list_<category>(×20),list_capabilities,describe_layer,find_layer. They return curated metadata (freshness, useful fields, gaps, caveats) so the model can pick the right layer before it commits to a query. - Action tools pull data:
arcgis_query,arcgis_aggregate,arcgis_raw(and the 7 mapserv tools for non-FeatureServer endpoints). The query primitives take EITHER{ org, layer }(cataloged Tier 1) OR{ url }(anything else).
Every discovery tool's description ends with: "Pair with arcgis_query / arcgis_aggregate to pull data. If the layer you need isn't here, try find_layer({ query })." The redundancy is deliberate; LLMs respond to direct in-context instructions.
Three coverage tiers
- Tier 1 — categorized. ~235 SGID layers across 20 categories, generated into
src/registry/sgid.tsfrom agrc/sgid-index, enriched with hand-curated facts inscripts/enrichment.ts. Reached vialist_<category>thenarcgis_query({ org, layer, ... }). - Tier 2 — uncategorized UGRC long tail. ~528 UGRC services not in Tier 1. Reached via
find_layer({ query })(live ArcGIS Hub Search), thenarcgis_query({ url, ... })with the URL the search returned. - Tier 3 — outside UGRC. County / federal / tribal portals. Reached via
arcgis_raw({ url, params }). v0.3 federation will register more orgs insrc/registry/orgs.ts.
Cross-cutting invariants
- Geometry I/O is always GeoJSON in WGS84. UGRC layers are stored in EPSG:26912 (UTM 12N NAD83); ArcGIS handles the transform server-side. For sub-meter precision, consider
datumTransformation=4485oninSR— non-critical at the polygon scale we operate on. - ArcGIS errors return HTTP 200 with
{"error": {"code", "message"}}.arcgisJson()detects this shape and re-raises as a tool error preserving code+message. A naiveresponse.raise_for_status()will miss them. - Geometry-too-large is a common failure mode when passing state-sized polygons as a spatial filter.
arcgis_querycatches it and recommendsbboxin the error message. spatial_relationshipmaps to ArcGISspatialRelcodes — translateintersects/contains/within/crosses/touches/overlaps/envelope_intersectsrather than exposing the rawesriSpatialRel*enum.- Don't auto-paginate features.
arcgis_queryreturnsexceeded_transfer_limit+next_offsetand trusts the model to chain.arcgis_aggregatedoes page internally because group counts are bounded.
Layer registry note
src/registry/sgid.ts is autogenerated — never hand-edit. To refresh, run npm run sync-sgid-registry. Per-layer overrides (useful_fields, gaps, caveats, time_field, layer_key_override) live in scripts/enrichment.ts and are applied at sync time. UGRC has historically renamed services — if a URL 404s after a sync, check gis.utah.gov/products/sgid/... rather than guessing.
Out of scope for v0.2 (don't drift into these)
Write ops (applyEdits), image rendering (export), other vendors (PVWatts/NSRDB/CropScape/HIFLD/SSURGO — each is its own MCP), feature-data caching, Open SGID Postgres direct access, scheduled registry sync (still manual), federation beyond UGRC (county/federal/tribal portals — v0.3 work tracked in MEMORY.md).
Acceptance test
The five canonical conversations from docs/plan.md §"Acceptance criteria" (A1–A5): irrigated-alfalfa aggregation, reverse-geocode, parcel polygon overlay, Stratos honest-gaps query (cadastre owner names → county-held), and the springs long-tail (find_layer → NHD Springs). If a fresh MCP Inspector agent walks A1–A5 without writing Python/curl, v0.2 is doing its job.
Commands
npm install # first-time setup
npm run cf-typegen # regenerate worker-configuration.d.ts from wrangler.jsonc bindings
npm run sync-sgid-registry # refresh src/registry/sgid.ts from agrc/sgid-index
npm run dev # local wrangler dev — MCP at /mcp (streamable HTTP), legacy SSE at /sse
npm run typecheck # tsc --noEmit
npx wrangler secret put UGRC_API_KEY # one-time per environment; required for the 7 mapserv tools
npx wrangler deploy # ship to Cloudflare (account from `wrangler login`)
npx wrangler tail # stream production logs
npx @modelcontextprotocol/inspector@latest # local MCP client for poking tools — point it at the dev URL + /mcpNo test suite yet. When tests land, document the runner and how to run a single test here.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

