@webjsdev/mcp 0.1.17 → 0.1.19

package/src/mcp.js

@@ -23,19 +23,12 @@
 import { createInterface } from 'node:readline';
 import { relative } from 'node:path';
 
-import {
-  resolveDocsLocation,
-  listResources,
-  readResource,
-  initText,
-  searchDocs,
-  PROMPTS,
-  getPrompt,
-} from './mcp-docs.js';
-import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
+import { initText } from './mcp-init.js';
+import { resolveFrameworkRoots, runSourceTool, listDir } from './mcp-source.js';
 // The export lookup behind the `source` tool's `export` arg, re-exported for
 // `webjs source <Export>` in the CLI (#1623), which shells the same text.
-export { lookupExport, resolveFrameworkRoots } from './mcp-source.js';
+export { lookupExport, resolveFrameworkRoots, listDir, listSources } from './mcp-source.js';
+export { featureCatalog, FEATURE_CATALOG } from './catalog.js';
 import { projectRoutes } from './routes-report.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
@@ -56,10 +49,9 @@ const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'vali
 /**
  * The `appDir` property, shared by every tool that is scoped to one app.
  *
- * `init` and `docs` carry it too, not just the introspection tools: the docs
- * corpus is resolved from the app being asked about (#1319), so a tool that did
- * not ADVERTISE `appDir` could never receive one from a conforming client, and
- * the app-corpus rung would be reachable only from hand-written JSON-RPC.
+ * `init` carries it too: it compares the app's installed `@webjsdev/mcp` with
+ * the running server's to warn about a stale server (#1319), and a tool that did
+ * not ADVERTISE `appDir` could never receive one from a conforming client.
  */
 const APPDIR_PROP = {
   type: 'string',
@@ -73,45 +65,38 @@ const APPDIR_SCHEMA = {
   required: [],
 };
 
-/** `init` takes only the optional appDir, which selects whose docs corpus it reports. */
+/** `init` takes only the optional appDir, whose installed server version it compares. */
 const INIT_SCHEMA = {
   type: 'object',
   properties: {
     appDir: {
       ...APPDIR_PROP,
-      description: "App directory whose docs corpus to read. Defaults to the server cwd.",
+      description: 'App directory the agent is editing, checked for a newer @webjsdev/mcp than this server. Defaults to the server cwd.',
     },
   },
   required: [],
 };
 
-/** `docs` takes an optional topic OR a free-text query, plus the optional appDir. */
-const DOCS_SCHEMA = {
+/** `ui` lists the @webjsdev/ui kit, or details one component or block by `name`. */
+const UI_SCHEMA = {
   type: 'object',
   properties: {
-    appDir: {
-      ...APPDIR_PROP,
-      description: "App directory whose docs corpus to read. Defaults to the server cwd.",
-    },
-    topic: {
+    name: {
       type: 'string',
-      description: 'A doc name (e.g. components, recipes, lit-muscle-memory-gotchas, AGENTS). Returns the full doc.',
+      description: 'A component (button, dialog) or block (login-01) name. Omit for the inventory.',
     },
-    query: {
+    type: {
       type: 'string',
-      description: 'Free-text search across all webjs docs. Returns matching lines with their source.',
+      enum: ['ui', 'block', 'chart', 'all'],
+      description: 'List one kind with one-line descriptions: ui (components), block, chart, or all.',
     },
-  },
-  required: [],
-};
-
-/** `ui` lists the @webjsdev/ui kit, or details one component by `name`. */
-const UI_SCHEMA = {
-  type: 'object',
-  properties: {
-    name: {
+    category: {
       type: 'string',
-      description: 'A component name (e.g. button, accordion, dialog). Omit for the full kit inventory.',
+      description: 'List the blocks and charts in one category (login, signup, sidebar, dashboard, area, ...) with descriptions.',
+    },
+    source: {
+      type: 'boolean',
+      description: 'With a block `name`: include the file sources. Off by default, since installing the block and reading the files is cheaper.',
     },
   },
   required: [],
@@ -135,42 +120,35 @@ const SOURCE_SCHEMA = {
     },
     package: {
       type: 'string',
-      description: 'Limit a no-args listing to one package (core, server, cli, intellisense, ui).',
+      description: 'List one package\'s source entry points (core, server, cli, intellisense, ui).',
     },
   },
   required: [],
 };
 
 /**
- * The tools. The four introspection tools project an EXISTING @webjsdev/server
- * function (read-only, appDir-scoped). `init` + `docs` (#376) surface the
- * framework knowledge: `init` is the "read first" mental-model primer, `docs`
- * retrieves a doc by topic or searches the corpus. Descriptions are crisp so a
- * model picks the right tool without reading source.
+ * The tools. The introspection tools project an EXISTING @webjsdev/server
+ * function (read-only, appDir-scoped). `init` returns the WebJs brief, `source`
+ * reads the framework's own source, and `ui` reads the @webjsdev/ui kit.
+ * Descriptions are crisp so a model picks the right tool without reading source.
  */
 const TOOL_DEFS = [
   {
     name: 'init',
     description:
-      'READ THIS FIRST before writing or editing a webjs app. Returns the webjs mental model (NOT React/Next: no RSC, components hydrate but pages do not, signals-default state, the .server boundary) plus the invariants and the doc index. Read-only.',
+      'READ THIS FIRST before writing or editing a WebJs app. Returns the WebJs brief (Next.js App Router routing plus Lit component APIs, imported from @webjsdev/*, with the few differences that matter) and what each other tool is for. Read-only.',
     inputSchema: INIT_SCHEMA,
   },
-  {
-    name: 'docs',
-    description:
-      'Retrieve webjs framework docs: pass `topic` for a full doc (components, recipes, styling, built-ins, configuration, advanced, metadata, typescript, testing, lit-muscle-memory-gotchas, AGENTS, ...) or `query` to search the corpus. No args returns the topic index. Read-only.',
-    inputSchema: DOCS_SCHEMA,
-  },
   {
     name: 'source',
     description:
-      '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 `export` for the signature plus doc comment of ONE export (the cheap way to check a contract: `export: "createAuth"`), `path` to read a file (e.g. server/src/ssr/head.js; the bare server/src/ssr.js is a barrel that re-exports from the sibling directory), `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.',
+      '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 `export` for the signature plus doc comment of ONE export (the cheap way to check a contract: `export: "createAuth"`), `path` to read a file (e.g. server/src/ssr/head.js; the bare server/src/ssr.js is a barrel that re-exports from the sibling directory), `query` to grep the @webjsdev/* src trees, `package` to list one package\'s entry points, or NO ARGS for the feature catalogue: what WebJs provides by need (auth, sessions, caching, rate limits, uploads, realtime, SEO, test helpers), each name one `export` call away from its signature and example. Call it before hand-writing any of those. 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.',
+      'The @webjsdev/ui kit (shadcn-style, copied into your repo): components, plus blocks and charts (a block is a ready-made view you install and then edit: a login or signup page, a sidebar shell, a dashboard, a chart). No args returns the component inventory (tier, helper signatures, npm deps) and the block and chart NAMES grouped by category; `type` / `category` list them with one-line descriptions. Pass `name` for one component (helper signatures, the paste-ready example, the a11y header, deps) or one block (description, dependencies, the install command, and the files it writes with their targets; `source: true` adds the sources). Before hand-writing a page, a dashboard, a sidebar shell, an auth form or a chart, look for a block and install it. Reads the kit, not your app. Read-only.',
     inputSchema: UI_SCHEMA,
   },
   {
@@ -191,12 +169,6 @@ const TOOL_DEFS = [
       'List registered custom-element tags: tag name, defining file, and class name. Read-only.',
     inputSchema: APPDIR_SCHEMA,
   },
-  {
-    name: 'list_elision',
-    description:
-      'Report the display-only elision verdict: every component module with whether it is elided (the browser never downloads it) or shipped plus the evidence that produced the verdict, every page/layout route module as inert / import-only / shipped (with the first client-effecting blocker that pins it), and any ORPHAN component class, one that either has no registration call at all or registers a computed tag, which the scanner cannot see either way, so it always loses its elision verdict, its tag-to-module registry entry, and its preload hint (and never upgrades at all with no registration call, or when a computed-tag class has no importer that ships whole). Identical to `webjs elision --json`. Read-only.',
-    inputSchema: APPDIR_SCHEMA,
-  },
   {
     name: 'check',
     description:
@@ -332,7 +304,7 @@ export function extractActionConfig(src) {
  * JSON-serialisable projection of an existing server data function. All are
  * read-only.
  *
- * @param {{ buildRouteTable: Function, buildActionIndex: Function, hashFile: Function, scanComponents: Function, analyzeAppElision: Function, checkConventions: Function, projectCheck: Function, readFile: Function }} deps
+ * @param {{ buildRouteTable: Function, buildActionIndex: Function, hashFile: Function, scanComponents: Function, checkConventions: Function, projectCheck: Function, readFile: Function }} deps
  */
 export function makeToolRunners(deps) {
   const {
@@ -340,7 +312,6 @@ export function makeToolRunners(deps) {
     buildActionIndex,
     hashFile,
     scanComponents,
-    analyzeAppElision,
     checkConventions,
     projectCheck,
     readFile,
@@ -404,15 +375,6 @@ export function makeToolRunners(deps) {
         .sort((a, b) => a.tag.localeCompare(b.tag));
     },
 
-    async list_elision(appDir) {
-      // The whole report IS the contract: `analyzeAppElision` already returns
-      // an app-relative, sorted, JSON-serializable object, so unlike
-      // `list_routes` there is no projector leaf here and nothing to keep in
-      // sync. `webjs elision --json` prints this same object, and a drift test
-      // asserts the two are equal.
-      return analyzeAppElision(appDir);
-    },
-
     async check(appDir) {
       const violations = await checkConventions(appDir);
       return projectCheck(violations);
@@ -420,16 +382,6 @@ 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
@@ -439,29 +391,70 @@ export function makeToolRunners(deps) {
  * 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 }>}
+ * A `@webjsdev/ui` that predates blocks (no `uiBlocks` export) still serves
+ * the components: the block deps then answer with nothing rather than throw.
+ *
+ * @param {() => Promise<any>} importer
+ * @returns {Promise<UiDeps>}
  */
 export async function loadUiDeps(importer) {
   try {
     const ui = await importer();
-    return { uiInventory: ui.uiInventory, uiComponent: ui.uiComponent };
+    return {
+      uiInventory: ui.uiInventory,
+      uiComponent: ui.uiComponent,
+      uiBlocks: ui.uiBlocks ?? (() => []),
+      uiBlockIndex: ui.uiBlockIndex ?? (() => ({ blocks: {}, charts: {} })),
+      uiBlock: ui.uiBlock ?? (() => null),
+    };
   } 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 };
+    return { uiInventory: unavailable, uiComponent: unavailable, uiBlocks: unavailable, uiBlockIndex: unavailable, uiBlock: unavailable };
   }
 }
 
+/**
+ * @typedef {{
+ *   uiInventory: Function, uiComponent: Function,
+ *   uiBlocks: Function, uiBlockIndex: Function, uiBlock: Function,
+ * }} UiDeps
+ */
+
+/**
+ * Run the `ui` tool. No args: the component inventory plus the block and chart
+ * names grouped by category. `type` / `category`: one compact entry per match
+ * with its description. A component `name`: its projection (helper signatures,
+ * paste-ready example, a11y header, deps). A block `name`: its description,
+ * dependencies, install command and files with targets (sources with
+ * `source: true`). 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 {UiDeps} uiDeps
+ * @param {{ name?: string, type?: string, category?: string, source?: boolean }} args
+ */
 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.`);
+  const type = typeof args.type === 'string' && args.type ? args.type : null;
+  if (type && !['ui', 'block', 'chart', 'all'].includes(type)) {
+    throw new Error(`Unknown type "${type}". Use ui, block, chart or all.`);
+  }
+  const category = typeof args.category === 'string' && args.category ? args.category : null;
+  if (!name) {
+    // A filter lists one kind with its one-line descriptions. The bare call
+    // stays cheap: the component inventory plus the block and chart NAMES by
+    // category (D18), and a test caps its size.
+    if (type || category) return { items: uiDeps.uiBlocks({ type: type ?? undefined, category: category ?? undefined }) };
+    return { inventory: uiDeps.uiInventory(), ...uiDeps.uiBlockIndex() };
   }
-  return component;
+  const component = uiDeps.uiComponent(name);
+  if (component) return component;
+  const block = uiDeps.uiBlock(name, { source: args.source === true });
+  if (block) return block;
+  throw new Error(`Unknown component or block "${String(name)}". Call ui with no args for the inventory.`);
 }
 
 /**
@@ -519,7 +512,6 @@ export async function runMcpServer(opts) {
       buildActionIndex: server.buildActionIndex,
       hashFile: server.hashFile,
       scanComponents: server.scanComponents,
-      analyzeAppElision: server.analyzeAppElision,
       checkConventions: check.checkConventions,
       projectCheck,
       readFile,
@@ -527,47 +519,16 @@ export async function runMcpServer(opts) {
   }
   const runners = makeToolRunners(deps);
 
-  // The docs corpus deps for the knowledge layer (#376): resources / prompts /
-  // init / docs. Injectable for tests; otherwise resolved from the app's own
-  // installed corpus, the bundled (published) snapshot, or the repo-root (dev)
-  // docs, plus node fs.
-  //
-  // Resolved PER CALL and memoized by appDir (#1319), not once at boot. `appDir`
-  // is a per-call tool argument, so a boot-time resolution would pin the corpus
-  // to the launch directory forever and defeat the app-corpus rung for any host
-  // that overrides it. `resources/list` and `resources/read` carry no appDir in
-  // the MCP protocol, so they resolve from `cwd`, which is the same value a
-  // `tools/call` with no `appDir` argument defaults to; the surfaces can only
-  // diverge when a caller deliberately asks about a different app.
-  let docsFs = null;
-  if (!opts.docsDeps) {
+  // The `init` deps: fs readers for the stale-server check, which compares the
+  // app's installed @webjsdev/mcp with this server's version (#1319). Resolved
+  // per call from the tool's `appDir`. Injectable for tests via `initFs`.
+  let initFs = opts.initFs;
+  if (!initFs) {
     const { readFile } = await import('node:fs/promises');
-    const { readdirSync, existsSync } = await import('node:fs');
-    docsFs = { listDir: readdirSync, exists: existsSync, readFile };
+    const { existsSync } = await import('node:fs');
+    initFs = { readFile, exists: existsSync };
   }
-  /** @type {Map<string, object>} */
-  const docsDepsCache = new Map();
-  /** The docs deps for one appDir. An injected `opts.docsDeps` wins for every appDir. */
-  const docsDepsFor = (dir) => {
-    if (opts.docsDeps) return opts.docsDeps;
-    const key = typeof dir === 'string' ? dir : '';
-    let built = docsDepsCache.get(key);
-    if (!built) {
-      const loc = resolveDocsLocation(import.meta.url, key);
-      built = {
-        docsDir: loc.docsDir,
-        agentsPath: loc.agentsPath,
-        skillPath: loc.skillPath,
-        corpusPath: loc.corpusPath,
-        corpusSource: loc.corpusSource,
-        appDir: key,
-        serverVersion: version,
-        ...docsFs,
-      };
-      docsDepsCache.set(key, built);
-    }
-    return built;
-  };
+  const initDepsFor = (dir) => ({ ...initFs, appDir: dir, serverVersion: version });
 
   // The `source` tool (#378): read the framework's own source from
   // node_modules/@webjsdev/*/src (no-build, so it is the real JSDoc). Roots are
@@ -575,8 +536,8 @@ export async function runMcpServer(opts) {
   let sourceDeps = opts.sourceDeps;
   if (!sourceDeps) {
     const { readFile } = await import('node:fs/promises');
-    const { readdirSync, existsSync, realpathSync } = await import('node:fs');
-    const readdir = (d) => readdirSync(d, { withFileTypes: true }).map((e) => ({ name: e.name, isDir: e.isDirectory() }));
+    const { existsSync, realpathSync } = await import('node:fs');
+    const readdir = listDir;
     sourceDeps = {
       roots: resolveFrameworkRoots(cwd, { exists: existsSync }),
       readFile,
@@ -613,7 +574,7 @@ export async function runMcpServer(opts) {
     if (method === 'initialize') {
       return rpcResult(id, {
         protocolVersion: PROTOCOL_VERSION,
-        capabilities: { tools: {}, resources: {}, prompts: {} },
+        capabilities: { tools: {} },
         serverInfo: { name: 'webjs', version },
       });
     }
@@ -631,39 +592,12 @@ export async function runMcpServer(opts) {
       });
     }
 
-    // Knowledge layer (#376): the framework docs as MCP resources.
-    if (method === 'resources/list') {
-      return rpcResult(id, { resources: listResources(docsDepsFor(cwd)) });
-    }
-    if (method === 'resources/read') {
-      const uri = ((msg && msg.params) || {}).uri;
-      try {
-        const r = await readResource(docsDepsFor(cwd), uri);
-        return rpcResult(id, { contents: [r] });
-      } catch (e) {
-        return rpcError(id, -32602, e && e.message ? e.message : String(e));
-      }
-    }
-
-    // Knowledge layer (#376): the recipes as guided-workflow prompts.
-    if (method === 'prompts/list') {
-      return rpcResult(id, { prompts: PROMPTS });
-    }
-    if (method === 'prompts/get') {
-      const params = (msg && msg.params) || {};
-      try {
-        return rpcResult(id, getPrompt(params.name, params.arguments));
-      } catch (e) {
-        return rpcError(id, -32602, e && e.message ? e.message : String(e));
-      }
-    }
-
     if (method === 'tools/call') {
       const params = (msg && msg.params) || {};
       const name = params.name;
       const args = params.arguments || {};
-      // The knowledge tools route to the docs / source layer; they return text.
-      const isKnowledgeTool = name === 'init' || name === 'docs' || name === 'source';
+      // The knowledge tools (the brief, the framework source) return text.
+      const isKnowledgeTool = name === 'init' || name === 'source';
       // `ui` is kit-scoped (not app-scoped), so it is dispatched separately.
       const isUiTool = name === 'ui';
       if (!isKnowledgeTool && !isUiTool && !runners[name]) {
@@ -673,10 +607,8 @@ export async function runMcpServer(opts) {
       try {
         const result = isKnowledgeTool
           ? name === 'init'
-            ? await initText(docsDepsFor(appDir))
-            : name === 'docs'
-              ? await searchDocs(docsDepsFor(appDir), args)
-              : await runSourceTool(sourceDeps, args)
+            ? await initText(initDepsFor(appDir))
+            : await runSourceTool(sourceDeps, args)
           : isUiTool
             ? runUiTool(uiDeps, args)
             : await runners[name](appDir);