fa-mcp-sdk 0.4.124 → 0.4.134

package/dist/core/mcp/debug-trace.js

@@ -0,0 +1,79 @@
+/**
+ * JSON-lines debug sink for MCP server traffic.
+ *
+ * Stderr output via `DEBUG=mcp:*` (`af-tools-ts/Debug`) is great for live
+ * development but useless for post-mortem analysis: ANSI colors, multi-process
+ * interleaving, no structured fields. This module mirrors every `debugMcp*`
+ * stream into a single newline-delimited JSON file when `mcp.debug.logFile`
+ * is configured. Stderr behavior is unchanged — the sink is purely additive.
+ *
+ * Activation:
+ *   - via `appConfig.mcp.debug.logFile` (absolute path) — set the file path
+ *     at startup and call {@link initDebugTraceFromConfig}; or
+ *   - via {@link configureDebugSink} for programmatic control (tests).
+ *
+ * Each event is one line like:
+ *   {"ts":"2026-05-19T12:34:56.124Z","ch":"mcp:tool","kind":"req","name":"get_rate","corr":"a3f1",...}
+ *
+ * No-op when no sink is configured — call sites are cheap (one `if`).
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import * as path from 'node:path';
+import { appConfig } from '../bootstrap/init-config.js';
+let sink = null;
+/**
+ * Configure (or disable) the JSON-lines sink.
+ *
+ * @param logFile Absolute path to the .jsonl file. Empty / undefined disables the sink.
+ *
+ * Writes are fire-and-forget: failures (permission, disk full) are swallowed
+ * so debug logging never breaks the server. The parent directory is created
+ * lazily on the first event.
+ */
+export function configureDebugSink(logFile) {
+    if (!logFile || typeof logFile !== 'string' || logFile.trim() === '') {
+        sink = null;
+        return;
+    }
+    const resolved = path.resolve(logFile.trim());
+    let dirEnsured = false;
+    sink = (event) => {
+        const line = JSON.stringify(event) + '\n';
+        const write = () => appendFile(resolved, line, 'utf-8').catch(() => { });
+        if (dirEnsured) {
+            void write();
+            return;
+        }
+        void mkdir(path.dirname(resolved), { recursive: true })
+            .catch(() => { })
+            .then(() => {
+            dirEnsured = true;
+            return write();
+        });
+    };
+}
+/**
+ * Emit a single trace event. Always adds `ts` (ISO timestamp) and `ch` (channel).
+ * No-op when the sink is not configured.
+ */
+export function emitTrace(channel, event) {
+    if (!sink) {
+        return;
+    }
+    sink({ ts: new Date().toISOString(), ch: channel, ...event });
+}
+/**
+ * Generate a short correlation ID for matching req/res/err events of a single call.
+ * 8 hex chars — collision-resistant enough for human reading; not cryptographic.
+ */
+export function makeCorr() {
+    return Math.random().toString(16).slice(2, 10).padStart(8, '0');
+}
+/**
+ * Initialize the sink from `appConfig.mcp.debug.logFile`. Called once at server
+ * startup; safe to call again to apply config changes during tests.
+ */
+export function initDebugTraceFromConfig() {
+    configureDebugSink(appConfig.mcp?.debug?.logFile);
+}
+//# sourceMappingURL=debug-trace.js.map

package/dist/core/mcp/debug-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-trace.js","sourceRoot":"","sources":["../../../src/core/mcp/debug-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAIxD,IAAI,IAAI,GAAgB,IAAI,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkC;IACnE,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrE,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9C,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,GAAG,CAAC,KAAK,EAAE,EAAE;QACf,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QAC1C,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACxE,IAAI,UAAU,EAAE,CAAC;YACf,KAAK,KAAK,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,KAAK,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;aACpD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;aACf,IAAI,CAAC,GAAG,EAAE;YACT,UAAU,GAAG,IAAI,CAAC;YAClB,OAAO,KAAK,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,KAA8B;IACvE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;IACT,CAAC;IACD,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,kBAAkB,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC"}

