# AGENTS.md for @webjsdev/mcp

The webjs **Model Context Protocol server** (extracted from `@webjsdev/cli` in
#415). A hand-rolled, READ-ONLY MCP stdio server, ZERO runtime dependency
beyond `@webjsdev/server` for its introspection data functions.

Framework-wide rules (workflow, JSDoc-in-`packages/`, no-build, commit
conventions) live in the **framework root [`../../AGENTS.md`](../../AGENTS.md)**
and apply here. Read that first. This file covers only what is specific to
`@webjsdev/mcp`.

## Entry points

- **`npx @webjsdev/mcp`** (`bin/webjs-mcp.js`): the agent-facing server an MCP
  host registers. The scaffold wires it into `.claude.json`.
- **`webjs mcp`** (the CLI subcommand): delegates to `runMcpServer` from this
  package, so the implementation has a single home. Back-compat only.

Both speak newline-delimited JSON-RPC 2.0 over stdio. STDOUT IS THE PROTOCOL
CHANNEL; every diagnostic goes to stderr. A malformed line is answered with a
parse error and never crashes the loop.

## Module map

```
bin/
  webjs-mcp.js           npx entry: reads the package version, runs runMcpServer
                         with the process streams.
src/
  mcp.js                 runMcpServer({ stdin, stdout, stderr, cwd, version,
                         deps?, docsDeps?, sourceDeps? }). The JSON-RPC loop +
                         the tool/resource/prompt dispatch. Handshake:
                         initialize -> serverInfo + capabilities (tools +
                         resources + prompts); notifications/initialized -> no
                         reply; tools/list, tools/call, resources/*, prompts/*.
                         INTROSPECTION tools (read-only, appDir-scoped), each
                         projecting a @webjsdev/server function: list_routes
                         (buildRouteTable), list_actions (buildActionIndex +
                         hashFile), list_components (scanComponents), check
                         (checkConventions via projectCheck). Export names are
                         extracted LEXICALLY (extractExportNames /
                         extractRouteMethods) so no app module is loaded.
                         `deps` / `docsDeps` / `sourceDeps` are injectable for
                         in-process tests.
  mcp-docs.js            KNOWLEDGE layer (#376): resolveDocsLocation (bundled
                         resources/ first, repo-root agent-docs fallback in
                         dev), the init primer (sources the AGENTS.md
                         execution-model + invariants so it cannot drift), the
                         docs tool, resources (the agent-docs corpus + AGENTS.md
                         as webjs-docs://*), and the recipe PROMPTS.
  mcp-source.js          SOURCE tool (#378): reads the framework's own no-build
                         source from node_modules/@webjsdev/*/src (read-only,
                         traversal-guarded via realpath, loads no module).
                         resolveFrameworkRoots locates each package by probing
                         the require.resolve node_modules dirs.
  check-report.js        projectCheck(violations) -> { violations, summary }.
                         The shared shape returned by BOTH the MCP `check` tool
                         and `webjs check --json` (the CLI imports it from
                         `@webjsdev/mcp/check-report`), so the two are identical.
scripts/
  copy-mcp-resources.js  prepack: bundle the repo-root agent-docs/ + AGENTS.md
                         into resources/ (in `files`) so npx is self-contained.
                         Exports the reusable bundleDocs(...).
  clean-mcp-resources.js postpack: remove the transient resources/ bundle so dev
                         always reads the live repo-root docs. Exports
                         cleanBundle(...).
```

## Invariants

1. **STDOUT is JSON-RPC only.** Never `console.log` in the request path;
   diagnostics go to stderr (`logErr`). A stray stdout write corrupts the
   stream.
2. **Read-only.** Every tool projects an existing `@webjsdev/server` data
   function (or reads source/docs) and mutates nothing. No app module is loaded
   (export names are extracted lexically) so there are no DB-init side effects.
3. **The docs bundle is transient.** `resources/` exists only inside the
   published tarball (prepack writes it, postpack removes it). In the monorepo
   it is absent and `resolveDocsLocation` falls back to the live repo-root docs,
   so source stays single.

## Tests

`test/mcp.test.mjs`, `test/mcp-docs.test.mjs`, `test/mcp-source.test.mjs`,
`test/check-report.test.mjs`. `runMcpServer` is driven in-process with injected
deps, so no real server boots. Run `npm test` from the repo root.

---

Framework-wide rules and full API reference:

@../../AGENTS.md
