utah-water-rights-mcp
CLAUDE.md0 starsChanged 6 months agoMITView on GitHub
A remote MCP server that wraps the Utah Division of Water Rights' public surfaces and exposes them as 20 read-only tools. Runs stateless on Cloudflare Workers via createMcpHandler from the agents SDK. No auth, no Durable Objects, no KV. Read docs/dwr-reverse-engineering.md before adding tools or probing new endpoints. It's the institutional memory: endpoint catalog, wrDB schema, confirmed-non-existent tables, the WRCHEX-vs-WRNUM gotcha, scanned-doc URL construction, and a decision tree for "where does this data live." The whole server exists to paper…
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
No secrets, no bindings, no DOs.
- Very specific: line 39
agents/mcponly loads in the Workers runtime: Don't import it from Node scripts.
≈ “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 notes for utah-water-rights-mcp
A remote MCP server that wraps the Utah Division of Water Rights' public surfaces and exposes them as 20 read-only tools. Runs stateless on Cloudflare Workers via createMcpHandler from the agents SDK. No auth, no Durable Objects, no KV.
Read docs/dwr-reverse-engineering.md before adding tools or probing new endpoints. It's the institutional memory: endpoint catalog, wrDB schema, confirmed-non-existent tables, the WRCHEX-vs-WRNUM gotcha, scanned-doc URL construction, and a decision tree for "where does this data live."
Stack at a glance
- Cloudflare Worker, TypeScript,
@modelcontextprotocol/sdk+agents/mcp(createMcpHandler, notMcpAgent— this server is fully stateless, so a freshMcpServeris constructed per request). nodejs_compatflag is required at runtime; theagentspackage depends on it (tsc --noEmitdoesn't catch this). See commit 46f37b6 for context.- Zod v4 for tool input schemas;
agents@0.12.4declares it as a peer. - No secrets, no bindings, no DOs. The worker is a pure proxy over three upstream surfaces.
File responsibilities
| File | Holds | Don't put here |
src/index.ts | All tool registrations, the three upstream fetch wrappers (dwrGet, wrindexPost, wrprintAjax), and the WRINDEX HTML parser. | Anything renderable as HTML — that goes in cards.ts. |
src/cards.ts | HTML widget renderers for card-emitting tools (renderWaterRightCard, renderSearchResultsCard, renderScannedDocsCard) and the htmlResource helper. | Business logic, fetches, parsing. |
scripts/preview-cards.mjs | Local preview harness for iterating on card HTML without redeploying. | Anything imported by the worker. |
docs/dwr-reverse-engineering.md | Authoritative spec for what each upstream surface returns and why. | Code. |
wrangler.jsonc | Worker name (utah-diwr-mcp), compatibility_date, nodejs_compat, observability. | Secrets, bindings. |
The three upstream surfaces
The whole server exists to paper over these three being inconsistent. Know which surface a tool hits before debugging.
/api/*— clean JSON. Map utilities, hydrography, distribution accounting. Standardfetch+Accept: application/json. Wrapped bydwrGet./cgi-bin/wrindex.exe— legacy CGI returning HTML. Owner/source search across the full statewide WR database. Parsed in-worker byparseWrindexHtml. Sometimes the first POST returns empty;wrindexPosttransparently retries with a warmedASPSESSIONIDcookie when that happens — don't strip the retry./asp_apps/wrprint/lclAjax.asp— session-cookied AJAX. Per-WR detail and arbitrarySELECTagainst wrDB. Each request needs a freshASPSESSIONID(obtained bywrprintCookie). Error responses come back as single-quoted pseudo-JSON like{'Error':'...'}—wrprintAjaxnormalizes both that and{'RecordCount':'0'}.
The application tracker is a fourth, narrower surface: server-rendered HTML at /applicationsrecords/*AppTracker.asp, parsed similarly to WRINDEX.
Gotchas
- WRCHEX vs WRNUM. The
ownerstable is keyed byWRCHEX, notWRNUM. Exchange rights look likeE5428. To find owners by WR number useWHERE wrchex LIKE '%<wrnum>%'. The spec covers this in detail. - SQL safety in
uwr_wrdb_queryanduwr_water_right_uses. Where-clauses interpolate user input into single-quoted SQL strings. Thewr_numberparameter is regex-validated upstream bySAFE_WRNUM(/^[A-Za-z]?\d+(?:-\d+)?$/). Don't relax that regex without thinking through injection vectors against wrDB. - WRINDEX session-cookie behavior is non-deterministic. Some queries work cold, others need a warmed cookie. The empty-then-retry pattern in
wrindexPostis the working compromise — don't replace it with eager warming (extra round trip on every call) or no warming (random empty results). agents/mcponly loads in the Workers runtime. Don't import it from Node scripts. Test throughwrangler devor against the deployed Worker.worker-configuration.d.tsis generated bynpx wrangler types(script:npm run cf-typegen) and is.gitignore'd. Re-run after adding bindings. Fresh clones need to run it once beforetsc --noEmitwill pass; the Worker bundle itself doesn't need it.- The lockfile is committed.
npm clean-installis what CF runs — peer-dep conflicts (e.g. zod major mismatches) will fail the build. If you bump a dep with peers, runnpm installlocally and commit the lockfile.
When extending
- New tool →
server.registerTool(...)insidecreateServer()insrc/index.ts. Follow the existing pattern:title, prosedescription(LLM reads this — be specific about parameters and return shape), ZodinputSchema,annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: <true if it queries arbitrary external data> }. Use thetext(...)helper to wrap the response. - New wrDB query → reach for
uwr_wrdb_queryfirst; only add a convenience tool if (a) the SQL needs validation/escaping the generic tool can't safely do, or (b) the return shape is so specialized it justifies a dedicated tool. - Card-emitting tool → add the renderer to
src/cards.tsand append the HTML resource viahtmlResource(...)in the tool's response. End the tool'sdescriptionwith the RENDERING directive so clients withshow_widgetrender the card inline. - New upstream surface → update the spec before writing code. Discovering the same gotcha twice is the failure mode the spec exists to prevent.
Testing
npx tsc --noEmitfor type-checking.npm run devforwrangler dev(port 8787, endpoint/mcp).- Inspector:
npx @modelcontextprotocol/inspector@latest→ Streamable HTTP →http://localhost:8787/mcp. - CF Workers Builds runs
npm clean-installthenwrangler deployon every push; check the build before declaring a change shipped.
Conventions
- Comments explain why, not what. The reader can read the code.
- Tool descriptions are prose, not lists — write them for the LLM that will read them, not for humans skimming docs.
- Atomic commits per logical change. Subjects use lowercase prefix (
feat:,fix:,refactor:,docs:,chore:).
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.