package/dist/core/mcp/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAA+B,MAAM,qBAAqB,CAAC;AAgDxG,wBAAsB,cAAc,CAAC,IAAI,EAAE,iBAAiB;;;;;;;GAU3D;AAED,eAAO,MAAM,SAAS,GAAU,SAAS,iBAAiB,EAAE,MAAM,iBAAiB,KAAG,OAAO,CAAC,GAAG,CAmChG,CAAC"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAA+B,MAAM,qBAAqB,CAAC;AAiDxG,wBAAsB,cAAc,CAAC,IAAI,EAAE,iBAAiB;;;;;;;GAc3D;AAED,eAAO,MAAM,SAAS,GAAU,SAAS,iBAAiB,EAAE,MAAM,iBAAiB,KAAG,OAAO,CAAC,GAAG,CAyChG,CAAC"}

package/dist/core/mcp/prompts.js

@@ -1,5 +1,6 @@
 import { getProjectData } from '../bootstrap/init-config.js';
 import { debugMcpPrompt } from '../debug.js';
+import { emitTrace } from './debug-trace.js';
 async function getPrompts(args) {
     const projectData = getProjectData();
     if (!projectData) {
@@ -41,24 +42,31 @@ async function getPrompts(args) {
     ];
 }
 export async function getPromptsList(args) {
+    const startedAt = Date.now();
     if (debugMcpPrompt.enabled) {
         debugMcpPrompt('→ prompts/list');
     }
+    emitTrace('mcp:prompt', { kind: 'list-req' });
     const prompts = await getPrompts(args);
     const result = { prompts: prompts.map(({ content, ...rest }) => ({ ...rest })) };
+    const ms = Date.now() - startedAt;
     if (debugMcpPrompt.enabled) {
         debugMcpPrompt(`← prompts/list (${result.prompts.length})\n${JSON.stringify(result, null, 2)}`);
     }
+    emitTrace('mcp:prompt', { kind: 'list-res', count: result.prompts.length, ms });
     return result;
 }
 export const getPrompt = async (request, args) => {
     const { name } = request.params;
+    const startedAt = Date.now();
     if (debugMcpPrompt.enabled) {
         debugMcpPrompt(`→ prompts/get ${name}\n${JSON.stringify(request.params ?? {}, null, 2)}`);
     }
+    emitTrace('mcp:prompt', { kind: 'get-req', name });
     const prompts = await getPrompts(args);
     // Check if prompts are available
     if (!prompts || prompts.length === 0) {
+        emitTrace('mcp:prompt', { kind: 'get-err', name, ms: Date.now() - startedAt, error: 'no-prompts' });
         throw new Error('No prompts available. Project data may not be properly initialized.');
     }
     let content = prompts.filter((p) => p.name === name).map((p) => p.content)[0] || null;
@@ -66,6 +74,7 @@ export const getPrompt = async (request, args) => {
         content = await content(request);
     }
     if (!content) {
+        emitTrace('mcp:prompt', { kind: 'get-err', name, ms: Date.now() - startedAt, error: 'unknown-prompt' });
         throw new Error(`Unknown prompt: ${name}`);
     }
     const result = {
@@ -79,9 +88,11 @@ export const getPrompt = async (request, args) => {
             },
         ],
     };
+    const ms = Date.now() - startedAt;
     if (debugMcpPrompt.enabled) {
         debugMcpPrompt(`← prompts/get ${name}\n${content}`);
     }
+    emitTrace('mcp:prompt', { kind: 'get-res', name, ms });
     return result;
 };
 //# sourceMappingURL=prompts.js.map

package/dist/core/mcp/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/core/mcp/prompts.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,KAAK,UAAU,UAAU,CAAC,IAAuB;IAC/C,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,CAAC,iFAAiF,CAAC,CAAC;QACjG,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,WAAW,CAAC;IAE/D,+CAA+C;IAC/C,IAAI,CAAC,UAAU,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,iFAAiF,CAAC,CAAC;QACjG,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,yDAAyD;IACzD,IAAI,qBAAqB,GAAkB,EAAE,CAAC;IAC9C,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE,CAAC;YACxC,qBAAqB,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,qBAAqB,GAAG,aAAa,CAAC;QACxC,CAAC;IACH,CAAC;IAED,OAAO;QACL;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,mEAAmE;YAChF,SAAS,EAAE,EAAE;YACb,OAAO,EAAE,UAAU;YACnB,WAAW,EAAE,KAAK;SACnB;QACD;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,8BAA8B;YAC3C,SAAS,EAAE,EAAE;YACb,OAAO,EAAE,WAAW;YACpB,WAAW,EAAE,KAAK;SACnB;QACD,GAAG,qBAAqB;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAuB;IAC1D,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC3B,cAAc,CAAC,gBAAgB,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IACjF,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC3B,cAAc,CAAC,mBAAmB,MAAM,CAAC,OAAO,CAAC,MAAM,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAAE,OAA0B,EAAE,IAAuB,EAAgB,EAAE;IACnG,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAChC,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC3B,cAAc,CAAC,iBAAiB,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvC,iCAAiC;IACjC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IAED,IAAI,OAAO,GAA0B,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC7G,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,MAAM,GAAG;QACb,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,OAAO;iBACd;aACF;SACF;KACF,CAAC;IACF,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC3B,cAAc,CAAC,iBAAiB,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/core/mcp/prompts.ts"],"names":[],"mappings":"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"}

