mcpspan 0.1.0 → 0.3.0

package/README.md

@@ -208,8 +208,9 @@ out of this as well.
 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, which client called, and
-the SDK version. For a resource or a prompt, the same, under the name it was
+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
 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.1.0";
+const SDK_VERSION = "0.3.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. */
+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,7 @@ function track(toolName, handler) {
 					timestamp,
 					sdkVersion: SDK_VERSION,
 					...session !== void 0 && { sessionId: session },
+					...definition(toolName),
 					...outcome
 				});
 			} catch {}
@@ -782,15 +865,21 @@ function track(toolName, handler) {
 				recorded = true;
 				return;
 			}
+			const size = responseBytes(value);
+			const measured = size === void 0 ? {} : { responseBytes: size };
 			if (!isErrorResult(value)) {
-				emit({ success: true });
+				emit({
+					success: true,
+					...measured
+				});
 				return;
 			}
 			const errorMessage = describeErrorResult(value);
 			emit({
 				success: false,
 				errorSource: "result",
-				...errorMessage !== void 0 && { errorMessage }
+				...errorMessage !== void 0 && { errorMessage },
+				...measured
 			});
 		};
 		const fail = (error) => {
@@ -874,7 +963,8 @@ 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)
 		});
 	} catch {}
 }
@@ -903,7 +993,8 @@ function recordPrimitiveCall(call) {
 			...parameters !== void 0 && { parameters },
 			timestamp: call.timestamp,
 			sdkVersion: SDK_VERSION,
-			...call.sessionId !== void 0 && { sessionId: call.sessionId }
+			...call.sessionId !== void 0 && { sessionId: call.sessionId },
+			...call.responseBytes !== void 0 && { responseBytes: call.responseBytes }
 		});
 	} catch {}
 }
@@ -911,6 +1002,26 @@ 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;
+/**
+* Size of an answer, in bytes of its compact JSON (contract, 3.7), or undefined
+* when it cannot be encoded. The JSON is counted and dropped: nothing of it is
+* kept or sent.
+*/
+function responseBytes(value) {
+	try {
+		const json = JSON.stringify(value);
+		return json === void 0 ? void 0 : Math.min(Buffer.byteLength(json, "utf8"), MAX_RESPONSE_BYTES);
+	} catch {
+		return;
+	}
+}
 /** A result the 2026-07-28 protocol calls interim: the tool needs more input first. */
 function isInputRequired(value) {
 	return typeof value === "object" && value !== null && value.resultType === "input_required";
@@ -1226,7 +1337,8 @@ function watchPrimitive(handler, server) {
 					durationMs: performance.now() - startedAt,
 					sessionId: typeof context === "object" && context !== null ? sessionFor(server, context) : void 0,
 					client: clientFor(server, typeof context === "object" && context !== null ? context : void 0),
-					serverVersion: serverVersionOf(server)
+					serverVersion: serverVersionOf(server),
+					responseBytes: outcome.responseBytes
 				});
 			} catch {}
 		};
@@ -1249,7 +1361,10 @@ function watchPrimitive(handler, server) {
 			});
 			throw error;
 		}
-		if (!(typeof result === "object" && result !== null && result.resultType === "input_required")) record({ success: true });
+		if (!(typeof result === "object" && result !== null && result.resultType === "input_required")) record({
+			success: true,
+			responseBytes: responseBytes(result)
+		});
 		return result;
 	};
 }
@@ -1469,7 +1584,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));
 	}
@@ -1487,7 +1606,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) {

package/dist/index.d.cts

@@ -194,6 +194,13 @@ interface ToolCallEvent {
    * the version the MCP server gives itself.
    */
   serverVersion?: string;
+  /**
+   * Size of the answer, in bytes of compact JSON (contract, 3.7). Only when the
+   * call returned one; the content is counted, never kept.
+   */
+  responseBytes?: number;
+  /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
+  definitionHash?: string;
   /** 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

@@ -194,6 +194,13 @@ interface ToolCallEvent {
    * the version the MCP server gives itself.
    */
   serverVersion?: string;
+  /**
+   * Size of the answer, in bytes of compact JSON (contract, 3.7). Only when the
+   * call returned one; the content is counted, never kept.
+   */
+  responseBytes?: number;
+  /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
+  definitionHash?: string;
   /** 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.1.0";
+const SDK_VERSION = "0.3.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. */
+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,7 @@ function track(toolName, handler) {
 					timestamp,
 					sdkVersion: SDK_VERSION,
 					...session !== void 0 && { sessionId: session },
+					...definition(toolName),
 					...outcome
 				});
 			} catch {}
@@ -781,15 +864,21 @@ function track(toolName, handler) {
 				recorded = true;
 				return;
 			}
+			const size = responseBytes(value);
+			const measured = size === void 0 ? {} : { responseBytes: size };
 			if (!isErrorResult(value)) {
-				emit({ success: true });
+				emit({
+					success: true,
+					...measured
+				});
 				return;
 			}
 			const errorMessage = describeErrorResult(value);
 			emit({
 				success: false,
 				errorSource: "result",
-				...errorMessage !== void 0 && { errorMessage }
+				...errorMessage !== void 0 && { errorMessage },
+				...measured
 			});
 		};
 		const fail = (error) => {
@@ -873,7 +962,8 @@ 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)
 		});
 	} catch {}
 }
@@ -902,7 +992,8 @@ function recordPrimitiveCall(call) {
 			...parameters !== void 0 && { parameters },
 			timestamp: call.timestamp,
 			sdkVersion: SDK_VERSION,
-			...call.sessionId !== void 0 && { sessionId: call.sessionId }
+			...call.sessionId !== void 0 && { sessionId: call.sessionId },
+			...call.responseBytes !== void 0 && { responseBytes: call.responseBytes }
 		});
 	} catch {}
 }
@@ -910,6 +1001,26 @@ 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;
+/**
+* Size of an answer, in bytes of its compact JSON (contract, 3.7), or undefined
+* when it cannot be encoded. The JSON is counted and dropped: nothing of it is
+* kept or sent.
+*/
+function responseBytes(value) {
+	try {
+		const json = JSON.stringify(value);
+		return json === void 0 ? void 0 : Math.min(Buffer.byteLength(json, "utf8"), MAX_RESPONSE_BYTES);
+	} catch {
+		return;
+	}
+}
 /** A result the 2026-07-28 protocol calls interim: the tool needs more input first. */
 function isInputRequired(value) {
 	return typeof value === "object" && value !== null && value.resultType === "input_required";
@@ -1225,7 +1336,8 @@ function watchPrimitive(handler, server) {
 					durationMs: performance.now() - startedAt,
 					sessionId: typeof context === "object" && context !== null ? sessionFor(server, context) : void 0,
 					client: clientFor(server, typeof context === "object" && context !== null ? context : void 0),
-					serverVersion: serverVersionOf(server)
+					serverVersion: serverVersionOf(server),
+					responseBytes: outcome.responseBytes
 				});
 			} catch {}
 		};
@@ -1248,7 +1360,10 @@ function watchPrimitive(handler, server) {
 			});
 			throw error;
 		}
-		if (!(typeof result === "object" && result !== null && result.resultType === "input_required")) record({ success: true });
+		if (!(typeof result === "object" && result !== null && result.resultType === "input_required")) record({
+			success: true,
+			responseBytes: responseBytes(result)
+		});
 		return result;
 	};
 }
@@ -1468,7 +1583,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));
 	}
@@ -1486,7 +1605,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpspan",
-  "version": "0.1.0",
+  "version": "0.3.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",