@adia-ai/a2ui-mcp 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog — @adia-ai/a2ui-mcp
 
+## [0.6.7] — 2026-05-19
+
+### Added
+- **`list_patterns` tool** — enumerate the full A2UI composition corpus
+  with optional `domain` / `category` filters. Was previously only
+  searchable by keyword via `search_chunks` / `search_patterns`.
+- **`server_status` tool** — reports transport (stdio/http), sampling
+  capability, corpus stats (components, compositions, chunks), and
+  version. Useful for consumer health checks and observability.
+- **`refine_ui` tool** — retry monolithic-engine generation with validation
+  errors fed back to the LLM. Closes the missing-refine gap for the
+  monolithic path (zettel already had `refine_composition`).
+
+### Fixed
+- **HTTP transport body-parsing** — `transport.handleRequest(req, res)` was
+  not passing the express-parsed body; SDK then errored `-32700 Parse error`
+  on every request. Fixed by passing `req.body` as the third argument.
+  Surfaced by new HTTP smoke test.
+- **Excluded `.ts` source files from npm tarball** — TypeScript sources
+  were shipping alongside the emitted `.js` (7 files in mcp/, 1 in compose/,
+  16 in retrieval/). Now filtered via `files` field while keeping `.d.ts`
+  declarations.
+- **Removed unused `sessionServer` instantiation in HTTP transport** —
+  previously the HTTP request handler created a per-session `McpServer`
+  instance but never used it (called `server.connect()` against the outer
+  server). Removed the dead allocation; comment updated to reflect that
+  the outer server is shared across sessions (tools are stateless).
+
+## [0.6.6] — 2026-05-18
+
+### Changed
+- Lockstep version bump for §304 `<field-ui align>` prop.
 ## [0.6.5] — 2026-05-18
 
 ### Changed

package/README.md

@@ -2,8 +2,8 @@
 
 MCP server wrapping [`@adia-ai/a2ui-compose`](../compose). Exposes the generation
 engine, component catalog, pattern library, validator, and training
-feedback loop as stdio tools for Claude Desktop, Claude Code, and any
-other MCP-speaking host.
+feedback loop as MCP tools for Claude Desktop, Claude Code, Cursor,
+Windsurf, and any deployed MCP-capable host.
 
 > Runtime only. Generation logic lives in `@adia-ai/a2ui-compose`; UI atoms in
 > [`@adia-ai/web-components`](../../web-components); the A2UI protocol runtime
@@ -11,6 +11,24 @@ other MCP-speaking host.
 > [`@adia-ai/a2ui-runtime`](../runtime); corpus in
 > [`@adia-ai/a2ui-corpus`](../corpus).
 
+## Two transports, one server
+
+The server auto-selects transport based on environment:
+
+| Mode | When | LLM source |
+|---|---|---|
+| **stdio** (default) | Local IDE tools — Claude Code, Cursor, Hermes | Host's LLM via MCP sampling (no API key needed) |
+| **HTTP** (`MCP_HTTP_PORT`) | Deployed web service, remote MCP clients | `.env` API key required |
+
+**stdio** is the right choice for developers working inside their editor.
+The server requests LLM inference from the host (Claude Code, Cursor) via
+MCP `sampling/createMessage` — no separate API key, same model, same token
+budget the user is already paying for.
+
+**HTTP** is the right choice for a deployed backend service where clients
+connect remotely. Each client session gets its own transport instance.
+API keys must be in `.env` since no sampling-capable host is present.
+
 ## Install
 
 ```bash
@@ -19,16 +37,22 @@ npm install -g @adia-ai/a2ui-mcp     # global — exposes the `adiaui-mcp` bin
 npm install @adia-ai/a2ui-mcp        # local — invoke via npx
 ```
 
-The package ships an `adiaui-mcp` executable + a `server.js` entry point. Most MCP hosts (Claude Desktop, Claude Code) invoke the binary directly via `command` + `args` in their MCP config.
+The package ships an `adiaui-mcp` executable + a `server.js` entry point.
 
 ## Quick start
 
 ```bash
-adiaui-mcp                            # if globally installed
+# stdio (local IDE — default)
+adiaui-mcp                            # global install
 npx @adia-ai/a2ui-mcp                 # via npx
-node packages/a2ui/mcp/server.js      # from a local checkout
+node packages/a2ui/mcp/server.js      # from local checkout
+
+# HTTP (deployed service)
+MCP_HTTP_PORT=3460 node packages/a2ui/mcp/server.js
+# → POST/GET/DELETE http://0.0.0.0:3460/mcp
 ```
 
+
 Register with Claude Code (`.claude/settings.json`):
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -12,7 +12,9 @@
     "scripts/",
     "personas/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "!**/*.ts",
+    "**/*.d.ts"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -31,6 +33,10 @@
     "@adia-ai/a2ui-validator": "^0.6.0",
     "@adia-ai/a2ui-corpus": "^0.6.0",
     "@adia-ai/llm": "^0.6.0",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "express": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0"
   }
 }

