@fitchmultz/pi-mcp-adapter 8.0.6 → 8.0.8

package/dist/mcp-trace.js

@@ -5,8 +5,9 @@ export const MCP_TRACE_SCHEMA_VERSION = 1;
 export const DEFAULT_MCP_TRACE_MAX_BYTES = 256 * 1024;
 export const DEFAULT_MCP_TRACE_MAX_EVENTS = 10_000;
 function boundedPositiveInteger(value, fallback) {
-    if (!Number.isFinite(value) || value === undefined || value <= 0)
+    if (!Number.isFinite(value) || value === undefined || value <= 0) {
         return fallback;
+    }
     return Math.floor(value);
 }
 /** Redact strings before they can become durable trace metadata. */
@@ -18,22 +19,27 @@ export function redactTraceText(value, maxLength = 160) {
         .replace(/\b[a-z][a-z\d+.-]*:\/\/[^\s"'<>]+/gi, "[REDACTED_URL]")
         .replace(/\b(?:bearer|basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[REDACTED_AUTH]")
         .replace(/\b(?:token|secret|password|passwd|api[_-]?key|authorization|cookie)\s*[:=]\s*[^\s,;]+/gi, "$1=[REDACTED]");
-    if (redacted.length > maxLength)
+    if (redacted.length > maxLength) {
         redacted = `${redacted.slice(0, maxLength - 1)}…`;
+    }
     return redacted;
 }
 function messageKind(message) {
-    if ("method" in message)
+    if ("method" in message) {
         return "id" in message ? "request" : "notification";
+    }
     return "response";
 }
 function traceId(value) {
-    if (value === null)
+    if (value === null) {
         return null;
-    if (typeof value === "number" && Number.isFinite(value))
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
         return value;
-    if (typeof value === "string")
+    }
+    if (typeof value === "string") {
         return "[REDACTED_ID]";
+    }
     return undefined;
 }
 function messageBytes(message) {
@@ -44,33 +50,49 @@ function messageBytes(message) {
         return undefined;
     }
 }
-export function createMcpTraceEvent(direction, server, transport, message, status, options) {
-    const kind = messageKind(message);
-    const bytes = messageBytes(message);
-    const event = {
+export function createMcpTraceEvent(request) {
+    const kind = messageKind(request.message);
+    const bytes = messageBytes(request.message);
+    return {
         version: MCP_TRACE_SCHEMA_VERSION,
         timestamp: new Date().toISOString(),
-        direction,
-        server: redactTraceText(server, 120),
-        transport,
+        direction: request.direction,
+        server: redactTraceText(request.server, 120),
+        transport: request.transport,
         kind,
-        status,
+        status: request.status,
         ...(bytes !== undefined ? { bytes } : {}),
+        ...traceMessageMetadata(request.message),
+        ...traceOutcomeMetadata(request),
     };
-    if ("method" in message)
-        event.method = redactTraceText(message.method, 120);
-    if ("id" in message)
-        event.id = traceId(message.id) ?? null;
-    const relatedRequestId = traceId(options?.relatedRequestId);
-    if (relatedRequestId !== undefined && relatedRequestId !== null)
-        event.relatedRequestId = relatedRequestId;
-    if ("error" in message && message.error && typeof message.error.code === "number") {
-        event.errorCode = message.error.code;
-    }
-    if (options?.durationMs !== undefined && Number.isFinite(options.durationMs)) {
-        event.durationMs = Math.max(0, Math.round(options.durationMs * 100) / 100);
-    }
-    return event;
+}
+function traceMessageMetadata(message) {
+    const fields = {};
+    if ("method" in message) {
+        fields.method = redactTraceText(message.method, 120);
+    }
+    if ("id" in message) {
+        fields.id = traceId(message.id) ?? null;
+    }
+    return fields;
+}
+function traceOutcomeMetadata(request) {
+    const fields = {};
+    const relatedRequestId = traceId(request.relatedRequestId);
+    if (relatedRequestId !== undefined && relatedRequestId !== null) {
+        fields.relatedRequestId = relatedRequestId;
+    }
+    const wireError = "error" in request.message ? request.message.error : undefined;
+    if (typeof wireError === "object" &&
+        wireError !== null &&
+        "code" in wireError &&
+        typeof wireError.code === "number") {
+        fields.errorCode = wireError.code;
+    }
+    if (request.durationMs !== undefined && Number.isFinite(request.durationMs)) {
+        fields.durationMs = Math.max(0, Math.round(request.durationMs * 100) / 100);
+    }
+    return fields;
 }
 export class McpTraceWriter {
     maxBytes;
@@ -90,19 +112,25 @@ export class McpTraceWriter {
         this.options = options;
         this.maxBytes = boundedPositiveInteger(options.maxBytes, DEFAULT_MCP_TRACE_MAX_BYTES);
         this.maxEvents = boundedPositiveInteger(options.maxEvents, DEFAULT_MCP_TRACE_MAX_EVENTS);
-        this.append = options.appendFile ?? (async (path, data, appendOptions) => {
-            await appendFile(path, data, appendOptions);
-        });
-        this.resetFile = options.writeFile ?? (async (path, data, writeOptions) => {
-            await writeFile(path, data, writeOptions);
-        });
-        this.makeDirectory = options.mkdir ?? (async (path) => {
-            await mkdir(path, { recursive: true });
-            return undefined;
-        });
+        this.append =
+            options.appendFile ??
+                (async (path, data, appendOptions) => {
+                    await appendFile(path, data, appendOptions);
+                });
+        this.resetFile =
+            options.writeFile ??
+                (async (path, data, writeOptions) => {
+                    await writeFile(path, data, writeOptions);
+                });
+        this.makeDirectory =
+            options.mkdir ??
+                (async (path) => {
+                    await mkdir(path, { recursive: true });
+                    return;
+                });
         this.fileReady = this.makeDirectory(dirname(this.options.filePath), { recursive: true })
             .then(() => this.resetFile(this.options.filePath, "", { encoding: "utf8" }))
-            .catch(error => {
+            .catch((error) => {
             // Tracing must never change MCP request/response behavior.
             this.persistenceError = error;
             this.initializationFailed = true;
@@ -119,8 +147,9 @@ export class McpTraceWriter {
         return { bytes: this.bytesWritten, events: this.eventsWritten };
     }
     write(event) {
-        if (this.disabled || this.eventsWritten >= this.maxEvents)
+        if (this.disabled || this.eventsWritten >= this.maxEvents) {
             return;
+        }
         let line;
         try {
             line = `${JSON.stringify(event)}\n`;
@@ -136,12 +165,16 @@ export class McpTraceWriter {
         }
         this.bytesWritten += bytes;
         this.eventsWritten += 1;
-        this.queue = this.queue.then(async () => {
+        this.queue = this.queue
+            .then(async () => {
             await this.fileReady;
-            if (this.initializationFailed)
+            if (this.initializationFailed) {
                 return;
+            }
             await this.append(this.options.filePath, line, { encoding: "utf8" });
-        }).catch(error => {
+            return;
+        })
+            .catch((error) => {
             // Tracing must never change MCP request/response behavior.
             this.persistenceError ??= error;
             this.disabled = true;
@@ -150,16 +183,24 @@ export class McpTraceWriter {
     async flush(strict = false) {
         await this.fileReady;
         await this.queue;
-        if (strict && this.persistenceError !== undefined)
+        if (strict && this.persistenceError !== undefined) {
+            // oxlint-disable-next-line typescript/only-throw-error -- QX-009: preserve the recorded persistence failure.
             throw this.persistenceError;
+        }
     }
 }
 export function createMcpTraceWriter(sessionCwd, settings = {}, randomSuffix = Math.random().toString(36).slice(2, 10)) {
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
     const configuredPath = settings.file;
-    const filePath = configuredPath
-        ? (isAbsolute(configuredPath) ? configuredPath : resolve(sessionCwd ?? process.cwd(), configuredPath))
-        : resolve(sessionCwd ?? process.cwd(), ".pi", "fitch-mcp-adapter", "traces", `mcp-${timestamp}-${randomSuffix}.jsonl`);
+    let filePath;
+    if (typeof configuredPath === "string" && configuredPath !== "") {
+        filePath = isAbsolute(configuredPath)
+            ? configuredPath
+            : resolve(sessionCwd ?? process.cwd(), configuredPath);
+    }
+    else {
+        filePath = resolve(sessionCwd ?? process.cwd(), ".pi", "fitch-mcp-adapter", "traces", `mcp-${timestamp}-${randomSuffix}.jsonl`);
+    }
     return new McpTraceWriter({
         filePath,
         ...(settings.maxBytes !== undefined ? { maxBytes: settings.maxBytes } : {}),
@@ -184,23 +225,34 @@ export function wrapTransportWithMcpTrace(transport, server, transportKind, obse
             // An observer failure must never alter SDK transport behavior.
         }
     };
-    // Instrument the native instance: the SDK inspects stdio identity and HTTP
-    // hasPerRequestStream to choose negotiation and cancellation behavior.
+    // The SDK requires the native stdio prototype for sibling probing and reads
+    // HTTP hasPerRequestStream for cancellation. Compose callbacks in place.
     const send = transport.send.bind(transport);
+    // oxlint-disable-next-line eslint/no-param-reassign -- QX-001: SDK invokes this member on the instance it holds.
     transport.send = async (message, options) => {
         const started = performance.now();
         const messages = Array.isArray(message) ? message : [message];
         try {
             await send(message, options);
             for (const item of messages) {
-                record(createMcpTraceEvent("outbound", server, transportKind, item, "sent", {
+                record(createMcpTraceEvent({
+                    direction: "outbound",
+                    server,
+                    transport: transportKind,
+                    message: item,
+                    status: "sent",
                     durationMs: performance.now() - started,
                 }));
             }
         }
         catch (error) {
             for (const item of messages) {
-                record(createMcpTraceEvent("outbound", server, transportKind, item, "error", {
+                record(createMcpTraceEvent({
+                    direction: "outbound",
+                    server,
+                    transport: transportKind,
+                    message: item,
+                    status: "error",
                     durationMs: performance.now() - started,
                 }));
             }
@@ -211,23 +263,37 @@ export function wrapTransportWithMcpTrace(transport, server, transportKind, obse
         configurable: true,
         get: () => messageHandler,
         set: (handler) => {
-            messageHandler = handler ? (message, extra) => {
-                record(createMcpTraceEvent("inbound", server, transportKind, message, "received"));
-                handler(message, extra);
-            } : undefined;
+            messageHandler = handler
+                ? (message, extra) => {
+                    record(createMcpTraceEvent({
+                        direction: "inbound",
+                        server,
+                        transport: transportKind,
+                        message,
+                        status: "received",
+                    }));
+                    handler(message, extra);
+                }
+                : undefined;
         },
     });
     return transport;
 }
 export function traceTransportKind(definition, transport) {
-    if (definition.command)
+    if (typeof definition.command === "string" && definition.command !== "") {
         return "stdio";
-    if (definition.socket)
+    }
+    if (typeof definition.socket === "string" && definition.socket !== "") {
         return "unix-socket";
-    const constructorName = transport.constructor?.name.toLowerCase() ?? "";
-    if (constructorName.includes("sse"))
+    }
+    const constructorName = transport.constructor.name.toLowerCase();
+    if (constructorName.includes("sse")) {
         return "sse";
-    if (constructorName.includes("streamable"))
+    }
+    if (constructorName.includes("streamable")) {
         return "streamable-http";
-    return definition.url ? "streamable-http" : "unknown";
+    }
+    return typeof definition.url === "string" && definition.url !== ""
+        ? "streamable-http"
+        : "unknown";
 }

package/dist/metadata-cache.d.ts

@@ -1,11 +1,10 @@
-import type { CachedPrompt, CachedResource, CachedTool, McpConfig, McpTool, McpResource, McpPrompt, MetadataCache, ServerCacheEntry, ServerEntry, ToolMetadata, PromptMetadata } from "./types.ts";
-import { type ToolPrefix } from "./types.ts";
-export type { CachedPrompt, CachedResource, CachedTool, MetadataCache, ServerCacheEntry } from "./types.ts";
+import { type CachedPrompt, type CachedResource, type CachedTool, type McpConfig, type McpTool, type McpResource, type McpPrompt, type MetadataCache, type ServerCacheEntry, type ServerEntry, type ToolMetadata, type PromptMetadata, type ToolPrefix } from "./types.ts";
+export type { CachedPrompt, CachedResource, CachedTool, MetadataCache, ServerCacheEntry, } from "./types.ts";
 export declare function getMetadataCachePath(): string;
 export declare function loadMetadataCache(enabled?: boolean): MetadataCache | null;
 export declare function saveMetadataCache(cache: MetadataCache, enabled?: boolean, selectedServers?: Iterable<string>): void;
 export declare function computeServerHash(definition: ServerEntry): string;
-export declare function isServerCacheValid(entry: ServerCacheEntry, definition: ServerEntry, maxAgeMs?: number): boolean;
+export declare function isServerCacheValid(entry: unknown, definition: ServerEntry, maxAgeMs?: number): boolean;
 export declare function parseDirectToolSelectors(selectors: string[]): {
     servers: Set<string>;
     tools: Map<string, Set<string>>;

package/dist/metadata-cache.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, statSyn
 import { dirname } from "node:path";
 import { getAdapterPath } from "./agent-dir.js";
 import { createHash } from "node:crypto";
-import { formatPromptCommandName, isServerDisabled, resolveToolPrefix } from "./types.js";
+import { formatPromptCommandName, isServerDisabled, resolveToolPrefix, } from "./types.js";
 import { buildToolMetadata } from "./tool-metadata.js";
 import { interpolateEnvRecord, resolveBearerToken, resolveConfigPath, resolveServerUrl, } from "./utils.js";
 // Version 2 stores raw descriptors; version 1 readers cannot enforce raw UI visibility.
@@ -17,8 +17,9 @@ function cacheRevision(path) {
 }
 function freezeMetadata(value) {
     if (value && typeof value === "object" && !Object.isFrozen(value)) {
-        for (const child of Object.values(value))
+        for (const child of Object.values(value)) {
             freezeMetadata(child);
+        }
         Object.freeze(value);
     }
     return value;
@@ -27,20 +28,28 @@ export function getMetadataCachePath() {
     return getAdapterPath("mcp-cache.json");
 }
 export function loadMetadataCache(enabled = true) {
-    if (!enabled)
+    if (!enabled) {
         return null;
+    }
     const cachePath = getMetadataCachePath();
     try {
         const revision = cacheRevision(cachePath);
-        if (snapshot?.path === cachePath && snapshot.revision === revision)
+        if (snapshot?.path === cachePath && snapshot.revision === revision) {
             return snapshot.cache;
+        }
         const raw = JSON.parse(readFileSync(cachePath, "utf-8"));
-        const cache = raw && typeof raw === "object" && !Array.isArray(raw)
-            && (raw.version === 1 || raw.version === CACHE_VERSION)
-            && raw.servers && typeof raw.servers === "object" && !Array.isArray(raw.servers)
-            ? freezeMetadata(raw) : null;
+        const cache = raw &&
+            typeof raw === "object" &&
+            !Array.isArray(raw) &&
+            (raw.version === 1 || raw.version === CACHE_VERSION) &&
+            raw.servers &&
+            typeof raw.servers === "object" &&
+            !Array.isArray(raw.servers)
+            ? freezeMetadata(raw)
+            : null;
         // A concurrent rename must not associate the old bytes with the new file's revision.
-        snapshot = cacheRevision(cachePath) === revision ? { path: cachePath, revision, cache } : undefined;
+        snapshot =
+            cacheRevision(cachePath) === revision ? { path: cachePath, revision, cache } : undefined;
         return cache;
     }
     catch {
@@ -49,16 +58,19 @@ export function loadMetadataCache(enabled = true) {
     }
 }
 export function saveMetadataCache(cache, enabled = true, selectedServers = []) {
-    if (!enabled)
+    if (!enabled) {
         return;
+    }
     const cachePath = getMetadataCachePath();
     const dir = dirname(cachePath);
     mkdirSync(dir, { recursive: true });
-    let merged = { version: CACHE_VERSION, servers: {} };
+    const merged = { version: CACHE_VERSION, servers: {} };
     try {
         if (existsSync(cachePath)) {
             const existing = JSON.parse(readFileSync(cachePath, "utf-8"));
-            if (existing && (existing.version === 1 || existing.version === CACHE_VERSION) && existing.servers) {
+            if (existing &&
+                (existing.version === 1 || existing.version === CACHE_VERSION) &&
+                existing.servers) {
                 merged.servers = { ...existing.servers };
             }
         }
@@ -71,8 +83,9 @@ export function saveMetadataCache(cache, enabled = true, selectedServers = []) {
     const protectedServers = new Set([...selectedServers, ...Object.keys(cache.servers)]);
     const now = Date.now();
     for (const [name, entry] of Object.entries(merged.servers)) {
-        if (!protectedServers.has(name) && isCacheEntry(entry)
-            && (entry.cachedAt > now || now - entry.cachedAt > CACHE_MAX_AGE_MS)) {
+        if (!protectedServers.has(name) &&
+            isCacheEntry(entry) &&
+            (entry.cachedAt > now || now - entry.cachedAt > CACHE_MAX_AGE_MS)) {
             delete merged.servers[name];
         }
     }
@@ -110,23 +123,30 @@ export function isServerCacheValid(entry, definition, maxAgeMs = CACHE_MAX_AGE_M
     catch {
         return false;
     }
-    if (!isCacheEntry(entry) || entry.configHash !== configHash)
+    if (!isCacheEntry(entry) || entry.configHash !== configHash) {
         return false;
-    if (entry.cachedAt > Date.now())
+    }
+    if (entry.cachedAt > Date.now()) {
         return false;
-    if (maxAgeMs > 0 && Date.now() - entry.cachedAt > maxAgeMs)
+    }
+    if (maxAgeMs > 0 && Date.now() - entry.cachedAt > maxAgeMs) {
         return false;
+    }
     return true;
 }
 function isCacheEntry(entry) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
         return false;
+    }
     const value = entry;
-    return typeof value.configHash === "string"
-        && typeof value.cachedAt === "number" && Number.isFinite(value.cachedAt) && value.cachedAt > 0
-        && Array.isArray(value.tools) && Array.isArray(value.resources)
-        && (value.prompts === undefined || Array.isArray(value.prompts))
-        && (value.instructions === undefined || typeof value.instructions === "string");
+    return (typeof value.configHash === "string" &&
+        typeof value.cachedAt === "number" &&
+        Number.isFinite(value.cachedAt) &&
+        value.cachedAt > 0 &&
+        Array.isArray(value.tools) &&
+        Array.isArray(value.resources) &&
+        (value.prompts === undefined || Array.isArray(value.prompts)) &&
+        (value.instructions === undefined || typeof value.instructions === "string"));
 }
 export function parseDirectToolSelectors(selectors) {
     const servers = new Set();
@@ -155,15 +175,17 @@ export function getMissingConfiguredDirectToolServers(config, cache, envOverride
     const globalDirect = config.settings?.directTools;
     const envSelection = envOverride ? parseDirectToolSelectors(envOverride) : null;
     for (const [serverName, definition] of Object.entries(config.mcpServers)) {
-        if (isServerDisabled(definition))
+        if (isServerDisabled(definition)) {
             continue;
+        }
         const hasDirectTools = envSelection
             ? envSelection.servers.has(serverName) || envSelection.tools.has(serverName)
             : definition.directTools !== undefined
-                ? !!definition.directTools
-                : !!globalDirect;
-        if (!hasDirectTools)
+                ? Boolean(definition.directTools)
+                : Boolean(globalDirect);
+        if (!hasDirectTools) {
             continue;
+        }
         const serverCache = cache?.servers?.[serverName];
         if (!serverCache || !isServerCacheValid(serverCache, definition)) {
             missing.push(serverName);
@@ -172,19 +194,29 @@ export function getMissingConfiguredDirectToolServers(config, cache, envOverride
     return missing;
 }
 export function reconstructToolMetadata(serverName, entry, prefix, definition) {
-    const key = JSON.stringify([serverName, prefix, definition.exposeResources, definition.includeTools,
-        definition.excludeTools, definition.toolPrefix, definition.disabled]);
+    const key = JSON.stringify([
+        serverName,
+        prefix,
+        definition.exposeResources,
+        definition.includeTools,
+        definition.excludeTools,
+        definition.toolPrefix,
+        definition.disabled,
+    ]);
     const previous = toolProjections.get(entry);
-    if (Object.isFrozen(entry) && previous?.key === key)
+    if (Object.isFrozen(entry) && previous?.key === key) {
         return previous.metadata;
-    const metadata = buildToolMetadata((entry.tools ?? []).filter(tool => tool?.name).map(restoreCachedTool), entry.resources ?? [], definition, serverName, prefix).metadata;
-    if (Object.isFrozen(entry))
+    }
+    const metadata = buildToolMetadata((entry.tools ?? []).filter((tool) => tool?.name).map(restoreCachedTool), entry.resources ?? [], definition, serverName, prefix).metadata;
+    if (Object.isFrozen(entry)) {
         toolProjections.set(entry, { key, metadata: freezeMetadata(metadata) });
+    }
     return metadata;
 }
 function restoreCachedTool(tool) {
     const { uiResourceUri, uiVisibility, uiStreamMode, ...descriptor } = tool;
-    if (descriptor._meta !== undefined || (uiResourceUri === undefined && uiVisibility === undefined && uiStreamMode === undefined)) {
+    if (descriptor._meta !== undefined ||
+        (uiResourceUri === undefined && uiVisibility === undefined && uiStreamMode === undefined)) {
         return descriptor;
     }
     return {
@@ -199,23 +231,27 @@ function restoreCachedTool(tool) {
     };
 }
 export function serializeTools(tools) {
-    return tools.filter(tool => tool?.name);
+    return tools.filter((tool) => tool?.name);
 }
 export function serializeResources(resources) {
-    return resources.filter(resource => resource?.name && resource?.uri);
+    return resources.filter((resource) => resource?.name && resource?.uri);
 }
 export function serializePrompts(prompts) {
     return (prompts ?? [])
-        .filter(prompt => prompt?.name)
-        .map(prompt => ({
+        .filter((prompt) => prompt?.name)
+        .map((prompt) => ({
         name: prompt.name,
         ...(prompt.title !== undefined ? { title: prompt.title } : {}),
         ...(prompt.description !== undefined ? { description: prompt.description } : {}),
         ...(Array.isArray(prompt.arguments)
             ? {
-                arguments: prompt.arguments.filter(argument => argument?.name).map(argument => ({
+                arguments: prompt.arguments
+                    .filter((argument) => argument?.name)
+                    .map((argument) => ({
                     name: argument.name,
-                    ...(argument.description !== undefined ? { description: argument.description } : {}),
+                    ...(argument.description !== undefined
+                        ? { description: argument.description }
+                        : {}),
                     ...(argument.required !== undefined ? { required: argument.required } : {}),
                 })),
             }
@@ -224,9 +260,13 @@ export function serializePrompts(prompts) {
 }
 export function reconstructPromptMetadata(serverName, prompts, prefix, definition) {
     const effectivePrefix = resolveToolPrefix(definition, prefix);
-    return (prompts ?? []).filter(prompt => prompt?.name).map(prompt => {
+    return (prompts ?? [])
+        .filter((prompt) => prompt?.name)
+        .map((prompt) => {
         const args = Array.isArray(prompt.arguments)
-            ? prompt.arguments.filter(argument => argument?.name).map(argument => ({
+            ? prompt.arguments
+                .filter((argument) => argument?.name)
+                .map((argument) => ({
                 name: argument.name,
                 ...(argument.description !== undefined ? { description: argument.description } : {}),
                 ...(argument.required !== undefined ? { required: argument.required } : {}),
@@ -248,9 +288,9 @@ function stableStringify(value) {
         return serialized === undefined ? "undefined" : serialized;
     }
     if (Array.isArray(value)) {
-        return `[${value.map(v => stableStringify(v)).join(",")}]`;
+        return `[${value.map((v) => stableStringify(v)).join(",")}]`;
     }
     const obj = value;
     const keys = Object.keys(obj).sort();
-    return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
 }