package/dist/core/mcp/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/resources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAmB,SAAS,EAAiB,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAyElH,eAAO,MAAM,gBAAgB,GAAU,MAAM,iBAAiB,KAAG,OAAO,CAAC;IAAE,SAAS,EAAE,aAAa,EAAE,CAAA;CAAE,CAUtG,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,KAAK,MAAM,EAAE,MAAM,iBAAiB,KAAG,OAAO,CAAC,SAAS,CA+BzF,CAAC"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/resources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAmB,SAAS,EAAiB,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA0ElH,eAAO,MAAM,gBAAgB,GAAU,MAAM,iBAAiB,KAAG,OAAO,CAAC;IAAE,SAAS,EAAE,aAAa,EAAE,CAAA;CAAE,CActG,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,KAAK,MAAM,EAAE,MAAM,iBAAiB,KAAG,OAAO,CAAC,SAAS,CAqCzF,CAAC"}

package/dist/core/mcp/resources.js

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import { appConfig, getProjectData } from '../bootstrap/init-config.js';
 import { ROOT_PROJECT_DIR } from '../constants.js';
 import { debugMcpResource } from '../debug.js';
+import { emitTrace } from './debug-trace.js';
 import { assembleReadmeWithSatellites } from './readme-assembler.js';
 let readme = assembleReadmeWithSatellites(ROOT_PROJECT_DIR);
 let packageJson;
@@ -72,23 +73,30 @@ This information is used by searching for this MCP server and its information in
     return [...resources, ...resolvedCustomResources];
 };
 export const getResourcesList = async (args) => {
+    const startedAt = Date.now();
     if (debugMcpResource.enabled) {
         debugMcpResource('→ resources/list');
     }
+    emitTrace('mcp:resource', { kind: 'list-req' });
     const resources = await createResources(args);
     const result = { resources: resources.map(({ content, ...rest }) => ({ ...rest })) };
+    const ms = Date.now() - startedAt;
     if (debugMcpResource.enabled) {
         debugMcpResource(`← resources/list (${result.resources.length})\n${JSON.stringify(result, null, 2)}`);
     }
+    emitTrace('mcp:resource', { kind: 'list-res', count: result.resources.length, ms });
     return result;
 };
 export const getResource = async (uri, args) => {
+    const startedAt = Date.now();
     if (debugMcpResource.enabled) {
         debugMcpResource(`→ resources/read ${uri}`);
     }
+    emitTrace('mcp:resource', { kind: 'read-req', uri });
     const resources = await createResources(args);
     const resource = resources.find((r) => r.uri === uri);
     if (!resource) {
+        emitTrace('mcp:resource', { kind: 'read-err', uri, ms: Date.now() - startedAt, error: 'unknown-resource' });
         throw new Error(`Unknown resource: ${uri}`);
     }
     let { content } = resource;
@@ -96,6 +104,7 @@ export const getResource = async (uri, args) => {
         content = await content(uri);
     }
     if (!content) {
+        emitTrace('mcp:resource', { kind: 'read-err', uri, ms: Date.now() - startedAt, error: 'no-content' });
         throw new Error(`Can not get content of resource '${uri}' by custom handler`);
     }
     const result = {
@@ -108,10 +117,12 @@ export const getResource = async (uri, args) => {
             },
         ],
     };
+    const ms = Date.now() - startedAt;
     if (debugMcpResource.enabled) {
         const body = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
         debugMcpResource(`← resources/read ${uri}\n${body}`);
     }
+    emitTrace('mcp:resource', { kind: 'read-res', uri, ms });
     return result;
 };
 //# sourceMappingURL=resources.js.map

