@nifrajs/cli 2.3.0 → 2.5.0

package/dist/mcp-app-tool.js

@@ -0,0 +1,80 @@
+/**
+ * The `nifra_examples_app` MCP tool: nifra's verified code examples as an MCP Apps widget. It returns the
+ * examples as `structuredContent`, rendered by the {@link examplesWidget} `ui://` widget in MCP Apps hosts
+ * (ChatGPT Apps, MCPJam, Goose); text-only hosts still get the example names as plain text. Part of the
+ * public docs-MCP tool set (served by `handleMcpHttp`), so every self-host gets it from one definition.
+ * `loadExamples` is injected, so the same tool reads the corpus from disk (CLI) or a cached fetch (edge).
+ */
+import { defineMcpTool, defineMcpWidget } from "@nifrajs/mcp";
+/** The widget: renders `structuredContent.examples` as a filterable list of example cards. */
+export const examplesWidget = defineMcpWidget({
+    uri: "ui://nifra/examples",
+    name: "nifra examples",
+    description: "Interactive browser of verified, copy-pasteable nifra code examples.",
+    head: `<style>
+    :root { color-scheme: light dark; font: 14px/1.5 system-ui, sans-serif; }
+    body { margin: 0; padding: 16px; }
+    h1 { font-size: 16px; margin: 0 0 4px; }
+    #q { width: 100%; box-sizing: border-box; padding: 6px 10px; margin: 8px 0 14px; border-radius: 6px; border: 1px solid color-mix(in srgb, currentColor 25%, transparent); background: transparent; color: inherit; font: inherit; }
+    .card { border: 1px solid color-mix(in srgb, currentColor 15%, transparent); border-radius: 10px; padding: 10px 12px; margin-bottom: 10px; }
+    .topic { font-size: 12px; opacity: .6; }
+    .name { font-weight: 600; margin: 2px 0 6px; }
+    pre { margin: 0; padding: 8px 10px; border-radius: 6px; background: color-mix(in srgb, currentColor 8%, transparent); overflow-x: auto; font: 12px/1.5 ui-monospace, monospace; }
+  </style>`,
+    html: `
+    <h1>nifra examples</h1>
+    <input id="q" placeholder="Filter examples…" />
+    <div id="list"></div>
+    <script>
+      var ALL = [];
+      function esc(s){ return String(s).replace(/[&<>]/g, function(c){ return c==="&"?"&amp;":c==="<"?"&lt;":"&gt;"; }); }
+      function paint(items){
+        document.getElementById("list").innerHTML = items.map(function(e){
+          var code = e.code.length > 600 ? e.code.slice(0, 600) + "\\n…" : e.code;
+          return "<div class='card'><div class='topic'>" + esc(e.topic) + "</div><div class='name'>" + esc(e.name) +
+            "</div><pre>" + esc(code) + "</pre></div>";
+        }).join("") || "<p style='opacity:.6'>No matching examples.</p>";
+      }
+      function render(data){ ALL = (data && data.examples) || []; paint(ALL); }
+      mcpApp.onData(render);
+      document.getElementById("q").addEventListener("input", function(ev){
+        var q = ev.target.value.toLowerCase();
+        paint(ALL.filter(function(e){ return (e.topic + e.name + e.slug).toLowerCase().indexOf(q) !== -1; }));
+      });
+    </script>
+  `,
+});
+/** The widget-backed tool. `loadExamples` is injected (disk on the CLI, cached fetch on the edge). */
+export function examplesAppTool(loadExamples) {
+    return defineMcpTool({
+        name: "nifra_examples_app",
+        description: "Browse nifra's verified code examples as an interactive, filterable list (MCP Apps widget). Pass query to pre-filter; the widget also filters client-side.",
+        inputSchema: {
+            type: "object",
+            properties: { query: { type: "string", description: "Pre-filter examples by keyword." } },
+            additionalProperties: false,
+        },
+        widget: examplesWidget,
+        handler: async (args) => {
+            const all = (await loadExamples()) ?? [];
+            const q = (args.query ?? "").toLowerCase();
+            const matched = (q
+                ? all.filter((e) => `${e.topic} ${e.name} ${e.slug} ${e.code}`.toLowerCase().includes(q))
+                : all).slice(0, 30);
+            return {
+                text: matched.length === 0
+                    ? "No matching examples."
+                    : `${matched.length} example(s): ${matched.map((e) => e.name).join(", ")}.`,
+                structuredContent: {
+                    examples: matched.map((e) => ({
+                        name: e.name,
+                        topic: e.topic,
+                        slug: e.slug,
+                        code: e.code,
+                    })),
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=mcp-app-tool.js.map

package/dist/mcp-app-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-app-tool.js","sourceRoot":"","sources":["../src/mcp-app-tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAgB,MAAM,cAAc,CAAA;AAG3E,8FAA8F;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;IAC5C,GAAG,EAAE,qBAAqB;IAC1B,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE,sEAAsE;IACnF,IAAI,EAAE;;;;;;;;;WASG;IACT,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;GAqBL;CACF,CAAC,CAAA;AAEF,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,YAAkD;IAChF,OAAO,aAAa,CAAC;QACnB,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,4JAA4J;QAC9J,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iCAAiC,EAAE,EAAE;YACzF,oBAAoB,EAAE,KAAK;SAC5B;QACD,MAAM,EAAE,cAAc;QACtB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,GAAG,GAAG,CAAC,MAAM,YAAY,EAAE,CAAC,IAAI,EAAE,CAAA;YACxC,MAAM,CAAC,GAAG,CAAE,IAAI,CAAC,KAAgB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;YACtD,MAAM,OAAO,GAAG,CACd,CAAC;gBACC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBACzF,CAAC,CAAC,GAAG,CACR,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;YACd,OAAO;gBACL,IAAI,EACF,OAAO,CAAC,MAAM,KAAK,CAAC;oBAClB,CAAC,CAAC,uBAAuB;oBACzB,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,gBAAgB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC/E,iBAAiB,EAAE;oBACjB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAC5B,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,KAAK,EAAE,CAAC,CAAC,KAAK;wBACd,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;qBACb,CAAC,CAAC;iBACJ;aACF,CAAA;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/mcp-docs-tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * The two project-INDEPENDENT MCP tools - `nifra_docs` + `nifra_example` - as a single factory shared
+ * The project-INDEPENDENT MCP tools - `nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` - as a single factory shared
  * by every transport: the project stdio server ({@link projectTools}), the CLI HTTP server
  * (`nifra docs-mcp`), and the site's Cloudflare-Pages worker (`/mcp`). The corpus source is injected as
  * loaders, so the SAME tool definitions work whether the corpus comes from disk (`Bun.file`, on the

package/dist/mcp-docs-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-docs-tools.d.ts","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,OAAO,EAAwB,MAAM,eAAe,CAAA;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAKrE,yFAAyF;AACzF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EAC3C,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,EAClD,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,GAChD,OAAO,EAAE,CA8FX"}
+{"version":3,"file":"mcp-docs-tools.d.ts","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,OAAO,EAAwB,MAAM,eAAe,CAAA;AAElE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAKrE,yFAAyF;AACzF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EAC3C,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,EAClD,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,GAChD,OAAO,EAAE,CA8GX"}

package/dist/mcp-docs-tools.js

@@ -1,5 +1,5 @@
 /**
- * The two project-INDEPENDENT MCP tools - `nifra_docs` + `nifra_example` - as a single factory shared
+ * The project-INDEPENDENT MCP tools - `nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` - as a single factory shared
  * by every transport: the project stdio server ({@link projectTools}), the CLI HTTP server
  * (`nifra docs-mcp`), and the site's Cloudflare-Pages worker (`/mcp`). The corpus source is injected as
  * loaders, so the SAME tool definitions work whether the corpus comes from disk (`Bun.file`, on the
@@ -8,6 +8,7 @@
  */
 import { renderDocsResult } from "./docs-search.js";
 import { renderExamplesResult } from "./examples.js";
+import { renderLearnResult } from "./learn.js";
 import { renderTypesResult } from "./types-search.js";
 const clamp = (n, lo, hi, dflt) => Math.min(Math.max(typeof n === "number" ? n : dflt, lo), hi);
 /** Build `nifra_docs` + `nifra_example` + `nifra_types` over injected corpus loaders. */
@@ -93,6 +94,21 @@ export function docsTools(loadDocs, loadExamples, loadTypes) {
                 return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5), full === true);
             },
         },
+        {
+            name: "nifra_learn",
+            description: "Walk the guided path to build a nifra app end to end - an ORDERED sequence (create → page route → loader → typed API → typed client → auth → background jobs → deploy), not the random-access search of nifra_docs/nifra_example. Call with no args for the step index; pass `step: N` for that step's goal, how to do it (which tool emits the correct artifact), and how to verify it. Use it when scaffolding a new app or learning nifra's flow - each step composes the other nifra_* tools.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    step: {
+                        type: "number",
+                        description: "1-based step number to expand (omit for the index).",
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => renderLearnResult(args.step),
+        },
     ];
 }
 //# sourceMappingURL=mcp-docs-tools.js.map

package/dist/mcp-docs-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-docs-tools.js","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-docs-tools.js","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"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"}

package/dist/mcp-http.d.ts

@@ -1,8 +1,9 @@
 /**
  * The PUBLIC nifra docs MCP - Streamable-HTTP transport exposing the project-INDEPENDENT tools
- * (`nifra_docs` + `nifra_example`) so any remote AI agent can learn nifra without a local checkout.
- * Both tools read the bundled corpus (llms-full.txt / examples.json shipped in this package) and ignore
- * `cwd`, so they reuse the exact definitions from {@link projectTools} - one source, no drift.
+ * (`nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` + the `nifra_examples_app` MCP Apps widget)
+ * so any remote AI agent can learn nifra without a local checkout. They read the bundled corpus
+ * (llms-full.txt / examples.json / types.json shipped in this package) and ignore `cwd`, so they reuse the
+ * exact definitions from {@link projectTools} - one source, no drift.
  *
  * The transport itself (body cap, CORS, JSON-RPC dispatch) lives in `@nifrajs/mcp/http`; this module is
  * the docs-specific layer over it: it supplies the bundled corpus tools and the `nifra-docs` server info.
@@ -11,12 +12,14 @@
  * filesystem). `export default { port, fetch }` also lets `bun run mcp-http.ts` serve it directly.
  */
 import { type McpHttpOptions } from "@nifrajs/mcp/http";
-import type { McpTool } from "@nifrajs/mcp/protocol";
+import { type McpTool } from "@nifrajs/mcp/protocol";
 export type { McpHttpOptions } from "@nifrajs/mcp/http";
 export type { Example } from "./examples.js";
+export { examplesAppTool, examplesWidget } from "./mcp-app-tool.js";
 export { docsTools } from "./mcp-docs-tools.js";
 export type { TypeEntry } from "./types-search.js";
-/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
+/** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text
+ * docs tools plus the `nifra_examples_app` MCP Apps widget tool. */
 export declare function publicDocsTools(): McpTool[];
 /**
  * Handle one MCP request against the given `tools` with the docs server identity. A thin docs-flavored
@@ -24,7 +27,8 @@ export declare function publicDocsTools(): McpTool[];
  * `(request, tools, options?)` shape (the site's edge worker calls it with two args).
  */
 export declare function respondMcpHttp(request: Request, tools: McpTool[], options?: McpHttpOptions): Promise<Response>;
-/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */
+/** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`
+ * resource so MCP Apps hosts can render `nifra_examples_app`. (`nifra docs-mcp` / `bun run` this file.) */
 export declare function handleMcpHttp(request: Request): Promise<Response>;
 /**
  * Worker/edge + local entry. `export default { fetch }` is the universal server shape: Cloudflare /

package/dist/mcp-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAwC,MAAM,mBAAmB,CAAA;AAC7F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAMpD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAQlD,mGAAmG;AACnG,wBAAgB,eAAe,IAAI,OAAO,EAAE,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED,2GAA2G;AAC3G,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEjE;AAED;;;;;GAKG;;;;;AACH,wBAGC"}
+{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAwC,MAAM,mBAAmB,CAAA;AAC7F,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,uBAAuB,CAAA;AAO7D,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAG5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAWlD;oEACoE;AACpE,wBAAgB,eAAe,IAAI,OAAO,EAAE,CAK3C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED;2GAC2G;AAC3G,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CASjE;AAED;;;;;GAKG;;;;;AACH,wBAGC"}

package/dist/mcp-http.js

@@ -1,8 +1,9 @@
 /**
  * The PUBLIC nifra docs MCP - Streamable-HTTP transport exposing the project-INDEPENDENT tools
- * (`nifra_docs` + `nifra_example`) so any remote AI agent can learn nifra without a local checkout.
- * Both tools read the bundled corpus (llms-full.txt / examples.json shipped in this package) and ignore
- * `cwd`, so they reuse the exact definitions from {@link projectTools} - one source, no drift.
+ * (`nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` + the `nifra_examples_app` MCP Apps widget)
+ * so any remote AI agent can learn nifra without a local checkout. They read the bundled corpus
+ * (llms-full.txt / examples.json / types.json shipped in this package) and ignore `cwd`, so they reuse the
+ * exact definitions from {@link projectTools} - one source, no drift.
  *
  * The transport itself (body cap, CORS, JSON-RPC dispatch) lives in `@nifrajs/mcp/http`; this module is
  * the docs-specific layer over it: it supplies the bundled corpus tools and the `nifra-docs` server info.
@@ -11,20 +12,30 @@
  * filesystem). `export default { port, fetch }` also lets `bun run mcp-http.ts` serve it directly.
  */
 import { respondMcpHttp as respondMcpHttpCore } from "@nifrajs/mcp/http";
+import { UI_MIME } from "@nifrajs/mcp/protocol";
 import { loadDocsCorpus } from "./docs-search.js";
 import { loadExamplesCorpus } from "./examples.js";
+import { examplesAppTool, examplesWidget } from "./mcp-app-tool.js";
 import { docsTools } from "./mcp-docs-tools.js";
 import { loadTypesCorpus } from "./types-search.js";
-// Re-exported so a self-host (e.g. a Cloudflare-Pages `/mcp` worker route) gets the corpus-injectable
-// tool factory + the transport core from one entry: `import { respondMcpHttp, docsTools } from "@nifrajs/cli/mcp"`.
+// Re-exported so a self-host gets the corpus-injectable tool factories + the transport core from one
+// entry: `import { respondMcpHttp, docsTools, examplesAppTool } from "@nifrajs/cli/mcp"`.
+export { examplesAppTool, examplesWidget } from "./mcp-app-tool.js";
 export { docsTools } from "./mcp-docs-tools.js";
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.3.0";
+const VERSION = "2.5.0";
 const SERVER_INFO = { name: "nifra-docs", version: VERSION };
-const DOCS_HEALTH = "nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example.";
-/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
+// Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
+const docsHealth = (tools) => `nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: ${tools
+    .map((tool) => tool.name)
+    .join(", ")}.`;
+/** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text
+ * docs tools plus the `nifra_examples_app` MCP Apps widget tool. */
 export function publicDocsTools() {
-    return docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus);
+    return [
+        ...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus),
+        examplesAppTool(loadExamplesCorpus),
+    ];
 }
 /**
  * Handle one MCP request against the given `tools` with the docs server identity. A thin docs-flavored
@@ -32,11 +43,18 @@ export function publicDocsTools() {
  * `(request, tools, options?)` shape (the site's edge worker calls it with two args).
  */
 export function respondMcpHttp(request, tools, options = {}) {
-    return respondMcpHttpCore(request, tools, SERVER_INFO, { health: DOCS_HEALTH, ...options });
+    return respondMcpHttpCore(request, tools, SERVER_INFO, { health: docsHealth(tools), ...options });
 }
