@adia-ai/mcp 0.8.37

package/TOOLS.md

@@ -0,0 +1,565 @@
+# AdiaUI MCP — Tool Reference
+
+<!-- GENERATED by scripts/build/generate-mcp-tools-md.mjs from each server's live tools/list.
+     Do not hand-edit: run `npm run build:mcp-tools-md`. Tool text lives on the
+     server.tool(...) call; grouping lives in each server's own tool-groups.mjs. -->
+
+One npm package, two MCP servers (gh#1240) — the ADR-0048 §3 two-server
+decision is unchanged; only the distribution and this reference merged.
+Every tool appears once per section below, and every heading link is
+section-scoped so no two tools — same-named or not — ever resolve to the
+same anchor (gh#1248 renamed the protocol server's 4 formerly-same-named
+tools before it ever published; zero names overlap between the two
+servers as of that change).
+
+## `adia-mcp gen-ui` — generation server
+
+The AdiaUI **generation** MCP server (`adia-mcp gen-ui`, `server.js`) exposes the gen-ui compose engine, the training-chunk corpus, retrieval, and the feedback/eval loop — consumed by Claude Desktop, Cursor, and the factory plugin. For installation + configuration see [`README.md`](./README.md).
+
+Protocol-only tooling (validate or introspect an A2UI document with no corpus and no model) lives on a separate server, `adia-mcp protocol` — see its section below in this same file. `validate_schema` and `get_component_map` exist on both; the forms here are the catalog-aware ones.
+
+This server exposes **30 tools**.
+
+### Tool index
+
+| Group | Tools |
+|---|---|
+| **Generation** | [`generate_ui`](#gen-ui-generate_ui), [`refine_ui`](#gen-ui-refine_ui) |
+| **Discovery (catalog + traits + wiring + status)** | [`get_component_map`](#gen-ui-get_component_map), [`lookup_component`](#gen-ui-lookup_component), [`lookup_chunk`](#gen-ui-lookup_chunk), [`get_traits`](#gen-ui-get_traits), [`get_wiring_catalog`](#gen-ui-get_wiring_catalog), [`list_patterns`](#gen-ui-list_patterns), [`server_status`](#gen-ui-server_status) |
+| **Retrieval (chunks + compositions)** | [`search_chunks`](#gen-ui-search_chunks), [`get_chunk`](#gen-ui-get_chunk), [`search_patterns`](#gen-ui-search_patterns), [`get_composition`](#gen-ui-get_composition), [`get_graph`](#gen-ui-get_graph), [`resolve_composition`](#gen-ui-resolve_composition), [`zettel_stats`](#gen-ui-zettel_stats) |
+| **Synthesis + state (zettel two-call chunk workflow)** | [`compose_from_chunks`](#gen-ui-compose_from_chunks), [`refine_composition`](#gen-ui-refine_composition), [`get_state`](#gen-ui-get_state), [`report_issue`](#gen-ui-report_issue) |
+| **Intent + context** | [`plan_app_state`](#gen-ui-plan_app_state), [`classify_intent`](#gen-ui-classify_intent), [`assemble_context`](#gen-ui-assemble_context) |
+| **Validation + conversion** | [`validate_schema`](#gen-ui-validate_schema), [`check_anti_patterns`](#gen-ui-check_anti_patterns), [`convert_html`](#gen-ui-convert_html) |
+| **Feedback + evaluation** | [`submit_feedback`](#gen-ui-submit_feedback), [`get_quality_metrics`](#gen-ui-get_quality_metrics), [`get_training_gaps`](#gen-ui-get_training_gaps), [`run_eval`](#gen-ui-run_eval) |
+
+#### Generation
+
+<a id="gen-ui-generate_ui"></a>
+
+##### `generate_ui`
+
+Generate A2UI components from a natural language description.
+
+Engine selection:
+- "monolithic" (default) — pattern-match + adapt. Searches a corpus of 96+ pre-authored monolithic templates and adapts the best match. Battle-tested; highest F1 on held-out intents.
+- "zettel" — fragment-graph composer. Composes UI from named atomic fragments (labeled-input, card-header-with-description, etc.) with a precomputed backlink graph. Higher reusability; supports composition-iterated refinement on multi-turn edits.
+
+Mode selection (monolithic only; zettel uses "instant"):
+- "pro" (default) — LLM-powered generation with pattern adaptation.
+- "thinking" — Full LLM-powered generation with semantic search, decomposition, and streaming.
+- "instant" — fast pattern matching, no LLM.
+
+The generator knows 96+ UI patterns across 5 domains: forms, data, layout, agent, navigation.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `intent` | string | yes | — | Description of the UI to generate |
+| `engine` | `monolithic` \| `zettel` | no | — | Generation engine. "monolithic" (default) is pattern-match + adapt. "zettel" is fragment-graph composition. |
+| `mode` | `instant` \| `pro` \| `thinking` | no | — | Generation mode (monolithic). "pro" (default) uses LLM with pattern adaptation. "thinking" uses full LLM generation. "instant" uses fast pattern matching. |
+| `sessionId` | string | no | — | Opaque session identifier for multi-turn iteration (zettel only). When provided, follow-up calls with the same sessionId modify the prior turn's canvas instead of regenerating from scratch. Omit for stateless generation. |
+| `context` | object | no | — | Ontology context parsed by plan_app_state — intent, domain, tasks, experience (REQ-03, gh#1208: all four blocks are accepted and validated here; previously only domain/tasks survived the schema, intent/experience were silently dropped). Per-engine caveat: only the "monolithic" engine's system-prompt injection reads it today, and only five of the schema's leaves (domain.entities, domain.metrics, tasks.primary, experience.mode, experience.shell) — intent.* and tasks.inspection validate but are not yet interpolated into the prompt. The "zettel" engine (and the free-form tier reachable via engine escalation) ignores context entirely; passing it has no effect there. |
+
+<a id="gen-ui-refine_ui"></a>
+
+##### `refine_ui`
+
+Refine a previous generate_ui result whose validation failed. Pass the messages from the prior result + the validation errors, and the tool produces a corrected version. For monolithic engine; zettel has refine_composition.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `intent` | string | yes | — | Original intent string |
+| `previousMessages` | any[] | yes | — | Messages from the prior generate_ui call |
+| `validationErrors` | any[] | yes | — | Errors from the prior result.validation.errors |
+
+#### Discovery (catalog + traits + wiring + status)
+
+<a id="gen-ui-get_component_map"></a>
+
+##### `get_component_map`
+
+Get the full AdiaUI component catalog.
+
+_No arguments._
+
+<a id="gen-ui-lookup_component"></a>
+
+##### `lookup_component`
+
+Look up a AdiaUI component by type name.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `type` | string | yes | — | Component type (e.g., "Card", "Button") |
+| `level` | `index` \| `summary` \| `reference` | no | — | Detail level (default: reference) |
+
+<a id="gen-ui-lookup_chunk"></a>
+
+##### `lookup_chunk`
+
+List every chunk whose primary element is `<component_name>`.
+
+Useful for "show me every page that opens with a `<card-ui raw>`" or "every
+chunk built around a `<grid-ui>` root." Returns chunk names + kinds + sources.
+
+Pair with `get_chunk` to fetch full records for any of the returned names.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `component_name` | string | yes | — | Component tag name, e.g. "card-ui", "grid-ui", "drawer-ui" |
+
+<a id="gen-ui-get_traits"></a>
+
+##### `get_traits`
+
+Get the trait catalog, optionally filtered by category.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `category` | string | no | — | Trait category filter (e.g., "input-interaction", "motion-positioning") |
+
+<a id="gen-ui-get_wiring_catalog"></a>
+
+##### `get_wiring_catalog`
+
+Get the AdiaUI wiring catalog: available controllers, action handlers, refresh strategies, value sources, and association types.
+
+_No arguments._
+
+<a id="gen-ui-list_patterns"></a>
+
+##### `list_patterns`
+
+List all composition patterns in the A2UI corpus. Optional filters narrow by domain (auth, settings, dashboard, etc.) or category (block, page, flow).
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `domain` | string | no | — | Filter by domain (e.g. "forms", "data", "navigation") |
+| `category` | string | no | — | Filter by category ("block", "page", "flow") |
+
+<a id="gen-ui-server_status"></a>
+
+##### `server_status`
+
+Returns operational status of the MCP server: transport, sampling capability, corpus stats, version.
+
+_No arguments._
+
+#### Retrieval (chunks + compositions)
+
+<a id="gen-ui-search_chunks"></a>
+
+##### `search_chunks`
+
+Search the gen-UI training-chunk corpus by keyword.
+
+The chunk corpus comes from `packages/gen-ui/corpus/chunks/` — JSON records
+extracted from every `[data-chunk]` element in site/pages/* and the corpus
+exemplars. There are three kinds:
+  - block (default): atomic UI fragment (KPI grid, sign-in form, table)
+  - panel: tab-panel fragment of a page (e.g. dashboard-overview-panel)
+  - page: full-page composition (e.g. dashboard-admin-page)
+
+Returns ranked candidates with chunk name, kind, primary tag, and a relevance
+score. Use `get_chunk` to fetch the full record (HTML + slot bindings + nested
+chunks) for a specific name.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `query` | string | yes | — | Keyword query — chunk name fragment, intent words, primary-tag name |
+| `kind` | `block` \| `panel` \| `page` | no | — | Filter by chunk kind |
+| `limit` | integer | no | `20` | Max results |
+
+<a id="gen-ui-get_chunk"></a>
+
+##### `get_chunk`
+
+Fetch the full record for a single gen-UI training chunk by name.
+
+Returns the chunk's bounding HTML, slot annotations, nested chunk names, and
+metadata (primary tag, kind, source page). For chunks that appear on multiple
+pages (reusable slot chunks like `auth-card-header`, `reg-step-header`),
+returns an `instances` array — one entry per page where the chunk appears.
+
+The HTML is suitable for direct rendering / inclusion in an A2UI message
+construction prompt.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | string | yes | — | The chunk name, e.g. "dashboard-kpi-grid", "auth-signin-card-email", "code-language" |
+
+<a id="gen-ui-search_patterns"></a>
+
+##### `search_patterns`
+
+Search the composition library for reusable UI templates. Returns matching compositions with full A2UI component trees that can be used directly or adapted.
+
+Use this to find a starting point before generating from scratch. If a good composition exists, pass it to generate_ui with instant mode. If no composition matches, use generate_ui with thinking mode.
+
+Keyword search only (§64 v0.4.6 migration: now backed by composition-library; the historical "pattern" library and its `semantic` / `remix` params are retired).
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `query` | string | yes | — | Search query (natural language) |
+
+<a id="gen-ui-get_composition"></a>
+
+##### `get_composition`
+
+Fetch a composition by name. Returns the flat A2UI template (compositions are pre-inlined; no $fragment refs). Zettel-only.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | string | yes | — | — |
+
+<a id="gen-ui-get_graph"></a>
+
+##### `get_graph`
+
+Return the composition catalog. Zettel-only. (Backlinks to fragments retired in §37; only composition nodes remain.)
+
+_No arguments._
+
+<a id="gen-ui-resolve_composition"></a>
+
+##### `resolve_composition`
+
+Return the flat A2UI template + updateComponents messages for a composition. Zettel-only. (Pre-inlined since §37 — `resolve` is now a defensive copy + strip pass.)
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | string | yes | — | — |
+
+<a id="gen-ui-zettel_stats"></a>
+
+##### `zettel_stats`
+
+Zettel corpus stats — composition count + average node count. (Fragment stats retired in §37.)
+
+_No arguments._
+
+#### Synthesis + state (zettel two-call chunk workflow)
+
+<a id="gen-ui-compose_from_chunks"></a>
+
+##### `compose_from_chunks`
+
+Compose a UI page from training chunks — retrieval-first, synthesis-fallback.
+
+Mix-and-match composition for intents that don't have a 1:1 chunk match. Workflow:
+  1. Pure-retrieval tier: if `search_chunks` returns a strong direct match, return
+     that chunk's HTML immediately (no LLM call).
+  2. Synthesis tier: when retrieval is weak, the LLM picks a page-kind chunk and
+     binds block/panel chunks to its named slots. Output validated against the
+     chunk catalog (slot names exist, bound chunks exist, kinds match).
+
+Returns the composed HTML string + a binding plan describing which chunks plug
+where. Useful when the prompt is novel ("dashboard with KPI grid + funnel +
+country list") and no exact chunk has all those parts together — the LLM mixes
+and matches from the corpus.
+
+Two-call mode also available via `plan` parameter — pass a pre-baked binding
+plan to skip the LLM call and just materialize HTML.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `intent` | string | no | — | Natural-language description of what to build (uses LLM synthesis) |
+| `plan` | object | no | — | Pre-baked binding plan (skips LLM, materializes directly) |
+| `max_attempts` | integer | no | `2` | LLM retry budget for synthesis |
+
+<a id="gen-ui-refine_composition"></a>
+
+##### `refine_composition`
+
+Refine an existing chunk-composed UI based on a natural-language intent or an explicit op-list.
+
+Use when the user wants to modify an *existing* UI. Triggers on "change", "update", "modify", "add to", "remove from", "this", "it", "the X". Requires `state_id` from a prior `compose_from_chunks` call.
+
+Two modes:
+  - **Intent-driven** — pass `intent`. Engine runs two-pass synthesis (locator pass identifies which slots to modify; modifier pass emits chunk-plan ops). Validator-driven retry on op-validation failure.
+  - **Explicit ops** — pass `ops` directly. Skips the LLM entirely; engine applies + materializes.
+
+Returns a new `state_id` (versioned chain from the parent), the A2UI op-list applied, the post-op HTML, and a delta summary. Failed ops are reported in `ops_failed` with reasons.
+
+For *fresh creation* use `compose_from_chunks`, not this tool.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `state_id` | string | yes | — | State id from a prior compose_from_chunks or refine_composition call |
+| `intent` | string | no | — | Natural-language description of what to change (e.g. "add a country list to page-content") |
+| `ops` | any[] | no | — | Pre-computed chunk-plan ops to apply directly (skips the LLM) |
+| `max_attempts` | integer | no | `2` | Validator retry budget for synthesis |
+
+<a id="gen-ui-get_state"></a>
+
+##### `get_state`
+
+Inspect a cached composition state by state_id.
+
+Returns the full cache entry including the materialized HTML, the chunk binding plan, the chronological ops history (every refinement applied to this state's lineage), and the parent state_id (chain-back to the originating compose_from_chunks call).
+
+Useful for debugging refinement sequences, replaying a state's history, or verifying that a state_id is still cached before issuing a refine_composition call.
+
+Auto-fires a low-severity `cache-miss-on-known-state` issue when the state_id is not in the cache (the cache is bounded LRU; long-paused conversations may evict their state).
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `state_id` | string | yes | — | State id from a prior compose_from_chunks or refine_composition call |
+
+<a id="gen-ui-report_issue"></a>
+
+##### `report_issue`
+
+File a structured issue ticket — writes BOTH a machine-readable JSON file AND a human-readable Markdown report containing the full session trace (intent, retrieval log, LLM prompts, every attempt's raw response, composer plan, generated HTML preview, component count, warnings, environment).
+
+When to call (any of these is a trigger):
+  (a) USER PHRASES — call immediately when the user says any of:
+      "file a ticket", "log a ticket", "save a ticket",
+      "report this as a bug", "report this issue", "log this issue",
+      "save the trace", "capture the session", "save the session for review",
+      "create a session ticket", "this is broken — debug it",
+      "download the trace", "export this for review",
+      "track this regression", "open a ticket for this".
+  (b) USER COMPLAINS the output is broken / wrong / missing.
+  (c) YOU CANNOT satisfy the user's intent after retrying.
+  (d) YOU DETECT a mismatch between requested and produced output you can't fix.
+
+ALWAYS pass `state_id` from the most-recent compose_from_chunks or refine_composition call when one exists. The default `trace: "full"` then writes the high-resolution Markdown ticket. (Pass `trace: "summary"` for compact tickets, or `trace: "none"` to suppress the trace entirely.)
+
+Do NOT call this for ordinary clarification or for output the user has not yet seen.
+
+The tool returns BOTH paths in its response: `path` (.json) and `markdown_path` (.md). Surface BOTH to the user so they can navigate / download either:
+
+  📋 Logged ticket `{issue_id}` (`{severity}` · owner: {suggested_owner})
+  • Trace report: `{markdown_path}` ← human-readable, scan this first
+  • Raw JSON:     `{path}`           ← machine-readable
+
+Issue files land under `qa/findings/issues/` (immutable; resolution lands in a sidecar file). Severity taxonomy matches the project's ui-audit-coherence vocabulary: blocker = contract violation; drift = quality erosion; nit = cosmetic.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `type` | `bug` \| `training-gap` \| `protocol-gap` \| `ux-feedback` | yes | — | Issue category |
+| `severity` | `blocker` \| `drift` \| `nit` | yes | — | Severity tier |
+| `title` | string | yes | — | One-line title (≤ 80 chars) |
+| `body` | string | yes | — | Markdown body — observed vs expected, repro steps |
+| `state_id` | string | no | — | State id from a prior tool call; auto-attaches the trace |
+| `trace` | `full` \| `summary` \| `none` | no | — | Trace depth — DEFAULT: "full" when state_id is provided (writes both .json + .md ticket with retrieval log, LLM prompts/attempts, plan, HTML preview). Use "summary" for compact tickets; "none" to suppress trace entirely. |
+| `suggested_owner` | `synthesis` \| `retrieval` \| `validator` \| `chunk-corpus` \| `mcp-protocol` \| `unknown` | no | — | Best-guess owner for triage |
+| `tags` | string[] | no | — | Free-form tags for filtering |
+
+#### Intent + context
+
+<a id="gen-ui-plan_app_state"></a>
+
+##### `plan_app_state`
+
+Analyze a natural language prompt and extract the top-level Generative UI Ontology structures (Intent, Domain, Tasks, Experience).
+
+Use this tool BEFORE generating UI to ensure you have walked the Reasoning Ladder and properly modeled the nouns and verbs of the feature. This bounds hallucination and forces a focus on tasks over raw layouts.
+
+Honesty clause (REQ-03, gh#1208): this tool mechanizes only the Reasoning Ladder's ~Tier 0/1 rungs — one prompt, one LLM pass, no plan a reviewer can gate. It is the agent operator's (P4's) only ladder surface — a persona that cannot preload skills — not a substitute for the full rungs 0-19 walk. For anything past Tier 0/1 (roles, decisions, a scored wireframe checkpoint), use a Domain Plan from app-planning-agent's preloaded ladder skill instead.
+
+Output shape — the four ontology blocks generate_ui's context param accepts (ontologyContextSchema, tools/ontology-context.ts): intent (user_goal, product_goal), domain (entities[], metrics[]), tasks (primary[], inspection[]), experience (mode: workspace|dashboard|wizard|chat, shell: admin|chat|editor|simple|embed|none — matches the Orientation Record's own Shell axis). The extracted output is validated against this same schema before being returned (gh#1208 review finding 2): a malformed shell/mode value (or any other schema violation) fails loudly with a typed error instead of passing the raw LLM text through.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `prompt` | string | yes | — | The natural language request (e.g., "Build a dashboard for incoming sales leads") |
+
+<a id="gen-ui-classify_intent"></a>
+
+##### `classify_intent`
+
+Classify intent into a UI domain.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `text` | string | yes | — | Intent text |
+
+<a id="gen-ui-assemble_context"></a>
+
+##### `assemble_context`
+
+Assemble progressive-disclosure context for a given intent and budget tier. Returns domain-relevant components, matching patterns, and anti-patterns.
+
+Tier 0: domain only. Tier 1: components. Tier 2: +patterns. Tier 3: +anti-patterns. Tier 4: full catalog.
+
+Use this when you want to manually compose A2UI output rather than using generate_ui. The returned context gives you the building blocks.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `intent` | string | yes | — | Natural language intent |
+| `tier` | number | no | — | Budget tier 0-4 (default: 1) |
+
+#### Validation + conversion
+
+<a id="gen-ui-validate_schema"></a>
+
+##### `validate_schema`
+
+Validate A2UI messages against schema rules.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `messages` | string | yes | — | JSON array of A2UI messages |
+
+<a id="gen-ui-check_anti_patterns"></a>
+
+##### `check_anti_patterns`
+
+Check HTML against all anti-patterns. Returns only violations.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `html` | string | yes | — | HTML string to check |
+
+<a id="gen-ui-convert_html"></a>
+
+##### `convert_html`
+
+Convert HTML markup to A2UI flat adjacency component messages. Maps HTML tags to AdiaUI components, infers layout from styles, enforces Card content model.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `html` | string | yes | — | HTML markup to convert |
+| `mode` | `instant` \| `reasoning` | no | — | instant = rules only, reasoning = LLM for complex layouts |
+
+#### Feedback + evaluation
+
+<a id="gen-ui-submit_feedback"></a>
+
+##### `submit_feedback`
+
+Submit structured feedback for a generation execution. Used by the evolution engine to learn from each generation.
+
+Persists the rating to `packages/gen-ui/corpus/feedback/<date>.jsonl` through the shared `submitFeedback` path — the same one the gen-UI gallery's thumbs affordance posts to (gh#668). Optional `engine` / `strategy` / `score` / `source` context is carried onto the stored rating so human signal can rank weak domains.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `executionId` | string | yes | — | Execution ID from generate_ui |
+| `rating` | number | yes | — | Overall quality 1-5 (>=4 counts as a thumbs-up) |
+| `intent` | string | no | — | — |
+| `domain` | string | no | — | — |
+| `engine` | string | no | — | Engine that produced the output (zettel, free-form, …) |
+| `strategy` | string | no | — | Strategy label from the generation result |
+| `score` | number | no | — | Self-graded validator score at generation time |
+| `source` | string | no | — | Where the rating came from; defaults to "mcp" |
+| `intentAlignment` | number | no | — | — |
+| `visualQuality` | number | no | — | — |
+| `componentChoice` | number | no | — | — |
+| `userEdited` | boolean | no | — | — |
+| `editSummary` | string | no | — | — |
+| `notes` | string | no | — | — |
+| `shouldBePattern` | boolean | no | — | — |
+| `suggestedName` | string | no | — | — |
+
+<a id="gen-ui-get_quality_metrics"></a>
+
+##### `get_quality_metrics`
+
+Get aggregated quality metrics from the feedback store: avg score, thumb-up rate, per-domain breakdown, training gaps.
+
+`thumbUpRate` is a percentage over rating entries alone, reported even when the read window holds no executions (a rated surface whose generation happened offline). Adds a `ratings` summary and `humanRatings` / `thumbUpRate` per domain (gh#668).
+
+_No arguments._
+
+<a id="gen-ui-get_training_gaps"></a>
+
+##### `get_training_gaps`
+
+Get training gap signals: LLM self-critique gaps by type, plus weak domains ranked with human thumbs weighted above the self-grade.
+
+Output (gh#668, backward compatible — the gap-type keys stay at the top level): `{ ...gapsByType, gapsByType, weakDomains, weighting }`. `weakDomains` is ranked weakest-first by `blendedScore`: `0.7 * humanScore + 0.3 * selfScore` where a domain has both signals (`signal: "human+self"`), `humanScore` alone where it has no self-grade (`"human"`), `selfScore` alone where it has no thumbs (`"self-only"`). A missing signal is not a zero — a domain with NEITHER (executions logged, none graded, nobody rated) is `signal: "none"` and sorts after every ranked domain rather than at the weak end, ordered by execution count (gh#678). `selfScore` averages execution scores plus any `score` carried inline on a rating (`selfScoreSamples` counts them); `engine` / `strategy` are recorded on ratings for triage but are not ranked on.
+
+_No arguments._
+
+<a id="gen-ui-run_eval"></a>
+
+##### `run_eval`
+
+Run the offline eval harness against the held-out intent set. Returns aggregate scores and per-intent results.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `domain` | string | no | — | Filter by domain (forms, data, layout, agent, navigation) |
+| `limit` | number | no | — | Max intents to evaluate |
+
+Tools on this server (30): `assemble_context`, `check_anti_patterns`, `classify_intent`, `compose_from_chunks`, `convert_html`, `generate_ui`, `get_chunk`, `get_component_map`, `get_composition`, `get_graph`, `get_quality_metrics`, `get_state`, `get_training_gaps`, `get_traits`, `get_wiring_catalog`, `list_patterns`, `lookup_chunk`, `lookup_component`, `plan_app_state`, `refine_composition`, `refine_ui`, `report_issue`, `resolve_composition`, `run_eval`, `search_chunks`, `search_patterns`, `server_status`, `submit_feedback`, `validate_schema`, `zettel_stats`.
+
+---
+
+## `adia-mcp protocol` — A2UI protocol server
+
+The A2UI **protocol** MCP server (`adia-mcp protocol`, `server.js`) exposes tooling for the standard itself: validate any A2UI document, and introspect the protocol registry. It has no generation system and no model client in its dependency tree — `@adia-ai/gen-ui` and `@adia-ai/llm` are deliberate non-dependencies (ADR-0048 P4).
+
+Looking for generation, retrieval, or the training corpus? That is a different server, `adia-mcp gen-ui` — see its section above in this same file.
+
+These four tool names are DISTINCT from the gen-ui server's own tool surface (gh#1248 renamed them off their original same-named forms before this server ever published) but each still serves a narrower, protocol-only counterpart — `validate_document` (schema + runtime registry, no catalog; gen-ui's `validate_schema`) and `get_registry_map` (type → tag, no descriptions or prop schemas; gen-ui's `get_component_map`). `get_wiring_registry` likewise reports the live wiring registry rather than the authoring knowledge base (gen-ui's `get_wiring_catalog`). For installation + configuration see [`README.md`](./README.md).
+
+This server exposes **4 tools**.
+
+### Tool index
+
+| Group | Tools |
+|---|---|
+| **Validation** | [`validate_document`](#protocol-validate_document) |
+| **Registry introspection** | [`get_registry_map`](#protocol-get_registry_map), [`get_wiring_registry`](#protocol-get_wiring_registry) |
+| **Status** | [`protocol_status`](#protocol-protocol_status) |
+
+#### Validation
+
+<a id="protocol-validate_document"></a>
+
+##### `validate_document`
+
+Validate A2UI messages against the protocol: message envelope shape, flat-adjacency child references, component types resolvable in the runtime registry, and the semantic checks the renderer relies on (Card content model, renderable content, slot addressing).
+
+This is the PROTOCOL-side form of validation. It needs no catalog and no corpus, so it validates any A2UI document from any producer. For catalog-aware validation (per-component prop schemas via the v0.9 catalog) plus anti-pattern scoring, use gen-ui-mcp's `validate_schema` instead.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `messages` | string | yes | — | JSON array of A2UI messages (a single message object is also accepted) |
+
+#### Registry introspection
+
+<a id="protocol-get_registry_map"></a>
+
+##### `get_registry_map`
+
+Get the A2UI protocol registry: every component type name mapped to the custom-element tag that renders it.
+
+This is the registry view — the authoritative answer to "what types exist and what does each one render to". It carries no descriptions, categories, or prop schemas: those are catalog data and live on gen-ui-mcp's `get_component_map` tool instead. Alias types (several type names resolving to one tag, e.g. Toggle and Switch both -> switch-ui) are reported as such.
+
+_No arguments._
+
+<a id="protocol-get_wiring_registry"></a>
+
+##### `get_wiring_registry`
+
+Get the A2UI wiring registry: controller types, action-handler names, and data-URI resolver schemes the runtime can resolve.
+
+Read live from the runtime's wiringRegistry, so it cannot drift from what the renderer will actually accept. The richer authoring knowledge base (UI event payloads, refresh strategies, value sources, association types) is generation-side — see gen-ui-mcp's `get_wiring_catalog` tool instead.
+
+_No arguments._
+
+#### Status
+
+<a id="protocol-protocol_status"></a>
+
+##### `protocol_status`
+
+Returns operational status of this A2UI protocol MCP server: transport and protocol-registry stats. Reports on the protocol server only — gen-ui-mcp's `server_status` tool reports its own corpus-side status separately.
+
+_No arguments._
+
+Tools on this server (4): `get_registry_map`, `get_wiring_registry`, `protocol_status`, `validate_document`.
+
+---
+
+## Verification
+
+Every heading above is derived from a live `tools/list` response, so this page cannot
+claim a tool, a param, or a default a server does not serve. To reproduce:
+
+```bash
+npm run build:mcp-tools-md         # regenerate this file (both servers)
+npm run check:mcp-tools-md-fresh   # the freshness gate (rides `npm run check`)
+```

package/bin/adia-mcp

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * adia-mcp — the ONE bin for @adia-ai/mcp's two servers (gh#1240).
+ *
+ * ADR-0048 §3 ruled two distinct MCP servers ("they do different things") and
+ * that decision stands; gh#1240 (operator ruling 2026-08-14) unified only the
+ * DISTRIBUTION — one npm package, one bin, still two server processes:
+ *
+ *   adia-mcp gen-ui    — the generation server (30 tools: compose, corpus,
+ *                        retrieval, feedback/eval loop)
+ *   adia-mcp protocol  — the A2UI protocol server (4 tools: validate + registry
+ *                        introspection; no generation system, no model client)
+ *   adia-mcp           — (bare) prints this menu
+ *   adia-mcp --help    — same menu, exits 0 (an unrecognized subcommand
+ *                        prints the same menu too, but exits 1 — help is
+ *                        never an error)
+ *
+ * WHY SPAWN RATHER THAN IMPORT
+ *
+ * The two servers do not share an entry-point contract: gen-ui/server.js calls
+ * its own `main()` unconditionally at module scope (so booting it has always
+ * meant `node server.js`, not `import`), while protocol/server.js guards
+ * `main()` behind an `isEntryPoint()` check comparing `process.argv[1]` to its
+ * own resolved path — which would read as "not the entry point" and never
+ * start if this dispatcher `import()`ed it in-process instead of spawning it.
+ * Neither behavior is a bug to paper over here (server internals are
+ * unchanged per the fold's own shape) — spawning a real child process with a
+ * real argv[1] is what makes both servers boot exactly as they did standalone,
+ * and it is also what an MCP stdio transport needs anyway: the child owns
+ * stdin/stdout for the JSON-RPC channel, so `stdio: 'inherit'` hands it over
+ * directly rather than proxying it.
+ *
+ * PACKED-INSTALL SAFE: every path below resolves off THIS FILE's own location
+ * (import.meta.url), never off process.cwd() or a workspace-relative guess —
+ * so `npx -y @adia-ai/mcp gen-ui` from a real npm install boots the same way
+ * as a workspace-local `node packages/mcp/bin/adia-mcp gen-ui`.
+ */
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const SERVERS = {
+  'gen-ui': {
+    path: join(__dirname, '..', 'gen-ui', 'server.js'),
+    summary: '30-tool generation server (compose, corpus, retrieval, feedback/eval)',
+  },
+  protocol: {
+    path: join(__dirname, '..', 'protocol', 'server.js'),
+    summary: '4-tool protocol server (validate + registry introspection; no gen-ui, no llm)',
+  },
+};
+
+function printMenu() {
+  console.error('adia-mcp — @adia-ai/mcp\'s two MCP servers, one bin.');
+  console.error('');
+  console.error('Usage: adia-mcp <server>');
+  console.error('');
+  for (const [name, { summary }] of Object.entries(SERVERS)) {
+    console.error(`  ${name.padEnd(10)} ${summary}`);
+  }
+  console.error('');
+  console.error('Each server speaks MCP over stdio and takes no CLI flags of its own —');
+  console.error('configure via environment (e.g. MCP_HTTP_PORT for gen-ui\'s HTTP transport).');
+}
+
+const [sub, ...rest] = process.argv.slice(2);
+
+// --help / -h / help print the same menu and exit 0 — asking for help is not
+// an error, unlike an unrecognized subcommand below.
+if (sub === '--help' || sub === '-h' || sub === 'help') {
+  printMenu();
+  process.exit(0);
+}
+
+const target = SERVERS[sub];
+
+if (!target) {
+  printMenu();
+  process.exit(sub ? 1 : 0);
+}
+
+const child = spawn(process.execPath, [target.path, ...rest], { stdio: 'inherit' });
+
+// Forward the signals a caller sends to THIS wrapper on to the child it
+// spawned — without this, `kill -TERM <wrapper-pid>` (or Ctrl-C reaching only
+// the wrapper in some shells/process-group setups) kills the wrapper and
+// leaves the actual MCP server running with no parent, orphaned (reviewer
+// proved it live on PR #1245). Registered before the child's own 'exit'
+// handler so a signal-caused shutdown is always a forward, never a race.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(sig, () => child.kill(sig));
+}
+
+child.on('error', (err) => {
+  console.error(`[adia-mcp] failed to start '${sub}' server: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});