package/dist/core/mcp/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../../src/core/mcp/resources.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../../src/core/mcp/resources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAErE,IAAI,MAAM,GAAG,4BAA4B,CAAC,gBAAgB,CAAC,CAAC;AAC5D,IAAI,WAAgB,CAAC;AACrB,IAAI,CAAC;IACH,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAClG,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,oCAAoC,EAAE,YAAY,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;AACnG,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,eAAe,GAAG,KAAK,EAAE,IAAuB,EAA4B,EAAE;IAClF,MAAM,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,GAAG,cAAc,EAAE,CAAC;IAElF,2DAA2D;IAC3D,IAAI,uBAAuB,GAAoB,EAAE,CAAC;IAClD,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,OAAO,eAAe,KAAK,UAAU,EAAE,CAAC;YAC1C,uBAAuB,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,uBAAuB,GAAG,eAAe,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAoB;QACjC;YACE,GAAG,EAAE,cAAc;YACnB,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE;;;oCAGiB;YAC9B,QAAQ,EAAE,YAAY;YACtB,OAAO,EAAE,SAAS,CAAC,IAAI;YACvB,WAAW,EAAE,KAAK;SACnB;QACD;YACE,GAAG,EAAE,gBAAgB;YACrB,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,+CAA+C;YAC5D,QAAQ,EAAE,YAAY;YACtB,OAAO,EAAE,SAAS,CAAC,WAAW;YAC9B,WAAW,EAAE,KAAK;SACnB;QACD;YACE,GAAG,EAAE,cAAc;YACnB,IAAI,EAAE,WAAW;YACjB,WAAW,EAAE,6BAA6B,SAAS,CAAC,WAAW;;;CAGpE;YACK,QAAQ,EAAE,eAAe;YACzB,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,KAAK;SACnB;KACF,CAAC;IACF,MAAM,eAAe,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAsB,CAAC;IAExE,SAAS,CAAC,IAAI,CAAC;QACb,GAAG,EAAE,oBAAoB;QACzB,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,mBAAmB;QAChC,QAAQ,EAAE,kBAAkB;QAC5B,OAAO,EAAE,eAAe;QACxB,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,SAAS,EAAE,GAAG,uBAAuB,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,IAAuB,EAA2C,EAAE;IACzG,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;IACvC,CAAC;IACD,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,GAAoB,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IACrF,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAClC,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,gBAAgB,CAAC,qBAAqB,MAAM,CAAC,SAAS,CAAC,MAAM,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACxG,CAAC;IACD,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IACpF,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,GAAW,EAAE,IAAuB,EAAsB,EAAE;IAC5F,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,gBAAgB,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC5G,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IAC3B,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;QACtG,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,qBAAqB,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAc;QACxB,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,OAAO;gBACb,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrD;SACF;KACF,CAAC;IACF,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAClC,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACtF,gBAAgB,CAAC,oBAAoB,GAAG,KAAK,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/core/utils/formatToolResult.d.ts

@@ -14,5 +14,44 @@ export declare function asJson<T = any>(json: T): IToolHandlerStructuredResponse
  * Returns either structured content (JSON) or formatted text
  */
 export declare function formatToolResult<T = any>(json: T): TToolHandlerResponse<T>;
+/**
+ * Text response with `isError: true`. Use for tool-level errors that the LLM
+ * should see and react to (resource not found, business validation failed,
+ * upstream API returned 404, etc.). Per MCP spec these MUST NOT be thrown as
+ * JSON-RPC errors — throwing turns them into protocol-level failures the LLM
+ * cannot self-correct from.
+ *
+ * @example
+ * if (!issue) {
+ *   return asTextError(`Issue ${key} not found`);
+ * }
+ */
+export declare function asTextError(text: string): IToolHandlerTextResponse;
+/**
+ * Structured (`structuredContent`) response with `isError: true`. See
+ * {@link asTextError} for when to use error responses vs throwing.
+ */
+export declare function asJsonError<T = any>(json: T): IToolHandlerStructuredResponse<T>;
+/**
+ * Config-aware tool error formatter — mirror of {@link formatToolResult} but
+ * sets `isError: true`. Honors `appConfig.mcp.tools.answerAs` so error
+ * responses follow the same shape as success responses for the same MCP.
+ *
+ * Use this for tool-level errors the LLM should see (not-found, validation,
+ * upstream failure). Reserve `throw new ToolExecutionError(...)` for protocol
+ * issues: unknown tool, malformed call, missing transport feature.
+ *
+ * @example
+ * try {
+ *   const data = await fetchIssue(key);
+ *   return formatToolResult(data);
+ * } catch (err) {
+ *   if (err.code === 'NOT_FOUND') {
+ *     return formatToolError(`Issue ${key} not found`);
+ *   }
+ *   throw err; // genuine infra failure → JSON-RPC error is appropriate
+ * }
+ */
+export declare function formatToolError<T = any>(json: T): TToolHandlerResponse<T>;
 export declare const getJsonFromResult: <T = any>(result: any) => T;
 //# sourceMappingURL=formatToolResult.d.ts.map