-/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */
+/** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`
+ * resource so MCP Apps hosts can render `nifra_examples_app`. (`nifra docs-mcp` / `bun run` this file.) */
 export function handleMcpHttp(request) {
-    return respondMcpHttp(request, publicDocsTools());
+    return respondMcpHttp(request, publicDocsTools(), {
+        features: {
+            resources: [examplesWidget.resource],
+            ui: { mimeTypes: [UI_MIME] },
+            instructions: "nifra's own documentation, runnable examples, and API types - for building with the nifra framework. Call nifra_docs / nifra_example / nifra_types / nifra_learn to learn it without a local checkout.",
+        },
+    });
 }
 /**
  * Worker/edge + local entry. `export default { fetch }` is the universal server shape: Cloudflare /

package/dist/mcp-http.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-http.js","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAuB,cAAc,IAAI,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE7F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAInD,sGAAsG;AACtG,oHAAoH;AACpH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAG/C,+FAA+F;AAC/F,MAAM,OAAO,GAAG,OAAO,CAAA;AACvB,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,CAAA;AAC5D,MAAM,WAAW,GACf,0HAA0H,CAAA;AAE5H,mGAAmG;AACnG,MAAM,UAAU,eAAe;IAC7B,OAAO,SAAS,CAAC,cAAc,EAAE,kBAAkB,EAAE,eAAe,CAAC,CAAA;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgB,EAChB,KAAgB,EAChB,UAA0B,EAAE;IAE5B,OAAO,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;AAC7F,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC,CAAA;AACnD,CAAC;AAED;;;;;GAKG;AACH,eAAe;IACb,IAAI,EAAE,OAAO,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;IACtE,KAAK,EAAE,aAAa;CACrB,CAAA"}
+{"version":3,"file":"mcp-http.js","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAuB,cAAc,IAAI,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC7F,OAAO,EAAgB,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAInD,qGAAqG;AACrG,0FAA0F;AAC1F,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAG/C,+FAA+F;AAC/F,MAAM,OAAO,GAAG,OAAO,CAAA;AACvB,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,CAAA;AAC5D,yGAAyG;AACzG,MAAM,UAAU,GAAG,CAAC,KAAgB,EAAU,EAAE,CAC9C,iGAAiG,KAAK;KACnG,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;KACxB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAA;AAElB;oEACoE;AACpE,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,GAAG,SAAS,CAAC,cAAc,EAAE,kBAAkB,EAAE,eAAe,CAAC;QACjE,eAAe,CAAC,kBAAkB,CAAC;KACpC,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgB,EAChB,KAAgB,EAChB,UAA0B,EAAE;IAE5B,OAAO,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;AACnG,CAAC;AAED;2GAC2G;AAC3G,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE;QAChD,QAAQ,EAAE;YACR,SAAS,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;YACpC,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,OAAO,CAAC,EAAE;YAC5B,YAAY,EACV,wMAAwM;SAC3M;KACF,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,eAAe;IACb,IAAI,EAAE,OAAO,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;IACtE,KAAK,EAAE,aAAa;CACrB,CAAA"}

package/dist/mcp.d.ts

@@ -12,12 +12,18 @@
  *   - `nifra_docs`    - keyword-search the framework docs; returns only the matching sections.
  *   - `nifra_example` - a verified, copy-pasteable snippet for a task (typechecked against the live API,
  *     so it can't hallucinate a drifted nifra API).
+ *   - `nifra_learn`   - the guided, ordered path to build a nifra app end to end (create → deploy), each
+ *     step naming the tool that emits the correct artifact and how to verify it.
  *   - `nifra_scaffold`- map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   - the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
  *   - `nifra_assure`  - route classification + enforcement-evidence gate.
  *   - `nifra_levels`  - the cumulative verification ladder (L0 contract → L4 invariants): what the
  *     project actually proves, and why each level it misses does not hold.
  *   - `nifra_doctor`  - package.json dependency drift detector, with safe local-version auto-fix.
+ *   - `nifra_explain` - resolve an error (pasted, or the dev server's last) into a structured
+ *     diagnostic: stable code, a codeframe in the user's source, and the recognised cause + fix.
+ *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
+ *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
  * project root. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
@@ -27,6 +33,14 @@
  */
 import type { LoadAppOptions, LoadedApp } from "./load.js";
 import { type McpPrompt, type McpResource, type McpServerFeatures, type McpTool } from "./mcp-protocol.js";
