@nifrajs/cli 3.3.0 → 4.0.0

package/src/mcp-project-child.ts

@@ -0,0 +1,182 @@
+/**
+ * The subprocess `nifra mcp` runs project code in. The server (`mcp-isolate.ts`) spawns a fresh one
+ * per call in the project's directory, so Bun loads that directory's `.env` files here, and the
+ * config, the backend and everything they import run here and exit with the process. The tools,
+ * resources and prompts answered here are the same ones the server lists: the project tools, and the
+ * ones the app declares on its backend.
+ *
+ * Protocol: one JSON request on stdin; on stdout, progress lines and then one answer line, each
+ * prefixed with the request's token, so anything project code prints cannot be read as an answer.
+ */
+
+import { detectMonorepo } from "./load.ts"
+import { projectResources } from "./mcp-context.ts"
+import { createCachedAppLoader, projectTools } from "./mcp-exec.ts"
+import { CHILD_INPUT_MAX_BYTES, readBoundedStream } from "./mcp-io.ts"
+import type {
+  McpPrompt,
+  McpPromptMessage,
+  McpResource,
+  McpTool,
+  McpToolResult,
+} from "./mcp-protocol.ts"
+import {
+  extractBackendPrompts,
+  extractBackendResources,
+  extractBackendTools,
+} from "./mcp-reflect.ts"
+
+export type ProjectChildRequest =
+  | { readonly op: "monorepo" }
+  | { readonly op: "surface" }
+  | { readonly op: "tool"; readonly name: string; readonly args: Record<string, unknown> }
+  | { readonly op: "resource"; readonly uri: string }
+  | { readonly op: "prompt"; readonly name: string; readonly args: Record<string, unknown> }
+
+/** What the server lists for the tools, resources and prompts the app declares on its backend. */
+export interface AppSurface {
+  readonly tools: readonly Omit<McpTool, "handler">[]
+  readonly resources: readonly Omit<McpResource, "read">[]
+  readonly prompts: readonly Omit<McpPrompt, "handler">[]
+}
+
+export type ProjectChildAnswer =
+  | { readonly ok: true; readonly apps: Readonly<Record<string, string>> | null }
+  | { readonly ok: true; readonly surface: AppSurface }
+  | { readonly ok: true; readonly result: string | McpToolResult }
+  | { readonly ok: true; readonly resource: { readonly text: string; readonly mimeType?: string } }
+  | { readonly ok: true; readonly messages: readonly McpPromptMessage[] }
+  | { readonly ok: false; readonly message: string }
+
+export type ProjectChildMessage =
+  | { readonly type: "progress"; readonly progress: number; readonly total?: number }
+  | { readonly type: "answer"; readonly answer: ProjectChildAnswer }
+
+/**
+ * Answer `request` for the project at `cwd`. A tool, resource or prompt that throws answers
+ * `ok: false` with its message; an app that cannot be loaded declares nothing, as in the server.
+ */
+export async function answerProjectRequest(
+  cwd: string,
+  request: ProjectChildRequest,
+  reportProgress: (progress: number, total?: number) => void = () => {},
+): Promise<ProjectChildAnswer> {
+  try {
+    if (request.op === "monorepo") {
+      return { ok: true, apps: (await detectMonorepo(cwd))?.apps ?? null }
+    }
+    const loadAppCached = createCachedAppLoader(cwd)
+    const backend = (): Promise<unknown> =>
+      loadAppCached().then(
+        (app) => app.backend,
+        () => undefined,
+      )
+    if (request.op === "surface") {
+      const declared = await backend()
+      return {
+        ok: true,
+        surface: {
+          tools: extractBackendTools(declared),
+          resources: extractBackendResources(declared),
+          prompts: extractBackendPrompts(declared),
+        },
+      }
+    }
+    if (request.op === "tool") {
+      const tool =
+        projectTools(cwd, loadAppCached).find((t) => t.name === request.name) ??
+        extractBackendTools(await backend()).find((t) => t.name === request.name)
+      if (tool === undefined) return { ok: false, message: `unknown tool: ${request.name}` }
+      const result = await tool.handler(request.args, {
+        signal: new AbortController().signal,
+        requestId: null,
+        reportProgress,
+      })
+      return { ok: true, result }
+    }
+    if (request.op === "resource") {
+      const resource =
+        projectResources(cwd, loadAppCached).find((r) => r.uri === request.uri) ??
+        extractBackendResources(await backend()).find((r) => r.uri === request.uri)
+      if (resource === undefined) return { ok: false, message: `unknown resource: ${request.uri}` }
+      return { ok: true, resource: await resource.read() }
+    }
+    const prompt = extractBackendPrompts(await backend()).find((p) => p.name === request.name)
+    if (prompt === undefined) return { ok: false, message: `unknown prompt: ${request.name}` }
+    return { ok: true, messages: await prompt.handler(request.args) }
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const isArgs = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+function parseRequest(text: string): { token: string; request: ProjectChildRequest } | undefined {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (!isArgs(value)) return undefined
+  const { token, op, name, uri, args } = value
+  if (typeof token !== "string" || !/^[0-9a-f-]{16,64}$/.test(token)) return undefined
+  if (op === "monorepo" || op === "surface") return { token, request: { op } }
+  if (op === "resource" && typeof uri === "string") return { token, request: { op, uri } }
+  if ((op === "tool" || op === "prompt") && typeof name === "string" && isArgs(args)) {
+    return { token, request: { op, name, args } }
+  }
+  return undefined
+}
+
+/**
+ * Serve one request: read it from `input`, answer it and write each message through `write`,
+ * prefixed with the request's token. Returns false (writing nothing) for a malformed request.
+ */
+export async function serveProjectChild(
+  cwd: string,
+  input: ReadableStream<Uint8Array>,
+  write: (line: string) => Promise<void>,
+): Promise<boolean> {
+  const text = await readBoundedStream(input, CHILD_INPUT_MAX_BYTES)
+  const parsed = text.truncated ? undefined : parseRequest(text.text)
+  if (parsed === undefined) return false
+  const send = (message: ProjectChildMessage): Promise<void> =>
+    write(`${parsed.token} ${JSON.stringify(message)}\n`)
+  const answer = await answerProjectRequest(cwd, parsed.request, (progress, total) => {
+    void send(
+      total === undefined ? { type: "progress", progress } : { type: "progress", progress, total },
+    )
+  })
+  let line: string
+  try {
+    line = JSON.stringify({ type: "answer", answer } satisfies ProjectChildMessage)
+  } catch {
+    line = JSON.stringify({
+      type: "answer",
+      answer: { ok: false, message: "the answer is not serializable" },
+    } satisfies ProjectChildMessage)
+  }
+  await write(`${parsed.token} ${line}\n`)
+  return true
+}
+
+if (import.meta.main) {
+  // Bound before project code loads, so nothing it patches can reach the protocol channel.
+  const stdout = process.stdout.write.bind(process.stdout)
+  const toStderr = (...args: unknown[]): void => {
+    process.stderr.write(`${args.map((arg) => String(arg)).join(" ")}\n`)
+  }
+  console.log = toStderr
+  console.info = toStderr
+  console.debug = toStderr
+  const served = await serveProjectChild(
+    process.argv[2] ?? process.cwd(),
+    Bun.stdin.stream(),
+    (line) => new Promise((done) => stdout(line, () => done())),
+  )
+  if (!served) process.stderr.write("nifra mcp: invalid project request\n")
+  // Project code may leave a handle open (a pool, an interval); the answer is written, so stop here.
+  process.exit(served ? 0 : 2)
+}

package/src/mcp-reflect.ts

@@ -5,7 +5,8 @@
  * about stdio, HTTP, root trust, or project loading, so the reflection seam is independently testable.
  */
 
-import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+import { reflectedRoutesFromEvidence, snapshotProjectEvidence } from "@nifrajs/core/evidence"
+import type { ReflectedRoute } from "@nifrajs/core/reflection"
 import type {
   McpPrompt,
   McpPromptMessage,
@@ -24,7 +25,7 @@ type ToolBackend = {
 export function extractBackendTools(backend: unknown): McpTool[] {
   const b = backend as ToolBackend | null
   if (!b || typeof b.routes !== "function") return []
-  const routes = reflectRoutes(b)
+  const routes = reflectedRoutesFromEvidence(snapshotProjectEvidence(b))
 
   return routes
     .filter(

package/src/mcp-render.ts

@@ -10,11 +10,18 @@
  * `{ error }` so the agent gets the actionable message.
  */
 
-import { inProcessClient } from "@nifrajs/client"
 import { type AppLike, runApp } from "@nifrajs/runner"
 import { createWebApp, type RenderAdapter } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import { loadApp, resolvePlugins } from "./load.ts"
+import {
+  CHILD_INPUT_MAX_BYTES,
+  CHILD_OUTPUT_MAX_BYTES,
+  readBoundedLines,
+  readBoundedStream,
+  serializeBoundedJson,
+} from "./mcp-io.ts"
+import { frameworkWebAppOptions } from "./web-app-options.ts"
 
 const errString = (err: unknown): string =>
   err instanceof Error ? `${err.name}: ${err.message}` : String(err)
@@ -47,7 +54,7 @@ async function buildWebApp(cwd: string): Promise<{ app: AppLike } | { error: str
       adapter: app.framework.adapter as RenderAdapter,
       manifest: discoverRoutes(app.routesDir),
       clientEntry: "/_nifra-render-only.js", // placeholder; SSR HTML does not need the built client
-      ...(app.backend !== undefined ? { api: inProcessClient(app.backend as never) } : {}),
+      ...frameworkWebAppOptions(app.framework, app.backend),
     }) as unknown as AppLike
     return { app: webApp }
   } catch (err) {
@@ -89,6 +96,12 @@ function redirectConsoleToStderr(): void {
   console.error = (...args: unknown[]) => write("error", args)
 }
 
+function safeResponseId(value: unknown): number | string | null {
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value
+  if (typeof value === "string" && value.length <= 128) return value
+  return null
+}
+
 /**
  * Warm-worker loop (`--worker`): build the web app ONCE, then SSR each `{ id, input: { requests } }` line
  * against that hot app and reply `{ id, output }`. The parent (`mcp.ts`'s warm-render handler) spawns this,
@@ -100,43 +113,51 @@ async function runWorker(cwd: string): Promise<void> {
   // Build once; the same `{ error }` is returned for every request if the build failed, so an agent sees
   // the actionable message and the parent restarts the worker on the next file change.
   const built = await buildWebApp(cwd)
-  const decoder = new TextDecoder()
-  let buffer = ""
   const send = (id: unknown, output: unknown): void => {
-    process.stdout.write(`${JSON.stringify({ id, output })}\n`)
+    const responseId = safeResponseId(id)
+    const encoded = serializeBoundedJson({ id: responseId, output }, CHILD_OUTPUT_MAX_BYTES - 1)
+    process.stdout.write(
+      `${encoded ?? JSON.stringify({ id: responseId, output: { error: "worker output exceeded the size limit" } })}\n`,
+    )
   }
-  for await (const chunk of Bun.stdin.stream()) {
-    buffer += decoder.decode(chunk as Uint8Array, { stream: true })
-    let nl = buffer.indexOf("\n")
-    while (nl !== -1) {
-      const line = buffer.slice(0, nl).trim()
-      buffer = buffer.slice(nl + 1)
-      nl = buffer.indexOf("\n")
-      if (line === "") continue
+  for await (const item of readBoundedLines(Bun.stdin.stream(), CHILD_INPUT_MAX_BYTES)) {
+    if (item.kind === "too-large") {
+      send(null, { error: `worker input exceeded ${CHILD_INPUT_MAX_BYTES} bytes` })
+      continue
+    }
+    const line = item.text.trim()
+    if (line === "") continue
 
-      let message: RenderWorkerMessage
-      try {
-        message = JSON.parse(line) as RenderWorkerMessage
-      } catch {
-        send(null, { error: "invalid worker input: expected JSON line" })
-        continue
-      }
-      const requests = message.input?.requests
-      if (!Array.isArray(requests)) {
-        send(message.id, { error: "expected { requests: [...] }" })
-        continue
-      }
-      if ("error" in built) {
-        send(message.id, built)
-        continue
-      }
-      try {
-        send(message.id, {
-          results: await runApp(built.app, requests as Parameters<typeof runApp>[1]),
-        })
-      } catch (err) {
-        send(message.id, { error: errString(err) })
-      }
+    let message: unknown
+    try {
+      message = JSON.parse(line) as unknown
+    } catch {
+      send(null, { error: "invalid worker input: expected JSON line" })
+      continue
+    }
+    const record =
+      message !== null && typeof message === "object" && !Array.isArray(message)
+        ? (message as RenderWorkerMessage)
+        : undefined
+    const input =
+      record?.input !== null && typeof record?.input === "object" && !Array.isArray(record.input)
+        ? record.input
+        : undefined
+    const requests = input?.requests
+    if (!Array.isArray(requests)) {
+      send(record?.id, { error: "expected { requests: [...] }" })
+      continue
+    }
+    if ("error" in built) {
+      send(record?.id, built)
+      continue
+    }
+    try {
+      send(record?.id, {
+        results: await runApp(built.app, requests as Parameters<typeof runApp>[1]),
+      })
+    } catch (err) {
+      send(record?.id, { error: errString(err) })
     }
   }
 }
@@ -163,13 +184,22 @@ if (import.meta.main) {
     process.exit(0)
   }
   let output: unknown
-  try {
-    const { requests } = JSON.parse(await Bun.stdin.text()) as { requests: unknown }
-    output = await renderPages(cwd, requests)
-  } catch {
-    output = { error: "invalid input: expected JSON { requests: [...] }" }
+  const input = await readBoundedStream(Bun.stdin.stream(), CHILD_INPUT_MAX_BYTES)
+  if (input.truncated) {
+    output = { error: `input exceeded ${CHILD_INPUT_MAX_BYTES} bytes` }
+  } else {
+    try {
+      const { requests } = JSON.parse(input.text) as { requests: unknown }
+      output = await renderPages(cwd, requests)
+    } catch {
+      output = { error: "invalid input: expected JSON { requests: [...] }" }
+    }
   }
-  await Bun.write(Bun.stdout, JSON.stringify(output, null, 2))
+  await Bun.write(
+    Bun.stdout,
+    serializeBoundedJson(output, CHILD_OUTPUT_MAX_BYTES, 2) ??
+      JSON.stringify({ error: `output exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes` }),
+  )
   // Exit explicitly, exactly as the `--worker` branch above already does.
   //
   // Loading the app runs its module side effects, and a real app opens things: a database pool, a

package/src/mcp-root.ts

@@ -5,9 +5,12 @@
  *   1. An explicit `nifra mcp <dir>` argument is taken literally (human configuration wins).
  *   2. A cwd guess walks UP to the nearest nifra marker (a `package.json` depending on `@nifrajs/*`,
  *      or a `nifra.config.ts` monorepo root), so running from a subdirectory still finds the project.
+ *      When nothing above is a project but the spawn directory is a package-manager workspace root
+ *      (`package.json` `workspaces`) with exactly one nifra member, the server adopts that member.
  *   3. The client's MCP `roots` (its workspace folders) are requested after the handshake. When the
  *      guess found no project - or found one DISJOINT from every workspace root - and exactly one
- *      workspace root is a nifra project, the server adopts it.
+ *      workspace root (or one member of a workspace-root folder) is a nifra project, the server
+ *      adopts it.
  *   4. What cannot be resolved fails CLOSED: project-scoped tools refuse with a remediation message
  *      instead of describing whatever directory the server happened to start in.
  *
@@ -15,12 +18,13 @@
  */
 
 import { readFile } from "node:fs/promises"
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 
 /** How the current root was chosen. `arg` = explicit `nifra mcp <dir>`; `cwd` = the spawn directory;
- * `parent` = a marker found walking up from cwd; `client-root` = adopted from the client's MCP roots. */
-export type McpRootSource = "arg" | "cwd" | "parent" | "client-root"
+ * `parent` = a marker found walking up from cwd; `workspace` = the one nifra member of the spawn
+ * directory's package-manager workspaces; `client-root` = adopted from the client's MCP roots. */
+export type McpRootSource = "arg" | "cwd" | "parent" | "workspace" | "client-root"
 
 export interface McpRootState {
   /** Absolute directory every project-scoped tool operates on. */
@@ -31,8 +35,18 @@ export interface McpRootState {
   /** The client's workspace roots (absolute paths), or `null` until (unless) the client answers
    * `roots/list`. `null` disables mismatch detection - no data is not a mismatch. */
   readonly clientRoots: readonly string[] | null
+  /** Nifra members of the spawn directory's workspaces when there were several to choose from - the
+   * remediation list, since adopting one of them would be a guess. */
+  readonly workspaceCandidates?: readonly string[]
 }
 
+const MAX_CLIENT_ROOTS = 64
+const MAX_ROOT_URI_LENGTH = 16_384
+const MAX_ROOT_PATH_LENGTH = 4_096
+/** Workspace members probed per workspace root. A monorepo larger than this is pointed at explicitly
+ * (`nifra mcp <dir>`) rather than scanned on every server start. */
+const MAX_WORKSPACE_MEMBERS = 256
+
 /** A directory is a nifra project when its `package.json` depends on any `@nifrajs/*` package, or it
  * is a `nifra.config.ts` monorepo root. Backend-only projects (no web config, no `routes/`) count -
  * the marker is the dependency, not the app shape. */
@@ -65,8 +79,56 @@ export async function findNifraRoot(start: string): Promise<string | null> {
   }
 }
 
+/** The `workspaces` globs a `package.json` declares (the array form, or Yarn's `{ packages }`), or
+ * `null` when the directory is not a workspace root. Negated patterns are dropped: they only exclude. */
+async function workspacePatterns(dir: string): Promise<readonly string[] | null> {
+  let field: unknown
+  try {
+    field = (
+      JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as Record<string, unknown>
+    ).workspaces
+  } catch {
+    return null
+  }
+  const list = Array.isArray(field)
+    ? field
+    : typeof field === "object" && field !== null
+      ? (field as { packages?: unknown }).packages
+      : undefined
+  if (!Array.isArray(list)) return null
+  return list.filter(
+    (pattern): pattern is string =>
+      typeof pattern === "string" && pattern !== "" && !pattern.startsWith("!"),
+  )
+}
+
+/**
+ * The nifra projects among `dir`'s package-manager workspace members, in declaration order. Empty when
+ * `dir` declares no `workspaces`. A member is a directory a pattern matches that holds a `package.json`;
+ * `node_modules` is never a member.
+ */
+export async function workspaceProjects(dir: string): Promise<string[]> {
+  const patterns = await workspacePatterns(dir)
+  if (patterns === null) return []
+  const members = new Set<string>()
+  let probed = 0
+  for (const pattern of patterns) {
+    const glob = new Bun.Glob(`${pattern.replace(/\/+$/, "")}/package.json`)
+    for await (const match of glob.scan({ cwd: dir, onlyFiles: true })) {
+      if (match.split(/[\\/]/).includes("node_modules")) continue
+      if (++probed > MAX_WORKSPACE_MEMBERS) break
+      members.add(dirname(join(dir, match)))
+    }
+    if (probed > MAX_WORKSPACE_MEMBERS) break
+  }
+  const projects: string[] = []
+  for (const member of members) if (await isNifraProjectDir(member)) projects.push(member)
+  return projects
+}
+
 /** Initial root state. An explicit dir is taken literally (no walk-up - the human named it); a cwd
- * guess walks up so a subdirectory spawn still lands on the project. */
+ * guess walks up so a subdirectory spawn still lands on the project, then tries the spawn directory's
+ * workspace members so a monorepo root finds its one nifra app. */
 export async function resolveRootState(
   requested: string,
   explicit: boolean,
@@ -88,7 +150,17 @@ export async function resolveRootState(
       clientRoots: null,
     }
   }
-  return { root: requested, source: "cwd", isProject: false, clientRoots: null }
+  const members = await workspaceProjects(requested)
+  if (members.length === 1) {
+    return { root: members[0] as string, source: "workspace", isProject: true, clientRoots: null }
+  }
+  return {
+    root: requested,
+    source: "cwd",
+    isProject: false,
+    clientRoots: null,
+    ...(members.length > 1 ? { workspaceCandidates: members } : {}),
+  }
 }
 
 /** `file://` roots from a `roots/list` result, as absolute paths. Non-file and malformed URIs are
@@ -98,9 +170,12 @@ export function pathsFromRootsResult(result: unknown): string[] {
   const roots = (result as { roots?: unknown }).roots
   if (!Array.isArray(roots)) return []
   const paths: string[] = []
+  const seen = new Set<string>()
   for (const entry of roots) {
+    if (paths.length >= MAX_CLIENT_ROOTS) break
     const uri = (entry as { uri?: unknown })?.uri
-    if (typeof uri !== "string" || !uri.startsWith("file://")) continue
+    if (typeof uri !== "string" || uri.length > MAX_ROOT_URI_LENGTH || !uri.startsWith("file://"))
+      continue
     try {
       const parsed = new URL(uri)
       // A remote file host is a UNC path on Windows, not a local workspace root. MCP roots are
@@ -111,7 +186,11 @@ export function pathsFromRootsResult(result: unknown): string[] {
         (parsed.hostname !== "" && parsed.hostname !== "localhost")
       )
         continue
-      paths.push(fileURLToPath(parsed))
+      const path = fileURLToPath(parsed)
+      if (path.length === 0 || path.length > MAX_ROOT_PATH_LENGTH || path.includes("\0")) continue
+      if (seen.has(path)) continue
+      seen.add(path)
+      paths.push(path)
     } catch {
       // Malformed URI - skip.
     }
@@ -140,9 +219,9 @@ export function rootMismatch(state: McpRootState): boolean {
 /**
  * Fold the client's workspace roots into the state, adopting one of them when the current root is
  * wrong and the correction is unambiguous: the root was GUESSED (never an explicit `nifra mcp <dir>`),
- * it is not a project - or is one disjoint from the whole workspace - and exactly ONE workspace root
- * is a nifra project. Ambiguity (zero or several candidates) adopts nothing; the guard's remediation
- * message lists the candidates instead.
+ * it is not a project - or is one disjoint from the whole workspace - and exactly ONE candidate exists
+ * (see {@link nifraCandidates}). Ambiguity (zero or several candidates) adopts nothing; the guard's
+ * remediation message lists the candidates instead.
  */
 export async function applyClientRoots(
   state: McpRootState,
@@ -151,8 +230,7 @@ export async function applyClientRoots(
   const next: McpRootState = { ...state, clientRoots: paths }
   if (state.source === "arg") return next
   if (next.isProject && !rootMismatch(next)) return next
-  const candidates: string[] = []
-  for (const path of paths) if (await isNifraProjectDir(path)) candidates.push(path)
+  const candidates = await nifraCandidates(paths)
   if (candidates.length !== 1) return next
   return {
     root: candidates[0] as string,
@@ -162,11 +240,15 @@ export async function applyClientRoots(
   }
 }
 
-/** The nifra project roots among the client's workspace roots - the remediation list when adoption
- * was ambiguous. */
+/** The nifra projects the client's workspace roots name: each root that is a project itself, and
+ * otherwise the nifra members of a root that is a package-manager workspace. The remediation list
+ * when adoption was ambiguous. */
 export async function nifraCandidates(paths: readonly string[]): Promise<string[]> {
   const candidates: string[] = []
-  for (const path of paths) if (await isNifraProjectDir(path)) candidates.push(path)
+  for (const path of paths) {
+    if (await isNifraProjectDir(path)) candidates.push(path)
+    else for (const member of await workspaceProjects(path)) candidates.push(member)
+  }
   return candidates
 }
 
@@ -187,10 +269,15 @@ export async function rootVerdict(state: McpRootState): Promise<McpRootVerdict>
       ? ` Client workspace roots: ${state.clientRoots.join(", ")}.`
       : ""
   if (!state.isProject) {
-    const candidates = state.clientRoots !== null ? await nifraCandidates(state.clientRoots) : []
+    const candidates = [
+      ...new Set([
+        ...(state.workspaceCandidates ?? []),
+        ...(state.clientRoots !== null ? await nifraCandidates(state.clientRoots) : []),
+      ]),
+    ]
     const hint =
       candidates.length > 1
-        ? ` Several workspace roots are nifra projects (${candidates.join(", ")}) - pass one: \`nifra mcp <dir>\`.`
+        ? ` Several workspace folders are nifra projects (${candidates.join(", ")}) - pass one: \`nifra mcp <dir>\`.`
         : ""
     return {
       blocked:
@@ -239,7 +326,8 @@ export interface ToolingDrift {
 export const driftNote = (drift: ToolingDrift): string =>
   `WARNING: this server runs nifra CLI ${drift.cli}, but the project installs ${drift.package} ${drift.project}. ` +
   "Types, checks, and docs may describe a different version than your code builds with. " +
-  "Fix: run the project's own CLI (`bunx --bun nifra mcp` from the project directory, or point the client at ./node_modules/.bin/nifra)."
+  `Fix: re-pin the project's MCP launch to the nifra it installs with \`${syncMcpCommand(drift.cli)}\` (run in the project directory), then restart the agent. ` +
+  "If this server is not launched from the project's .mcp.json, run the project's own CLI instead (`bunx --bun nifra mcp` from the project directory, or point the client at ./node_modules/.bin/nifra)."
 
 /** Feature-level agreement. Patch drift is not reported: it never changes the surface being described. */
 const featureVersion = (version: string): string => version.split(".").slice(0, 2).join(".")
@@ -274,16 +362,34 @@ export async function detectToolingDrift(
   root: string,
   cliVersion: string,
 ): Promise<ToolingDrift | undefined> {
+  const installed = await installedNifraVersion(root)
+  if (installed === undefined) return undefined
+  return featureVersion(installed.version) === featureVersion(cliVersion)
+    ? undefined
+    : { cli: cliVersion, project: installed.version, package: installed.package }
+}
+
+/**
+ * The nifra the project builds with: its `@nifrajs/cli` when installed, else its `@nifrajs/core`
+ * (`fixed` versioning keeps the two in lockstep, so either names the CLI that matches the project).
+ * The version drift detection compares against and the version `init-agents --sync-mcp` pins to.
+ */
+export async function installedNifraVersion(
+  root: string,
+): Promise<{ readonly package: string; readonly version: string } | undefined> {
   for (const name of ["@nifrajs/cli", "@nifrajs/core"]) {
-    const project = await installedVersion(root, name)
-    if (project === undefined) continue
-    return featureVersion(project) === featureVersion(cliVersion)
-      ? undefined
-      : { cli: cliVersion, project, package: name }
+    const version = await installedVersion(root, name)
+    if (version !== undefined) return { package: name, version }
   }
   return undefined
 }
 
+/** The command that re-pins a project's MCP launch to the nifra it installs. Named with the running
+ * CLI's own exact version: the binary printing this is the one known to have `--sync-mcp`, and it pins
+ * to the project's version, not its own. */
+export const syncMcpCommand = (cliVersion: string): string =>
+  `bunx @nifrajs/cli@${cliVersion} init-agents --sync-mcp`
+
 /** Tool names served from the bundled corpus; they do not depend on the project root. */
 const PROJECT_FREE_TOOLS = new Set(["nifra_docs", "nifra_example", "nifra_types", "nifra_learn"])