Register the MCP durable quota policy as a function, not a config-referenced Resource (#1809)

[kylebernhardy]

Closes #1809. Supersedes the interim docs fix in HarperFast/documentation#576.

Problem

The durable MCP quota hook (#1610) was configured by mcp.<profile>.quota.resource pointing at an exported Resource. Because Resources are public-by-default, that Resource's inherited CRUD surfaced on every transport (update_/delete_ MCP tools + REST/SSE/WS/GraphQL/MQTT), so a client subject to the quota could reset its own counter. The docs example papered over it by turning six exportTypes flags off — making the safe path the easy-to-forget one, for the one built-in whose entire purpose is server-side enforcement. Per @kriszyp's review on documentation#576, the fix belongs in the API, not the docs.

Change

Configure the quota policy with a registration function instead:

// in a component's resources.js, at module top level — no Resource, no config, no exposure
server.setMcpQuotaHandler(async ({ identity, tool, user, profile, sessionId }) => {
  if (profile !== 'application') return true;   // gate per-profile in code
  const used = await bumpCounter(identity);
  return used > DAILY_LIMIT ? { allowed: false, message: 'daily quota reached', retryAfterSeconds: 3600 } : true;
});

• Enabled by registration, not config — register a handler → quota active; none → allowed (opt-in, unchanged). Throw → fail-closed deny (unchanged). Single global handler; latest registration wins (a reloaded component replaces it); profile is in the info so one handler covers both profiles.
• Wired server.setMcpQuotaHandler next to server.registerOperation (serverUtilities.ts), declared on the Server interface. Worker-local like the tool dispatch that consults it, so no cross-thread announce (matches the old per-worker registry resolution).
• Removed the mcp.<profile>.quota.resource/.method config params (only 5.2-alpha shipped them; no deprecated fallback).
• Migrated the mcp-quota fixture off tables.QuotaCounter: an exported tool (Answerer) + an internal (non-@export) counter table + a registered handler — nothing exposes the counter. The integration test now asserts the counter is not REST-reachable.

Where to look

• server.setMcpQuotaHandler wiring (serverUtilities.ts) — availability timing (set at server init, before components load) and the worker-local rationale.
• The single-global-handler shape was chosen deliberately (Kyle's call): one handler branches on profile. Two components both registering means last-wins — acceptable for a single policy, worth a glance.
• Integration test validated in CI — the mcp-quota end-to-end couldn't run locally (this machine lacks the 127.0.0.x loopback aliases the test framework needs); unit tests (quota.test.js) pass locally and the fixture mirrors the proven custom-resources extends Resource + mcpTools pattern.

Generated by an LLM (Claude Opus 4.8). Cross-model review (Codex + Gemini) in progress.

---

Docs: companion docs PR HarperFast/documentation#576 rewrites the reference/mcp/configuration.md durable-quota section to server.setMcpQuotaHandler (removes the mcp.<profile>.quota.* config); merges together.

[gemini-code-assist]

Code Review

This pull request refactors the durable MCP quota policy mechanism by replacing the configuration-based resource lookup with a functional registration approach via server.setMcpQuotaHandler. This change simplifies the quota logic, removes obsolete configuration parameters, and ensures that the quota counter table remains internal and not exposed over REST. The review feedback correctly identifies that the setMcpQuotaHandler signatures in the Server interface and serverUtilities.ts should be updated to accept undefined to match the underlying implementation, allowing handlers to be cleared or unregistered.

[claude]

Reviewed; no blockers found. The previously-open finding (candidate quota handler live on the shared singleton during deploy-validation load) is resolved by commit 8da8768: registrations now no-op during validation instead of snapshot/restore, closing the race entirely and generalizing the same protection to server.registerOperation.

[kriszyp]

Love it!
As KrAIs said "Kyle didn't just build [the option we were discussing] — he improved on it"