diff --git a/canon/patterns/docs-proxy-canon-as-tool.md b/canon/patterns/docs-proxy-canon-as-tool.md new file mode 100644 index 0000000..f787c39 --- /dev/null +++ b/canon/patterns/docs-proxy-canon-as-tool.md @@ -0,0 +1,52 @@ +--- +uri: klappy://canon/patterns/docs-proxy-canon-as-tool +title: "Docs Proxy — Canon-as-Tool So Consumers Wire One MCP" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["canon", "pattern", "mcp-server", "docs-proxy", "consumer-experience", "vodka-architecture"] +derives_from: + - klappy://canon/principles/vodka-architecture + - klappy://canon/principles/consistency-same-pattern-every-time + - klappy://canon/principles/dry-canon-says-it-once +complements: + - klappy://canon/principles/doing-less-enables-more +status: active +--- + +# Docs Proxy — Canon-as-Tool + +> An MCP server whose action surface depends on a sibling canon repo for domain semantics SHOULD expose a `docs(query, audience?, depth?)` tool that proxies the canon-server (oddkit), parameterized to its own repo. Consumers get both surfaces through one MCP wiring. + +## The Pattern + +The action MCP server adds one tool — typically named `docs` or `_docs` — whose entire job is to forward queries to the canon-server with the action server's own repo URL pinned as the `knowledge_base_url` parameter. + +- **Inputs**: `query` (required), `audience` (optional, server-defined enum), `depth` (optional `1|2|3` — snippet, full top doc, top + next two) +- **Returns**: `{ answer, sources[], deeper[], governance_source }` +- **Failure**: graceful degradation when the canon-server is unreachable — `{ answer: null, sources: [], governance_source: "minimal", error }` rather than a hard error that blocks consumer flow + +## Vodka Check the Tool Must Pass + +The proxy tool knows exactly two URLs: this server's canon repo and the canon-server's MCP endpoint. It holds zero domain semantics. It does not parse, rank, filter, score, or reframe results. It is a pinned forwarding layer. + +If the proxy ever grows a domain-flavored taxonomy or a scoring tweak, that taxonomy moves into governance documents in the canon repo (which the canon-server retrieves through the same proxy), not into the tool's implementation. Domain logic in the proxy is a vodka-boundary leak. + +## Why the Pattern Exists + +Without the pattern, every consumer pays a wire-two-MCPs tax: one MCP for actions, a second MCP for canon retrieval, configured with the action server's repo as `knowledge_base_url`. Consumers who do not pay the tax lose canon-in-flow access at the moment they need it most. The pattern absorbs the tax once, server-side, for every present and future consumer. + +This pattern is orthogonal to `canon/principles/consistency-same-pattern-every-time`, which covers the *same-server-many-knowledge-bases* axis. This pattern covers *many-servers-one-knowledge-base*. Both are real; both deserve canon coverage. + +## Failure Mode + +Without this pattern: per-consumer onboarding friction; canon drifts from living context to web-search-of-last-resort; the canon-as-living-context value proposition silently degrades because consumers never wire it. + +With the pattern: one MCP wired, both surfaces accessible; canon stays in-flow as designed. + +## Receipts + +- **PTXprint-MCP v1.2 §3 `docs` tool.** Added in session 13 (2026-04-29), reversing v1.0's "no retrieval in MCP server" decision with explicit rationale: downstream agents like BT Servant want one MCP wiring. Vodka boundary preserved. +- *(Future receipts: each server adopting the pattern adds one row — server, tool name, date adopted, link to spec section.)* diff --git a/docs/promotions/P0004-docs-proxy-canon-as-tool.md b/docs/promotions/P0004-docs-proxy-canon-as-tool.md index fcf3b09..cee03f0 100644 --- a/docs/promotions/P0004-docs-proxy-canon-as-tool.md +++ b/docs/promotions/P0004-docs-proxy-canon-as-tool.md @@ -6,8 +6,8 @@ exposure: nav tier: 3 voice: neutral stability: evolving -tags: ["promotions", "proposed", "mcp-server", "docs-proxy", "canon", "vodka-architecture", "consumer-experience"] -promotion_status: proposed +tags: ["promotions", "accepted", "mcp-server", "docs-proxy", "canon", "vodka-architecture", "consumer-experience"] +promotion_status: accepted --- # P0004: Docs Proxy — Canon-as-Tool So Consumers Wire One MCP, Not Two @@ -131,16 +131,14 @@ The placement under `canon/patterns/` rather than `canon/principles/` is deliber ## Status -`proposed` +`accepted` (2026-05-05) ## Review Notes -(To be filled during review) - -- **Reviewer**: -- **Decision**: -- **Date**: -- **Notes**: +- **Reviewer**: klappy (operator) +- **Decision**: `accepted` +- **Date**: 2026-05-05 +- **Notes**: Accepted in the 8-proposal sweep. Created `canon/patterns/docs-proxy-canon-as-tool.md` as a tier-2 pattern doc. **Note for review:** this is the first doc under a new top-level subdirectory `canon/patterns/` — the existing canon hierarchy has bootstrap, case-studies, constraints, decisions, defaults, definitions, diagnostics, instructions, meta, methods, observations, principles, resonance, values. The proposal explicitly names this path; if you want this relocated under `methods/` or `principles/` instead, the file is small (one move + one frontmatter `uri:` edit + zero downstream consumers). ## Execution Record