package/dist/core/utils/formatToolResult.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatToolResult.d.ts","sourceRoot":"","sources":["../../../src/core/utils/formatToolResult.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,8BAA8B,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AA+BrH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,CASpE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,8BAA8B,CAAC,CAAC,CAAC,CAK1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAW1E;AAED,eAAO,MAAM,iBAAiB,GAAI,CAAC,GAAG,GAAG,EAAE,QAAQ,GAAG,KAAG,CAYxD,CAAC"}
+{"version":3,"file":"formatToolResult.d.ts","sourceRoot":"","sources":["../../../src/core/utils/formatToolResult.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,8BAA8B,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AA+BrH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,CASpE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,8BAA8B,CAAC,CAAC,CAAC,CAK1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAW1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,CAKlE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,8BAA8B,CAAC,CAAC,CAAC,CAK/E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CASzE;AAED,eAAO,MAAM,iBAAiB,GAAI,CAAC,GAAG,GAAG,EAAE,QAAQ,GAAG,KAAG,CAYxD,CAAC"}

package/dist/core/utils/formatToolResult.js

@@ -69,6 +69,64 @@ export function formatToolResult(json) {
     }
     return asTextContent(ppj(json));
 }
+/**
+ * Text response with `isError: true`. Use for tool-level errors that the LLM
+ * should see and react to (resource not found, business validation failed,
+ * upstream API returned 404, etc.). Per MCP spec these MUST NOT be thrown as
+ * JSON-RPC errors — throwing turns them into protocol-level failures the LLM
+ * cannot self-correct from.
+ *
+ * @example
+ * if (!issue) {
+ *   return asTextError(`Issue ${key} not found`);
+ * }
+ */
+export function asTextError(text) {
+    return {
+        content: [{ type: 'text', text }],
+        isError: true,
+    };
+}
+/**
+ * Structured (`structuredContent`) response with `isError: true`. See
+ * {@link asTextError} for when to use error responses vs throwing.
+ */
+export function asJsonError(json) {
+    if (isObject(json)) {
+        cleanUndefinedDeep(json);
+    }
+    return { structuredContent: json, isError: true };
+}
+/**
+ * Config-aware tool error formatter — mirror of {@link formatToolResult} but
+ * sets `isError: true`. Honors `appConfig.mcp.tools.answerAs` so error
+ * responses follow the same shape as success responses for the same MCP.
+ *
+ * Use this for tool-level errors the LLM should see (not-found, validation,
+ * upstream failure). Reserve `throw new ToolExecutionError(...)` for protocol
+ * issues: unknown tool, malformed call, missing transport feature.
+ *
+ * @example
+ * try {
+ *   const data = await fetchIssue(key);
+ *   return formatToolResult(data);
+ * } catch (err) {
+ *   if (err.code === 'NOT_FOUND') {
+ *     return formatToolError(`Issue ${key} not found`);
+ *   }
+ *   throw err; // genuine infra failure → JSON-RPC error is appropriate
+ * }
+ */
+export function formatToolError(json) {
+    if (appConfig.mcp.tools.answerAs === 'structuredContent') {
+        return asJsonError(json);
+    }
+    if (isObject(json)) {
+        cleanUndefinedDeep(json);
+    }
+    const text = typeof json === 'string' ? json : ppj(json);
+    return asTextError(text);
+}
 export const getJsonFromResult = (result) => {
     if (appConfig.mcp.tools.answerAs === 'structuredContent') {
         return result?.structuredContent;

package/dist/core/utils/formatToolResult.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatToolResult.js","sourceRoot":"","sources":["../../../src/core/utils/formatToolResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAG3C,MAAM,kBAAkB,GAAG,CAAC,KAAU,EAAQ,EAAE;IAC9C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;IACT,CAAC;IACD,oDAAoD;IACpD,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACpB,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBACjB,kBAAkB,CAAC,EAAE,CAAC,CAAC;YACzB,CAAC;YACD,oFAAoF;QACtF,CAAC;QACD,OAAO;IACT,CAAC;IACD,oBAAoB;IACpB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,kBAAkB,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI;aACL;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAU,IAAO;IACrC,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAU,IAAO;IAC/C,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,mBAAmB,EAAE,CAAC;QACzD,OAAO,MAAM,CAAI,IAAI,CAAsC,CAAC;IAC9D,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,aAAa,CAAC,IAAI,CAA6B,CAAC;IACzD,CAAC;IACD,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAU,MAAW,EAAK,EAAE;IAC3D,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,mBAAmB,EAAE,CAAC;QACzD,OAAO,MAAM,EAAE,iBAAsB,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;QACpF,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,EAAE;QACJ,CAAC;IACH,CAAC;IACD,OAAO,SAAc,CAAC;AACxB,CAAC,CAAC"}
+{"version":3,"file":"formatToolResult.js","sourceRoot":"","sources":["../../../src/core/utils/formatToolResult.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/testing/debug-tool.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Universal `debug-tool` for integration testing of MCP clients (Agent Tester,
+ * custom hosts, CI smoke tests).
+ *
+ * One parameterised tool that can produce **any** variation of
+ * `CallToolResult`: every content-block type from the MCP spec, single vs.
+ * multiple blocks, `structuredContent` / `_meta` toggles, `isError: true`,
+ * delay simulation, and a `largeInput` knob for streaming / truncate tests.
+ *
+ * Activated together with the other built-ins via
+ * `appConfig.mcp.debug.builtinTools = true`. Test code can also import the
+ * tool descriptor + handler directly to spin up a stand-alone server.
+ *
+ * The constants for an image / audio block (`BLUE_PNG_1X1`, `SILENT_WAV`)
+ * are kept private to this file — never exported.
+ */
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { IToolHandlerParams, TToolHandlerResponse } from '../../_types_/types.js';
+export declare const DEBUG_TOOL_NAME = "debug-tool";
+/** `Tool` descriptor for the universal debug-tool. */
+export declare const DEBUG_TOOL: Tool;
+/** Execute the debug-tool. Returns a `CallToolResult`-shaped response. */
+export declare function handleDebugTool(params: IToolHandlerParams): Promise<TToolHandlerResponse>;
+/**
+ * Register the debug-tool against a `McpServer` from
+ * `@modelcontextprotocol/sdk/server/mcp.js`. Use this for stand-alone test
+ * servers that do not go through `initMcpServer()`.
+ *
+ * The signature deliberately uses a structural type so the SDK does not take
+ * a hard dependency on the high-level `McpServer` class.
+ */
+export declare function registerDebugTool(server: {
+    registerTool: (name: string, def: any, handler: (args: any) => unknown) => void;
+}): void;
+//# sourceMappingURL=debug-tool.d.ts.map

package/dist/core/utils/testing/debug-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-tool.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/testing/debug-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE1D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAElF,eAAO,MAAM,eAAe,eAAe,CAAC;AAsB5C,sDAAsD;AACtD,eAAO,MAAM,UAAU,EAAE,IA4CxB,CAAC;AAmDF,0EAA0E;AAC1E,wBAAsB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgC/F;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,KAAK,IAAI,CAAC;CACjF,GAAG,IAAI,CAgBP"}

package/dist/core/utils/testing/debug-tool.js

@@ -0,0 +1,146 @@
+export const DEBUG_TOOL_NAME = 'debug-tool';
+// Minimal 1×1 blue PNG (base64). Private — keeps the public surface clean.
+const BLUE_PNG_1X1 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPj/HwADBwIAMCbHYQAAAABJRU5ErkJggg==';
+// Minimal silent WAV (base64) — 44 byte header + 1 sample.
+const SILENT_WAV = 'UklGRiYAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQIAAAAAAA==';
+let callCounter = 0;
+/** `Tool` descriptor for the universal debug-tool. */
+export const DEBUG_TOOL = {
+    name: DEBUG_TOOL_NAME,
+    title: 'Debug tool',
+    description: 'App-only test helper. Produces any variation of CallToolResult (text/image/audio/resource/' +
+        'resourceLink/mixed, single or multi-block, isError, delays, large payload) so MCP host tests ' +
+        'can exercise every code path without standing up a bespoke fake server. Hidden from the LLM ' +
+        'via _meta.ui.visibility=["app"].',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            contentType: {
+                type: 'string',
+                enum: ['text', 'image', 'audio', 'resource', 'resourceLink', 'mixed'],
+                description: 'Which content-block type to emit. "mixed" returns one of each (ignores multipleBlocks).',
+            },
+            multipleBlocks: {
+                type: 'boolean',
+                description: 'When true, emit 3 blocks of the chosen type; otherwise emit 1. Default: true.',
+            },
+            includeStructuredContent: {
+                type: 'boolean',
+                description: 'Include result.structuredContent with config/timestamp/counter. Default: true.',
+            },
+            includeMeta: {
+                type: 'boolean',
+                description: 'Include result._meta with diagnostic fields. Default: true.',
+            },
+            largeInput: {
+                type: 'string',
+                description: 'Optional large payload — its length is echoed back in structuredContent.largeInputLength.',
+            },
+            simulateError: {
+                type: 'boolean',
+                description: 'When true, set result.isError = true (the call still resolves). Default: false.',
+            },
+            delayMs: {
+                type: 'number',
+                description: 'Optional artificial delay (ms) before responding — for timeout / loading-state tests.',
+                minimum: 0,
+            },
+        },
+    },
+    _meta: { ui: { visibility: ['app'] } },
+};
+function buildContent(args) {
+    const contentType = args.contentType ?? 'text';
+    const multiple = args.multipleBlocks !== false;
+    if (contentType === 'mixed') {
+        return [
+            { type: 'text', text: 'Mixed content: text block' },
+            { type: 'image', data: BLUE_PNG_1X1, mimeType: 'image/png' },
+            { type: 'audio', data: SILENT_WAV, mimeType: 'audio/wav' },
+        ];
+    }
+    const count = multiple ? 3 : 1;
+    const blocks = [];
+    for (let i = 0; i < count; i++) {
+        const suffix = multiple ? ` #${i + 1}` : '';
+        switch (contentType) {
+            case 'text':
+                blocks.push({ type: 'text', text: `Debug text content${suffix}` });
+                break;
+            case 'image':
+                blocks.push({ type: 'image', data: BLUE_PNG_1X1, mimeType: 'image/png' });
+                break;
+            case 'audio':
+                blocks.push({ type: 'audio', data: SILENT_WAV, mimeType: 'audio/wav' });
+                break;
+            case 'resource':
+                blocks.push({
+                    type: 'resource',
+                    resource: {
+                        uri: `debug://embedded-resource${suffix.replace(/\s/g, '-')}`,
+                        text: `Embedded resource content${suffix}`,
+                        mimeType: 'text/plain',
+                    },
+                });
+                break;
+            case 'resourceLink':
+                blocks.push({
+                    type: 'resource_link',
+                    uri: `debug://linked-resource${suffix.replace(/\s/g, '-')}`,
+                    name: `Linked Resource${suffix}`,
+                    mimeType: 'text/plain',
+                });
+                break;
+        }
+    }
+    return blocks;
+}
+/** Execute the debug-tool. Returns a `CallToolResult`-shaped response. */
+export async function handleDebugTool(params) {
+    const args = (params.arguments ?? {});
+    if (typeof args.delayMs === 'number' && args.delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, args.delayMs));
+    }
+    const content = buildContent(args);
+    const result = { content };
+    if (args.includeStructuredContent !== false) {
+        result.structuredContent = {
+            config: args,
+            timestamp: new Date().toISOString(),
+            counter: ++callCounter,
+            ...(args.largeInput ? { largeInputLength: args.largeInput.length } : {}),
+        };
+    }
+    if (args.includeMeta !== false) {
+        result._meta = {
+            debugInfo: {
+                processedAt: Date.now(),
+            },
+        };
+    }
+    if (args.simulateError) {
+        result.isError = true;
+    }
+    return result;
+}
+/**
+ * Register the debug-tool against a `McpServer` from
+ * `@modelcontextprotocol/sdk/server/mcp.js`. Use this for stand-alone test
+ * servers that do not go through `initMcpServer()`.
+ *
+ * The signature deliberately uses a structural type so the SDK does not take
+ * a hard dependency on the high-level `McpServer` class.
+ */
+export function registerDebugTool(server) {
+    server.registerTool(DEBUG_TOOL_NAME, {
+        title: DEBUG_TOOL.title,
+        description: DEBUG_TOOL.description,
+        inputSchema: DEBUG_TOOL.inputSchema,
+        _meta: DEBUG_TOOL._meta,
+    }, async (args) => handleDebugTool({
+        name: DEBUG_TOOL_NAME,
+        arguments: args,
+        transport: 'stdio',
+    }));
+}
+//# sourceMappingURL=debug-tool.js.map