+/** 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 declare const LOCAL_TOOL_FETCH_TIMEOUT_MS = 2000;
+export declare const LOCAL_TOOL_MAX_RESPONSE_BYTES = 1048576;
+/** Accept only a concrete TCP port. Port 0 (bind-any-free-port) is not a valid read target. */
+export declare function validateLocalPort(port: unknown): number | undefined;
+/** Read a dev-tool response without allowing an untrusted localhost service to allocate unbounded memory. */
+export declare function readBoundedResponse(response: Response, maxBytes?: number): Promise<string>;
 /** A persistent `mcp-run`/`mcp-render` `--worker` subprocess: the backend/web app is loaded ONCE and
  * reused across newline-delimited `{ id, input }` requests, replying `{ id, output }`. The same machinery
  * powers both `nifra_run warm` and `nifra_render warm` - `child` selects which engine, `label` shapes the

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAUH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAG1D,OAAO,EAML,KAAK,SAAS,EAEd,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAIb,MAAM,mBAAmB,CAAA;AA0G1B;;;;;mGAKmG;AACnG,qBAAa,UAAU;IAkBnB,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAlBxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAOrB;IACH,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,MAAM,CAAQ;gBAGpB,KAAK,EAAE,SAAS,GAAG,YAAY,EAC/B,GAAG,EAAE,MAAM,EACF,WAAW,EAAE,MAAM,EACX,KAAK,EAAE,MAAM;IAsBhC,IAAI,IAAI,IAAI;IAIN,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;YAwCtD,UAAU;YAiBV,UAAU;IAUxB,OAAO,CAAC,UAAU;CAkBnB;AAsFD,KAAK,eAAe,GAAG,CACrB,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,KACrB,OAAO,CAAC,SAAS,CAAC,CAAA;AAEvB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACxD;AAmCD,qGAAqG;AACrG,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,sBAA2B,GACnC,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CA+B7C;AA0CD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,aAAa,GAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAA8B,GACtF,WAAW,EAAE,CAmCf;AAED,wBAAgB,cAAc,IAAI,SAAS,EAAE,CAkE5C;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,aAAa,GAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAA8B,GACtF,iBAAiB,CAEnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAItF;AAWD,gDAAgD;AAChD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,aAAa,GAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAA8B,GACtF,OAAO,EAAE,CAqdX;AAOD;yFACyF;AACzF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAoD/D;AAYD,gHAAgH;AAChH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,EAAE,CAqBvE;AAWD,4GAA4G;AAC5G,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,EAAE,CAgBnE;AA2ED,uGAAuG;AACvG,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8E9E"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/mcp.js

@@ -12,12 +12,18 @@
  *   - `nifra_docs`    - keyword-search the framework docs; returns only the matching sections.
  *   - `nifra_example` - a verified, copy-pasteable snippet for a task (typechecked against the live API,
  *     so it can't hallucinate a drifted nifra API).
+ *   - `nifra_learn`   - the guided, ordered path to build a nifra app end to end (create → deploy), each
+ *     step naming the tool that emits the correct artifact and how to verify it.
  *   - `nifra_scaffold`- map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   - the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
  *   - `nifra_assure`  - route classification + enforcement-evidence gate.
  *   - `nifra_levels`  - the cumulative verification ladder (L0 contract → L4 invariants): what the
  *     project actually proves, and why each level it misses does not hold.
  *   - `nifra_doctor`  - package.json dependency drift detector, with safe local-version auto-fix.
+ *   - `nifra_explain` - resolve an error (pasted, or the dev server's last) into a structured
+ *     diagnostic: stable code, a codeframe in the user's source, and the recognised cause + fix.
+ *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
+ *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
  * project root. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
@@ -56,6 +62,59 @@ function childPath(name) {
  * within one attention span rather than after minutes of polling.
  */
 const CHILD_TIMEOUT_MS = 30_000;
