@adia-ai/mcp 0.8.38 → 0.8.39

package/CHANGELOG.md

@@ -9,6 +9,14 @@
 > entire changelog was still `[Unreleased]` at fold time (minted at ADR-0048 P4,
 > never released under its own name) and is merged into the section below.
 
+## [0.8.39] — 2026-08-15
+
+### Added
+- **`get_catalog_ladder` on the `protocol` server (ADR-0050, gh#1291 phase 3) — 4 → 5 tools there (all-server total 43: gen-ui 31 · protocol 5 · factory 7).** ADR-0050's serving map gives the protocol server L0+L1; phase 1 held it at four tools because an L0-only enumerate tool duplicates `get_registry_map`. With L1 populated (44 curated widgets) the tool earns its place: an L1 entry carries its A2UI `template`, so a chat agent can enumerate a widget and emit it with no generation system and no corpus. No arguments returns the ladder summary — all five rungs with unit/composesTier/status/count plus a `servedHere` flag and the serving map in prose, so a client learns where L2–L4 live; `tier` (a two-value enum, `L0`|`L1`, so an unserved rung is refused at the schema rather than answered emptily) lists that rung's entry names; `tier` + `name` returns one entry's full record. **Isolation is unchanged by construction** — the tier index is data inside the zero-dependency `@adia-ai/a2ui` (`./catalog/tiers`), so the P4 module-graph walk still proves zero reach into `@adia-ai/gen-ui`/`@adia-ai/llm`/`@adia-ai/agent`. Zero tool-name overlap across the three servers (the factory smoke's ADR-0051 §4 assertion). **Purely additive** — no existing tool's input or output shape changed, so no versioning event; `protocol_status` deliberately did not grow catalog counters, which would have been an output-contract change for cosmetic value. gen-ui's `get_catalog_tiers` (all five rungs, for retrieval) is unchanged.
+
+### Maintenance
+- **`bin/` touched in this release window** (1 file(s), e.g. `bin/adia-mcp`) — carried by the entries above.
+
 ## [0.8.38] — 2026-08-15
 
 ### Added

package/README.md

@@ -152,13 +152,13 @@ Wraps [`@adia-ai/a2ui`](../a2ui) and nothing else. `@adia-ai/gen-ui` and
 `@adia-ai/llm` are deliberate **non**-dependencies of this surface — see
 [Why a separate server](#why-a-separate-server-not-just-a-shared-one).
 
-Four tools, no API key, no `.env`, **stdio only** (no HTTP mode — express and
+Five tools, no API key, no `.env`, **stdio only** (no HTTP mode — express and
 session-sweep belong to `gen-ui`): `validate_document` · `get_registry_map` ·
-`get_wiring_registry` · `protocol_status`.
+`get_wiring_registry` · `get_catalog_ladder` · `protocol_status`.
 
 ```bash
 node packages/gen-ui/mcp/protocol/server.js       # stdio only
-npm run mcp:protocol:smoke                 # boot + exercise all 4 tools + isolation proof
+npm run mcp:protocol:smoke                 # boot + exercise all 5 tools + isolation proof
 ```
 
 ### Tool name disambiguation
@@ -265,7 +265,7 @@ npm run build:protocol-mcp-server   # protocol: server.ts + tools/*.ts -> .js (e
 npm run build:factory-mcp-server    # factory: server.ts + tools/*.ts -> .js (esbuild)
 npm run build:factory-mcp-assets    # factory: re-vendor scripts + re-derive doctrine resources from the plugin
 npm run mcp:smoke                   # gen-ui: boot over stdio, exercise all 31 tools
-npm run mcp:protocol:smoke          # protocol: boot over stdio, exercise all 4 tools + isolation proof
+npm run mcp:protocol:smoke          # protocol: boot over stdio, exercise all 5 tools + isolation proof
 npm run mcp:factory:smoke           # factory: asset freshness + boot + tools + zero-overlap/parity/isolation proofs
 npm run build:mcp-tools-md          # regenerate TOOLS.md (all three servers, sectioned) from the live tool lists
 ```

package/TOOLS.md

@@ -509,9 +509,9 @@ The A2UI **protocol** MCP server (`adia-mcp protocol`, `server.js`) exposes tool
 
 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).
+Every tool name here is DISTINCT from the gen-ui and factory servers' surfaces (gh#1248 renamed the original four off their 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`), `get_registry_map` (type → tag, no descriptions or prop schemas; gen-ui's `get_component_map`), and `get_catalog_ladder` (the L0+L1 rungs ADR-0050's serving map puts on this server; gen-ui's `get_catalog_tiers` serves the whole ladder for retrieval). `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**.
+This server exposes **5 tools**.
 
 ### Tool index
 
@@ -519,6 +519,7 @@ This server exposes **4 tools**.
 |---|---|
 | **Validation** | [`validate_document`](#protocol-validate_document) |
 | **Registry introspection** | [`get_registry_map`](#protocol-get_registry_map), [`get_wiring_registry`](#protocol-get_wiring_registry) |
+| **Catalog contract** | [`get_catalog_ladder`](#protocol-get_catalog_ladder) |
 | **Status** | [`protocol_status`](#protocol-protocol_status) |
 
 #### Validation
@@ -557,6 +558,23 @@ Read live from the runtime's wiringRegistry, so it cannot drift from what the re
 
 _No arguments._
 
+#### Catalog contract
+
+<a id="protocol-get_catalog_ladder"></a>
+
+##### `get_catalog_ladder`
+
+Enumerate the AdiaUI catalog contract's served rungs: L0 primitives (component vocabulary) and L1 widgets (named, versioned, chat-scale functional units — a Row of stat cards, a sign-in card, a tool-call accordion). An L1 entry carries its A2UI `template`, so this is the tool to call before generating a document by hand: find the widget, take its template, fill in the copy.
+
+Called with no arguments it returns the ladder summary — every rung with its entry unit, the rung it composes, populated/reserved status, and entry count. Pass `tier` ("L0" or "L1") for that rung's entry names; pass `tier` + `name` for one entry's full record (`composes`, `template`, `keywords`, `domain`, provenance).
+
+Scope, per ADR-0050's serving map: this server serves **L0 + L1** — the rungs a chat agent enumerates to emit A2UI. L2 layouts, L3 shells, and L4 flows are developer-facing and belong to the factory surface; `adia-mcp gen-ui`'s `get_catalog_tiers` serves the whole ladder for retrieval. The ladder's one law is that every tier-N entry is a declared composition of tier-(N-1) entries, so `composes` is the edge you follow down a rung — an L1 entry's `composes` names L0 types you can validate with `validate_document`.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `tier` | `L0` \| `L1` | no | — | List one served rung's entry names instead of the ladder summary |
+| `name` | string | no | — | With `tier` (required alongside it), return this single entry's full record |
+
 #### Status
 
 <a id="protocol-protocol_status"></a>
@@ -567,7 +585,7 @@ Returns operational status of this A2UI protocol MCP server: transport and proto
 
 _No arguments._
 
-Tools on this server (4): `get_registry_map`, `get_wiring_registry`, `protocol_status`, `validate_document`.
+Tools on this server (5): `get_catalog_ladder`, `get_registry_map`, `get_wiring_registry`, `protocol_status`, `validate_document`.
 
 ---
 

package/bin/adia-mcp

@@ -10,7 +10,7 @@
  *
  *   adia-mcp gen-ui    — the generation server (31 tools: compose, corpus,
  *                        retrieval, feedback/eval loop)
- *   adia-mcp protocol  — the A2UI protocol server (4 tools: validate + registry
+ *   adia-mcp protocol  — the A2UI protocol server (5 tools: validate + registry
  *                        introspection; no generation system, no model client)
  *   adia-mcp factory   — the adia-factory server (7 tools: orient, scaffold,
  *                        audit, surface QA — the factory plugin's gated
@@ -54,7 +54,7 @@ const SERVERS = {
   },
   protocol: {
     path: join(__dirname, '..', 'protocol', 'server.js'),
-    summary: '4-tool protocol server (validate + registry introspection; no gen-ui, no llm)',
+    summary: '5-tool protocol server (validate + registry introspection + L0/L1 catalog rungs; no gen-ui, no llm)',
   },
   factory: {
     path: join(__dirname, '..', 'factory', 'server.js'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/mcp",
-  "version": "0.8.38",
-  "description": "AdiaUI's three MCP servers, one npm package (gh#1240, ADR-0051). `adia-mcp gen-ui` — the 30-tool generation server (compose engine, corpus, retrieval, feedback/eval loop). `adia-mcp protocol` — the 4-tool A2UI protocol server (validate + registry introspection, no generation system, no model client). `adia-mcp factory` — the 7-tool adia-factory server (orient, scaffold, audit, surface QA for building adia-ui apps from any MCP harness; no generation system, no model client). ADR-0048 §3's distinct-server decision is unchanged; only the distribution unified.",
+  "version": "0.8.39",
+  "description": "AdiaUI's three MCP servers, one npm package (gh#1240, ADR-0051). `adia-mcp gen-ui` — the 31-tool generation server (compose engine, corpus, retrieval, feedback/eval loop). `adia-mcp protocol` — the 5-tool A2UI protocol server (validate + registry introspection + the L0/L1 catalog-contract rungs, no generation system, no model client). `adia-mcp factory` — the 7-tool adia-factory server (orient, scaffold, audit, surface QA for building adia-ui apps from any MCP harness; no generation system, no model client). ADR-0048 §3's distinct-server decision is unchanged; only the distribution unified.",
   "type": "module",
   "bin": {
     "adia-mcp": "./bin/adia-mcp"

package/protocol/server.d.ts

@@ -1,8 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
- * Builds the A2UI protocol MCP server (4 tools: validate_document,
- * get_registry_map, get_wiring_registry, protocol_status) with no transport
+ * Builds the A2UI protocol MCP server (5 tools: validate_document,
+ * get_registry_map, get_wiring_registry, get_catalog_ladder, protocol_status)
+ * with no transport
  * attached. Exported for tests and for `scripts/build/generate-mcp-tools-md.mjs`;
  * the module's own top-level `isEntryPoint()` guard is what actually starts a
  * stdio transport when this file is run directly (`node server.js`), not when

package/protocol/server.js

@@ -16,7 +16,7 @@ async function main() {
   const server = createServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("[a2ui-protocol-mcp] stdio transport ready (4 protocol tools)");
+  console.error("[a2ui-protocol-mcp] stdio transport ready (5 protocol tools)");
 }
 function isEntryPoint() {
   if (typeof process === "undefined" || !process.argv[1]) return false;

package/protocol/tools/protocol.js

@@ -10,6 +10,11 @@ This is the registry view \u2014 the authoritative answer to "what types exist a
 const GET_WIRING_REGISTRY_DESCRIPTION = `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 \u2014 see gen-ui-mcp's \`get_wiring_catalog\` tool instead.`;
+const GET_CATALOG_LADDER_DESCRIPTION = `Enumerate the AdiaUI catalog contract's served rungs: L0 primitives (component vocabulary) and L1 widgets (named, versioned, chat-scale functional units \u2014 a Row of stat cards, a sign-in card, a tool-call accordion). An L1 entry carries its A2UI \`template\`, so this is the tool to call before generating a document by hand: find the widget, take its template, fill in the copy.
+
+Called with no arguments it returns the ladder summary \u2014 every rung with its entry unit, the rung it composes, populated/reserved status, and entry count. Pass \`tier\` ("L0" or "L1") for that rung's entry names; pass \`tier\` + \`name\` for one entry's full record (\`composes\`, \`template\`, \`keywords\`, \`domain\`, provenance).
+
+Scope, per ADR-0050's serving map: this server serves **L0 + L1** \u2014 the rungs a chat agent enumerates to emit A2UI. L2 layouts, L3 shells, and L4 flows are developer-facing and belong to the factory surface; \`adia-mcp gen-ui\`'s \`get_catalog_tiers\` serves the whole ladder for retrieval. The ladder's one law is that every tier-N entry is a declared composition of tier-(N-1) entries, so \`composes\` is the edge you follow down a rung \u2014 an L1 entry's \`composes\` names L0 types you can validate with \`validate_document\`.`;
 const PROTOCOL_STATUS_DESCRIPTION = `Returns operational status of this A2UI protocol MCP server: transport and protocol-registry stats. Reports on the protocol server only \u2014 gen-ui-mcp's \`server_status\` tool reports its own corpus-side status separately.`;
 function buildRegistryView() {
   const byTag = /* @__PURE__ */ new Map();
@@ -25,6 +30,14 @@ function buildRegistryView() {
   })).sort((a, b) => a.type.localeCompare(b.type));
   return { totalTypes: registry.size, totalTags: byTag.size, entries };
 }
+const SERVED_TIERS = ["L0", "L1"];
+let _tierIndex = null;
+async function loadTierIndex() {
+  if (_tierIndex) return _tierIndex;
+  const mod = await import("@adia-ai/a2ui/catalog/tiers", { with: { type: "json" } });
+  _tierIndex = mod.default ?? mod;
+  return _tierIndex;
+}
 function buildWiringView() {
   return {
     controllers: [...wiringRegistry.controllers.keys()].sort(),
@@ -68,6 +81,116 @@ function registerProtocolTools(server) {
       return { content: [{ type: "text", text: JSON.stringify(buildWiringView(), null, 2) }] };
     }
   );
+  server.tool(
+    "get_catalog_ladder",
+    GET_CATALOG_LADDER_DESCRIPTION,
+    {
+      tier: z.enum(["L0", "L1"]).optional().describe("List one served rung's entry names instead of the ladder summary"),
+      name: z.string().optional().describe("With `tier` (required alongside it), return this single entry's full record")
+    },
+    async ({ tier, name }) => {
+      if (name && !tier) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\`name\` needs a \`tier\`: entry names are unique only within a rung. Retry with { tier: "L1", name: "${name}" } (or "L0"), or omit \`name\` for the ladder summary.`
+            }
+          ],
+          isError: true
+        };
+      }
+      let index;
+      try {
+        index = await loadTierIndex();
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return {
+          content: [{ type: "text", text: `Catalog tier index unavailable: ${e.message}` }],
+          isError: true
+        };
+      }
+      if (!tier) {
+        const ladder = Object.fromEntries(
+          Object.entries(index.tiers).map(([id, t]) => [
+            id,
+            {
+              unit: t.unit,
+              composesTier: t.composesTier,
+              status: t.status,
+              count: t.count,
+              servedHere: SERVED_TIERS.includes(id)
+            }
+          ])
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  catalogId: index.catalogId,
+                  servedTiers: [...SERVED_TIERS],
+                  servingMap: "protocol server: L0+L1 (this tool) \xB7 gen-ui server: all tiers, for retrieval (get_catalog_tiers) \xB7 factory server: L2-L4, developer-facing",
+                  ladder
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+      const rung = index.tiers[tier];
+      if (!rung) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Tier "${tier}" is absent from the catalog tier index (${Object.keys(index.tiers).join(", ")} present) \u2014 the index may predate it.`
+            }
+          ],
+          isError: true
+        };
+      }
+      if (name) {
+        const entry = rung.entries[name];
+        if (!entry) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No ${tier} entry named "${name}". ${rung.count} entries in this tier \u2014 call this tool with just \`tier\` for the names.`
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify({ tier, name, entry }, null, 2) }]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                tier,
+                unit: rung.unit,
+                composesTier: rung.composesTier,
+                status: rung.status,
+                count: rung.count,
+                entries: Object.keys(rung.entries).sort()
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
   server.tool(
     "protocol_status",
     PROTOCOL_STATUS_DESCRIPTION,