@webjsdev/mcp 0.1.13 → 0.1.15

package/README.md

@@ -34,9 +34,11 @@ subcommand) delegates to this same server, so both routes run identical code.
   no verdict at all; identical to `webjs elision --json`),
   `check` (the structured `webjs check` violations). Each projects an existing
   `@webjsdev/server` data function and mutates nothing.
-- **Knowledge layer**: an `init` mental-model primer, a `docs` retrieval tool,
-  MCP `resources` (the skill references + `SKILL.md` + `AGENTS.md` as `webjs-docs://*`),
-  and `prompts` (the recipes as guided workflows).
+- **Knowledge layer**: an `init` mental-model primer (which also names the docs
+  corpus it is serving, and warns when this server's copy looks stale against
+  the app's), a `docs` retrieval tool, MCP `resources` (the skill references +
+  `SKILL.md` + `AGENTS.md` as `webjs-docs://*`), 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
@@ -44,10 +46,65 @@ subcommand) delegates to this same server, so both routes run identical code.
   `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.
+## Which docs you get
 
-That bundle is a snapshot frozen at publish time, so a published tarball keeps
+The corpus is resolved in three rungs, highest first:
+
+1. `<appDir>/node_modules/@webjsdev/mcp/resources`, the app's own installed copy.
+2. `<pkg>/resources`, this server's bundled snapshot, so `npx @webjsdev/mcp` is
+   self-contained.
+3. Whatever the server resolves locally, which is the repo-root skill on the
+   monorepo dev path. This rung is an unconditional fallback rather than a
+   checkout probe, so a published install whose `resources/` bundle is missing
+   lands here too, with an empty corpus. That is why neither the corpus line nor
+   the warning asserts a checkout.
+
+The app's copy wins because it is version-matched to the framework you are
+editing, and so is the only corpus that can be correct about that app. This
+matters most for a GLOBAL install (`npm i -g` / `bun add -g`), which otherwise
+keeps serving the docs it was published with forever, contradicting the copy
+sitting in your own `node_modules`. That is a real incident, not a hypothetical:
+a server published one day before the client router stopped needing an explicit
+`import '@webjsdev/core/client-router'` kept teaching that import for months, and
+an agent following it wrote dead imports into three layouts, each of which the
+elision analyser then correctly refused to strip.
+
+`appDir` is a per-call argument, so the corpus follows it. `resources/list` and
+`resources/read` carry no `appDir` in the MCP protocol and resolve from the
+server's working directory, which is what a `tools/call` with no `appDir`
+defaults to, so in the ordinary case every surface reads one corpus.
+
+`init` names the corpus it served on its first line, and prepends a warning when
+the app's installed `@webjsdev/mcp` is strictly newer than the running server's:
+
+```
+Warning: this MCP server is @webjsdev/mcp@0.1.4, but this app has @webjsdev/mcp@0.1.12,
+so the server may be stale. The docs below come from this app's own copy, so they
+match it; update the server so its TOOLS match too. 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.
+Docs corpus: @webjsdev/mcp@0.1.12, copied from webjsdev/webjs e5806e2 on 2026-08-08.
+```
+
+It warns rather than refusing to answer, because a knowledge tool that declines
+sends the agent back to its training data, which is what the caveat exists to
+correct. Equal versions, an older app, and an unreadable app manifest are all
+silent.
+
+Two details the wording is deliberate about. It does not name a global install as
+the thing to fix, because nothing observes how the server was started and the two
+shipped configurations are an `npx` invocation (whose staleness is a package
+cache) and `webjs mcp` (whose staleness is the CLI's own dependency). And it does
+not promise the docs below came from the app: the warning reads the app's
+`package.json` while the corpus rung probes that install's `resources/`, so a
+workspace-linked install can have a manifest to compare and no corpus to serve.
+In that case the corpus falls through to the server's snapshot and the warning
+says so, rather than contradicting the corpus line printed under it.
+
+## The build stamp
+
+The bundle is a snapshot frozen at publish time, so a published tarball keeps
 serving the docs as they read on the day it was cut. `prepack` stamps it with
 `resources/corpus.json` so the snapshot can say which docs it holds:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "description": "The Model Context Protocol server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Gives AI coding agents live app introspection over routes, actions, components, and convention checks, plus a knowledge layer of docs, recipes, and framework source.",
   "bin": {