feat: extend webjs mcp with a knowledge + authoring layer (Next-MCP parity)

[vivek7405]

Problem

webjs mcp (packages/cli/lib/mcp.js, #262) is a hand-rolled, zero-dependency stdio MCP server that exposes four READ-ONLY introspection tools: list_routes, list_actions, list_components, check. That maps to Next.js's BUILT-IN /_next/mcp introspection layer (and is arguably better: static-analysis based, so it needs no running dev server). But it is missing the entire SECOND layer that Next's agent-facing next-devtools-mcp package provides: the knowledge + authoring surface that actually helps an agent write idiomatic code.

Analysis of the Next.js MCP (both halves: the in-framework packages/next/src/server/mcp/ endpoint and the standalone vercel/next-devtools-mcp) shows the high-leverage patterns webjs lacks:

• Bundled docs as MCP resources + a docs retrieval tool (nextjs_docs, an llms.txt index, ~14 cache-component deep-dive docs as resources).
• An init "call this first" tool that loads conventions/mental-model before the agent acts (directly fights the "agent applies a React/RSC mental model" failure, which is webjs's Corrected backtick errors #1 risk too).
• Guided-workflow prompts (MCP prompts: upgrade_nextjs_16, enable_cache_components).
• An eval harness (@anthropic-ai/claude-agent-sdk) that scores whether the MCP improves agent success, and add-mcp cross-agent install.

webjs already ships the raw knowledge (agent-docs/*.md, the invariants in AGENTS.md, the recipes in agent-docs/recipes.md, the lit-gotchas doc) but does not surface ANY of it through the MCP, so an agent gets introspection but no authoring guidance or self-serve docs.

Design / approach

Extend the EXISTING hand-rolled server in packages/cli/lib/mcp.js, staying zero-dependency (do NOT pull in @modelcontextprotocol/sdk the way Next does; webjs is buildless + minimal-deps, and the JSON-RPC dispatch is already there). Add the second layer in coherent pieces:

1. MCP resources. Implement resources/list + resources/read in the dispatch, exposing the framework knowledge as resources: each agent-docs/*.md, the AGENTS.md invariants, CONVENTIONS.md, the recipes. Advertise the resources capability in initialize. The docs ship inside @webjsdev/cli (or are read from the resolved framework install) so the server is self-contained.
2. init tool (the "read first" primer). Returns the webjs mental-model essentials in one shot: the execution model (no RSC / no use-client split, components hydrate, pages/layouts do not), signals-default state, the .server.{js,ts} boundary, the modules layout, and the most-violated invariants. Sourced from the existing docs, not hand-duplicated, so it cannot drift.
3. docs retrieval tool. docs({ query | topic }) searches/returns the relevant agent-docs section, for agents that prefer a tool call over browsing resources. Includes a topic index (the table at the top of AGENTS.md).
4. MCP prompts. Implement prompts/list + prompts/get, exposing the recipes as guided workflows (add a page, a dynamic route, a server action, a component, a module). Advertise the prompts capability.
5. Protocol + capabilities. Advertise resources + prompts (currently only tools); keep the handshake otherwise unchanged. Stay on newline-delimited JSON-RPC stdio.

Keep every addition read-only and side-effect-free (lexical reads only, no app module loads), matching the current server's discipline. Update the scaffold .claude.json comment + the cli AGENTS.md webjs mcp entry + the docs site so the new surface is discoverable, and note the cross-agent install story (Cursor .cursor/mcp.json, etc.).

Deliberately deferred to follow-ups (keep this PR coherent):

• A validate({ code }) snippet checker (writes a temp file, runs the relevant webjs check rules) - useful but needs temp-file plumbing; file separately.
• An eval harness scoring agent success with the MCP on/off (a @anthropic-ai/claude-agent-sdk dev-dependency) - valuable quality gate, separate issue.
• A live-dev-server bridge / get-errors-style runtime tools - lower value since webjs is buildless and static check already covers correctness.

Acceptance criteria

• initialize advertises resources and prompts capabilities alongside tools.
• resources/list + resources/read serve the framework knowledge (each agent-docs/*.md, the AGENTS.md invariants, CONVENTIONS.md, recipes); a resource read returns the doc text.
• An init tool returns the webjs mental-model primer (execution model, signals, .server boundary, modules layout, top invariants), sourced from the shipped docs.
• A docs tool retrieves a doc section by topic/query, with a topic index.
• prompts/list + prompts/get expose the recipe workflows (page / route / action / component / module).
• Everything stays READ-ONLY, side-effect-free, and ZERO new runtime dependency (hand-rolled, consistent with Add a read-only webjs MCP server and webjs check --json #262).
• Unit tests cover the new JSON-RPC methods (resources/list, resources/read, prompts/list, prompts/get) and the new tools, including a counterfactual (an unknown resource URI / prompt name errors cleanly, never crashes the loop).
• Docs updated: packages/cli/AGENTS.md webjs mcp entry, the scaffold .claude.json (+ cross-agent note), and the docs site if user-facing.
• The docs shipped as resources are packaged with @webjsdev/cli (or resolved from the framework install) so npx @webjsdev/cli mcp is self-contained.