hsm-mcp CLAUDE.md

CLAUDE.md

MCP server mirroring the IND (Netherlands) public register of recognised sponsors (Work category) for AI-assisted checking. Cloudflare Workers Free plan — every design choice respects free-tier limits. Read CONTEXT.md for domain vocabulary before changing tool behavior; docs/adr/ records the decisions that are hard to reverse.

Commands

npm test              # vitest unit tests (pure logic only, no workers runtime)
npm run typecheck     # tsc --noEmit
npm run types         # regenerate worker-configuration.d.ts after wrangler.jsonc changes
npm run dev           # wrangler dev (local)
npm run deploy        # wrangler deploy
npx wrangler tail     # live logs (cron runs, scrape results)

Trigger a scrape locally: wrangler dev, then curl "http://localhost:8787/cdn-cgi/handler/scheduled" (wrangler's scheduled-event test endpoint; add --test-scheduled flag if needed).

Architecture (why, not just what)

• src/validate.ts — pure policy: date parsing, KvK validation, sanity gates. Separated from scraper.ts so vitest runs without Workers-only APIs (cloudflare:email, HTMLRewriter). Gates are load-bearing: they are what keeps a silent IND page redesign from wiping good data.
• src/scraper.ts — scrape pipeline. Fail-soft: errors touch only the status KV key, never the register blob. Alert email fires once at exactly 3 consecutive failures.
• src/scraper-do.ts — the scrape EXECUTES inside the Scraper Durable Object, not the scheduled handler. Free-plan Workers get 10 ms CPU per invocation and parsing ~13k rows exceeds it intermittently (observed "Worker exceeded CPU time limit"); DO requests are not subject to that cap. The cron handler only calls the DO stub. Don't "simplify" this back into the scheduled handler.
• Manual refresh: POST /admin/scrape with Authorization: Bearer <SCRAPE_TOKEN> (secret via wrangler secret put SCRAPE_TOKEN; rotate by putting a new value). Returns the scrape status JSON. Used for first data load and after IND publishes mid-month.
• src/matcher.ts — pure matching. The expensive index build happens in the Durable Object at query time (big CPU budget) and is cached per-isolate keyed by register version — NOT in the cron handler. Tunable: FUZZY_MIN_SCORE.
• src/mcp.ts — McpAgent + 2 tools. Tool descriptions carry the domain caveats (no-verdict, trade-name gap); treat description text as part of the API.
• src/resolver.ts — EntityResolver seam. A future KvK-API resolver (trade-name lookup, €6.40/month) plugs in here; see CONTEXT.md "Registered Name vs Trade Name".
• KV layout: register:current (compact blob), snapshot:<yyyy-mm-dd> (one per IND publication date, never delete — future diff feature depends on them), status (scrape bookkeeping).