@adia-ai/mcp 0.8.37

package/README.md

@@ -0,0 +1,210 @@
+# @adia-ai/mcp
+
+**Two MCP servers, one npm package, one bin.** ADR-0048 §3 ruled two distinct
+servers ("they do different things"); gh#1240 (operator ruling 2026-08-14)
+unified only the *distribution* — before either predecessor name
+(`@adia-ai/gen-ui-mcp`, `@adia-ai/a2ui-protocol-mcp`) ever published a 0.8.x —
+into this one package.
+
+| You want to… | Run |
+|---|---|
+| Generate UI from an intent, search the training corpus, run evals, catalog-aware validation + anti-pattern scoring | `adia-mcp gen-ui` |
+| Check that an A2UI document is well-formed, whoever produced it; see which component types/wiring exist with no corpus and no model | `adia-mcp protocol` |
+| See the two-server menu | `adia-mcp` (bare) |
+
+**The protocol server's four tool names are distinct from the gen-ui
+server's** (gh#1248 renamed them off their original same-named forms before
+the protocol server ever published) — each still has a narrower,
+protocol-only counterpart on `gen-ui`; see
+[Tool name disambiguation](#tool-name-disambiguation) for the mapping if you
+have both servers installed.
+
+## Install
+
+```bash
+npm install -g @adia-ai/mcp     # global — exposes the `adia-mcp` bin
+# OR
+npm install @adia-ai/mcp        # local — invoke via npx
+```
+
+Claude Desktop / Cursor / any MCP host, `mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "adia-ui": {
+      "command": "npx",
+      "args": ["-y", "@adia-ai/mcp", "gen-ui"]
+    },
+    "a2ui-protocol": {
+      "command": "npx",
+      "args": ["-y", "@adia-ai/mcp", "protocol"]
+    }
+  }
+}
+```
+
+From a local checkout:
+
+```bash
+node packages/mcp/bin/adia-mcp gen-ui       # stdio, local IDE
+node packages/mcp/bin/adia-mcp protocol     # stdio, protocol-only
+MCP_HTTP_PORT=3460 node packages/mcp/bin/adia-mcp gen-ui   # HTTP transport (gen-ui only)
+```
+
+## `gen-ui` — the generation server
+
+Wraps [`@adia-ai/gen-ui`](../gen-ui/compose). Exposes the generation engine,
+component catalog, pattern library, validator, and training feedback loop as
+**30 MCP tools** for Claude Desktop, Claude Code, Cursor, Windsurf, and any
+deployed MCP-capable host.
+
+> Runtime only. Generation logic lives in `@adia-ai/gen-ui`; UI atoms in
+> [`@adia-ai/web-components`](../web-components); the A2UI protocol runtime
+> (renderer, registry, streams, wiring) in [`@adia-ai/a2ui`](../a2ui); corpus
+> in [`@adia-ai/gen-ui/corpus`](../gen-ui/corpus).
+
+### Two transports, one tool surface
+
+| 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** requests LLM inference from the host via MCP `sampling/createMessage`
+— no separate API key, same model, same token budget the user is already
+paying for. **HTTP** gives each session its own transport **and its own
+`McpServer`** (the SDK binds one transport per server instance); corpus,
+catalog and chunk index stay process-wide and shared.
+
+#### Session idle TTL (HTTP only)
+
+| Env | Default | Meaning |
+|---|---|---|
+| `MCP_SESSION_TTL_MS` | `1800000` (30 min) | Idle time before a session is evicted. `0` or negative disables eviction entirely. |
+
+Every request refreshes a session's last-activity stamp; an idle-evicted
+session's next request gets the same `-32001` an unknown session id gets —
+re-`initialize` to continue. stdio has no sessions and is unaffected.
+
+### Quick start
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-…   # at least one provider key, for generate_ui
+adia-mcp gen-ui                                        # global install, stdio
+npx @adia-ai/mcp gen-ui                                # via npx
+node packages/mcp/gen-ui/server.js                     # from local checkout
+MCP_HTTP_PORT=3460 node packages/mcp/gen-ui/server.js  # HTTP → 0.0.0.0:3460/mcp
+```
+
+### Tools
+
+**See [`TOOLS.md`](./TOOLS.md) for the full reference** (both servers,
+sectioned) — tool names, descriptions, grouping, argument schemas. Quick map
+for `gen-ui`:
+
+| Group | Tools |
+|---|---|
+| **Generation** | `generate_ui`, `refine_ui` |
+| **Discovery** | `get_component_map`, `lookup_component`, `lookup_chunk`, `get_traits`, `get_wiring_catalog`, `list_patterns`, `server_status` |
+| **Retrieval** | `search_chunks`, `get_chunk`, `search_patterns`, `get_composition`, `get_graph`, `resolve_composition`, `zettel_stats` |
+| **Synthesis + state** | `compose_from_chunks`, `refine_composition`, `get_state`, `report_issue` |
+| **Intent + context** | `plan_app_state`, `classify_intent`, `assemble_context` |
+| **Validation + conversion** | `validate_schema`, `check_anti_patterns`, `convert_html` |
+| **Feedback + evaluation** | `submit_feedback`, `get_quality_metrics`, `get_training_gaps`, `run_eval` |
+
+### Layout
+
+```
+gen-ui/
+├── server.js      MCP bootstrap — registers tools inline; the rest live in tools/ modules
+├── scripts/       Standalone runners (smoke tests, eval diffs, visual validate)
+├── tools/         tool modules: synthesis · validation · feedback · corpus · zettel · discovery · refine
+└── evals/         held-out eval fixtures
+```
+
+### Gotchas
+
+- **Corpus load is noisy.** The zettel composer prints stats to stderr on
+  first invocation. Callers expecting silent MCP should swallow stderr.
+- **API keys must be set before the server starts.** Changing env vars
+  mid-session doesn't hot-reload adapters.
+- **Engine selector is internal.** Don't pass `engine: 'mcp'` — the generator
+  picks `monolithic` vs `zettel` from intent + mode.
+- **Multi-turn state is per-process, in-memory, ephemeral.** Restarting the
+  server drops every multi-turn chain in flight. Checkpoint the canvas to your
+  own store between turns and pass `currentCanvas` on resume rather than
+  relying on `executionId`/`sessionId` for durability.
+
+## `protocol` — the A2UI protocol server
+
+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
+session-sweep belong to `gen-ui`): `validate_document` · `get_registry_map` ·
+`get_wiring_registry` · `protocol_status`.
+
+```bash
+node packages/mcp/protocol/server.js       # stdio only
+npm run mcp:protocol:smoke                 # boot + exercise all 4 tools + isolation proof
+```
+
+### Tool name disambiguation
+
+**Until gh#1248, all four of these tool names were shared with `gen-ui`, each
+returning a different shape depending on which server answered — a host with
+both installed saw each name twice.** The protocol server had never
+published, so gh#1248 (adversarial-review finding F7, 2026-08-14) renamed all
+four off their original same-named forms while the cost was still zero. Each
+renamed tool keeps its narrower, protocol-only counterpart on `gen-ui`:
+
+| Tool (`protocol`) | Counterpart (`gen-ui`) | `protocol` shape | `gen-ui` shape |
+|---|---|---|---|
+| `validate_document` | `validate_schema` | protocol verdict only | same verdict **plus** a `catalog` key (AJV against the v0.9 catalog) and anti-pattern scoring |
+| `get_registry_map` | `get_component_map` | `{ totalTypes, totalTags, entries: [{ type, tag, aliases }] }` | newline-delimited `Type -> <tag>: description` text from the catalog |
+| `get_wiring_registry` | `get_wiring_catalog` | `{ controllers, handlers, uriSchemes }` — **names only**, read live from the runtime registry | the full authoring knowledge base: UI event payloads, refresh strategies, value sources, association types, per-controller config/commands/bind |
+| `protocol_status` | `server_status` | transport + protocol-registry stats | transport, sampling capability, corpus stats |
+
+That asymmetry is the point — `protocol` answers questions about the standard
+itself (any producer's document), `gen-ui` answers questions about this
+producer's catalog. The rename only changed how a client asks; it changed
+neither shape.
+
+### Why a separate server (not just a shared one)
+
+ADR-0048 Decision §3 and `.claude/docs/specs/a2ui-gen-ui-split.md` ## Interfaces
+▸ MCP partition: the MCP SDK and zod would otherwise become dependencies of
+every embedding host that only needs to render a canvas and validate
+documents against the standard, with no need for the generation engine or a
+model client. Two servers keep that boundary at the process level, not just
+the package level; gh#1240 only moved where the two servers' code and npm
+manifest live, not that boundary.
+
+## Package exports
+
+`package.json`'s `exports` map declares exactly two subpaths — `./gen-ui/server.js`
+and `./protocol/server.js` — the two entry points the `packages/shims/a2ui-mcp`
+bin forwarder and the packed-boot probe reach by deep import
+(`@adia-ai/mcp/gen-ui/server.js`). This is an explicit **invariant**, not an
+accident of omission: without a declared `exports` map every file in `files`
+is deep-importable by default, which is what let that resolution work before
+this map existed. Adding ANY future subpath key here is fine; removing or
+renarrowing either of the two above breaks the shim silently for anyone still
+on the retired `@adia-ai/a2ui-mcp` name. Re-run `npm run probe:packed-boot`
+and `node scripts/verify/check-shim-bridges.mjs` after touching this map.
+
+## Local development
+
+```bash
+npm run build:mcp-server            # gen-ui: server.ts + tools/*.ts -> .js (esbuild)
+npm run build:protocol-mcp-server   # protocol: server.ts + tools/*.ts -> .js (esbuild)
+npm run mcp:smoke                   # gen-ui: boot over stdio, exercise all 30 tools
+npm run mcp:protocol:smoke          # protocol: boot over stdio, exercise all 4 tools + isolation proof
+npm run build:mcp-tools-md          # regenerate TOOLS.md (both servers, sectioned) from the live tool lists
+```
+
+## License
+
+MIT