@webjsdev/mcp 0.1.8 → 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.8",
+  "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": {
@@ -13,6 +13,9 @@
     "./check-report": {
       "default": "./src/check-report.js"
     },
+    "./routes-report": {
+      "default": "./src/routes-report.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -22,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).
 
 ---
 
@@ -462,9 +462,12 @@ webjs dev    [--port N] [--no-hot] # dev server with live reload (node --watch o
 webjs start  [--port N]            # prod server; source IS the runtime, plain HTTP/1.1 (reverse-proxy for TLS + HTTP/2). Runs webjs.start.before first (#550)
 webjs test   [--server] [--browser] [--watch]
 webjs check  [--rules] [--json]    # correctness validator (report-only, no autofix); --json for an agent loop
-webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, check
-webjs doctor                       # 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
+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, 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)
+webjs help   [command]             # full usage banner, or per-command usage + Options + Examples (e.g. webjs help routes, #975). Flag forms: webjs --help / -h (banner), webjs <command> --help / -h (that command). typecheck/db/ui --help forward to their wrapped tool; an unknown topic exits 1
 webjs typecheck [tsc args...]      # the project's own tsc --noEmit
 webjs create <name> [--template api|saas]
 webjs db <generate|migrate|push|studio|seed>   # wraps drizzle-kit (+ runs db/seed.server.ts)

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

@@ -33,6 +33,7 @@ import {
   getPrompt,
 } from './mcp-docs.js';
 import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
+import { projectRoutes } from './routes-report.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
@@ -80,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',
@@ -126,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:
@@ -274,22 +293,6 @@ export function extractActionConfig(src) {
   };
 }
 
-/**
- * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
- * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
- * same normalization `buildRouteTable` uses for matching.
- *
- * @param {string} routeDir  POSIX-style, `.` for the app root.
- * @returns {string}
- */
-function routePathFromDir(routeDir) {
-  if (!routeDir || routeDir === '.') return '/';
-  const segs = routeDir
-    .split('/')
-    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
-  return segs.length ? '/' + segs.join('/') : '/';
-}
-
 /**
  * The tool runners. Each is async, takes `(appDir)`, and returns a plain
  * JSON-serialisable projection of an existing server data function. All are
@@ -311,34 +314,10 @@ export function makeToolRunners(deps) {
   return {
     async list_routes(appDir) {
       const table = await buildRouteTable(appDir);
-      const pages = await Promise.all(
-        table.pages.map(async (r) => {
-          /** @type {{ path: string, file: string, dynamic?: boolean, params?: string[] }} */
-          const out = {
-            path: routePathFromDir(r.routeDir),
-            file: relative(appDir, r.file),
-          };
-          if (r.paramNames && r.paramNames.length) {
-            out.dynamic = true;
-            out.params = r.paramNames;
-          }
-          return out;
-        }),
-      );
-      const apis = await Promise.all(
-        table.apis.map(async (r) => {
-          let methods = [];
-          try {
-            methods = extractRouteMethods(await readFile(r.file, 'utf8'));
-          } catch {}
-          return {
-            path: routePathFromDir(r.routeDir),
-            file: relative(appDir, r.file),
-            methods,
-          };
-        }),
-      );
-      return { pages, apis };
+      // The projection lives in `routes-report.js` so `list_routes` and the CLI
+      // `webjs routes --json` stay byte-identical (#975), the same split as
+      // `check-report.js` for the `check` tool.
+      return projectRoutes(table, { appDir, readFile, extractRouteMethods });
     },
 
     async list_actions(appDir) {
@@ -397,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
@@ -493,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');
@@ -565,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;
@@ -576,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);

package/src/routes-report.js

@@ -0,0 +1,90 @@
+/**
+ * Shared JSON projector for the app route table (#975).
+ *
+ * `webjs routes --json` and the `webjs mcp` server's `list_routes` tool BOTH
+ * return the identical shape, so the projection lives here once (the same
+ * pattern as `check-report.js` for `check --json` / the MCP `check` tool). The
+ * input is the raw `RouteTable` from `buildRouteTable(appDir)` (the ONE route
+ * walker, reused, never re-implemented); the output is a stable, agent-friendly
+ * `{ pages, apis }` shape.
+ *
+ * This module is a LEAF: it imports only `node:path` and receives the two
+ * effectful dependencies it needs (`readFile` to read a `route.{js,ts}` file's
+ * source, `extractRouteMethods` to lexically pull its HTTP-verb exports) as
+ * injected arguments, the same dependency-injection style the MCP tool runners
+ * already use. That keeps it free of any `@webjsdev/mcp` main-entry import (so
+ * the CLI can pull just this projector without loading the MCP server) and free
+ * of a cycle with `mcp.js`.
+ *
+ * @module routes-report
+ */
+
+import { relative } from 'node:path';
+
+/**
+ * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
+ * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
+ * same normalization `buildRouteTable` uses for matching.
+ *
+ * @param {string} routeDir  POSIX-style, `.` for the app root.
+ * @returns {string}
+ */
+export function routePathFromDir(routeDir) {
+  if (!routeDir || routeDir === '.') return '/';
+  const segs = routeDir
+    .split('/')
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
+  return segs.length ? '/' + segs.join('/') : '/';
+}
+
+/**
+ * @typedef {{ path: string, file: string, dynamic?: boolean, params?: string[] }} PageRouteReport
+ * @typedef {{ path: string, file: string, methods: string[] }} ApiRouteReport
+ * @typedef {{ pages: PageRouteReport[], apis: ApiRouteReport[] }} RoutesReport
+ */
+
+/**
+ * Project a `RouteTable` into the structured `{ pages, apis }` report shared by
+ * `webjs routes --json` and the MCP `list_routes` tool. Pure over its inputs
+ * (given the same table + deps it produces the same output); the only I/O is
+ * the injected `readFile` reading each `route.{js,ts}` source to extract its
+ * methods. A `route.{js,ts}` that cannot be read degrades to an empty method
+ * list rather than throwing, so one unreadable file never sinks the whole
+ * report.
+ *
+ * @param {{ pages: any[], apis: any[] }} table  the `buildRouteTable(appDir)` result
+ * @param {{
+ *   appDir: string,
+ *   readFile: (path: string, enc: string) => Promise<string>,
+ *   extractRouteMethods: (src: string) => string[],
+ * }} deps
+ * @returns {Promise<RoutesReport>}
+ */
+export async function projectRoutes(table, { appDir, readFile, extractRouteMethods }) {
+  const pages = table.pages.map((r) => {
+    /** @type {PageRouteReport} */
+    const out = {
+      path: routePathFromDir(r.routeDir),
+      file: relative(appDir, r.file),
+    };
+    if (r.paramNames && r.paramNames.length) {
+      out.dynamic = true;
+      out.params = r.paramNames;
+    }
+    return out;
+  });
+  const apis = await Promise.all(
+    table.apis.map(async (r) => {
+      let methods = [];
+      try {
+        methods = extractRouteMethods(await readFile(r.file, 'utf8'));
+      } catch {}
+      return {
+        path: routePathFromDir(r.routeDir),
+        file: relative(appDir, r.file),
+        methods,
+      };
+    }),
+  );
+  return { pages, apis };
+}