# 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).