package/dist/core/utils/testing/debug-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-tool.js","sourceRoot":"","sources":["../../../../src/core/utils/testing/debug-tool.ts"],"names":[],"mappings":"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"}

package/dist/core/web/server-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-http.d.ts","sourceRoot":"","sources":["../../../src/core/web/server-http.ts"],"names":[],"mappings":"AAiDA,eAAO,MAAM,cAAc,SAAyC,CAAC;AAsCrE;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA+mBrD"}
+{"version":3,"file":"server-http.d.ts","sourceRoot":"","sources":["../../../src/core/web/server-http.ts"],"names":[],"mappings":"AAkDA,eAAO,MAAM,cAAc,SAAyC,CAAC;AAsCrE;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA2oBrD"}

package/dist/core/web/server-http.js

@@ -9,8 +9,9 @@ import { RateLimiterMemory } from 'rate-limiter-flexible';
 import { createAgentTesterRouter } from '../agent-tester/agent-tester-router.js';
 import { validateAdminAuthConfig } from '../auth/admin-auth.js';
 import { createAgentTesterSessionMW } from '../auth/agent-tester-auth.js';
-import { generateToken, MIN_ENCRYPT_KEY_LENGTH } from '../auth/jwt.js';
+import { checkJwtToken, generateToken, MIN_ENCRYPT_KEY_LENGTH } from '../auth/jwt.js';
 import { createAuthMW } from '../auth/middleware.js';
