@webjsdev/mcp 0.1.18 → 0.1.20

package/src/mcp-init.js

@@ -0,0 +1,139 @@
+/**
+ * The `init` tool of `webjs mcp`: the one thing an agent reads before it writes
+ * WebJs code.
+ *
+ * It returns the WebJs brief (see `brief.js`) plus a map of the server's other
+ * tools. There is no docs corpus behind it any more. Lit and Next.js habits are
+ * meant to produce correct WebJs code, and where one cannot, `webjs check` and
+ * the runtime refuse it with the fix in the message, so the brief is the whole
+ * of the agent-facing documentation. For an exact contract the agent reads the
+ * framework source, which is no-build and therefore the code that runs (the
+ * `source` tool).
+ *
+ * Pure given its injected `{ appDir, serverVersion, readFile, exists }` deps, so
+ * it is testable in-process without touching the real filesystem.
+ *
+ * @module mcp-init
+ */
+
+import { join } from 'node:path';
+
+import { BRIEF, BRIEF_HEADING } from './brief.js';
+
+/**
+ * Compare two `major.minor.patch` versions, returning `-1` / `0` / `1`.
+ *
+ * Dependency-free by design (this package ships zero dependencies), and
+ * deliberately coarse: any prerelease or build suffix is stripped before
+ * comparing, a missing segment reads as `0`, and a non-numeric segment reads as
+ * `0`. Its only consumer is the staleness warning, where the question is "is the
+ * app's copy meaningfully newer", so ranking two prereleases of one patch is not
+ * a case that needs an answer.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareVersions(a, b) {
+  const parts = (v) => String(v == null ? '' : v).trim().split(/[-+]/)[0].split('.');
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < 3; i++) {
+    const x = Number(pa[i]);
+    const y = Number(pb[i]);
+    const nx = Number.isFinite(x) ? x : 0;
+    const ny = Number.isFinite(y) ? y : 0;
+    if (nx !== ny) return nx < ny ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The `@webjsdev/mcp` version installed in `appDir`, or `null` when that cannot
+ * be known (no app dir, no install, an unreadable or unparseable manifest, no
+ * `version` field).
+ *
+ * @param {string} [appDir]
+ * @param {{ exists?: (p: string) => boolean, readFile: (p: string, enc: string) => Promise<string> }} deps
+ * @returns {Promise<string | null>}
+ */
+export async function readAppMcpVersion(appDir, deps) {
+  if (typeof appDir !== 'string' || !appDir) return null;
+  const manifest = join(appDir, 'node_modules', '@webjsdev', 'mcp', 'package.json');
+  try {
+    if (deps.exists && !deps.exists(manifest)) return null;
+    const version = JSON.parse(await deps.readFile(manifest, 'utf8')).version;
+    return typeof version === 'string' && version ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The staleness warning, or `null` when there is nothing to warn about.
+ *
+ * Fires only when the app's installed `@webjsdev/mcp` is strictly NEWER than the
+ * running server's (a globally installed server lags the app it is asked
+ * about, #1319). Equal or lower is silent. It warns rather than failing, since
+ * a stale brief and stale tools still beat no answer.
+ *
+ * It names every way the server may have been started rather than guessing one,
+ * because nothing here can observe it: a global install, the package cache
+ * behind `npx @webjsdev/mcp`, `@webjsdev/cli` when started as `webjs mcp`, or a
+ * checkout.
+ *
+ * @param {{ appDir?: string, serverVersion?: string, readFile: Function, exists?: Function }} deps
+ * @returns {Promise<string | null>}
+ */
+export async function staleWarning(deps) {
+  const server = deps.serverVersion;
+  // '0.0.0' is the sentinel both entry points fall back to when they cannot read
+  // their own manifest, so it means "unknown", not "older than everything".
+  if (!server || server === '0.0.0') return null;
+  const app = await readAppMcpVersion(deps.appDir, deps);
+  if (!app || compareVersions(app, server) <= 0) return null;
+  return (
+    `Warning: this MCP server is @webjsdev/mcp@${server}, but this app has @webjsdev/mcp@${app}, ` +
+    'so the brief and the tools below may be stale. ' +
+    'Update whichever copy runs this server: a global install (npm i -g @webjsdev/mcp@latest, ' +
+    'or bun add -g @webjsdev/mcp), the package cache behind npx @webjsdev/mcp, ' +
+    '@webjsdev/cli when the server is started as webjs mcp, or the checkout it runs from.'
+  );
+}
+
+/** What the server's other tools are for, so the agent reaches for the right one. */
+const TOOL_MAP = [
+  '## The tools on this server',
+  '',
+  '- Before hand-writing auth, sessions, caching, rate limits, uploads, realtime',
+  '  or SEO, call `source` with no arguments: it lists what WebJs provides.',
+  '- For an exact contract, call `source` with `export` set to one export name',
+  '  (its signature plus doc comment), `path` to read a framework file, or',
+  '  `query` to grep the `@webjsdev/*` source.',
+  '- To see the live app, call `list_routes`, `list_actions` and',
+  '  `list_components`.',
+  '- To validate an edit, call `check`. Every violation carries its fix.',
+  '- Before hand-writing a page, a form, a dashboard or a chart, call `ui` to',
+  '  find a ready-made block in the `@webjsdev/ui` kit.',
+].join('\n');
+
+/**
+ * The `init` tool output: an optional staleness warning, the brief, and the
+ * tool map.
+ *
+ * @param {{ appDir?: string, serverVersion?: string, readFile: Function, exists?: Function }} deps
+ * @returns {Promise<string>}
+ */
+export async function initText(deps) {
+  const warning = await staleWarning(deps);
+  return [
+    '# WebJs: read first',
+    '',
+    ...(warning ? [warning, ''] : []),
+    BRIEF_HEADING,
+    '',
+    BRIEF,
+    '',
+    TOOL_MAP,
+  ].join('\n');
+}

package/src/mcp-source.js

@@ -27,6 +27,9 @@
 
 import { createRequire } from 'node:module';
 import { join, resolve, sep, relative } from 'node:path';
+import { readdirSync, statSync } from 'node:fs';
+import { featureCatalog } from './catalog.js';
+import { guide, conventionPointer } from './guides.js';
 
 /** The published framework packages whose source an agent may want to read. */
 export const FRAMEWORK_PACKAGES = ['core', 'server', 'cli', 'intellisense', 'ui'];
@@ -91,6 +94,25 @@ export function resolveFrameworkRoots(cwd, fsDeps) {
  * @param {{ readdir: (d: string) => Array<{ name: string, isDir: boolean }> }} deps
  * @returns {string[]}
  */
+/**
+ * The real directory listing `walkSource` and the source tool read, following
+ * a symlinked directory the way the module resolver does.
+ * @param {string} dir
+ * @returns {Array<{ name: string, isDir: boolean }>}
+ */
+export function listDir(dir) {
+  return readdirSync(dir, { withFileTypes: true }).map((e) => {
+    let isDir = e.isDirectory();
+    // A symlinked directory is a directory: pnpm and workspace installs link
+    // a package (or its `src`) rather than copying it, and a Dirent of a link
+    // answers isDirectory() false, which skipped everything under it (#1686).
+    if (!isDir && e.isSymbolicLink()) {
+      try { isDir = statSync(join(dir, e.name)).isDirectory(); } catch { /* dangling */ }
+    }
+    return { name: e.name, isDir };
+  });
+}
+
 export function walkSource(dir, deps) {
   /** @type {string[]} */
   const files = [];
@@ -114,21 +136,25 @@ export function walkSource(dir, deps) {
 }
 
 /**
- * No-args / `package` mode: list the resolved packages and their `src/`
- * top-level files (the entry points), so the agent has a map to grep or read.
+ * `package` mode: list the resolved packages and their `src/` top-level files
+ * (the entry points), so the agent has a map to grep or read. `readHint` is
+ * the next step the caller offers, since the MCP tool and the CLI read the
+ * listing with different commands.
  *
  * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readdir: Function }} deps
  * @param {string} [pkgFilter]
+ * @param {{ readHint?: string }} [opts]
  * @returns {string}
  */
-export function listSources(deps, pkgFilter) {
+export function listSources(deps, pkgFilter, opts = {}) {
+  const readHint = opts.readHint ?? 'Read with `source({ path })` or search with `source({ query })`.';
   const roots = pkgFilter ? deps.roots.filter((r) => r.pkg === pkgFilter) : deps.roots;
   if (!roots.length) {
     return pkgFilter
       ? `@webjsdev/${pkgFilter} is not installed/resolvable here. Resolvable: ${deps.roots.map((r) => r.pkg).join(', ') || '(none)'}`
       : 'No @webjsdev/* packages resolvable from here (run inside a webjs app or the monorepo).';
   }
-  const lines = ['webjs framework authored source (buildless; server-side this runs directly, and core ships a built browser dist/ that is excluded here). Read with `source({ path })` or search with `source({ query })`.', ''];
+  const lines = [`webjs framework authored source (buildless; server-side this runs directly, and core ships a built browser dist/ that is excluded here). ${readHint}`, ''];
   for (const r of roots) {
     const dirName = r.src.split(sep).pop(); // 'src' for most, 'lib' for cli
     let entries = [];
@@ -325,9 +351,10 @@ function declarationFrom(lines, line, isTypes) {
  * @param {{ roots: Array<{ pkg: string, root: string, src: string }>, readFile: Function, readdir: Function }} deps
  * @param {string} name an export name, e.g. `createAuth`
  * @param {string} [pkgFilter] one of the framework packages, e.g. `server`
+ * @param {boolean} [caseRetried] internal: the case-swapped retry is already this call
  * @returns {Promise<string>}
  */
-export async function lookupExport(deps, name, pkgFilter) {
+export async function lookupExport(deps, name, pkgFilter, caseRetried = false) {
   const n = String(name || '').trim();
   if (!/^[A-Za-z_$][\w$]*$/.test(n)) return 'Pass an export name (letters, digits, _ or $), e.g. `createAuth`.';
   const roots = pkgFilter ? deps.roots.filter((r) => r.pkg === pkgFilter) : deps.roots;
@@ -360,6 +387,15 @@ export async function lookupExport(deps, name, pkgFilter) {
   }
   const searched = deps.roots.map((r) => r.pkg).join(', ');
   if (!hits.length) {
+    // The name as written with another case: a convention is written lower
+    // camel (`generateMetadata`) and its type upper (`GenerateMetadata`).
+    const other = n[0] === n[0].toLowerCase() ? n[0].toUpperCase() + n.slice(1) : n[0].toLowerCase() + n.slice(1);
+    if (other !== n && !caseRetried) {
+      const cased = await lookupExport(deps, other, pkgFilter, true);
+      if (cased.startsWith('@webjsdev/')) return `"${n}" is not an export; its type is ${other}:\n${cased}`;
+    }
+    const members = await lookupMember(deps, roots, n);
+    if (members) return members;
     return `No export named "${n}" in the searched @webjsdev/* packages (${roots.map((r) => r.pkg).join(', ')}${pkgFilter ? `; resolvable: ${searched}` : ''}). Try \`query\` for a substring search, or \`path\` to read a file.`;
   }
   // The typed declarations are the answer; the JS doc is added only when the
@@ -377,10 +413,61 @@ export async function lookupExport(deps, name, pkgFilter) {
   return out.join('\n').trimEnd();
 }
 
+/**
+ * A name that is no export but a MEMBER of an exported interface or class
+ * (`actionData` on `PageProps`, `fieldErrors` on `FormActionData`). Agents look
+ * those up by the name they write (#1686: `actionData` was the most grepped
+ * term across the eval builds), so the member's doc and declaration print,
+ * headed by the type that owns it.
+ * @param {{ readFile: Function, readdir: Function }} deps
+ * @param {Array<{ pkg: string, root: string }>} roots
+ * @param {string} n
+ * @returns {Promise<string | null>}
+ */
+async function lookupMember(deps, roots, n) {
+  const memberRe = new RegExp(`^\\s+(?:readonly\\s+)?(?:static\\s+)?${n.replace(/\$/g, '\\$')}\\??\\s*[:(<]`);
+  const ownerRe = /^export\s+(?:declare\s+)?(?:abstract\s+)?(?:interface|class|type)\s+([A-Za-z_$][\w$]*)/;
+  const out = [];
+  let count = 0;
+  for (const r of roots) {
+    for (const file of walkSource(r.root, deps).filter((f) => /\.d\.(?:ts|mts|cts)$/.test(f))) {
+      let text = '';
+      try { text = await deps.readFile(file, 'utf8'); } catch { continue; }
+      if (!text.includes(n)) continue;
+      const lines = text.split('\n');
+      const rel = relative(r.root, file).split(sep).join('/');
+      for (let i = 0; i < lines.length; i++) {
+        if (!memberRe.test(lines[i])) continue;
+        let owner = null;
+        for (let j = i - 1; j >= 0; j--) {
+          const m = ownerRe.exec(lines[j]);
+          if (m) { owner = m[1]; break; }
+          if (/^\S/.test(lines[j]) && !/^\s*(?:\*|\/\/|\/\*)/.test(lines[j]) && /^(?:}|export)/.test(lines[j])) break;
+        }
+        if (!owner) continue;
+        if (++count > MAX_EXPORT_HITS) continue;
+        const decl = [];
+        for (let k = i, depth = 0; k < lines.length && decl.length < MAX_DECL_LINES; k++) {
+          decl.push(lines[k]);
+          for (const ch of lines[k]) { if (ch === '{' || ch === '(') depth++; else if (ch === '}' || ch === ')') depth--; }
+          if (depth <= 0 && /[;,]\s*$/.test(lines[k])) break;
+        }
+        out.push(`"${n}" is a member of ${owner} (@webjsdev/${r.pkg} ${rel}:${i + 1}); \`source ${owner}\` prints the whole type.`);
+        out.push(...docAbove(lines, i), ...decl, '');
+      }
+    }
+  }
+  if (!out.length) return null;
+  if (count > MAX_EXPORT_HITS) out.push(`... (${count - MAX_EXPORT_HITS} more members named "${n}"; narrow with \`package\`)`);
+  return out.join('\n').trimEnd();
+}
+
 /**
  * The `source` tool entry point. Dispatches on the args: `export` looks up one
- * export's signature and doc, `path` reads a file, `query` greps, otherwise
- * (or with `package`) lists the packages. PURE given `deps`
+ * export's signature and doc, `path` reads a file, `query` greps, `package`
+ * lists that package's entry points, and no args prints the feature catalogue
+ * (what WebJs provides, by need). An `export` that names a pattern guide
+ * (`modules`, `optimistic-ui`, ...) returns the guide. PURE given `deps`
  * (`{ roots, readFile, readdir }`).
  *
  * @param {object} deps
@@ -389,8 +476,16 @@ export async function lookupExport(deps, name, pkgFilter) {
  */
 export async function runSourceTool(deps, args) {
   const a = args || {};
-  if (a.export) return lookupExport(deps, a.export, a.package);
+  // A guide name (`optimistic-ui`, `modules`) is a slug no package exports.
+  if (a.export) {
+    const g = a.package ? null : guide(a.export);
+    if (g) return g;
+    const out = await lookupExport(deps, a.export, a.package);
+    const pointer = conventionPointer(a.export);
+    return pointer ? `${out}\n\n${pointer}` : out;
+  }
   if (a.path) return readSource(deps, a.path);
   if (a.query) return grepSources(deps, a.query);
-  return listSources(deps, a.package);
+  if (a.package) return listSources(deps, a.package);
+  return featureCatalog();
 }

package/src/mcp.js

@@ -23,19 +23,13 @@
 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';
+export { guide, GUIDES, GUIDE_ALIASES, conventionPointer } from './guides.js';
 import { projectRoutes } from './routes-report.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
@@ -56,10 +50,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,33 +66,13 @@ 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.",
-    },
-  },
-  required: [],
-};
-
-/** `docs` takes an optional topic OR a free-text query, plus the optional appDir. */
-const DOCS_SCHEMA = {
-  type: 'object',
-  properties: {
-    appDir: {
-      ...APPDIR_PROP,
-      description: "App directory whose docs corpus to read. Defaults to the server cwd.",
-    },
-    topic: {
-      type: 'string',
-      description: 'A doc name (e.g. components, recipes, lit-muscle-memory-gotchas, AGENTS). Returns the full doc.',
-    },
-    query: {
-      type: 'string',
-      description: 'Free-text search across all webjs docs. Returns matching lines with their source.',
+      description: 'App directory the agent is editing, checked for a newer @webjsdev/mcp than this server. Defaults to the server cwd.',
     },
   },
   required: [],
@@ -148,36 +121,29 @@ 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. A file-convention name as `export` (such as `not-found` or `middleware.ts`) returns a short guide on how WebJs wants that built. Read-only.',
     inputSchema: SOURCE_SCHEMA,
   },
   {
@@ -204,12 +170,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:
@@ -345,7 +305,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 {
@@ -353,7 +313,6 @@ export function makeToolRunners(deps) {
     buildActionIndex,
     hashFile,
     scanComponents,
-    analyzeAppElision,
     checkConventions,
     projectCheck,
     readFile,
@@ -417,15 +376,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);
@@ -563,7 +513,6 @@ export async function runMcpServer(opts) {
       buildActionIndex: server.buildActionIndex,
       hashFile: server.hashFile,
       scanComponents: server.scanComponents,
-      analyzeAppElision: server.analyzeAppElision,
       checkConventions: check.checkConventions,
       projectCheck,
       readFile,
@@ -571,47 +520,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
@@ -619,8 +537,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,
@@ -657,7 +575,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 },
       });
     }
@@ -675,39 +593,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]) {
@@ -717,10 +608,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);