agentleFS
cwoodcoxcwoodcox/ugrc-mcp/CLAUDE.md

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
  1. Distinctive:

    No auth required for any SGID FeatureServer.

    line 16
  2. Very specific:

    Every discovery tool's description ends with: *"Pair with arcgis_query / arcgis_aggregate to pull data.

    line 55
  3. Very specific:

    Write ops (applyEdits), image rendering (export), other vendors (PVWatts/NSRDB/CropScape/HIFLD/SSURGO — each is its own MCP), feature-data …

    line 77
  4. Distinctive:

    No test suite yet. When tests land, document the runner and how to run a single test here.

    line 97

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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. The McpAgent base class puts MCP session state in a Durable Object — that's transparent; the business logic stays stateless.
  • HTTP: native fetch wrapped with AbortSignal.timeout(30_000) and a 5xx retry helper (src/arcgis-client.ts, src/tools/hub-search.ts, src/tools/mapserv.ts each share the same shape). No httpx/axios.
  • Geometry: hand-rolled GeoJSON↔esriJSON for Polygon/MultiPolygon in src/geometry.ts. Don't reach for @turf/turf.
  • describe_layer cache: module-level Map<string, unknown> in src/tools/generic.ts keyed by resolved layer URL. Per-isolate, best-effort. Promote to KV/Cache API only if measured latency calls for it.
  • mapserv auth: UGRC_API_KEY is a Worker secret (wrangler secret put), not a var. 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 sends UGRC_API_REFERER (a regular var in wrangler.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 notes

Architecture: 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

  1. Tier 1 — categorized. ~235 SGID layers across 20 categories, generated into src/registry/sgid.ts from agrc/sgid-index, enriched with hand-curated facts in scripts/enrichment.ts. Reached via list_<category> then arcgis_query({ org, layer, ... }).
  2. Tier 2 — uncategorized UGRC long tail. ~528 UGRC services not in Tier 1. Reached via find_layer({ query }) (live ArcGIS Hub Search), then arcgis_query({ url, ... }) with the URL the search returned.
  3. Tier 3 — outside UGRC. County / federal / tribal portals. Reached via arcgis_raw({ url, params }). v0.3 federation will register more orgs in src/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=4485 on inSR — 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 naive response.raise_for_status() will miss them.
  • Geometry-too-large is a common failure mode when passing state-sized polygons as a spatial filter. arcgis_query catches it and recommends bbox in the error message.
  • spatial_relationship maps to ArcGIS spatialRel codes — translate intersects/contains/within/crosses/touches/overlaps/envelope_intersects rather than exposing the raw esriSpatialRel* enum.
  • Don't auto-paginate features. arcgis_query returns exceeded_transfer_limit + next_offset and trusts the model to chain. arcgis_aggregate does 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 + /mcp

No test suite yet. When tests land, document the runner and how to run a single test here.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.