Rebuild Nyuchi Design MCP against the new function set (post-consolidation)

[bryanfawcett]

Why

The DB consolidation in #120 replaces the entire legacy SQL function surface (~66 functions) with a unified ~12-function set over the document store. The Nyuchi Design MCP server (design.nyuchi.com/mcp) currently boots from mcp_tool_registry and calls the legacy functions (get_component, list_components, get_brand_tokens, get_doc, list_skills, get_ubuntu_*, etc.), which read the old reference tables.

When #120 drops the legacy functions + tables, the live MCP will break. This is accepted and intentional — we are rebuilding the tools wholesale, not patching them.

Scope

• Rebuild MCP tool handlers against the new function set: read_documents, put_document, read_versions, emit_event, query_events, log_release, record_doctrine_change, count/summary fns
• Repoint every mcp_tool_registry row's source_table / handler to the new functions (registry-driven, no per-tool code)
• Update tool input_schema / output_shape for the document-shaped responses (returns document jsonb, not flat typed columns)
• Re-seed brand data so get_design_tokens / get_brand_info resolve for all five brands (known pre-existing bug)
• Fix unserialised error objects ([object Object]) in remaining tool response handlers (known pre-existing bug)
• Correct stale "five minerals" → "seven minerals" in the design-system skill + token output
• Re-test all MCP tools live after cutover

Also affects

• nyuchi-docs-api Cloudflare Worker reads documentation_pages directly via PostgREST — must repoint to the documentation document collection (or to read_documents).
• Registry API (design.nyuchi.com) typed routes — confirm contract strategy during DB consolidation → single source of truth: document store + unified function set (4.1.0) #120 cutover.

Blocked by #120.

[linear]

FRD-44

[bryanfawcett]

Reconciliation — 2026-05-29 — security model for the MCP rebuild

Adding the security clarifications for when this rebuild lands, plus the parallel state in nyuchi/mzizi-tools.

Rules the rebuilt design-portal MCP must follow

• RLS is canonical. Nothing bypasses it — including the MCP itself.
• The MCP's write tools must NOT call SECURITY DEFINER functions that skirt RLS. The DB-side fix is the same INVOKER + revoke-anon-EXECUTE pattern already applied to the fundi write surface in DB consolidation → single source of truth: document store + unified function set (4.1.0) #120.
• The MCP's read tools may use the anon (publishable) key only for the public collections (components, documentation, skills, documentation-architecture-nodes, ai-instructions). Every other collection and every event stream requires an authenticated JWT carried through to the RPC call.
• Service-role is OUT for routine MCP operations (bypasses RLS). The MCP authenticates each caller and forwards their identity; no global service-role escape hatch.

Auth model for MCP callers

• Human users: WorkOS AuthKit session → JWT presented to the MCP → forwarded to Supabase via @supabase/server createContextClient({ auth: { token } }).
• Programmatic clients (CLI, CI): SHA-256-hashed bearer tokens checked against first_party_clients (feat(db): first_party_clients allow-list table + is_first_party_caller() helper #78), then mapped to a WorkOS-issued JWT for the downstream RPC call.
• Anonymous (public registry browsing): anon key, public reads only.

Parallel: mzizi-mcp at nyuchi/mzizi-tools

The mzizi-tools repo has its own MCP — mzizi-mcp — that already shipped onto the document API (PR nyuchi/mzizi-tools#12 merged):

• Tools: read_documents, get_node_documents, get_component_with_source, read_versions, list_collections, list_components, get_component, get_database_status.
• Reads public.component_documents only via the canonical RPCs; never legacy.
• Currently anon (public-read tier). When the agent-tier collections come online it'll need the per-collection auth gate too.

It's not a replacement for mcp.nyuchi.dev/design; it's the consumer-tooling sibling. The architectural pattern (document-API-only, never legacy) is shared between both rebuilds.

Pre-existing bugs flagged here that the rebuild should fix

• Re-seed brand data so get_design_tokens / get_brand_info resolve for all five brands (still present).
• Fix unserialised error objects ([object Object]) — still present.
• "five minerals" → "seven minerals" — confirmed in the data (the styling-minerals collection has 7 docs).
• get_component_with_source currently errors with relation "components" does not exist because its body references the moved-to-legacy components table — the function needs to be rewritten to read from the components collection in component_documents (or dropped in favour of read_documents).

---

Generated by Claude Code