@nifrajs/cli 3.1.0 → 3.2.0

package/src/mcp-http.ts

@@ -29,7 +29,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "3.1.0"
+const VERSION = "3.2.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>

package/src/mcp-io.ts

@@ -0,0 +1,118 @@
+/**
+ * Transport-neutral bounded I/O for project MCP tools.
+ *
+ * HTTP docs and verification WebSocket transport keep their own adapters; stdio/run/render share only
+ * these limits and stream readers so an untrusted local endpoint or child process cannot exhaust MCP.
+ */
+
+export const CHILD_TIMEOUT_MS = 30_000
+/** Maximum stdout or stderr retained from a project subprocess. The process is killed at the limit. */
+export const CHILD_OUTPUT_MAX_BYTES = 1_048_576
+
+/** Local dev-tool reads are intentionally bounded: MCP runs in an agent process and must not hang on or
+ * buffer an unrelated loopback service just because a caller supplied its port. */
+export const LOCAL_TOOL_FETCH_TIMEOUT_MS = 2_000
+export const LOCAL_TOOL_MAX_RESPONSE_BYTES = 1_048_576
+
+/** Accept only a concrete TCP port. Port 0 (bind-any-free-port) is not a valid read target. */
+export function validateLocalPort(port: unknown): number | undefined {
+  return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65_535
+    ? port
+    : undefined
+}
+
+/** Read a dev-tool response without allowing an untrusted localhost service to allocate unbounded memory. */
+export async function readBoundedResponse(
+  response: Response,
+  maxBytes = LOCAL_TOOL_MAX_RESPONSE_BYTES,
+): Promise<string> {
+  const declared = response.headers.get("content-length")
+  if (declared !== null) {
+    const length = Number(declared)
+    if (Number.isFinite(length) && length > maxBytes)
+      throw new Error("response exceeded the size limit")
+  }
+  if (response.body === null) return ""
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (value === undefined) continue
+      total += value.byteLength
+      if (total > maxBytes) {
+        await reader.cancel()
+        throw new Error("response exceeded the size limit")
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(bytes)
+}
+
+export const notNifraResponse = (service: string): string =>
+  JSON.stringify(
+    {
+      code: "NIFRA_NOT_DEV_SERVER",
+      message: `The service on this port is not a Nifra ${service} endpoint.`,
+    },
+    null,
+    2,
+  )
+
+export const timeoutMessage = (label: string, ms: number): string =>
+  `${label} timed out after ${ms / 1000}s and was terminated.\n` +
+  `The app was loaded but the process did not finish. Most often this is a module-level side effect ` +
+  `that keeps the event loop alive (a database pool, a Redis client, an interval) opened during import ` +
+  `rather than lazily. Check for top-level connections in the app entry or anything it imports.`
+
+export interface BoundedOutput {
+  readonly text: string
+  readonly truncated: boolean
+}
+
+/** Read child output incrementally and cancel as soon as the byte budget is crossed. */
+export async function readBoundedStream(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes = CHILD_OUTPUT_MAX_BYTES,
+  onLimit?: () => void,
+): Promise<BoundedOutput> {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  const chunks: string[] = []
+  let totalBytes = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) {
+        chunks.push(decoder.decode())
+        return { text: chunks.join(""), truncated: false }
+      }
+      if (value === undefined) continue
+      const remaining = maxBytes - totalBytes
+      if (remaining <= 0 || value.byteLength > remaining) {
+        if (remaining > 0) {
+          chunks.push(decoder.decode(value.subarray(0, remaining), { stream: true }))
+          chunks.push(decoder.decode())
+        }
+        await reader.cancel()
+        onLimit?.()
+        return { text: chunks.join(""), truncated: true }
+      }
+      totalBytes += value.byteLength
+      chunks.push(decoder.decode(value, { stream: true }))
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}

package/src/mcp-reflect.ts