package/scripts/smoke-extended.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * smoke-extended.mjs — three additional MCP smokes beyond smoke-merged.mjs.
+ *
+ *   Smoke 1: HTTP transport boots, initialize returns mcp-session-id header,
+ *            then SIGTERM cleanup.
+ *   Smoke 2: Client declares { capabilities: { sampling: {} } }; server_status
+ *            reflects sampling=true. Skip if SDK plumbing can't surface it.
+ *   Smoke 3: list_patterns, server_status, refine_ui appear in tools/list and
+ *            each is callable without throwing.
+ *
+ * Exit codes:
+ *   0 — all smokes passed (or skipped with clear reason)
+ *   1 — at least one smoke failed
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = join(__dirname, '..', 'server.js');
+
+const results = [];
+function record(name, status, detail = '') {
+  results.push({ name, status, detail });
+  const icon = status === 'PASS' ? '✓' : status === 'SKIP' ? '○' : '✗';
+  console.log(`${icon} ${name}: ${status}${detail ? ` — ${detail}` : ''}`);
+}
+
+// ---------------------------------------------------------------------------
+// Smoke 1 — HTTP transport startup + initialize
+// ---------------------------------------------------------------------------
+async function smokeHttp() {
+  const PORT = 33460;
+  const child = spawn('node', [serverPath], {
+    env: { ...process.env, MCP_HTTP_PORT: String(PORT) },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  // Cleanup helpers — guarantee child is killed even on uncaught errors.
+  let killed = false;
+  const cleanup = () => {
+    if (killed) return;
+    killed = true;
+    try { child.kill('SIGTERM'); } catch {}
+    // Force-kill after 2s if SIGTERM ignored.
+    setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, 2000).unref();
+  };
+  process.once('SIGINT', cleanup);
+  process.once('SIGTERM', cleanup);
+  process.once('exit', cleanup);
+
+  try {
+    // Wait for "HTTP transport ready" on stderr (server.js logs there).
+    const ready = await new Promise((resolve, reject) => {
+      let buf = '';
+      const timer = setTimeout(() => reject(new Error('timeout waiting for HTTP ready')), 15000);
+      child.stderr.on('data', (chunk) => {
+        buf += chunk.toString();
+        if (/HTTP transport ready/.test(buf)) {
+          clearTimeout(timer);
+          resolve(buf);
+        }
+      });
+      child.on('exit', (code) => {
+        clearTimeout(timer);
+        reject(new Error(`server exited early (code=${code}); stderr:\n${buf}`));
+      });
+    });
+
+    // Small grace period to let express bind.
+    await delay(100);
+
+    // Use the SDK's HTTP client transport to drive a real initialize handshake.
+    // We extract the session id by intercepting the underlying fetch — the
+    // transport itself doesn't expose the header directly, but we can sniff it
+    // by overriding global fetch for the duration of the connect.
+    let sniffedSessionId = null;
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = async (...args) => {
+      const res = await realFetch(...args);
+      const sid = res.headers.get?.('mcp-session-id');
+      if (sid && !sniffedSessionId) sniffedSessionId = sid;
+      return res;
+    };
+
+    const httpTransport = new StreamableHTTPClientTransport(
+      new URL(`http://127.0.0.1:${PORT}/mcp`),
+    );
+    const client = new Client(
+      { name: 'smoke-extended-http', version: '0.0.1' },
+      { capabilities: {} },
+    );
+
+    try {
+      await client.connect(httpTransport);
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+
+    if (!sniffedSessionId) {
+      record('smoke-1-http', 'FAIL',
+        'initialize handshake succeeded but no mcp-session-id header observed');
+    } else {
+      record('smoke-1-http', 'PASS',
+        `session=${sniffedSessionId.slice(0, 8)}… initialize ok`);
+    }
+    try { await client.close(); } catch {}
+  } catch (e) {
+    // The current server.js calls `transport.handleRequest(req, res)` without
+    // passing the express-parsed body as the 3rd arg. The SDK then tries to
+    // re-read the already-consumed stream and emits a -32700 Parse error.
+    // Surface this clearly so the parent agent can patch server.js.
+    const hint = /Parse error: Invalid JSON/.test(e.message)
+      ? '\n      → Likely fix: in packages/a2ui/mcp/server.js startHttp(), change\n        `transport.handleRequest(req, res)` → `transport.handleRequest(req, res, req.body)`\n        (express.json() consumes the stream before the SDK can re-read it).'
+      : '';
+    record('smoke-1-http', 'FAIL', e.message + hint);
+  } finally {
+    cleanup();
+    // Wait briefly for child exit so its log doesn't bleed into later smokes.
+    await new Promise((r) => {
+      if (child.exitCode !== null) return r();
+      child.once('exit', r);
+      setTimeout(r, 2500).unref();
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Smoke 2 — Sampling capability detection
+// ---------------------------------------------------------------------------
+async function smokeSampling() {
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: [serverPath],
+    stderr: 'ignore',
+  });
+  // The SDK Client constructor takes (info, options); options.capabilities
+  // is sent in the initialize handshake.
+  const client = new Client(
+    { name: 'smoke-extended-sampling', version: '0.0.1' },
+    { capabilities: { sampling: {} } },
+  );
+
+  try {
+    await client.connect(transport);
+    const r = await client.callTool({ name: 'server_status', arguments: {} });
+    const text = r.content?.[0]?.text ?? '';
+    let parsed;
+    try { parsed = JSON.parse(text); }
+    catch { record('smoke-2-sampling', 'FAIL', `non-JSON server_status: ${text.slice(0, 120)}`); return; }
+    if (parsed.sampling === true) {
+      record('smoke-2-sampling', 'PASS', `server_status.sampling=true (transport=${parsed.transport})`);
+    } else {
+      // Server didn't reflect the capability — this is a real finding, not a skip,
+      // because we explicitly declared { sampling: {} } in the client init options.
+      record('smoke-2-sampling', 'FAIL',
+        `client declared sampling but server_status.sampling=${parsed.sampling}. ` +
+        `Check resolveAdapter / capability propagation in server.js.`);
+    }
+  } catch (e) {
+    record('smoke-2-sampling', 'FAIL', e.message);
+  } finally {
+    try { await client.close(); } catch {}
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Smoke 3 — New tools registered & callable
+// ---------------------------------------------------------------------------
+async function smokeNewTools() {
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: [serverPath],
+    stderr: 'ignore',
+  });
+  const client = new Client(
+    { name: 'smoke-extended-tools', version: '0.0.1' },
+    { capabilities: {} },
+  );
+
+  const want = ['list_patterns', 'server_status', 'refine_ui'];
+  const failures = [];
+  try {
+    await client.connect(transport);
+    const tl = await client.listTools();
+    const names = new Set(tl.tools.map((t) => t.name));
+    const missing = want.filter((n) => !names.has(n));
+    if (missing.length > 0) {
+      record('smoke-3-tools', 'FAIL', `missing from tools/list: ${missing.join(', ')}`);
+      return;
+    }
+
+    // list_patterns — should return JSON with a `patterns` array.
+    {
+      const r = await client.callTool({ name: 'list_patterns', arguments: {} });
+      const text = r.content?.[0]?.text ?? '';
+      try {
+        const p = JSON.parse(text);
+        if (!Array.isArray(p.patterns)) failures.push(`list_patterns: no patterns array (got keys: ${Object.keys(p).join(',')})`);
+      } catch (e) {
+        failures.push(`list_patterns: non-JSON response (${e.message})`);
+      }
+    }
+
+    // server_status — should return JSON with version + transport + sampling fields.
+    {
+      const r = await client.callTool({ name: 'server_status', arguments: {} });
+      const text = r.content?.[0]?.text ?? '';
+      try {
+        const s = JSON.parse(text);
+        for (const k of ['version', 'transport', 'sampling', 'corpus']) {
+          if (!(k in s)) failures.push(`server_status: missing field "${k}"`);
+        }
+      } catch (e) {
+        failures.push(`server_status: non-JSON response (${e.message})`);
+      }
+    }
+
+    // refine_ui — invoke with minimal args. Without an LLM adapter / API keys
+    // this may return an error inside content (that's fine — tool didn't throw).
+    // A thrown JSON-RPC error is a hard failure.
+    try {
+      const r = await client.callTool({
+        name: 'refine_ui',
+        arguments: {
+          intent: 'smoke test',
+          previousMessages: [],
+          validationErrors: [{ code: 'smoke', message: 'noop' }],
+        },
+      });
+      const text = r.content?.[0]?.text ?? '';
+      // Accept either a parseable JSON object (success or {error:...}) or any
+      // string — what matters is that the tool ran without throwing at the
+      // transport layer.
+      if (!text) failures.push('refine_ui: empty content array');
+    } catch (e) {
+      // Allow LLM-adapter-related errors (no API key in CI) since the tool's
+      // schema-side is what we're smoking, not the LLM call.
+      const msg = String(e?.message || e);
+      if (!/adapter|api.?key|ANTHROPIC|OPENAI|provider|model/i.test(msg)) {
+        failures.push(`refine_ui: unexpected throw: ${msg}`);
+      } else {
+        console.log(`  (refine_ui: tolerated LLM-adapter error — ${msg.slice(0, 80)})`);
+      }
+    }
+
+    if (failures.length === 0) {
+      record('smoke-3-tools', 'PASS', `${want.join(', ')} all callable`);
+    } else {
+      record('smoke-3-tools', 'FAIL', failures.join('; '));
+    }
+  } catch (e) {
+    record('smoke-3-tools', 'FAIL', e.message);
+  } finally {
+    try { await client.close(); } catch {}
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+console.log('=== MCP extended smoke ===');
+await smokeHttp();
+await smokeSampling();
+await smokeNewTools();
+
+const failed = results.filter((r) => r.status === 'FAIL');
+console.log(`\nSummary: ${results.length - failed.length}/${results.length} passed (${failed.length} failed)`);
+process.exit(failed.length === 0 ? 0 : 1);