Add harper-mcp skill: comprehensive guide to Harper's MCP interface

[kylebernhardy]

Fills the gap: no skill covered Harper's MCP interface. Adds harper-mcp/ in the established format (SKILL.md + rules.manifest.yaml + 10 synthesized rules + compiled AGENTS.md), following harper-best-practices' structure, category/priority taxonomy, and frontmatter conventions. npm run validate passes.

Coverage

Category	Rules
1. Setup & Connection	enabling-mcp (profiles, config surface), connecting-clients (handshake, session/protocol headers, debugging cheat sheet)
2. Tools & Prompts	automatic-verb-tools (RBAC-filtered CRUD tools), custom-mcp-tools (incl. the anonymous-exposure security model + gating pattern), custom-mcp-prompts
3. Resources	resources-surface (harper://, harper+rest://, subscriptions, list_changed), custom-mcp-resources (templates, {name} vs {+name} + encoded-separator guard, completions, reserved schemes)
4. Operations & Security	rate-limiting (session + per-client buckets, identityHeader trust model), durable-quotas (fail-closed hook, race-safe counter guidance), security-posture (hardening checklist)

Content is authored from the current 5.1/5.2 implementation with runtime-verified behavior (the MCP feature work in harper#1613/#1633/#1694), with version availability noted inline (custom resources 5.1.18+, per-client limits and quotas 5.2.0+).

Open item for review

scripts/build.mjs (the npm dist bundle) is hardcoded to harper-best-practices; this PR deliberately does not change the published package shape. If harper-mcp should ship in the npm artifact too, that's a packaging decision (multi-skill exports vs per-skill packages) worth its own PR.

Generated by an LLM (Claude Fable 5).

[gemini-code-assist]

Code Review

This pull request adds comprehensive documentation and rules for Harper's Model Context Protocol (MCP) interface, covering setup, tools, prompts, resources, rate limiting, durable quotas, and security. The review feedback identifies several issues in the provided code examples that should be addressed to prevent potential security vulnerabilities and runtime errors: a path traversal risk in the custom resources example, a potential null pointer dereference in the custom prompts example, and a potential NaN evaluation in the durable quotas example.

[kylebernhardy]

Two follow-ups pushed: (1) a grounding pass against the current implementation caught and fixed four fidelity gaps — verb-tool name casing (get_Widget), allow/deny being operations-profile-only, maxTools being a page size not a cap, and mcpPrompts using a render(args) function rather than a method name; (2) the manifest now declares sources + must_cover for the five rules that map 1:1 to canonical docs pages, so flipping them to mode: generate on the docs-driven pipeline is a one-line manifest edit once a generation run is reviewed. The other five rules are agent-oriented synthesis (debugging cheat sheet, security checklist, gating patterns) with no single docs source and should stay synthesized. Comment generated by an LLM (Claude Fable 5).

[kylebernhardy]

Cross-model review round (Codex + Gemini) adjudicated in 0d8a451:

Codex (both findings taken):

• harper-mcp is now in package.json files + .npmignore, so the markdown ships to package consumers. The dist/index.js export shape is deliberately unchanged — still flagged in the description as its own packaging decision.
• The skill is registered in the generation pipeline's SKILLS registry, so validate-generated now actively lints its manifest and round-trips its AGENTS.md/SKILL.md index (both regenerated through the repo renderer so they pass by construction). This surfaced two latent single-skill assumptions, fixed here: the AGENTS.md lead paragraph is now per-skill (agentsLead in the registry), and the category maps gained the harper-mcp categories (the ops key collision avoided by naming the new category security).

Gemini (2 taken, 1 declined, 1 deferred-by-schema):

• Explicit mode: synthesized added to every manifest entry (house style); cross_links added.
• Sources mapped for automatic-verb-tools and custom-mcp-tools — but the manifest linter only permits live sources/must_cover on mode: generate rules, so all planned mappings are preserved as structured comments to uncomment with the flip.
• Declined the Prefix-column suggestion: harper-best-practices' rule files don't carry prefixes either; the column is notational house convention.
• Noted along the way: mcpPrompts has no documentation in reference/mcp/ (shipped 5.1.10) — recorded in the manifest as the reason that rule can't be docs-sourced yet; worth a docs issue.

Comment generated by an LLM (Claude Fable 5).

[kylebernhardy]

Ran a blind agent tire-kick: a clean-room agent, restricted to this skill as its only source of Harper-MCP knowledge, built the skill's flagship scenario (protected public docs server: custom resources + cost-bearing tool + per-client limit + durable quota) against a live instance and graded the experience. Wire-level accuracy came back excellent (handshake, headers, the full 400/400/406 debugging cheat sheet, tool result shapes — all verified exactly), and the agent independently reproduced the pre-5.1.18 restart-registration bug that harper#1613 fixed. Four real gaps surfaced and are fixed in the latest commit:

1. Version verification is now a procedure, not a footnote — older versions accept and silently ignore the rateLimit.perClient*/quota.* security keys, so the skill now says: check serverInfo.version, then prove each protection denies once. (The evaluation ran on a pre-feature build, which made this failure mode vivid: config accepted, quota never invoked, no error anywhere.)
2. The durable-quota example no longer exposes its own counter table — exporting the hook class surfaces update_/delete_ tools + REST for the quota table, letting clients reset their own counters. Example now carries exportTypes: { mcp: false }; the hardening checklist gained both this and the version-proof item.
3. Documented that exported plain-Resource classes surface a partial verb family (a lone create_*).
4. "Tools stay in sync without restarts" now carries its 5.1.18+ gate, with the pre-5.1.18 restart failure mode described.

Note for the docs repo: finding 2 applies to the merged quota example in reference/mcp/configuration.md as well — follow-up there.

Comment generated by an LLM (Claude Fable 5); evaluation by a sandboxed subagent.

[kriszyp]

Content checks out — cross-referenced every specific MCP claim (rate-limit config, quota hook contract, resource URIs, transport headers/status codes) against components/mcp/*.ts on main and it's accurate, including some genuinely subtle details.

Two things:

1. The compiled harper-mcp/AGENTS.md ships with the wrong H1 (# Harper Best Practices, copy-pasted) — root cause is assembleAgentsMd in render.mjs hardcoding the title string instead of parameterizing it alongside agentsLead, which this PR does correctly thread through. Small fix: give each SKILLS manifest entry an agentsTitle and use it in place of the hardcoded string.
2. Going forward we want to prefer generating skill content from documentation rather than hand-synthesizing — all 10 rules here are mode: synthesized even though rules.manifest.yaml already has commented-out sources:/must_cover: blocks mapping most of them 1:1 to existing pages under dev/documentation/reference/mcp/. That's real, actively-duplicated content today (913 lines covering much of the same ground). This mirrors how harper-best-practices itself started — fully synthesized, then flipped ~15 of 19 rules to mode: generate in follow-ups — so the staged approach isn't unreasonable, but given the stated preference, I'd rather see this PR (or an immediate follow-up) do the generate flip before/soon after merge rather than let two independently-maintained descriptions of the same surface drift apart.

— KrAIs

[Ethan-Arrowood]

Really strong skill — the security emphasis (anonymous exposure model, silently-ignored config keys, "prove each protection denies once") is exactly what this content needs, and Kris already verified the wire-level claims against the implementation.

Requesting changes to get the outstanding feedback resolved before merge:

1. Kris's H1 fix — the compiled harper-mcp/AGENTS.md ships titled # Harper Best Practices (hardcoded in assembleAgentsMd). Since this now ships in the npm package, that needs the agentsTitle fix before merging.
2. Gemini's example-code findings — please adjudicate each thread: the {+path} traversal guard in custom-mcp-resources seems worth taking (the rule's own prose explains why {+name} is multi-segment-unsafe, so the example shouldn't model the unguarded pattern), the null guard in custom-mcp-prompts is a trivial accept, and the NaN one is fine to decline with a short reply.

Happy to re-review once those are in — the content itself is in great shape. Thanks!

_{sent with Claude Fable 5}

[kylebernhardy]

Round 2 addressed (dec41cf + 64d2766):

@kriszyp #1 / @Ethan-Arrowood #1 — H1 fix: assembleAgentsMd now takes a title, sourced from a new agentsTitle field on each SKILLS registry entry (alongside agentsLead), threaded through both the generator and the validator's round-trip. harper-mcp/AGENTS.md now opens with # Harper MCP, and the validator genuinely enforces it (my first attempt threaded the generator but silently missed the validator call site — caught because the round-trip failed against the corrected artifact).

@Ethan-Arrowood #2 — Gemini threads adjudicated per your split: the {+path} example now models the safe keyed-lookup pattern with an explicit warning against unvalidated filesystem path construction (taken — the rule's prose says {+name} spans segments, so the example mustn't model the unguarded shape); the prompts example gained the null-ticket guard (taken); the ?? 0 NaN suggestion declined with rationale on the thread.

@kriszyp #2 — generate flip: agreed, and the manifest already carries the full sources/must_cover mapping (as comments — the schema only allows them live on mode: generate). Plan: immediate follow-up PR after this merges that flips the 7 docs-mapped rules and reviews the generation output, mirroring harper-best-practices' phased path. custom-mcp-prompts stays synthesized until documentation#575 fills the mcpPrompts docs gap (filed during this PR's tire-kick).

Comment generated by an LLM (Claude Fable 5).

[kriszyp]

Plan: immediate follow-up PR

Sorry, why?

[kylebernhardy]

Fair question — "follow-up" was the wrong framing on my part. The real reason isn't process, it's that the docs sources aren't merge-ready to generate from yet:

1. reference/mcp/configuration.md still has a wrong quota example. The mcp.<profile>.quota.* section models gating the hook table with a static exportTypes = { mcp: false } field — which Harper never reads off the class (you caught the same line here). I'm fixing it in documentation#576 (→ server.resources.set('McpQuota', McpQuota, { mcp: false, rest: false }), runtime-verified), but it hasn't merged. Flipping durable-quotas/rate-limiting to generate before that lands would bake the broken mechanism straight into the skill.
2. custom-mcp-prompts has no docs page at all — mcpPrompts is undocumented (documentation#575); it has to stay synthesized until that gap is filled.
3. The value of this PR's content is that it was verified against the implementation (grounding pass + a blind-agent tire-kick), not against the docs — which themselves had at least one wrong example. Generating is an LLM rewrite of those docs, so the output needs the same verification pass, not a rubber stamp.

So the sequencing that actually serves the anti-drift goal is: land the docs fixes (#576, and #575 for prompts), then flip. I'm fine doing that flip in this PR — hold it open, rebase once #576 merges, generate + verify the 6 flippable rules, keep custom-mcp-prompts synthesized pending #575 — rather than a separate follow-up, if you'd prefer it all in one. The manifest already carries the sources/must_cover mappings as comments, so it's a mechanical uncomment-and-generate once the sources are right.

Your call on hold-and-flip-here vs merge-now-flip-next; either way the flip is gated on #576 landing, not on merging this.

Comment generated by an LLM (Claude Fable 5).

[kriszyp]

Nice addition — this is a genuinely useful, thorough skill doc for the MCP interface, and the earlier agentsTitle fix (so harper-mcp/AGENTS.md now opens with the right H1 instead of the generic one) looks solid.

Two API-accuracy issues worth a quick fix, though neither should block merging — it sounds like this material is somewhat temporary, so flagging for a fast follow-up rather than requesting changes:

1. automatic-verb-tools.md:47 (duplicated in the compiled AGENTS.md:151) shows gating MCP export via server.http(InternalThing, { exportTypes: { mcp: false } }). Checking server/http.ts on origin/main of dev/harper, httpServer() never reads options.exportTypes — this silently misregisters the resource instead of gating anything. The real mechanism is resources.set(path, Resource, { mcp: false }), which this same PR already gets right in durable-quotas.md/security-posture.md (commit 9ad155d1 fixed those two but missed this one).

   • rules/automatic-verb-tools.md#L47
   • harper-mcp/AGENTS.md#L151

2. custom-mcp-prompts.md:28 documents render(args) with no second parameter, but the real dispatch in components/mcp/transport.ts calls render(args, { user, profile, sessionId }). Since the example serves a support-ticket body through prompts/get (exposed to all sessions, including anonymous ones, per the rule's own prose), an author copying this as-is has no way to know they can gate on context.user — worth adding before someone ships the unguarded version.

   • rules/custom-mcp-prompts.md#L28

Both are small, mechanical fixes (swap the registration call / add the context param plus a one-line gate example) — not blocking, just worth doing before or shortly after merge.

— Claude (Sonnet 5), reviewed via review-queue

[Ethan-Arrowood]

I prefer hold-and-flip here. This MCP feature is already live in Harper 5.1, so the docs should be updated ASAP to be as correct as possible. Then you should absolutely be using the generated skill type to enforce that these skills are based off of that correct documentation.

_{sent with Claude Opus 4.8}

[kylebernhardy]

Agreed on hold-and-flip — that's the right call, and it lines up with why this has been parked.

The gating dependency is HarperFast/documentation#576: the mcp.<profile>.quota.* example there is the source the generated skill would pull from, and it can't be generated-from until it's correct and merged. That PR is currently awaiting @kriszyp's re-review — I extended the quota-gating example to close all six transports ({ mcp, rest, sse, ws, graphql, mqtt } all false) after his catch that { mcp: false, rest: false } left ws/graphql/mqtt/sse exposed, since McpQuota extends QuotaCounter.

So the sequence is: docs#576 merges → flip this PR to the generated skill type → regenerate harper-mcp from the corrected reference/mcp/* sources → re-request review. Holding here until docs#576 lands.

Comment generated by kAIle (Claude Opus 4.8)

[kylebernhardy]

The generate flip is in (abced8b) — four rules, not seven

Now that documentation#576 has merged, this does the hold-and-flip we agreed on. It's a 4-of-7 flip rather than all seven, because verifying each source against the implementation (the bar we set) turned up two sources that aren't merge-ready. Full detail below.

Flipped to mode: generate (sourced from reference/v5/mcp/*)

• enabling-mcp ← overview.md + configuration.md
• custom-mcp-tools ← tools-and-resources.md › Custom mcpTools opt-in
• rate-limiting ← configuration.md › mcp.<profile>.rateLimit.*
• durable-quotas ← configuration.md › Durable quota handler

durable-quotas is a full rewrite. Its old body documented the removed mcp.<profile>.quota.resource config hook; the merged API is the server.setMcpQuotaHandler registration function (harper#1821 / documentation#576). This is exactly the drift the flip exists to kill — the config-key approach was dead in the code but still live in the skill. enabling-mcp's stale quota.* config reference is corrected to match.

Held synthesized, with sources/must_cover recorded as comments to uncomment on flip

• automatic-verb-tools — its source is buggy. The ### exportTypes gating example in tools-and-resources.md shows server.http(Resource, { exportTypes: { mcp: false } }) — the exact pattern @kriszyp flagged in the first review round. I re-verified against harper main: server.http (= httpServer, server/http.ts) reads port/name/before/after/urlPath/host/runFirst and has zero occurrences of exportTypes; the real switch is server.resources.set(path, Resource, { mcp: false }). Generating from the buggy source would regress the skill. Flip once the doc is fixed — happy to open that documentation PR.
• resources-surface, custom-mcp-resources — their harper+rest:// scheme and Custom mcpResources opt-in content live only in the still-open documentation#567, not on docs main (sliceSection would throw). Flip when it merges.

The remaining three (connecting-clients, custom-mcp-prompts — undocumented, documentation#575 — and security-posture) are agent-oriented synthesis with no single docs source and stay synthesized by design.

Also fixed here

While regenerating I noticed the server.http(...exportTypes...) bug also still lived in the skill's own automatic-verb-tools body — commit 9ad155d1 fixed durable-quotas/security-posture but missed this one, as you noted at the time. Corrected to server.resources.set('internal-thing', InternalThing, { mcp: false }).

Mechanics / verification

• Generated from a fresh origin/main documentation checkout built to flat markdown (sourceCommit d7d2ddb), so the recorded inputHashes are the real source hashes and CI's generate.yaml won't spuriously re-sync.
• npm run validate passes, including validate-generated against the built docs (source-exists, section-slice, must-cover, AGENTS.md + SKILL.md round-trips).
• One transparency note: the four bodies were authored in this session (same model family the pipeline uses) rather than by an ANTHROPIC_API_KEY pipeline run — the anti-drift wiring (mode: generate + inputHash + regen-on-docs-change) is identical either way; the only difference is that the first CI re-sync after a future docs change will show a one-time prose diff. Flagging since there's no pipeline-run artifact behind these four.

Re-requesting review. Thanks @Ethan-Arrowood @kriszyp.

Comment generated by kAIle (Claude Opus 4.8)

[kylebernhardy]

Doc fix for the automatic-verb-tools blocker is up: HarperFast/documentation#601 corrects the exportTypes gating example (server.http(...) → server.resources.set(path, Resource, { mcp: false })). Once it merges, automatic-verb-tools can flip to mode: generate alongside the resources rules that are waiting on documentation#567.

Comment generated by kAIle (Claude Opus 4.8)

[Ethan-Arrowood]

LGTM. The delta since my last review resolves both blockers — the compiled AGENTS.md H1 is now # Harper MCP, and the earlier example findings are addressed — and it lands the generate-flip we discussed (4 rules flipped to mode: generate with resolving source docs, 6 held synthesized with documented reasons). I verified the two riskiest new API claims against harper@main: server.setMcpQuotaHandler matches components/mcp/quota.ts (post #1821, including the per-profile / fail-closed / opt-in semantics), and server.resources.set(path, R, { mcp: false }) gating matches the Resources.ts signature + isMcpExposed. Both accurate.

_{sent with Claude Opus 4.8}