mcpspan 0.2.0 → 0.4.0

package/README.md

@@ -209,8 +209,10 @@ mode, not in debug.
 
 What is collected: the tool name, how long it took, whether it succeeded, the
 error type and a truncated message when it did not, how large the answer was
-in bytes (its size only, never its content), which client called, and the SDK
-version. For a resource or a prompt, the same, under the name it was
+in bytes (its size only, never its content), whether it repeated the previous
+call's arguments to the same tool in its session (compared in your process;
+the arguments, or any digest of them, never leave it), which client called,
+and the SDK version. For a resource or a prompt, the same, under the name it was
 registered with: never the address a client read, only its template or, for
 an address the server does not have, its scheme.
 

package/dist/index.cjs

@@ -146,7 +146,7 @@ var EventQueue = class {
 * Single source of truth: `package.json` follows this constant, not the other
 * way round, and a unit test fails if the two ever drift apart.
 */
-const SDK_VERSION = "0.2.0";
+const SDK_VERSION = "0.4.0";
 //#endregion
 //#region src/transport.ts
 /** Path the ingest API accepts batches on, appended to the configured endpoint. */
@@ -498,6 +498,88 @@ function currentCall() {
 	return current;
 }
 //#endregion
+//#region src/definition.ts
+/**
+* Tool definitions as the server lists them, fingerprinted (contract, 3.8).
+*
+* Rewording a description can change how agents use a tool more than a change
+* to its code. The fingerprint is taken from the answer to `tools/list`, what
+* an agent actually read, and sent with every call to the tool, so the
+* dashboard can mark when a definition changed. Kept for the process: one
+* process reports to one server, and a listing on one connection describes
+* the same tools as on any other.
+*/
+const listed = /* @__PURE__ */ new Map();
+/** The latest fingerprint listed for a tool, if any listing in this process named it. */
+function definitionOf(toolName) {
+	return listed.get(toolName);
+}
+/** Notes every tool in an answer to `tools/list`. Never throws. */
+function noteListing(result) {
+	try {
+		const tools = result?.tools;
+		if (!Array.isArray(tools)) return;
+		for (const tool of tools) {
+			const name = tool?.name;
+			if (typeof name !== "string") continue;
+			const hash = definitionHash(tool);
+			if (hash !== void 0) listed.set(name, hash);
+		}
+	} catch {}
+}
+/**
+* The first 16 hex characters of the SHA-256 of the tool's name, title,
+* description and input schema, as canonical JSON. Undefined for a definition
+* that cannot be written so, which is then sent without one.
+*/
+function definitionHash(tool) {
+	const hashed = {};
+	for (const field of [
+		"name",
+		"title",
+		"description",
+		"inputSchema"
+	]) if (tool[field] !== void 0) hashed[field] = tool[field];
+	try {
+		return (0, node_crypto.createHash)("sha256").update(canonical(hashed), "utf8").digest("hex").slice(0, 16);
+	} catch {
+		return;
+	}
+}
+/** Sorted keys, no whitespace, minimal escaping: the same text in every SDK. Throws on what JSON cannot hold. */
+function canonical(value) {
+	if (value === null) return "null";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new TypeError("not a JSON number");
+		return String(value);
+	}
+	if (typeof value === "string") return text(value);
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (typeof value === "object") {
+		const object = value;
+		return `{${Object.keys(object).filter((key) => object[key] !== void 0).sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map((key) => `${text(key)}:${canonical(object[key])}`).join(",")}}`;
+	}
+	throw new TypeError(`cannot fingerprint ${typeof value}`);
+}
+const ESCAPES = {
+	"\"": "\\\"",
+	"\\": "\\\\",
+	"\b": "\\b",
+	"\f": "\\f",
+	"\n": "\\n",
+	"\r": "\\r",
+	"	": "\\t"
+};
+function text(value) {
+	let out = "\"";
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		out += ESCAPES[character] ?? (code < 32 ? `\\u${code.toString(16).padStart(4, "0")}` : character);
+	}
+	return `${out}"`;
+}
+//#endregion
 //#region src/client.ts
 /**
 * Names we recognise, matched as substrings of what a client reports.
@@ -773,6 +855,8 @@ function track(toolName, handler) {
 					timestamp,
 					sdkVersion: SDK_VERSION,
 					...session !== void 0 && { sessionId: session },
+					...definition(toolName),
+					...call?.repeated === true && { repeated: true },
 					...outcome
 				});
 			} catch {}
@@ -880,7 +964,9 @@ function recordRefusedCall(refused) {
 			...parameters !== void 0 && { parameters },
 			timestamp: refused.timestamp,
 			sdkVersion: SDK_VERSION,
-			...refused.sessionId !== void 0 && { sessionId: refused.sessionId }
+			...refused.sessionId !== void 0 && { sessionId: refused.sessionId },
+			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName),
+			...refused.repeated === true && { repeated: true }
 		});
 	} catch {}
 }
@@ -918,6 +1004,11 @@ function recordPrimitiveCall(call) {
 function isRecording() {
 	return sink !== void 0;
 }
+/** The fingerprint of a tool as last listed (contract, 3.8), as event fields. */
+function definition(toolName) {
+	const hash = definitionOf(toolName);
+	return hash === void 0 ? {} : { definitionHash: hash };
+}
 /** The largest size an event carries; anything larger is sent as this (contract, 3.7). */
 const MAX_RESPONSE_BYTES = 2147483647;
 /**
@@ -1280,6 +1371,40 @@ function watchPrimitive(handler, server) {
 	};
 }
 //#endregion
+//#region src/repeats.ts
+/**
+* Whether a call repeats the previous call to the same tool in the same
+* session (contract, 3.9): an agent stuck in a loop.
+*
+* Only the answer leaves the process. Kept here is a SHA-256 of the canonical
+* arguments of the latest call per session and tool, never sent: a digest of
+* a short identifier or an enumerated value is found by trying every one.
+*/
+/** Session and tool pairs kept, the oldest forgotten first. */
+const MAX_KEPT = 1e4;
+const latest = /* @__PURE__ */ new Map();
+/**
+* Notes a call's arguments, as the client sent them, and says whether they are
+* the previous call's to the same tool in the same session. Never throws: an
+* argument object that cannot be written down is never a repeat.
+*/
+function noteArguments(sessionId, toolName, args) {
+	try {
+		const digest = (0, node_crypto.createHash)("sha256").update(canonical(args ?? {}), "utf8").digest("hex");
+		const key = `${sessionId}\u0000${toolName}`;
+		const previous = latest.get(key);
+		latest.delete(key);
+		latest.set(key, digest);
+		if (latest.size > MAX_KEPT) {
+			const oldest = latest.keys().next().value;
+			if (oldest !== void 0) latest.delete(oldest);
+		}
+		return previous === digest;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/instrument.ts
 /**
 * Methods an MCP server registers tools through.
@@ -1308,6 +1433,28 @@ const registries = /* @__PURE__ */ new WeakMap();
 * it on its own. A weak set, so contexts leave with their requests.
 */
 const reachedHandler = /* @__PURE__ */ new WeakSet();
+/** Requests whose arguments repeat the previous call's to the same tool in the session (contract, 3.9). */
+const repeatedCalls = /* @__PURE__ */ new WeakSet();
+/**
+* Compares a call's arguments, as the client sent them, with the previous call's to the same tool in the same
+* session, as it arrives, before any validation; and marks the request so the handler side knows too. A call
+* without a session is never compared.
+*/
+function noteRepeat(server, request, context) {
+	try {
+		const name = request.params?.name;
+		if (typeof name !== "string" || typeof context !== "object" || context === null) return false;
+		const params = request.params;
+		if (params["inputResponses"] !== void 0 || params["requestState"] !== void 0) return false;
+		const sessionId = sessionFor(server, context);
+		if (sessionId === void 0) return false;
+		const repeated = noteArguments(sessionId, name, request.params?.arguments);
+		if (repeated) repeatedCalls.add(context);
+		return repeated;
+	} catch {
+		return false;
+	}
+}
 /**
 * Request contexts whose handler last answered with an interim
 * `input_required` result (the 2026-07-28 protocol's way to ask the client for
@@ -1457,10 +1604,12 @@ function noteReached(handler, server) {
 		const sessionId = hasContext ? sessionFor(server, context) : void 0;
 		const client = clientFor(server, hasContext ? context : void 0);
 		const serverVersion = serverVersionOf(server);
+		const repeated = hasContext && repeatedCalls.has(context);
 		const result = withCall({
 			...sessionId !== void 0 && { sessionId },
 			...client !== void 0 && { client },
-			...serverVersion !== void 0 && { serverVersion }
+			...serverVersion !== void 0 && { serverVersion },
+			...repeated && { repeated }
 		}, run);
 		if (hasContext) noteInterim(context, result);
 		return result;
@@ -1495,7 +1644,11 @@ function interceptToolCalls(server, registry) {
 	if (intercepted.has(inner)) return;
 	intercepted.add(inner);
 	const handlers = inner._requestHandlers;
-	if (handlers instanceof Map) for (const method of ["tools/call", ...PRIMITIVE_METHODS]) {
+	if (handlers instanceof Map) for (const method of [
+		"tools/call",
+		"tools/list",
+		...PRIMITIVE_METHODS
+	]) {
 		const installed = handlers.get(method);
 		if (typeof installed === "function") handlers.set(method, watch(installed, server, registry));
 	}
@@ -1513,7 +1666,15 @@ function interceptToolCalls(server, registry) {
 * so the handler for any other method runs exactly as it did.
 */
 function watch(handler, server, registry) {
-	return watchPrimitive(watchToolCalls(handler, server, registry), server);
+	return watchListing(watchPrimitive(watchToolCalls(handler, server, registry), server));
+}
+/** Notes the tools a `tools/list` answer describes, for the fingerprint each call carries (contract, 3.8). */
+function watchListing(handler) {
+	return async function watchedListing(request, ...rest) {
+		const result = await handler.call(this, request, ...rest);
+		if (request?.method === "tools/list" && isRecording()) noteListing(result);
+		return result;
+	};
 }
 function watchToolCalls(handler, server, registry) {
 	return async function watchedRequestHandler(request, context) {
@@ -1521,6 +1682,7 @@ function watchToolCalls(handler, server, registry) {
 		if (!isRecording() || request?.method !== "tools/call") return call();
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 		const startedAt = performance.now();
+		const repeated = noteRepeat(server, request, context);
 		const noteRefusal = (message) => {
 			try {
 				const reached = typeof context === "object" && context !== null && reachedHandler.has(context);
@@ -1536,7 +1698,8 @@ function watchToolCalls(handler, server, registry) {
 						durationMs: performance.now() - startedAt,
 						sessionId: sessionFor(server, context),
 						client: clientFor(server, context),
-						serverVersion: serverVersionOf(server)
+						serverVersion: serverVersionOf(server),
+						repeated
 					});
 					return;
 				}
@@ -1550,7 +1713,8 @@ function watchToolCalls(handler, server, registry) {
 					durationMs: performance.now() - startedAt,
 					sessionId: sessionFor(server, context),
 					client: clientFor(server, context),
-					serverVersion: serverVersionOf(server)
+					serverVersion: serverVersionOf(server),
+					repeated
 				});
 			} catch {}
 		};

package/dist/index.d.cts

@@ -199,6 +199,10 @@ interface ToolCallEvent {
    * call returned one; the content is counted, never kept.
    */
   responseBytes?: number;
+  /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
+  definitionHash?: string;
+  /** The arguments are the previous call's to the same tool in this session (contract, 3.9). */
+  repeated?: boolean;
   /** When the call started, as an ISO 8601 timestamp. */
   timestamp: string;
   /** Version of the mcpspan package that produced the event. */

package/dist/index.d.mts

@@ -199,6 +199,10 @@ interface ToolCallEvent {
    * call returned one; the content is counted, never kept.
    */
   responseBytes?: number;
+  /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
+  definitionHash?: string;
+  /** The arguments are the previous call's to the same tool in this session (contract, 3.9). */
+  repeated?: boolean;
   /** When the call started, as an ISO 8601 timestamp. */
   timestamp: string;
   /** Version of the mcpspan package that produced the event. */

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 /** Renders any thrown value as one readable line, for diagnostics. */
 function formatError(error) {
 	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
@@ -145,7 +145,7 @@ var EventQueue = class {
 * Single source of truth: `package.json` follows this constant, not the other
 * way round, and a unit test fails if the two ever drift apart.
 */
-const SDK_VERSION = "0.2.0";
+const SDK_VERSION = "0.4.0";
 //#endregion
 //#region src/transport.ts
 /** Path the ingest API accepts batches on, appended to the configured endpoint. */
@@ -497,6 +497,88 @@ function currentCall() {
 	return current;
 }
 //#endregion
+//#region src/definition.ts
+/**
+* Tool definitions as the server lists them, fingerprinted (contract, 3.8).
+*
+* Rewording a description can change how agents use a tool more than a change
+* to its code. The fingerprint is taken from the answer to `tools/list`, what
+* an agent actually read, and sent with every call to the tool, so the
+* dashboard can mark when a definition changed. Kept for the process: one
+* process reports to one server, and a listing on one connection describes
+* the same tools as on any other.
+*/
+const listed = /* @__PURE__ */ new Map();
+/** The latest fingerprint listed for a tool, if any listing in this process named it. */
+function definitionOf(toolName) {
+	return listed.get(toolName);
+}
+/** Notes every tool in an answer to `tools/list`. Never throws. */
+function noteListing(result) {
+	try {
+		const tools = result?.tools;
+		if (!Array.isArray(tools)) return;
+		for (const tool of tools) {
+			const name = tool?.name;
+			if (typeof name !== "string") continue;
+			const hash = definitionHash(tool);
+			if (hash !== void 0) listed.set(name, hash);
+		}
+	} catch {}
+}
+/**
+* The first 16 hex characters of the SHA-256 of the tool's name, title,
+* description and input schema, as canonical JSON. Undefined for a definition
+* that cannot be written so, which is then sent without one.
+*/
+function definitionHash(tool) {
+	const hashed = {};
+	for (const field of [
+		"name",
+		"title",
+		"description",
+		"inputSchema"
+	]) if (tool[field] !== void 0) hashed[field] = tool[field];
+	try {
+		return createHash("sha256").update(canonical(hashed), "utf8").digest("hex").slice(0, 16);
+	} catch {
+		return;
+	}
+}
+/** Sorted keys, no whitespace, minimal escaping: the same text in every SDK. Throws on what JSON cannot hold. */
+function canonical(value) {
+	if (value === null) return "null";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new TypeError("not a JSON number");
+		return String(value);
+	}
+	if (typeof value === "string") return text(value);
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (typeof value === "object") {
+		const object = value;
+		return `{${Object.keys(object).filter((key) => object[key] !== void 0).sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map((key) => `${text(key)}:${canonical(object[key])}`).join(",")}}`;
+	}
+	throw new TypeError(`cannot fingerprint ${typeof value}`);
+}
+const ESCAPES = {
+	"\"": "\\\"",
+	"\\": "\\\\",
+	"\b": "\\b",
+	"\f": "\\f",
+	"\n": "\\n",
+	"\r": "\\r",
+	"	": "\\t"
+};
+function text(value) {
+	let out = "\"";
+	for (const character of value) {
+		const code = character.codePointAt(0) ?? 0;
+		out += ESCAPES[character] ?? (code < 32 ? `\\u${code.toString(16).padStart(4, "0")}` : character);
+	}
+	return `${out}"`;
+}
+//#endregion
 //#region src/client.ts
 /**
 * Names we recognise, matched as substrings of what a client reports.
@@ -772,6 +854,8 @@ function track(toolName, handler) {
 					timestamp,
 					sdkVersion: SDK_VERSION,
 					...session !== void 0 && { sessionId: session },
+					...definition(toolName),
+					...call?.repeated === true && { repeated: true },
 					...outcome
 				});
 			} catch {}
@@ -879,7 +963,9 @@ function recordRefusedCall(refused) {
 			...parameters !== void 0 && { parameters },
 			timestamp: refused.timestamp,
 			sdkVersion: SDK_VERSION,
-			...refused.sessionId !== void 0 && { sessionId: refused.sessionId }
+			...refused.sessionId !== void 0 && { sessionId: refused.sessionId },
+			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName),
+			...refused.repeated === true && { repeated: true }
 		});
 	} catch {}
 }
@@ -917,6 +1003,11 @@ function recordPrimitiveCall(call) {
 function isRecording() {
 	return sink !== void 0;
 }
+/** The fingerprint of a tool as last listed (contract, 3.8), as event fields. */
+function definition(toolName) {
+	const hash = definitionOf(toolName);
+	return hash === void 0 ? {} : { definitionHash: hash };
+}
 /** The largest size an event carries; anything larger is sent as this (contract, 3.7). */
 const MAX_RESPONSE_BYTES = 2147483647;
 /**
@@ -1279,6 +1370,40 @@ function watchPrimitive(handler, server) {
 	};
 }
 //#endregion
+//#region src/repeats.ts
+/**
+* Whether a call repeats the previous call to the same tool in the same
+* session (contract, 3.9): an agent stuck in a loop.
+*
+* Only the answer leaves the process. Kept here is a SHA-256 of the canonical
+* arguments of the latest call per session and tool, never sent: a digest of
+* a short identifier or an enumerated value is found by trying every one.
+*/
+/** Session and tool pairs kept, the oldest forgotten first. */
+const MAX_KEPT = 1e4;
+const latest = /* @__PURE__ */ new Map();
+/**
+* Notes a call's arguments, as the client sent them, and says whether they are
+* the previous call's to the same tool in the same session. Never throws: an
+* argument object that cannot be written down is never a repeat.
+*/
+function noteArguments(sessionId, toolName, args) {
+	try {
+		const digest = createHash("sha256").update(canonical(args ?? {}), "utf8").digest("hex");
+		const key = `${sessionId}\u0000${toolName}`;
+		const previous = latest.get(key);
+		latest.delete(key);
+		latest.set(key, digest);
+		if (latest.size > MAX_KEPT) {
+			const oldest = latest.keys().next().value;
+			if (oldest !== void 0) latest.delete(oldest);
+		}
+		return previous === digest;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/instrument.ts
 /**
 * Methods an MCP server registers tools through.
@@ -1307,6 +1432,28 @@ const registries = /* @__PURE__ */ new WeakMap();
 * it on its own. A weak set, so contexts leave with their requests.
 */
 const reachedHandler = /* @__PURE__ */ new WeakSet();
+/** Requests whose arguments repeat the previous call's to the same tool in the session (contract, 3.9). */
+const repeatedCalls = /* @__PURE__ */ new WeakSet();
+/**
+* Compares a call's arguments, as the client sent them, with the previous call's to the same tool in the same
+* session, as it arrives, before any validation; and marks the request so the handler side knows too. A call
+* without a session is never compared.
+*/
+function noteRepeat(server, request, context) {
+	try {
+		const name = request.params?.name;
+		if (typeof name !== "string" || typeof context !== "object" || context === null) return false;
+		const params = request.params;
+		if (params["inputResponses"] !== void 0 || params["requestState"] !== void 0) return false;
+		const sessionId = sessionFor(server, context);
+		if (sessionId === void 0) return false;
+		const repeated = noteArguments(sessionId, name, request.params?.arguments);
+		if (repeated) repeatedCalls.add(context);
+		return repeated;
+	} catch {
+		return false;
+	}
+}
 /**
 * Request contexts whose handler last answered with an interim
 * `input_required` result (the 2026-07-28 protocol's way to ask the client for
@@ -1456,10 +1603,12 @@ function noteReached(handler, server) {
 		const sessionId = hasContext ? sessionFor(server, context) : void 0;
 		const client = clientFor(server, hasContext ? context : void 0);
 		const serverVersion = serverVersionOf(server);
+		const repeated = hasContext && repeatedCalls.has(context);
 		const result = withCall({
 			...sessionId !== void 0 && { sessionId },
 			...client !== void 0 && { client },
-			...serverVersion !== void 0 && { serverVersion }
+			...serverVersion !== void 0 && { serverVersion },
+			...repeated && { repeated }
 		}, run);
 		if (hasContext) noteInterim(context, result);
 		return result;
@@ -1494,7 +1643,11 @@ function interceptToolCalls(server, registry) {
 	if (intercepted.has(inner)) return;
 	intercepted.add(inner);
 	const handlers = inner._requestHandlers;
-	if (handlers instanceof Map) for (const method of ["tools/call", ...PRIMITIVE_METHODS]) {
+	if (handlers instanceof Map) for (const method of [
+		"tools/call",
+		"tools/list",
+		...PRIMITIVE_METHODS
+	]) {
 		const installed = handlers.get(method);
 		if (typeof installed === "function") handlers.set(method, watch(installed, server, registry));
 	}
@@ -1512,7 +1665,15 @@ function interceptToolCalls(server, registry) {
 * so the handler for any other method runs exactly as it did.
 */
 function watch(handler, server, registry) {
-	return watchPrimitive(watchToolCalls(handler, server, registry), server);
+	return watchListing(watchPrimitive(watchToolCalls(handler, server, registry), server));
+}
+/** Notes the tools a `tools/list` answer describes, for the fingerprint each call carries (contract, 3.8). */
+function watchListing(handler) {
+	return async function watchedListing(request, ...rest) {
+		const result = await handler.call(this, request, ...rest);
+		if (request?.method === "tools/list" && isRecording()) noteListing(result);
+		return result;
+	};
 }
 function watchToolCalls(handler, server, registry) {
 	return async function watchedRequestHandler(request, context) {
@@ -1520,6 +1681,7 @@ function watchToolCalls(handler, server, registry) {
 		if (!isRecording() || request?.method !== "tools/call") return call();
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 		const startedAt = performance.now();
+		const repeated = noteRepeat(server, request, context);
 		const noteRefusal = (message) => {
 			try {
 				const reached = typeof context === "object" && context !== null && reachedHandler.has(context);
@@ -1535,7 +1697,8 @@ function watchToolCalls(handler, server, registry) {
 						durationMs: performance.now() - startedAt,
 						sessionId: sessionFor(server, context),
 						client: clientFor(server, context),
-						serverVersion: serverVersionOf(server)
+						serverVersion: serverVersionOf(server),
+						repeated
 					});
 					return;
 				}
@@ -1549,7 +1712,8 @@ function watchToolCalls(handler, server, registry) {
 					durationMs: performance.now() - startedAt,
 					sessionId: sessionFor(server, context),
 					client: clientFor(server, context),
-					serverVersion: serverVersionOf(server)
+					serverVersion: serverVersionOf(server),
+					repeated
 				});
 			} catch {}
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpspan",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Self-hosted analytics for MCP servers: which tools, resources and prompts get used, by which client, how fast, and why they fail.",
   "keywords": [
     "mcp",