@dreamtree-org/twreact-ui 1.1.50 → 1.1.52

package/mcp/README.md

@@ -0,0 +1,83 @@
+# dreamtree-ui MCP server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
+`@dreamtree-org/twreact-ui` to AI agents: a coding agent can **discover the
+catalog, fetch authoritative prop contracts, search by capability, and read the
+docs — live**, instead of guessing prop names or copy-pasting from memory.
+
+This is the concrete delivery of the project's **AI-native moat** (roadmap issue
+[#61](https://github.com/DreamtreeTech/dreamtree-ui/issues/61)): something a
+copy-paste generator like shadcn/ui structurally cannot offer.
+
+## What it serves
+
+**Tools**
+| Tool | Args | Returns |
+| --- | --- | --- |
+| `list_components` | — | The full grouped catalog (core / feedback / navigation / utility + hooks + utils) with descriptions. |
+| `get_component` | `name` | One component's spec: import line, props (name/type/default/description), variants, sizes, examples, family exports, a11y + convention notes. Accepts a family-export name (`useToast` → `Toast`). |
+| `search_components` | `query` | Ranked matches across names, family exports, descriptions, prop names, and examples. |
+
+**Resources**
+- `dreamtree://skill` — the consumer AI usage guide (`ai-skills/dreamtree-ui.md`).
+- `dreamtree://docs/<Component>` — the per-component manual (`doc/<Component>.md`), one per documented component.
+
+**Prompt**
+- `compose_ui` (optional `task` arg) — primes an agent to build UI with the library correctly (vocabulary, providers, the get_component-before-use rule).
+
+## Single source of truth
+
+The catalog (`catalog.mjs`) is **derived, not hand-maintained**: it reads the
+public exports from `src/index.js` (names + group via import path) and the
+props/examples from `doc/<Component>.md`. Keep those accurate and the MCP server
+stays truthful automatically. There is no duplicate component list to drift.
+
+## Run it
+
+```bash
+# from the repo root
+npm run mcp          # node mcp/server.mjs  (stdio transport)
+npm run mcp:smoke    # end-to-end check: boots the server, exercises every tool/resource/prompt
+```
+
+It speaks MCP over **stdio** — logs go to stderr, the protocol uses stdout.
+
+## Use it from Claude Code (this repo)
+
+Already wired in [`.mcp.json`](../.mcp.json):
+
+```json
+{
+  "mcpServers": {
+    "dreamtree-ui": { "command": "node", "args": ["mcp/server.mjs"] }
+  }
+}
+```
+
+Open this repo in Claude Code and the `dreamtree-ui` tools/resources are
+available. The companion Claude Code skill at
+`.claude/skills/dreamtree-ui/SKILL.md` tells the agent to query these tools
+before composing UI.
+
+## Use it from another MCP client
+
+Point any MCP client at `node /path/to/dreamtree-ui/mcp/server.mjs`. It needs
+this repo present (the catalog reads `src/index.js` + `doc/`).
+
+## Repo-local vs shipped — both in this package
+
+- **Live server (`mcp/server.mjs`)** — reads `src/index.js` + `doc/*.md` live
+  via `mcp/catalog.mjs`. It's what `.mcp.json` and `npm run mcp` run.
+- **Shipped server** — consumers run `npx -y @dreamtree-org/twreact-ui mcp`
+  (the `mcp` subcommand of the library's bin, `bin/cli.mjs`). Since `src/` and
+  `doc/` aren't in the published tarball, it reads a frozen build-time
+  **snapshot** (`mcp/catalog.snapshot.json`) via `mcp/catalog-snapshot.mjs`.
+
+Both import the same handlers (`server-core.mjs`) and pure queries
+(`catalog-core.mjs`) — single source of truth, nothing copied.
+`npm run mcp:snapshot` regenerates the one generated artifact,
+`mcp/catalog.snapshot.json`. The MCP SDK is a runtime `dependency` of the
+library, lazy-imported only by the `mcp` subcommand (never in a consumer's app
+bundle). See
+[`docs/agents/11-mcp-sync.md §7`](../docs/agents/11-mcp-sync.md#7-consumer-distribution--bundled-in-the-main-package)
+(delivered under #74 / the moat in #61).

package/mcp/catalog-core.mjs

@@ -0,0 +1,44 @@
+// Pure catalog queries — no filesystem, no data source.
+// ---------------------------------------------------------------------------
+// These operate on an already-built catalog object (the shape returned by
+// buildCatalog()), so they are identical whether the catalog came from the
+// live source (mcp/catalog.mjs, reads src/ + doc/) or the frozen snapshot
+// (mcp/catalog-snapshot.mjs, reads mcp/catalog.snapshot.json). Both servers
+// import this file directly — no copying — which is what lets the repo-local
+// `mcp/server.mjs` and the shipped `twreact-ui mcp` subcommand share one
+// implementation.
+
+function allEntries(catalog) {
+  return [...catalog.components, ...catalog.hooks, ...catalog.utils, ...catalog.store];
+}
+
+// Resolve a name to a single catalog entry: exact match, then family-export
+// (e.g. "useToast" → "Toast"), then case-insensitive. Returns null if none.
+export function findComponentIn(catalog, name) {
+  const all = allEntries(catalog);
+  const lower = String(name || "").toLowerCase();
+  return (
+    all.find((x) => x.name === name) ||
+    all.find((x) => x.familyExports.includes(name)) ||
+    all.find((x) => x.name.toLowerCase() === lower) ||
+    null
+  );
+}
+
+// Ranked keyword search across names, family exports, descriptions, prop
+// names, and examples. Returns entries with a `_score`, highest first.
+export function searchCatalogIn(catalog, query) {
+  const q = String(query || "").toLowerCase().trim();
+  if (!q) return [];
+  const scored = [];
+  for (const x of allEntries(catalog)) {
+    let score = 0;
+    if (x.name.toLowerCase().includes(q)) score += 10;
+    if (x.familyExports.some((f) => f.toLowerCase().includes(q))) score += 6;
+    if (x.description.toLowerCase().includes(q)) score += 3;
+    if (x.props.some((p) => p.prop.toLowerCase().includes(q))) score += 2;
+    if (x.examples.toLowerCase().includes(q)) score += 1;
+    if (score > 0) scored.push({ ...x, _score: score });
+  }
+  return scored.sort((a, b) => b._score - a._score);
+}

package/mcp/catalog-snapshot.mjs

@@ -0,0 +1,42 @@
+// Snapshot-backed catalog — what the SHIPPED `twreact-ui mcp` server reads.
+// ---------------------------------------------------------------------------
+// Exposes the SAME surface as the live mcp/catalog.mjs
+//   buildCatalog, findComponent, searchCatalog, listDocNames, readDoc, readSkill
+// so the shared server core (mcp/server-core.mjs) is agnostic to the source.
+// Here the data is a frozen snapshot (mcp/catalog.snapshot.json, generated by
+// scripts/gen-mcp-snapshot.mjs) — no src/ or doc/ needed at runtime, so it
+// works after a plain `npm install @dreamtree-org/twreact-ui`. The pure query
+// helpers are shared verbatim with the live server (./catalog-core.mjs); no
+// copying — both the live and shipped servers import the same files in this
+// package.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { findComponentIn, searchCatalogIn } from "./catalog-core.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const snapshot = JSON.parse(readFileSync(join(__dirname, "catalog.snapshot.json"), "utf8"));
+
+export function buildCatalog() {
+  return snapshot.catalog;
+}
+
+export function findComponent(name) {
+  return findComponentIn(snapshot.catalog, name);
+}
+
+export function searchCatalog(query) {
+  return searchCatalogIn(snapshot.catalog, query);
+}
+
+export function listDocNames() {
+  return Object.keys(snapshot.docs);
+}
+
+export function readDoc(name) {
+  return snapshot.docs[name] ?? null;
+}
+
+export function readSkill() {
+  return snapshot.skill ?? null;
+}