mcpspan 0.2.0 → 0.3.0

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.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 {}
@@ -880,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 {}
 }
@@ -918,6 +1002,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;
 /**
@@ -1495,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));
 	}
@@ -1513,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

@@ -199,6 +199,8 @@ 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;
   /** 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,8 @@ 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;
   /** 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.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 {}
@@ -879,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 {}
 }
@@ -917,6 +1001,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;
 /**
@@ -1494,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));
 	}
@@ -1512,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.2.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",