+import { checkPermanentToken } from '../auth/permanent.js';
 import { appConfig, getProjectData } from '../bootstrap/init-config.js';
 import { debugMcpNotification } from '../debug.js';
 import { getMainDBConnectionStatus } from '../db/pg-db.js';
@@ -113,6 +114,29 @@ export async function startHttpServer() {
         }
         res.json(health);
     });
+    // Token check endpoint: GET /ct?t=<token> or POST /ct {"t": "<token>"}
+    // Returns { success, type: 'permanent' | 'JWT', payload? } or { success: false, error }
+    const handleTokenCheck = (req, res) => {
+        const raw = req.method === 'GET' ? req.query.t : req.body?.t;
+        const token = typeof raw === 'string' ? raw.trim() : '';
+        if (!token) {
+            return res.status(400).json({ success: false, error: 'Token not provided. Pass via "t" query/body parameter' });
+        }
+        const { errorReason: permError } = checkPermanentToken(token);
+        if (!permError) {
+            return res.json({ success: true, type: 'permanent' });
+        }
+        const xff = req.headers['x-forwarded-for'];
+        const xffStr = (Array.isArray(xff) ? (xff[0] ?? '') : (xff ?? '')).split(',').shift() ?? '';
+        const clientIp = req.ip ?? (xffStr.trim() || (req.socket?.remoteAddress ?? ''));
+        const jwtResult = checkJwtToken({ token, clientIp });
+        if (!jwtResult.errorReason) {
+            return res.json({ success: true, type: 'JWT', payload: jwtResult.payload });
+        }
+        return res.status(401).json({ success: false, error: jwtResult.errorReason });
+    };
+    app.get('/ct', handleTokenCheck);
+    app.post('/ct', handleTokenCheck);
     // Public endpoint: returns used HTTP headers configured in the template (optional)
     app.get('/used-http-headers', (req, res) => {
         try {
@@ -550,6 +574,7 @@ export async function startHttpServer() {
         const availableEndpoints = {
             home: 'GET /',
             health: 'GET /health',
+            checkToken: 'GET /ct?t=<token>, POST /ct',
             sse: 'GET /sse, POST /sse',
             messages: 'POST /messages',
             mcp: 'POST /mcp',