@dreamtree-org/twreact-ui 1.1.50 → 1.1.51

package/README.md

@@ -47,29 +47,29 @@ function App() {
 ## AI agents (MCP server)
 
 If you build UI with an AI coding agent (Claude Code, Cursor, …), wire up the
-companion **[`@dreamtree-org/twreact-ui-mcp`](https://www.npmjs.com/package/@dreamtree-org/twreact-ui-mcp)**
-[Model Context Protocol](https://modelcontextprotocol.io) server. It gives the
-agent live, queryable access to this library — `list_components`,
-`get_component` (authoritative props/variants/sizes/examples per component),
-`search_components`, the per-component docs as resources, and a `compose_ui`
-prompt — so it stops guessing prop names.
+**[Model Context Protocol](https://modelcontextprotocol.io) server bundled in
+this package**. It gives the agent live, queryable access to the library —
+`list_components`, `get_component` (authoritative props/variants/sizes/examples
+per component), `search_components`, the per-component docs as resources, and a
+`compose_ui` prompt — so it stops guessing prop names.
 
-Add it to your MCP client config (no install needed — `npx` fetches it):
+Add it to your MCP client config (no extra install — it ships with the
+library):
 
 ```jsonc
 {
   "mcpServers": {
     "dreamtree-ui": {
       "command": "npx",
-      "args": ["-y", "@dreamtree-org/twreact-ui-mcp"]
+      "args": ["-y", "@dreamtree-org/twreact-ui", "mcp"]
     }
   }
 }
 ```
 
-The catalog is a build-time snapshot baked into that package, so the server is
-self-contained (no source or network needed at runtime). Upgrade it alongside
-`@dreamtree-org/twreact-ui` to keep the served contracts current.
+The catalog is a build-time snapshot baked into the package, so the server is
+self-contained (no source or network needed at runtime) and always matches the
+library version you installed.
 
 > The MCP server also serves the skill below as the `dreamtree://skill`
 > resource, so MCP clients get it with **zero install**.

package/ai-skills/dreamtree-ui.md

@@ -65,16 +65,16 @@ module.exports = {
 
 ## Live prop contracts via MCP (prefer this over guessing)
 
-A companion **MCP server** ships the authoritative prop contracts for this
-library. If your client supports the Model Context Protocol, wire it up and
-**query it instead of guessing prop names**:
+An **MCP server bundled in this package** serves the authoritative prop
+contracts for this library. If your client supports the Model Context Protocol,
+wire it up and **query it instead of guessing prop names**:
 
 ```jsonc
 {
   "mcpServers": {
     "dreamtree-ui": {
       "command": "npx",
-      "args": ["-y", "@dreamtree-org/twreact-ui-mcp"]
+      "args": ["-y", "@dreamtree-org/twreact-ui", "mcp"]
     }
   }
 }
@@ -88,8 +88,8 @@ library. If your client supports the Model Context Protocol, wire it up and
 
 Resources: `dreamtree://skill` (this guide) and `dreamtree://docs/<Component>`.
 Prompt: `compose_ui`. The catalog is a snapshot baked into the package, so it is
-self-contained; upgrade `@dreamtree-org/twreact-ui-mcp` alongside the library.
-The lists below are the fallback when the MCP server isn't connected.
+self-contained and always matches the installed library version. The lists below
+are the fallback when the MCP server isn't connected.
 
 ## Public surface
 

package/bin/cli.mjs

@@ -55,18 +55,21 @@ function printHelp() {
   process.stdout.write(
     `${PKG} CLI (v${VERSION})\n\n` +
       `Usage:\n` +
-      `  npx ${PKG} init --ai <provider> [--out <path>] [--force]\n\n` +
-      `Installs the AI-assistant skill (ai-skills/dreamtree-ui.md) so your coding\n` +
-      `agent knows this library's components, conventions, and wiring.\n\n` +
-      `Options:\n` +
+      `  npx ${PKG} init --ai <provider> [--out <path>] [--force]\n` +
+      `  npx ${PKG} mcp\n\n` +
+      `Commands:\n` +
+      `  init    Install the AI-assistant skill (ai-skills/dreamtree-ui.md) so your\n` +
+      `          coding agent knows this library's components, conventions, wiring.\n` +
+      `  mcp     Run the Model Context Protocol server over stdio — gives an MCP\n` +
+      `          client live, queryable access to the library (list_components,\n` +
+      `          get_component, search_components + docs + a compose_ui prompt).\n` +
+      `          Wire it as: { "command": "npx", "args": ["-y", "${PKG}", "mcp"] }\n\n` +
+      `init options:\n` +
       `  --ai <provider>   Target assistant: ${providers}  (default: claude)\n` +
       `  --out <path>      Write to this path instead of the provider default\n` +
       `  --force           Overwrite the destination if it already exists\n` +
       `  -h, --help        Show this help\n` +
-      `  -v, --version     Print the version\n\n` +
-      `Tip: if your client speaks MCP, you don't need this — wire up\n` +
-      `@dreamtree-org/twreact-ui-mcp and the skill is served as the\n` +
-      `dreamtree://skill resource (zero install).\n`
+      `  -v, --version     Print the version\n`
   );
 }
 
@@ -114,15 +117,34 @@ function runInit(args) {
   );
 }
 
-function main() {
+// Boot the bundled MCP server over stdio. The SDK + server are lazy-imported
+// here so plain `init` carries no dependency cost. stdout is the MCP protocol
+// channel, so this path must only ever log to stderr. The shipped server reads
+// the frozen snapshot (mcp/catalog-snapshot.mjs), so it needs no src/ or doc/.
+async function runMcp() {
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { createServer } = await import("../mcp/server-core.mjs");
+  const catalog = await import("../mcp/catalog-snapshot.mjs");
+  const server = createServer({ version: VERSION, catalog });
+  await server.connect(new StdioServerTransport());
+  process.stderr.write(
+    `[dreamtree-ui mcp] serving ${PKG} — ${catalog.buildCatalog().counts.components} components\n`
+  );
+}
+
+async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.version) return process.stdout.write(`${VERSION}\n`);
   if (args.help || args._.length === 0) return printHelp();
 
   const cmd = args._[0];
   if (cmd === "init") return runInit(args);
+  if (cmd === "mcp") return runMcp();
 
   fail(`unknown command "${cmd}". Run \`npx ${PKG} --help\`.`);
 }
 
-main();
+main().catch((err) => {
+  process.stderr.write(`error: ${err?.stack || err}\n`);
+  process.exit(1);
+});

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;
+}