@webjsdev/mcp 0.1.13 → 0.1.15

package/src/mcp-docs.js

@@ -14,11 +14,15 @@
  * given its injected `{ docsDir, agentsPath, readFile }` deps, so it is testable
  * in-process without booting a server or touching the real filesystem.
  *
- * Docs resolution (so `npx @webjsdev/cli mcp` is self-contained): a published
- * install reads the corpus bundled under `<cli>/resources/references` (copied
- * at `prepack`, see `scripts/copy-mcp-resources.js`); a monorepo dev run falls
- * back to the repo-root skill. {@link resolveDocsLocation} encodes that
- * two-path lookup so source stays single (no committed duplicate docs).
+ * Docs resolution (so `npx @webjsdev/mcp` is self-contained): the APP's own
+ * installed `@webjsdev/mcp` corpus wins, then the running server's snapshot
+ * bundled under `<pkg>/resources/references` (copied at `prepack`, see
+ * `scripts/copy-mcp-resources.js`), then a repo-root-relative fallback, which is
+ * the skill on a monorepo dev run. {@link resolveDocsLocation} encodes that
+ * lookup so source stays single
+ * (no committed duplicate docs). `init` reports which of the three it served,
+ * from the `corpus.json` build stamp, and warns when the app's installed mcp is
+ * newer than the running server (#1319).
  *
  * @module mcp-docs
  */
@@ -30,38 +34,230 @@ import { fileURLToPath } from 'node:url';
 /** The URI scheme for a framework-docs resource: `webjs-docs://<name>`. */
 const DOCS_SCHEME = 'webjs-docs://';
 
+/**
+ * The paths of one bundled corpus root (`<something>/resources`), tagged with
+ * which rung it is so a caller can say WHOSE docs it ended up serving.
+ *
+ * @param {string} root  the `resources` directory
+ * @param {'app' | 'bundled'} corpusSource  which rung this root is
+ * @returns {{ docsDir: string, agentsPath: string, skillPath: string, corpusPath: string, corpusSource: 'app' | 'bundled' }}
+ */
+function bundleAt(root, corpusSource) {
+  return {
+    docsDir: join(root, 'references'),
+    agentsPath: join(root, 'AGENTS.md'),
+    skillPath: join(root, 'SKILL.md'),
+    corpusPath: join(root, 'corpus.json'),
+    corpusSource,
+  };
+}
+
 /**
  * Resolve where the framework-docs corpus lives, plus the `AGENTS.md` contract
- * path. Tries the BUNDLED location first (a published `@webjsdev/mcp` ships
- * `resources/references/` + `resources/SKILL.md` + `resources/AGENTS.md` via `prepack`), then falls
- * back to the monorepo-root skill layout used in dev and
- * tests. Returns `{ docsDir, agentsPath }`; either path may not exist, callers
- * fail soft (an empty corpus is valid, never a crash).
+ * and build-stamp paths. Three rungs, highest first:
+ *
+ * 1. `<appDir>/node_modules/@webjsdev/mcp/resources`, the APP's own installed
+ *    copy. It wins because it is version-matched to the framework the agent is
+ *    editing, and so is the only corpus that can be correct about that app. A
+ *    globally installed server otherwise serves a snapshot frozen at whatever
+ *    it was published from, which taught reverted guidance for months (#1319).
+ * 2. `<pkgRoot>/resources`, the running server's own bundled snapshot (copied
+ *    at `prepack`, see `scripts/copy-mcp-resources.js`).
+ * 3. A repo-root-relative path, which is the monorepo skill on a dev/test run.
+ *    This rung is an unconditional FALLBACK, not a checkout probe, so a
+ *    published install whose `resources/` bundle is missing lands here too,
+ *    with `repoRoot` inside `node_modules` and an empty corpus. `corpusPath` is
+ *    `null` because no bundle was found, which is why nothing downstream may
+ *    assert a checkout on this rung.
+ *
+ * The rung-1 probe is a plain `existsSync` on the references directory rather
+ * than `require.resolve('@webjsdev/mcp')` from `appDir`, because what this needs
+ * is "a directory of markdown at a known path" and nothing more. Resolving the
+ * package would go through its `exports` map, and in this monorepo that lands on
+ * the workspace symlink back to `packages/mcp`, whose `resources/` does not
+ * exist in a checkout, so the resolve would fall to rung 3 anyway.
+ *
+ * Any returned path may not exist; callers fail soft (an empty corpus is valid,
+ * never a crash).
  *
  * @param {string} [moduleUrl]  `import.meta.url` of the caller (defaults to this module)
- * @returns {{ docsDir: string, agentsPath: string }}
+ * @param {string} [appDir]  the app being asked about; enables the rung-1 probe
+ * @returns {{ docsDir: string, agentsPath: string, skillPath: string, corpusPath: string | null, corpusSource: 'app' | 'bundled' | 'repo' }}
  */
-export function resolveDocsLocation(moduleUrl) {
+export function resolveDocsLocation(moduleUrl, appDir) {
   const here = dirname(fileURLToPath(moduleUrl || import.meta.url));
   const pkgRoot = resolve(here, '..'); // packages/mcp/src -> packages/mcp
   const repoRoot = resolve(here, '..', '..', '..'); // -> monorepo root
 
-  const bundledRefs = join(pkgRoot, 'resources', 'references');
-  if (existsSync(bundledRefs)) {
-    return {
-      docsDir: bundledRefs,
-      agentsPath: join(pkgRoot, 'resources', 'AGENTS.md'),
-      skillPath: join(pkgRoot, 'resources', 'SKILL.md'),
-    };
+  if (typeof appDir === 'string' && appDir) {
+    const appRoot = join(appDir, 'node_modules', '@webjsdev', 'mcp', 'resources');
+    if (existsSync(join(appRoot, 'references'))) return bundleAt(appRoot, 'app');
   }
+  const bundledRoot = join(pkgRoot, 'resources');
+  if (existsSync(join(bundledRoot, 'references'))) return bundleAt(bundledRoot, 'bundled');
+
   const skill = join(repoRoot, '.agents', 'skills', 'webjs');
   return {
     docsDir: join(skill, 'references'),
     agentsPath: join(repoRoot, 'AGENTS.md'),
     skillPath: join(skill, 'SKILL.md'),
+    corpusPath: null,
+    corpusSource: 'repo',
   };
 }
 
+/**
+ * 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). Only mcp's own version is read: the corpus ships INSIDE this
+ * package, so mcp's version is the only one that bounds the docs, and reading
+ * the other `@webjsdev/*` manifests would multiply the failure modes without
+ * adding signal.
+ *
+ * @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 one line naming WHICH docs corpus `init` is serving, so an agent reading a
+ * stale global install can see that it is stale (#1319). Never throws: a
+ * missing, unreadable, or malformed stamp degrades to the unstamped wording,
+ * because refusing to answer is strictly worse than answering with a caveat.
+ *
+ * @param {object} deps
+ * @returns {Promise<string>}
+ */
+async function corpusLine(deps) {
+  // Rung 3 has no stamp, and it is a FALLBACK rather than a checkout probe, so
+  // this must not claim a checkout: a published install whose `resources/` is
+  // missing lands here too, with an empty corpus and no checkout to name.
+  if (!deps.corpusPath) return 'Docs corpus: no bundled snapshot; serving whatever docs this server resolved locally.';
+  const unstamped = 'Docs corpus: an unstamped @webjsdev/mcp bundled snapshot.';
+  try {
+    const stamp = JSON.parse(await deps.readFile(deps.corpusPath, 'utf8'));
+    if (!stamp || !stamp.version) return unstamped;
+    const pkg = stamp.package || '@webjsdev/mcp';
+    const date = typeof stamp.copiedAt === 'string' && stamp.copiedAt ? stamp.copiedAt.slice(0, 10) : 'an unknown date';
+    // A SHA the stamp could not capture drops the clause rather than printing a
+    // placeholder: the point of a provenance line is that no answer reads as no
+    // answer. Same reason the shape is checked, since only a real commit id
+    // resolves to a diff.
+    const sha = typeof stamp.sha === 'string' && /^[0-9a-f]{40}$/.test(stamp.sha) ? stamp.sha.slice(0, 7) : null;
+    return sha
+      ? `Docs corpus: ${pkg}@${stamp.version}, copied from webjsdev/webjs ${sha} on ${date}.`
+      : `Docs corpus: ${pkg}@${stamp.version}, copied on ${date}.`;
+  } catch {
+    return unstamped;
+  }
+}
+
+/**
+ * What the warning says about WHOSE docs it just served, one clause per rung.
+ *
+ * A `Map` rather than an object literal, for the reason `docsDepsCache` is one:
+ * an object literal inherits `Object.prototype`, so a lookup keyed on an
+ * unexpected value like `constructor` or `toString` returns a truthy FUNCTION,
+ * the `||` fallback never fires, and the warning splices native-code source into
+ * its own text. A `Map` has no prototype keys, so the fallback covers every value
+ * that is not one of these three.
+ *
+ * The `repo` clause deliberately does NOT claim a live checkout. Rung 3 is an
+ * unconditional fallback rather than a checkout probe (see
+ * {@link resolveDocsLocation}), so it is also where a published install with no
+ * bundled `resources/` lands, and there the "checkout" does not exist and the
+ * corpus is empty.
+ */
+const SERVED_CLAUSE = new Map([
+  ['app', "The docs below come from this app's own copy, so they match it; update the server so its TOOLS match too."],
+  ['bundled', "The docs below are the server's own older snapshot, not this app's copy."],
+  ['repo', "The docs below are whatever this server resolved locally, not this app's copy."],
+]);
+
+/**
+ * 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. Equal or lower is silent: a newer server reading an older app
+ * is the ordinary shape and is not a defect. It warns rather than failing,
+ * because a read-only knowledge tool that refuses to answer sends the agent back
+ * to its training data, which is the thing the caveat exists to correct.
+ *
+ * Two things the wording is careful about, because the obvious phrasings are both
+ * wrong:
+ *
+ * - It does NOT name a global install as the thing to update. Nothing here can
+ *   observe how the server was started, and the shipped configurations are an
+ *   `npx @webjsdev/mcp` (whose staleness is a package cache) and `webjs mcp`
+ *   (whose staleness is `@webjsdev/cli`'s own dependency), neither of which a
+ *   `npm i -g` would fix.
+ * - It does NOT promise the docs below are the app's. The warning's probe is the
+ *   app's `package.json`, while the corpus rung's probe is that install's
+ *   `resources/references`, and the two can disagree: a workspace-linked or
+ *   otherwise resources-less install has a manifest to read but no corpus to
+ *   serve, so the corpus falls through to the server's older snapshot. That case
+ *   gets an extra clause naming what was actually served, rather than a claim
+ *   that contradicts the corpus line printed directly beneath it.
+ *
+ * @param {object} deps
+ * @returns {Promise<string | null>}
+ */
+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;
+  const served = SERVED_CLAUSE.get(deps.corpusSource) || "The docs below may not be this app's copy.";
+  return (
+    `Warning: this MCP server is @webjsdev/mcp@${server}, but this app has @webjsdev/mcp@${app}, ` +
+    `so the server may be stale. ${served} ` +
+    '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.'
+  );
+}
+
 /**
  * A doc's logical name from its filename: `lit-muscle-memory-gotchas.md` ->
  * `lit-muscle-memory-gotchas`. The `AGENTS.md` contract keeps its own name.
@@ -191,6 +387,8 @@ export function sectionByHeading(md, headingRe) {
 export async function initText(deps) {
   let agents = '';
   try { agents = await deps.readFile(deps.agentsPath, 'utf8'); } catch { agents = ''; }
+  const corpus = await corpusLine(deps);
+  const warning = await staleWarning(deps);
   const execModel = sectionByHeading(agents, /^##\s+Execution model/im);
   const invariants = sectionByHeading(agents, /^##\s+Invariants/im);
 
@@ -217,6 +415,11 @@ export async function initText(deps) {
   const parts = [
     '# webjs: read first',
     '',
+    // Provenance first, so an agent reading a months-old global install sees
+    // which docs it is holding before it reads a word of them (#1319).
+    ...(warning ? [warning, ''] : []),
+    corpus,
+    '',
     router,
     '',
     execModel || '(execution-model section unavailable)',

package/src/mcp-source.js

@@ -13,7 +13,8 @@
  *     `src/` entry-point files.
  *   - `query`: grep the framework `src/` trees, returning bounded `file:line`
  *     hits (with a disclosed cap, no silent truncation).
- *   - `path`: read one source file (e.g. `server/src/ssr.js`), traversal-guarded
+ *   - `path`: read one source file (e.g. `server/src/ssr/head.js`; the bare
+ *     `server/src/ssr.js` is a barrel over the sibling directory), traversal-guarded
  *     to stay inside a resolved framework package root.
  *
  * READ-ONLY and side-effect-free: it only reads files, loads no module, and
@@ -209,7 +210,7 @@ export async function readSource(deps, path) {
   const pkg = segs[0];
   const entry = deps.roots.find((r) => r.pkg === pkg);
   if (!entry) {
-    return `Unknown or unresolvable package "${pkg || path}". Resolvable: ${deps.roots.map((r) => r.pkg).join(', ') || '(none)'}. Pass a path like server/src/ssr.js.`;
+    return `Unknown or unresolvable package "${pkg || path}". Resolvable: ${deps.roots.map((r) => r.pkg).join(', ') || '(none)'}. Pass a path like server/src/ssr/head.js.`;
   }
   const abs = resolve(entry.root, segs.slice(1).join('/'));
   const srcLabel = entry.src.split(sep).pop();
@@ -237,17 +238,158 @@ export async function readSource(deps, path) {
   }
 }
 
+/** Bound one export's rendered declaration (a long interface body is cut here). */
+const MAX_DECL_LINES = 40;
+/** Bound the hits one lookup returns (overloads plus a JS fallback stay well under this). */
+const MAX_EXPORT_HITS = 8;
+
+/**
+ * Collect the JSDoc block (or the `//` run) that ends on the line right above
+ * `line`, as the lines themselves, or `[]` when the declaration has no comment.
+ * @param {string[]} lines
+ * @param {number} line index of the declaration line
+ * @returns {string[]}
+ */
+function docAbove(lines, line) {
+  let i = line - 1;
+  if (i < 0) return [];
+  if (lines[i].trim().endsWith('*/')) {
+    const end = i;
+    while (i >= 0 && !lines[i].trim().startsWith('/**')) {
+      if (lines[i].trim().startsWith('/*') && !lines[i].trim().startsWith('/**')) return [];
+      i--;
+    }
+    return i < 0 ? [] : lines.slice(i, end + 1);
+  }
+  const end = i;
+  while (i >= 0 && lines[i].trim().startsWith('//')) i--;
+  return i === end ? [] : lines.slice(i + 1, end + 1);
+}
+
+/**
+ * The declaration that starts on `line`: a `function` / `const` / `type`
+ * statement runs to its terminating `;` (a `.js` function stops at its opening
+ * brace, so the body is never printed); an `interface` / `class` runs to the
+ * brace that closes it. Capped at {@link MAX_DECL_LINES}.
+ * @param {string[]} lines
+ * @param {number} line
+ * @param {boolean} isTypes true for a `.d.ts` file
+ * @returns {string[]}
+ */
+function declarationFrom(lines, line, isTypes) {
+  const first = lines[line];
+  const braced = /^export\s+(?:declare\s+)?(?:abstract\s+)?(?:interface|class|enum)\b/.test(first)
+    || (/^export\s+(?:declare\s+)?(?:const|let|var|type)\b/.test(first) && /[{(]\s*$/.test(first) && !/;\s*$/.test(first));
+  const out = [];
+  let depth = 0;
+  // An authored `export const x = (...) => {` is its first line: the value is
+  // the implementation, and the doc above it is the contract.
+  if (!isTypes && /^export\s+(?:const|let|var)\b/.test(first)) return [first];
+  for (let i = line; i < lines.length && out.length < MAX_DECL_LINES; i++) {
+    const l = lines[i];
+    if (!isTypes && /^export\s+(?:async\s+)?function\b/.test(first)) {
+      // A JS function: the signature only, cut at the body's opening brace.
+      const cut = l.indexOf('{');
+      if (cut >= 0 && (i > line || !/^\s*\/\//.test(l))) { out.push(l.slice(0, cut).trimEnd()); return out; }
+      out.push(l);
+      continue;
+    }
+    out.push(l);
+    if (braced) {
+      for (const ch of l) { if (ch === '{') depth++; else if (ch === '}') depth--; }
+      if (depth <= 0 && /}/.test(l) && i > line) return out;
+      if (depth <= 0 && i === line && /}\s*;?\s*$/.test(l)) return out;
+    } else {
+      // Balanced parens and braces matter for a multi-line signature; angle
+      // brackets are not counted (an arrow's `=>` would unbalance them).
+      for (const ch of l) { if (ch === '(' || ch === '{') depth++; else if (ch === ')' || ch === '}') depth--; }
+      if (depth <= 0 && /;\s*$/.test(l)) return out;
+      if (depth <= 0 && !isTypes && /=\s*\(.*\)\s*=>/.test(first) && i === line) return out;
+    }
+  }
+  if (out.length >= MAX_DECL_LINES) out.push(`  ... (cut at ${MAX_DECL_LINES} lines; read the file with \`path\` for the rest)`);
+  return out;
+}
+
+/**
+ * `export` mode: ONE export's signature plus its doc comment, so an agent
+ * checking a contract pays for the declaration instead of the whole file. The
+ * typed declarations win (`index.d.ts` and `src/**\/*.d.ts` under each package
+ * root, where `@webjsdev/server` keeps every export with its doc and
+ * `@webjsdev/core` keeps them beside the source); the authored `.js` is the
+ * fallback when no typed hit exists or none of them carries a doc, since the
+ * JSDoc there is the behaviour contract. Overloads are consecutive hits and
+ * all print. A miss discloses the searched packages (the #837 rule): nothing
+ * resolvable means NOTHING was searched, never "not found".
+ *
+ * @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`
+ * @returns {Promise<string>}
+ */
+export async function lookupExport(deps, name, pkgFilter) {
+  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;
+  if (!deps.roots.length) {
+    return 'No @webjsdev/* source is resolvable here, so NOTHING was searched (run inside a webjs app or the monorepo). This is not the same as "not found".';
+  }
+  if (!roots.length) {
+    return `@webjsdev/${pkgFilter} is not installed/resolvable here. Resolvable: ${deps.roots.map((r) => r.pkg).join(', ')}.`;
+  }
+  const typesRe = new RegExp(`^export\\s+(?:declare\\s+)?(?:abstract\\s+)?(?:async\\s+)?(?:function\\*?|const|let|var|class|interface|type|enum)\\s+${n.replace(/\$/g, '\\$')}\\b`);
+  const jsRe = new RegExp(`^export\\s+(?:async\\s+)?(?:function\\*?|const|let|var|class)\\s+${n.replace(/\$/g, '\\$')}\\b`);
+  /** @type {Array<{ pkg: string, rel: string, line: number, doc: string[], decl: string[], types: boolean }>} */
+  const hits = [];
+  for (const r of roots) {
+    const typeFiles = walkSource(r.root, deps).filter((f) => /\.d\.(?:ts|mts|cts)$/.test(f));
+    const jsFiles = walkSource(r.src, deps).filter((f) => /\.(?:js|mjs)$/.test(f));
+    for (const [files, isTypes] of [[typeFiles, true], [jsFiles, false]]) {
+      for (const file of files) {
+        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 (!(isTypes ? typesRe : jsRe).test(lines[i])) continue;
+          hits.push({ pkg: r.pkg, rel, line: i + 1, doc: docAbove(lines, i), decl: declarationFrom(lines, i, isTypes), types: isTypes });
+        }
+      }
+    }
+  }
+  const searched = deps.roots.map((r) => r.pkg).join(', ');
+  if (!hits.length) {
+    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
+  // typed hits say nothing about behaviour (no doc on any of them), or there
+  // is no typed hit at all.
+  const typed = hits.filter((h) => h.types);
+  const typedHasDoc = typed.some((h) => h.doc.length);
+  const shown = typed.length && typedHasDoc ? typed : typed.length ? [...typed, ...hits.filter((h) => !h.types && h.doc.length)] : hits;
+  const out = [];
+  for (const h of shown.slice(0, MAX_EXPORT_HITS)) {
+    out.push(`@webjsdev/${h.pkg} ${h.rel}:${h.line}`);
+    out.push(...h.doc, ...h.decl, '');
+  }
+  if (shown.length > MAX_EXPORT_HITS) out.push(`... (${shown.length - MAX_EXPORT_HITS} more declarations; narrow with \`package\`)`);
+  return out.join('\n').trimEnd();
+}
+
 /**
- * The `source` tool entry point. Dispatches on the args: `path` reads a file,
- * `query` greps, otherwise (or with `package`) lists the packages. PURE given
- * `deps` (`{ roots, readFile, readdir }`).
+ * 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`
+ * (`{ roots, readFile, readdir }`).
  *
  * @param {object} deps
- * @param {{ query?: string, path?: string, package?: string }} [args]
+ * @param {{ export?: string, query?: string, path?: string, package?: string }} [args]
  * @returns {Promise<string>}
  */
 export async function runSourceTool(deps, args) {
   const a = args || {};
+  if (a.export) return lookupExport(deps, a.export, a.package);
   if (a.path) return readSource(deps, a.path);
   if (a.query) return grepSources(deps, a.query);
   return listSources(deps, a.package);

package/src/mcp.js

@@ -33,6 +33,9 @@ import {
   getPrompt,
 } from './mcp-docs.js';
 import { resolveFrameworkRoots, runSourceTool } 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';
 import { projectRoutes } from './routes-report.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
@@ -50,25 +53,46 @@ const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'vali
  * into an agent-friendly shape. Descriptions are crisp so a model picks the
  * right tool without reading source.
  */
+/**
+ * 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.
+ */
+const APPDIR_PROP = {
+  type: 'string',
+  description: 'App directory to introspect. Defaults to the server cwd.',
+};
+
 /** The shared input schema for the introspection tools: an optional appDir override. */
 const APPDIR_SCHEMA = {
+  type: 'object',
+  properties: { appDir: { ...APPDIR_PROP } },
+  required: [],
+};
+
+/** `init` takes only the optional appDir, which selects whose docs corpus it reports. */
+const INIT_SCHEMA = {
   type: 'object',
   properties: {
     appDir: {
-      type: 'string',
-      description: 'App directory to introspect. Defaults to the server cwd.',
+      ...APPDIR_PROP,
+      description: "App directory whose docs corpus to read. Defaults to the server cwd.",
     },
   },
   required: [],
 };
 
-/** `init` takes no input. */
-const INIT_SCHEMA = { type: 'object', properties: {}, required: [] };
-
-/** `docs` takes an optional topic OR a free-text query. */
+/** `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.',
@@ -97,9 +121,13 @@ const UI_SCHEMA = {
 const SOURCE_SCHEMA = {
   type: 'object',
   properties: {
+    export: {
+      type: 'string',
+      description: 'One export name, e.g. createAuth or optimistic: returns its signature plus the doc comment above it (from the typed declarations, with the authored JSDoc as the fallback), not the whole file. The cheapest way to check a contract.',
+    },
     path: {
       type: 'string',
-      description: 'A framework source file to read, e.g. server/src/ssr.js or @webjsdev/core/src/render-client.js.',
+      description: 'A framework source file to read, e.g. server/src/ssr/head.js or @webjsdev/core/src/render-client/parts.js. The top-level ssr.js / render-client.js paths are barrels; the code is in the sibling directory.',
     },
     query: {
       type: 'string',
@@ -136,7 +164,7 @@ const TOOL_DEFS = [
   {
     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 `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.',
+      '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.',
     inputSchema: SOURCE_SCHEMA,
   },
   {
@@ -500,22 +528,46 @@ 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 bundled
-  // (published) or repo-root (dev) docs and node fs.
-  let docsDeps = opts.docsDeps;
-  if (!docsDeps) {
-    const loc = resolveDocsLocation(import.meta.url);
+  // 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) {
     const { readFile } = await import('node:fs/promises');
     const { readdirSync, existsSync } = await import('node:fs');
-    docsDeps = {
-      docsDir: loc.docsDir,
-      agentsPath: loc.agentsPath,
-      skillPath: loc.skillPath,
-      listDir: readdirSync,
-      exists: existsSync,
-      readFile,
-    };
+    docsFs = { listDir: readdirSync, exists: existsSync, readFile };
   }
+  /** @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;
+  };
 
   // 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
@@ -581,12 +633,12 @@ export async function runMcpServer(opts) {
 
     // Knowledge layer (#376): the framework docs as MCP resources.
     if (method === 'resources/list') {
-      return rpcResult(id, { resources: listResources(docsDeps) });
+      return rpcResult(id, { resources: listResources(docsDepsFor(cwd)) });
     }
     if (method === 'resources/read') {
       const uri = ((msg && msg.params) || {}).uri;
       try {
-        const r = await readResource(docsDeps, uri);
+        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));
@@ -621,9 +673,9 @@ export async function runMcpServer(opts) {
       try {
         const result = isKnowledgeTool
           ? name === 'init'
-            ? await initText(docsDeps)
+            ? await initText(docsDepsFor(appDir))
             : name === 'docs'
-              ? await searchDocs(docsDeps, args)
+              ? await searchDocs(docsDepsFor(appDir), args)
               : await runSourceTool(sourceDeps, args)
           : isUiTool
             ? runUiTool(uiDeps, args)