+/** 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) {
+    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, maxBytes = LOCAL_TOOL_MAX_RESPONSE_BYTES) {
+    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 = [];
+    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);
+}
+const notNifraResponse = (service) => JSON.stringify({
+    code: "NIFRA_NOT_DEV_SERVER",
+    message: `The service on this port is not a Nifra ${service} endpoint.`,
+}, null, 2);
 const timeoutMessage = (label, ms) => `${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 ` +
@@ -527,6 +586,135 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 return describeProject(await loadAppCached(), filter);
             },
         },
+        {
+            name: "nifra_explain",
+            description: "Turn a nifra error into a STRUCTURED diagnostic instead of eyeballing a stack trace: a stable `code`, the top frame in YOUR source, a codeframe around the offending line, and - when nifra recognises the failure - the plain-language `cause` + `fix` + docs anchor. Pass `error` (and `stack` if you have it, e.g. from nifra_run/nifra_test output or a failing build) to explain a specific failure; or pass `port` to fetch the running dev server's most recent SSR failure from `/__nifra/last-error`. Returns the same JSON the dev overlay renders.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    error: {
+                        type: "string",
+                        description: "The error message to explain (copy it from nifra_run/nifra_test output or a failing build).",
+                    },
+                    stack: {
+                        type: "string",
+                        description: "The error's stack trace, if you have it - enables the source codeframe and the top user frame.",
+                    },
+                    name: {
+                        type: "string",
+                        description: "The error's class name (e.g. TypeError, SchemaError), if known - sharpens classification.",
+                    },
+                    port: {
+                        type: "number",
+                        description: "Instead of a pasted error, fetch the running dev server's most recent SSR failure from this port.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const { error, stack, name, port } = args;
+                if (error !== undefined || stack !== undefined) {
+                    const { buildDiagnostic } = await import("@nifrajs/web/diagnostic");
+                    const e = new Error(error ?? "");
+                    if (name !== undefined)
+                        e.name = name;
+                    if (stack !== undefined)
+                        e.stack = stack;
+                    return JSON.stringify(buildDiagnostic(e, { root: cwd }), null, 2);
+                }
+                if (port !== undefined) {
+                    const validPort = validateLocalPort(port);
+                    if (validPort === undefined) {
+                        return JSON.stringify({ code: "NIFRA_INVALID_PORT", message: "port must be an integer from 1 to 65535." }, null, 2);
+                    }
+                    const { LAST_ERROR_PATH } = await import("@nifrajs/web/diagnostic");
+                    try {
+                        const res = await fetch(`http://127.0.0.1:${validPort}${LAST_ERROR_PATH}`, {
+                            signal: AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS),
+                        });
+                        if (res.headers.get("x-nifra-diagnostic") !== "true")
+                            return notNifraResponse("diagnostic");
+                        if (!res.ok) {
+                            return JSON.stringify({
+                                code: "NIFRA_NONE",
+                                message: `dev server at :${validPort} returned ${res.status}`,
+                            }, null, 2);
+                        }
+                        return await readBoundedResponse(res);
+                    }
+                    catch (cause) {
+                        return JSON.stringify({
+                            code: "NIFRA_NONE",
+                            message: `could not reach a nifra dev server at :${validPort} - ${cause instanceof Error ? cause.message : String(cause)}`,
+                        }, null, 2);
+                    }
+                }
+                return JSON.stringify({
+                    code: "NIFRA_NONE",
+                    message: "Pass `error` (and `stack` if available) to explain a failure, or `port` to fetch the dev server's last error.",
+                }, null, 2);
+            },
+        },
+        {
+            name: "nifra_inspect",
+            description: "Observe what your requests ACTUALLY did on the running dev server - the recent request traces the DevTools plugin records: `{ method, path, status, durationMs, isrStatus, bodyBytes }` per request. The read no other tool gives you: after nifra_run or a real browser request, call this to SEE the outcome (which route answered, the status, how long, ISR hit/miss) instead of guessing. Pass `port` (the running dev server); narrow with `path` (a path prefix) or `limit` (most recent N). Requires the app to mount `@nifrajs/web`'s `devtools()` plugin (which auto-enables in development).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    port: { type: "number", description: "The running dev server's port." },
+                    path: { type: "string", description: "Only traces whose path starts with this prefix." },
+                    limit: { type: "number", description: "Return only the most recent N traces." },
+                },
+                required: ["port"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const { port, path, limit } = args;
+                if (port === undefined) {
+                    return JSON.stringify({
+                        events: [],
+                        note: "Pass `port` - the running dev server whose request traces to read.",
+                    }, null, 2);
+                }
+                try {
+                    const validPort = validateLocalPort(port);
+                    if (validPort === undefined) {
+                        return JSON.stringify({
+                            events: [],
+                            code: "NIFRA_INVALID_PORT",
+                            note: "port must be an integer from 1 to 65535.",
+                        }, null, 2);
+                    }
+                    const url = new URL(`http://127.0.0.1:${validPort}/_nifra/devtools/state`);
+                    if (path !== undefined)
+                        url.searchParams.set("path", path);
+                    if (limit !== undefined)
+                        url.searchParams.set("limit", String(limit));
+                    const res = await fetch(url, {
+                        signal: AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS),
+                    });
+                    if (res.headers.get("x-nifra-devtools") !== "true")
+                        return notNifraResponse("DevTools");
+                    if (res.status === 404) {
+                        return JSON.stringify({
+                            events: [],
+                            note: "No DevTools endpoint on that server. Mount `devtools()` from @nifrajs/web and run in development.",
+                        }, null, 2);
+                    }
+                    if (!res.ok) {
+                        return JSON.stringify({ events: [], note: `DevTools state returned ${res.status}.` }, null, 2);
+                    }
+                    return await readBoundedResponse(res);
+                }
+                catch (cause) {
+                    const validPort = validateLocalPort(port);
+                    return JSON.stringify({
+                        events: [],
+                        note: `Could not reach a dev server at :${validPort ?? String(port)} - ${cause instanceof Error ? cause.message : String(cause)}`,
+                    }, null, 2);
+                }
+            },
+        },
         {
             name: "nifra_routes",
             description: "List this project's API routes as STRUCTURED JSON - each `{ method, path, call, body?, query?, response? }`, where `call` is the exact typed-client call form and the shapes are compact TS-typed contracts. For programmatic use (list_routes / get_route_schema) instead of parsing the nifra_context Markdown. No args = every route; pass `path` (a path or prefix like /api/orders) to narrow to those routes.",