@harperfast/template-react-ts-studio 1.11.3 → 1.11.5

package/.agents/skills/harper-mcp/rules.manifest.yaml

@@ -0,0 +1,203 @@
+# Rules manifest for the harper-mcp skill.
+#
+# Declarative source of truth for rule taxonomy, sources, and generation mode.
+#
+# Four rules with a 1:1 mapping to canonical HarperFast/documentation pages are
+# `mode: generate` (derived from reference/v5/mcp/* so the skill and the docs
+# cannot drift): enabling-mcp, custom-mcp-tools, rate-limiting, durable-quotas.
+#
+# Three more rules are docs-mapped but held synthesized pending a source fix,
+# each with its `sources`/`must_cover` recorded as comments to uncomment on flip:
+#   - automatic-verb-tools — its source's exportTypes-gating example is wrong on
+#     docs main (see the rule's note); flip once the doc is corrected.
+#   - resources-surface, custom-mcp-resources — pending documentation#567, which
+#     adds the `harper+rest://` scheme and the custom `mcpResources` section.
+#
+# The rest (connecting-clients' debugging guidance, custom-mcp-prompts — whose
+# mcpPrompts feature is UNDOCUMENTED in reference/v5/mcp/, see documentation#575
+# — and the security-posture checklist) are agent-oriented synthesis with no
+# single docs source and stay synthesized.
+
+rules:
+  # ===========================================================================
+  # Setup & Connection (priority 1 — HIGH)
+  # ===========================================================================
+
+  - rule: enabling-mcp
+    description: How to enable and configure Harper's MCP server profiles (application and operations).
+    category: setup
+    priority: 1
+    order: 1
+    mode: generate
+    sources:
+      - path: reference/v5/mcp/overview.md
+        role: primary
+      - path: reference/v5/mcp/configuration.md
+        role: supplemental
+    must_cover:
+      - '9926'
+      - '9925'
+      - presence
+      - 5.2.0+
+    cross_links:
+      - connecting-clients
+      - rate-limiting
+
+  - rule: connecting-clients
+    description: How MCP clients connect to Harper - the initialize handshake, session and protocol-version headers, and authentication.
+    category: setup
+    priority: 1
+    order: 2
+    mode: synthesized
+
+  # ===========================================================================
+  # Tools & Prompts (priority 2 — HIGH)
+  # ===========================================================================
+
+  - rule: automatic-verb-tools
+    description: How Harper auto-generates CRUD MCP tools from exported tables, with RBAC filtering and allow/deny/maxTools controls.
+    category: tools
+    priority: 2
+    order: 1
+    mode: synthesized
+    # Blocked from generate: the source's `### exportTypes gating` example shows
+    # `server.http(Resource, { exportTypes: { mcp: false } })`, but server.http
+    # (= httpServer in harper server/http.ts) never reads exportTypes — MCP
+    # gating is `server.resources.set(path, Resource, { mcp: false })`. Flip once
+    # the doc is corrected. This rule already carries the correct mechanism
+    # (skill commit 9ad155d1); generating from the buggy source would regress it.
+    # sources:
+    # - path: reference/v5/mcp/tools-and-resources.md
+    # section: 'Application profile — tool generation'
+    # role: primary
+    # must_cover:
+    # - tool names preserve Resource-path case (get_Widget)
+    # - tools/list is RBAC-filtered per user; calls enforce permissions
+    # - exportTypes.mcp gating via server.resources.set
+    cross_links:
+      - custom-mcp-tools
+
+  - rule: custom-mcp-tools
+    description: How to expose custom instance methods as MCP tools via static mcpTools, including the anonymous-exposure security model.
+    category: tools
+    priority: 2
+    order: 2
+    mode: generate
+    sources:
+      - path: reference/v5/mcp/tools-and-resources.md
+        section: 'Custom `mcpTools` opt-in'
+        role: primary
+    must_cover:
+      - mcpTools
+      - anonymous
+      - live-class
+      - context.user
+    cross_links:
+      - rate-limiting
+      - durable-quotas
+
+  - rule: custom-mcp-prompts
+    description: How to publish reusable prompt templates to MCP clients via static mcpPrompts.
+    category: tools
+    priority: 2
+    order: 3
+    mode: synthesized
+    # No canonical docs source exists for mcpPrompts yet (shipped 5.1.10,
+    # undocumented in reference/v5/mcp/, see documentation#575) — stays
+    # synthesized until that docs gap is filled; content grounded in the
+    # implementation.
+
+  # ===========================================================================
+  # Resources (priority 3 — MEDIUM)
+  # ===========================================================================
+
+  - rule: resources-surface
+    description: The MCP resources surface - harper:// metadata URIs, harper+rest:// table descriptors, templates, subscriptions, and list_changed notifications.
+    category: resources
+    priority: 3
+    order: 1
+    mode: synthesized
+    # Flip to generate once documentation#567 merges: it adds the
+    # `harper+rest://` descriptor scheme (currently only under `https://` on
+    # docs main) that this rule's must_cover requires.
+    # sources:
+    # - path: reference/v5/mcp/tools-and-resources.md
+    # section: 'Resources surface'
+    # role: primary
+    # - path: reference/v5/mcp/subscriptions.md
+    # role: supplemental
+    # must_cover:
+    # - the harper:// metadata URIs and which profile serves each
+    # - harper+rest:// descriptor scheme with http(s) back-compat
+    # - subscribe requires an open GET SSE stream
+    cross_links:
+      - custom-mcp-resources
+
+  - rule: custom-mcp-resources
+    description: How to serve custom content (docs pages, reports, binaries) as MCP resources via static mcpResources with URI templates and completions.
+    category: resources
+    priority: 3
+    order: 2
+    mode: synthesized
+    # Flip to generate once documentation#567 merges: the 'Custom `mcpResources`
+    # opt-in' section it adds does not yet exist on docs main, so sliceSection
+    # would fail.
+    # sources:
+    # - path: reference/v5/mcp/tools-and-resources.md
+    # section: 'Custom `mcpResources` opt-in'
+    # role: primary
+    # must_cover:
+    # - exactly one of uri/uriTemplate per entry; {name} vs {+name} semantics
+    # - encoded-separator rejection preserves the single-segment contract
+    # - reserved schemes are rejected at registration
+    # - anonymous sessions are served; gating is the read method's job
+    cross_links:
+      - resources-surface
+      - rate-limiting
+
+  # ===========================================================================
+  # Operations & Security (priority 4 — HIGH for public deployments)
+  # ===========================================================================
+
+  - rule: rate-limiting
+    description: MCP tools/call rate limiting - per-tool, per-session, and per-client-identity token buckets, and the identityHeader trust model.
+    category: security
+    priority: 4
+    order: 1
+    mode: generate
+    sources:
+      - path: reference/v5/mcp/configuration.md
+        section: '`mcp.<profile>.rateLimit.*`'
+        role: primary
+    must_cover:
+      - rate_limited
+      - perClientPerSecond
+      - identityHeader
+      - x-forwarded-for
+    cross_links:
+      - durable-quotas
+
+  - rule: durable-quotas
+    description: Operator-pluggable durable quotas for MCP tools/call via the server.setMcpQuotaHandler registration hook, with a race-safe counter pattern.
+    category: security
+    priority: 4
+    order: 2
+    mode: generate
+    sources:
+      - path: reference/v5/mcp/configuration.md
+        section: 'Durable quota handler'
+        role: primary
+    must_cover:
+      - setMcpQuotaHandler
+      - quota_exceeded
+      - Fail-closed
+      - read-modify-write
+    cross_links:
+      - rate-limiting
+
+  - rule: security-posture
+    description: The MCP security model - anonymous access, RBAC boundaries, origin validation, audit logging, and the hardening checklist for public instances.
+    category: security
+    priority: 4
+    order: 3
+    mode: synthesized