@webjsdev/mcp 0.1.9 → 0.1.10

package/README.md

@@ -35,6 +35,10 @@ subcommand) delegates to this same server, so both routes run identical code.
   and `prompts` (the recipes as guided workflows).
 - **`source` tool**: reads the framework's own no-build source from
   `node_modules/@webjsdev/*/src` (read-only, traversal-guarded).
+- **`ui` tool**: the `@webjsdev/ui` kit inventory (no args) or one component's
+  helper signatures, paste-ready structural example, a11y header, and deps (pass
+  `name`). Kit-scoped (not `appDir`-scoped); shares one projector with
+  `webjsui view`.
 
 The docs corpus is bundled into the package at `prepack`, so `npx @webjsdev/mcp`
 is self-contained; in the monorepo it falls back to the live repo-root docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "The webjs Model Context Protocol server: live app introspection (routes / actions / components / check) plus the framework knowledge layer (docs, recipes, source) for AI coding agents",
   "bin": {
@@ -25,7 +25,8 @@
     "resources"
   ],
   "dependencies": {
-    "@webjsdev/server": "^0.8.0"
+    "@webjsdev/server": "^0.8.0",
+    "@webjsdev/ui": "^0.3.9"
   },
   "publishConfig": {
     "access": "public"

package/resources/AGENTS.md

@@ -133,7 +133,7 @@ Self-check: `page.ts` / `layout.ts` should NOT appear in the network tab or the
 
 ## Framework source: where to find it
 
-Plain JS with JSDoc lives in `node_modules/@webjsdev/` (`core/`, `server/`, `cli/`, `mcp/`, `intellisense/`, `ui/`); what you read is what runs. Starting points: SSR `@webjsdev/server/src/ssr.js`, client hydration `@webjsdev/core/src/render-client.js`, client router `@webjsdev/core/src/router-client.js`, convention rules `@webjsdev/server/src/check.js`. For UI debugging use the Playwright MCP server; for live introspection the scaffold wires the read-only `@webjsdev/mcp` server (`npx @webjsdev/mcp`, also reachable as `webjs mcp`): `list_routes`, `list_actions`, `list_components`, `check`, plus a knowledge layer (docs / recipes / framework source).
+Plain JS with JSDoc lives in `node_modules/@webjsdev/` (`core/`, `server/`, `cli/`, `mcp/`, `intellisense/`, `ui/`); what you read is what runs. Starting points: SSR `@webjsdev/server/src/ssr.js`, client hydration `@webjsdev/core/src/render-client.js`, client router `@webjsdev/core/src/router-client.js`, convention rules `@webjsdev/server/src/check.js`. For UI debugging use the Playwright MCP server; for live introspection the scaffold wires the read-only `@webjsdev/mcp` server (`npx @webjsdev/mcp`, also reachable as `webjs mcp`): `list_routes`, `list_actions`, `list_components`, `check`, `ui` (the `@webjsdev/ui` kit inventory + a component's helpers / paste-ready example / a11y header), plus a knowledge layer (docs / recipes / framework source).
 
 ---
 
@@ -463,7 +463,7 @@ webjs start  [--port N]            # prod server; source IS the runtime, plain H
 webjs test   [--server] [--browser] [--watch]
 webjs check  [--rules] [--json]    # correctness validator (report-only, no autofix); --json for an agent loop
 webjs routes [--json] [--table] [--no-headers]   # print the route table (path / owner file / methods, #975). Default tree; --json is byte-identical to the MCP list_routes tool; --no-headers drops the --table header for piping
-webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, check
+webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, check, ui kit
 webjs doctor [--json] [--strict]   # project-health checklist (incl. a framework-resolve check that warns when @webjsdev/core can't be resolved from the app dir, the fresh-worktree-without-node_modules trap #954; a page/layout elision advisory); non-zero exit on a hard fail. --json emits `{ results, summary }` (results is the DoctorResult[], each carrying a stable code); --strict also fails the exit on warnings (#975)
 webjs types                        # generate .webjs/routes.d.ts (typed Route union + per-route params, #258)
 webjs version                      # print the installed @webjsdev/cli version (also: webjs --version / -v, #975)

package/resources/SKILL.md

@@ -44,6 +44,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
 | Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
 | Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
+| The `@webjsdev/ui` component kit (a `components.json` is present): class helpers, tokens, `add` / `view`, the MCP `ui` tool | `references/ui-kit.md`                         |
 | TypeScript at runtime, erasable syntax, full-stack types                     | `references/typescript.md`                     |
 | Unit, browser, e2e tests, the `handle()` harness, Bun parity                 | `references/testing.md`                        |
 | Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |

package/resources/references/ui-kit.md

@@ -0,0 +1,68 @@
+# The `@webjsdev/ui` component kit
+
+Load this when the app has a `components.json` (it uses `@webjsdev/ui`, the
+shadcn-style kit for WebJs). The source is copied into your repo (`components/ui/`),
+so you own and edit it. Two tiers:
+
+- **Tier 1, class helpers (23 components).** Pure functions returning Tailwind
+  class strings (`buttonClass({ variant })`, `cardClass()`), composed with
+  whatever native element you write. Reach for these instead of expanding
+  Tailwind by hand: the call site is a fraction of the tokens and the class list
+  cannot drift.
+- **Tier 2, stateful custom elements (9 components).** `<ui-dialog>`, `<ui-tabs>`,
+  `<ui-dropdown-menu>`, and friends own their ARIA (focus trap, roving tabindex,
+  `aria-controls` / `inert`, live regions). Write the tag and the accessible
+  behaviour comes with it. Do NOT hand-roll these; the wiring is easy to get
+  subtly wrong.
+
+## The workflow: query for the structure, do not guess it
+
+`add` copies a Tier-1 component's class helpers plus a lean header (what each
+helper is, the accessibility obligations) and a one-line pointer. It does NOT
+copy the worked structural example, because that example is guidance you consume
+once while composing, not code that should sit in your repo. Get the full
+paste-ready structure on demand:
+
+- **MCP `ui` tool** (preferred when available): call `ui` with no args for the
+  kit inventory (each component's tier, helper signatures, npm deps); pass
+  `{ name: "accordion" }` for one component's helper signatures, the paste-ready
+  structural example, the accessibility header, and deps.
+- **CLI**: `webjs ui list` (inventory), `webjs ui view <name>` (the projected
+  view plus the full source). Same data as the MCP tool (one shared projector).
+
+So the loop is: `add` the component, then query `ui <name>` (MCP) or
+`webjs ui view <name>` for the accessible structure, paste it, and fill it in.
+
+## Setup and resolution
+
+- `webjs ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
+  tokens the helpers render against (`--background`, `--foreground`,
+  `--destructive`, ...). It HARD-FAILS if the tokens cannot be written, so a
+  clean exit means the kit is styled. `add` self-heals the tokens if they go
+  missing.
+- Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
+  that ships inside the installed `@webjsdev/ui`, with no network. This pins you
+  to the installed version; run `webjs ui diff` to see where your local copies
+  drift from the upstream (that command alone compares against the live registry).
+
+## Inventory (run `webjs ui list` or the MCP `ui` tool for the authoritative, current set)
+
+**Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
+breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
+native-select, pagination, popover, progress, radio-group, separator, skeleton,
+switch, table, textarea.
+
+**Tier 2 (custom elements, own their ARIA):** alert-dialog, dialog,
+dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
+(these two register an element AND export a `*Class` helper).
+
+## Idioms
+
+- A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
+  The unquoted `${...}` is a normal `html` attribute hole.
+- Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
+  the tokens are missing (re-run `webjs ui init` or let `add` self-heal them).
+- Custom elements are display-only-safe at SSR and hydrate in the browser, the
+  standard WebJs component model (`references/components.md`).
+
+Full per-package reference lives in the installed `@webjsdev/ui/AGENTS.md`.

package/src/mcp.js

@@ -81,6 +81,18 @@ const DOCS_SCHEMA = {
   required: [],
 };
 
+/** `ui` lists the @webjsdev/ui kit, or details one component by `name`. */
+const UI_SCHEMA = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'A component name (e.g. button, accordion, dialog). Omit for the full kit inventory.',
+    },
+  },
+  required: [],
+};
+
 /** `source` reads the framework source: a `path` to read, a `query` to grep, or a `package` to list. */
 const SOURCE_SCHEMA = {
   type: 'object',
@@ -127,6 +139,12 @@ const TOOL_DEFS = [
       'Read the FRAMEWORK authored source (webjs is buildless: node_modules/@webjsdev/*/src is the JSDoc source, run directly server-side; only the core browser bundle is built into dist/, which this skips). Pass `path` to read a file (e.g. server/src/ssr.js), `query` to grep the @webjsdev/* src trees, or no args to list the packages + entry points. Use when the docs do not answer something. Read-only.',
     inputSchema: SOURCE_SCHEMA,
   },
+  {
+    name: 'ui',
+    description:
+      'The @webjsdev/ui component kit (shadcn-style, copied into your repo). No args returns the inventory (each component: tier, helper signatures, npm deps); pass `name` for one component: helper signatures, the paste-ready structural example, the a11y/description header, and deps. Use before hand-writing UI so you reach for a helper (e.g. buttonClass()) and the accessible structure instead of expanding Tailwind blind. Reads the kit, not your app. Read-only.',
+    inputSchema: UI_SCHEMA,
+  },
   {
     name: 'list_routes',
     description:
@@ -358,6 +376,50 @@ export function makeToolRunners(deps) {
   };
 }
 
+/**
+ * Run the `ui` tool: the @webjsdev/ui kit inventory (no args) or one component's
+ * projection (helper signatures + paste-ready example + a11y/description header
+ * + deps). Projects the SHARED `@webjsdev/ui/registry/extract` leaf, the same
+ * one `webjsui view` renders, so the CLI and MCP cannot drift (#983, the #979
+ * shared-projector pattern). `uiDeps` is injected so tests need no real package.
+ *
+ * @param {{ uiInventory: Function, uiComponent: Function }} uiDeps
+ * @param {{ name?: string }} args
+ */
+/**
+ * Resolve the `ui` tool's deps from the shared `@webjsdev/ui/registry/extract`
+ * leaf, GUARDED (#983): if `@webjsdev/ui` is absent or too old to carry the
+ * `./registry/extract` subpath (a cross-package version skew), only the `ui`
+ * tool degrades (its deps throw a clear "unavailable" error, surfaced as an
+ * isError tool result) while the rest of the server keeps working. An unguarded
+ * top-level import would instead reject during bootstrap and sink the whole
+ * server. `importer` is injected so the failure path is unit-testable.
+ *
+ * @param {() => Promise<{ uiInventory: Function, uiComponent: Function }>} importer
+ * @returns {Promise<{ uiInventory: Function, uiComponent: Function }>}
+ */
+export async function loadUiDeps(importer) {
+  try {
+    const ui = await importer();
+    return { uiInventory: ui.uiInventory, uiComponent: ui.uiComponent };
+  } catch {
+    const unavailable = () => {
+      throw new Error('@webjsdev/ui is not available (install/upgrade @webjsdev/ui to use the ui tool)');
+    };
+    return { uiInventory: unavailable, uiComponent: unavailable };
+  }
+}
+
+export function runUiTool(uiDeps, args) {
+  const name = typeof args.name === 'string' && args.name ? args.name : null;
+  if (!name) return { inventory: uiDeps.uiInventory() };
+  const component = uiDeps.uiComponent(name);
+  if (!component) {
+    throw new Error(`Unknown component "${String(name)}". Call ui with no args for the inventory.`);
+  }
+  return component;
+}
+
 /**
  * A JSON-RPC 2.0 result frame.
  * @param {string|number|null} id
@@ -454,6 +516,13 @@ export async function runMcpServer(opts) {
     };
   }
 
+  // The `ui` tool (#983): the @webjsdev/ui kit inventory / per-component
+  // projection, read from the shared `@webjsdev/ui/registry/extract` leaf.
+  // Injectable for tests; otherwise resolved (guarded) from the installed
+  // package. See {@link loadUiDeps} for why the import is guarded.
+  let uiDeps = opts.uiDeps;
+  if (!uiDeps) uiDeps = await loadUiDeps(() => import('@webjsdev/ui/registry/extract'));
+
   /** Write one JSON-RPC frame as a single line to stdout. */
   const send = (frame) => {
     stdout.write(JSON.stringify(frame) + '\n');
@@ -526,7 +595,9 @@ export async function runMcpServer(opts) {
       const args = params.arguments || {};
       // The knowledge tools route to the docs / source layer; they return text.
       const isKnowledgeTool = name === 'init' || name === 'docs' || name === 'source';
-      if (!isKnowledgeTool && !runners[name]) {
+      // `ui` is kit-scoped (not app-scoped), so it is dispatched separately.
+      const isUiTool = name === 'ui';
+      if (!isKnowledgeTool && !isUiTool && !runners[name]) {
         return rpcError(id, -32602, `Unknown tool: ${String(name)}`);
       }
       const appDir = typeof args.appDir === 'string' && args.appDir ? args.appDir : cwd;
@@ -537,7 +608,9 @@ export async function runMcpServer(opts) {
             : name === 'docs'
               ? await searchDocs(docsDeps, args)
               : await runSourceTool(sourceDeps, args)
-          : await runners[name](appDir);
+          : isUiTool
+            ? runUiTool(uiDeps, args)
+            : await runners[name](appDir);
         // Knowledge tools return a markdown string; introspection tools return
         // a JSON-serialisable object.
         const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);