@@ -0,0 +1,140 @@
+/**
+ * Backend reflection adapters for the project MCP surface.
+ *
+ * These functions only translate reflected Nifra declarations into MCP descriptors. They do not know
+ * about stdio, HTTP, root trust, or project loading, so the reflection seam is independently testable.
+ */
+
+import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+import type {
+  McpPrompt,
+  McpPromptMessage,
+  McpResource,
+  McpTool,
+  McpToolResult,
+} from "./mcp-protocol.ts"
+
+type ToolBackend = {
+  readonly routes?: () => readonly unknown[]
+  readonly fetch: (req: Request) => Promise<Response>
+}
+
+/** Extract tools registered via .tool() routes on the Nifra backend. Exported for the test that proves a
+ * `server().tool()` route surfaces in `tools/list` and executes through `tools/call`. */
+export function extractBackendTools(backend: unknown): McpTool[] {
+  const b = backend as ToolBackend | null
+  if (!b || typeof b.routes !== "function") return []
+  const routes = reflectRoutes(b)
+
+  return routes
+    .filter(
+      (
+        r,
+      ): r is ReflectedRoute & {
+        schema: NonNullable<ReflectedRoute["schema"]>
+        tool: NonNullable<ReflectedRoute["tool"]>
+      } => r.schema !== undefined && r.tool !== undefined,
+    )
+    .map((r) => {
+      const toolInfo = r.tool
+      const s = r.schema
+      return {
+        name: toolInfo.name,
+        description: toolInfo.description,
+        inputSchema: (s.body?.jsonSchema ?? {
+          type: "object",
+          properties: {},
+        }) as McpTool["inputSchema"],
+        ...(toolInfo.annotations !== undefined ? { annotations: toolInfo.annotations } : {}),
+        handler: async (args): Promise<string | McpToolResult> => {
+          const res = await b.fetch(
+            new Request(`http://localhost/_nifra/tool/${toolInfo.name}`, {
+              method: "POST",
+              headers: { "content-type": "application/json" },
+              body: JSON.stringify(args),
+            }),
+          )
+          if (!res.ok) {
+            const text = await res.text()
+            throw new Error(`Tool execution failed (${res.status}): ${text}`)
+          }
+          const body: unknown = await res.json()
+          if (typeof body === "string") return body
+          if (body && typeof body === "object") {
+            if ("content" in body || "structuredContent" in body) {
+              return body as McpToolResult
+            }
+            return {
+              content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+              structuredContent: body as Record<string, unknown>,
+            }
+          }
+          return String(body)
+        },
+      }
+    })
+}
+
+/** A resource declared on the backend via `server().resource()`, seen through `mcpResources()`. */
+type ResourceDescriptor = {
+  readonly uri: string
+  readonly name: string
+  readonly description?: string
+  readonly mimeType?: string
+  readonly read: () => unknown | Promise<unknown>
+}
+type ResourceBackend = { readonly mcpResources?: () => readonly ResourceDescriptor[] }
+
+/** Extract MCP resources registered via `.resource()` on the Nifra backend. Exported for the surfacing test. */
+export function extractBackendResources(backend: unknown): McpResource[] {
+  const b = backend as ResourceBackend | null
+  if (!b || typeof b.mcpResources !== "function") return []
+  let list: readonly ResourceDescriptor[]
+  try {
+    list = b.mcpResources()
+  } catch {
+    return []
+  }
+  return list.map((r) => ({
+    uri: r.uri,
+    name: r.name,
+    ...(r.description !== undefined ? { description: r.description } : {}),
+    ...(r.mimeType !== undefined ? { mimeType: r.mimeType } : {}),
+    read: async () => {
+      const out = await r.read()
+      if (typeof out === "string") return { text: out }
+      const o = out as { text: string; mimeType?: string }
+      return o.mimeType !== undefined ? { text: o.text, mimeType: o.mimeType } : { text: o.text }
+    },
+  }))
+}
+
+/** A prompt declared on the backend via `server().prompt()`, seen through `mcpPrompts()`. */
+type PromptDescriptor = {
+  readonly name: string
+  readonly description: string
+  readonly arguments?: readonly { name: string; description?: string; required?: boolean }[]
+  readonly handler: (args: Record<string, string>) => unknown | Promise<unknown>
+}
+type PromptBackend = { readonly mcpPrompts?: () => readonly PromptDescriptor[] }
+
+/** Extract MCP prompts registered via `.prompt()` on the Nifra backend. Exported for the surfacing test. */
+export function extractBackendPrompts(backend: unknown): McpPrompt[] {
+  const b = backend as PromptBackend | null
+  if (!b || typeof b.mcpPrompts !== "function") return []
+  let list: readonly PromptDescriptor[]
+  try {
+    list = b.mcpPrompts()
+  } catch {
+    return []
+  }
+  return list.map((p) => ({
+    name: p.name,
+    description: p.description,
+    ...(p.arguments !== undefined ? { arguments: p.arguments } : {}),
+    handler: async (args: Record<string, unknown>) =>
+      (await p.handler(args as Record<string, string>)) as readonly McpPromptMessage[],
+  }))
+}
+
+/** Prefix every tool name and resource URI for a named app in a monorepo. */

package/src/mcp-root.ts

@@ -15,7 +15,7 @@
  */
 
 import { readFile } from "node:fs/promises"
-import { dirname, sep } from "node:path"
+import { dirname, isAbsolute, 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;
@@ -102,7 +102,16 @@ export function pathsFromRootsResult(result: unknown): string[] {
     const uri = (entry as { uri?: unknown })?.uri
     if (typeof uri !== "string" || !uri.startsWith("file://")) continue
     try {
-      paths.push(fileURLToPath(uri))
+      const parsed = new URL(uri)
+      // A remote file host is a UNC path on Windows, not a local workspace root. MCP roots are
+      // intentionally local-only here: accepting it would let a client silently point the server
+      // at a different machine/share. `localhost` is the only equivalent spelling we accept.
+      if (
+        parsed.protocol !== "file:" ||
+        (parsed.hostname !== "" && parsed.hostname !== "localhost")
+      )
+        continue
+      paths.push(fileURLToPath(parsed))
     } catch {
       // Malformed URI - skip.
     }
@@ -110,8 +119,13 @@ export function pathsFromRootsResult(result: unknown): string[] {
   return paths
 }
 
-const contains = (parent: string, child: string): boolean =>
-  parent === child || child.startsWith(parent + sep)
+const contains = (parent: string, child: string): boolean => {
+  const distance = relative(resolve(parent), resolve(child))
+  return (
+    distance === "" ||
+    (distance !== ".." && !distance.startsWith(`..${sep}`) && !isAbsolute(distance))
+  )
+}
 
 /** True when the server root and the client's workspace are DISJOINT - neither contains the other.
  * A server rooted at a monorepo whose sub-app is the open workspace (or vice versa) is not a
@@ -269,3 +283,47 @@ export async function detectToolingDrift(
   }
   return undefined
 }
+
+/** 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"])
+
+/**
+ * Wrap project-scoped tools with root trust. A bad root refuses in-band; a good root stamps every
+ * result so the agent can see which project answered. Docs tools pass through untouched.
+ */
+export function guardTools(
+  tools: import("./mcp-protocol.ts").McpTool[],
+  verdict: McpRootVerdict,
+): import("./mcp-protocol.ts").McpTool[] {
+  return tools.map((tool) => {
+    if (PROJECT_FREE_TOOLS.has(tool.name)) return tool
+    return {
+      ...tool,
+      handler: async (
+        args: Record<string, unknown>,
+        context: import("./mcp-protocol.ts").McpToolContext,
+      ): Promise<import("./mcp-protocol.ts").McpToolResult> => {
+        if (verdict.blocked !== undefined) {
+          return { content: [{ type: "text", text: verdict.blocked }], isError: true }
+        }
+        const result = await tool.handler(args, context)
+        const note: import("./mcp-protocol.ts").McpContentBlock = {
+          type: "text",
+          text: verdict.note,
+        }
+        if (typeof result === "string") {
+          return { content: [{ type: "text", text: result }, note] }
+        }
+        return { ...result, content: [...(result.content ?? []), note] }
+      },
+    }
+  })
+}
+
+/** Whether the client's initialize params declare the roots capability. */
+export function clientSupportsRoots(params: Record<string, unknown> | undefined): boolean {
+  const capabilities = params?.capabilities
+  if (typeof capabilities !== "object" || capabilities === null) return false
+  const roots = (capabilities as { roots?: unknown }).roots
+  return typeof roots === "object" && roots !== null
+}