mcpspan 0.4.0 → 0.5.0

package/README.md

@@ -202,6 +202,14 @@ names and types of the arguments instead, which is what shows the agent wrote
 `dest` where the schema says `destination`. Tools passed through `exclude` stay
 out of this as well.
 
+For a refusal of arguments, the SDK also says which ones. It checks what the
+agent sent against the input schema your server listed, in your process, and
+records the top-level arguments that did not match, by the names the schema
+declares, so the tool's page can show that 29 refusals were all `passengers`.
+Values are never sent, and neither is a name the agent made up. It works from
+the latest `tools/list` your server answered in the same process; a refusal
+before any listing names nothing.
+
 ## Privacy
 
 **Parameter values never leave your process.** Not by default, not in any
@@ -211,8 +219,12 @@ 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), 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
+the arguments, or any digest of them, never leave it), a fingerprint of the
+tool's definition as your server lists it (its name, title, description and
+input schema, hashed, so the dashboard can mark when you changed it), for a call your
+server refused for its arguments the names of those that did not match the
+tool's schema (never what was sent), 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.
 
@@ -231,6 +243,21 @@ That records `{ destination: 'string', passengers: 'number' }`. Knowing
 destination tells you nothing you needed, and puts your users' data somewhere
 it does not belong.
 
+Error messages are sent, cut short, because they are usually what says why a
+call failed. If your tools can fail with text you would not send anywhere, as
+a tool that runs commands or reads files might quote a path or a token, turn
+them off:
+
+```ts
+instrument(server, {
+  apiKey: process.env.MCPSPAN_API_KEY,
+  captureErrorMessages: false,
+});
+```
+
+Every failure is still recorded, with where it came from and the exception's
+type. Only the text is left out.
+
 Types stay coarse and carry no length, because the distance between "a 34
 character string" and "a credit card number" is shorter than it looks. Nested
 objects are named but not opened.
@@ -282,6 +309,7 @@ That is the first rule, and everything below follows from it.
 | `apiKey` | `MCPSPAN_API_KEY` | Identifies your server. Without it, nothing is collected. |
 | `endpoint` | `MCPSPAN_ENDPOINT`; none | Your mcpspan installation. Nothing is collected without it. |
 | `captureParameterNames` | `false` | Records parameter names and types, never values. |
+| `captureErrorMessages` | `true` | Sends the text of a failure, cut short. Off sends that it failed and how, without the text. |
 | `serverVersion` | `MCPSPAN_SERVER_VERSION`, then the server's own | The version to record calls under: a release, a tag, a commit. |
 | `debug` | `false` | Writes delivery diagnostics to stderr. |
 | `onDiagnostic` | - | Receives diagnostics instead of stderr. Implies `debug`. |

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.4.0";
+const SDK_VERSION = "0.5.0";
 //#endregion
 //#region src/transport.ts
 /** Path the ingest API accepts batches on, appended to the configured endpoint. */
@@ -510,10 +510,16 @@ function currentCall() {
 * the same tools as on any other.
 */
 const listed = /* @__PURE__ */ new Map();
+/** Each tool's input schema as last listed, to tell which arguments a refusal was over (contract, 3.10). */
+const schemas = /* @__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);
 }
+/** The latest input schema listed for a tool, if any listing in this process named it. */
+function schemaOf(toolName) {
+	return schemas.get(toolName);
+}
 /** Notes every tool in an answer to `tools/list`. Never throws. */
 function noteListing(result) {
 	try {
@@ -524,6 +530,7 @@ function noteListing(result) {
 			if (typeof name !== "string") continue;
 			const hash = definitionHash(tool);
 			if (hash !== void 0) listed.set(name, hash);
+			schemas.set(name, tool.inputSchema);
 		}
 	} catch {}
 }
@@ -580,6 +587,99 @@ function text(value) {
 	return `${out}"`;
 }
 //#endregion
+//#region src/arguments.ts
+/**
+* Which top-level arguments of a refused call did not match the tool's input
+* schema (contract, 3.10).
+*
+* The server's own refusal is not read: each validation library words it
+* differently, and some quote the value the agent sent. The arguments are
+* checked here instead, against the schema the server listed, by a small set
+* of rules that never fail what they do not understand. Only names the schema
+* declares come out, so nothing the client made up, and no value, is sent.
+*/
+/** Names sent at most, per call. */
+const MAX_NAMES = 20;
+/** The declared names whose arguments fail the schema, sorted, at most twenty. Never throws. */
+function invalidArguments(schema, args) {
+	try {
+		if (!isObject(schema)) return [];
+		const values = args ?? {};
+		if (!isObject(values)) return [];
+		const names = /* @__PURE__ */ new Set();
+		if (Array.isArray(schema["required"])) {
+			for (const name of schema["required"]) if (typeof name === "string" && !Object.hasOwn(values, name)) names.add(name);
+		}
+		const properties = schema["properties"];
+		if (isObject(properties)) {
+			for (const [name, property] of Object.entries(properties)) if (Object.hasOwn(values, name) && !matches(property, values[name])) names.add(name);
+		}
+		return [...names].sort((a, b) => a < b ? -1 : a > b ? 1 : 0).slice(0, MAX_NAMES);
+	} catch {
+		return [];
+	}
+}
+/** Whether a value passes a schema under the checks the contract lists, and only those. */
+function matches(schema, value) {
+	if (schema === false) return false;
+	if (!isObject(schema)) return true;
+	const type = schema["type"];
+	if (typeof type === "string" && !isType(type, value)) return false;
+	if (Array.isArray(type) && type.every((name) => typeof name === "string") && !type.some((name) => isType(name, value))) return false;
+	if (Array.isArray(schema["enum"])) {
+		const sent = canonical(value);
+		if (!schema["enum"].some((allowed) => canonical(allowed) === sent)) return false;
+	}
+	if (Object.hasOwn(schema, "const") && canonical(schema["const"]) !== canonical(value)) return false;
+	if (typeof value === "number") {
+		if (isNumber(schema["minimum"]) && value < schema["minimum"]) return false;
+		if (isNumber(schema["maximum"]) && value > schema["maximum"]) return false;
+		if (isNumber(schema["exclusiveMinimum"]) && value <= schema["exclusiveMinimum"]) return false;
+		if (isNumber(schema["exclusiveMaximum"]) && value >= schema["exclusiveMaximum"]) return false;
+	}
+	if (typeof value === "string") {
+		const length = [...value].length;
+		if (isNumber(schema["minLength"]) && length < schema["minLength"]) return false;
+		if (isNumber(schema["maxLength"]) && length > schema["maxLength"]) return false;
+	}
+	if (Array.isArray(value)) {
+		if (isNumber(schema["minItems"]) && value.length < schema["minItems"]) return false;
+		if (isNumber(schema["maxItems"]) && value.length > schema["maxItems"]) return false;
+		const items = schema["items"];
+		if (isObject(items) || typeof items === "boolean") {
+			if (!value.every((item) => matches(items, item))) return false;
+		}
+	}
+	if (isObject(value)) {
+		if (Array.isArray(schema["required"])) {
+			for (const name of schema["required"]) if (typeof name === "string" && !Object.hasOwn(value, name)) return false;
+		}
+		const properties = schema["properties"];
+		if (isObject(properties)) {
+			for (const [name, property] of Object.entries(properties)) if (Object.hasOwn(value, name) && !matches(property, value[name])) return false;
+		}
+	}
+	return true;
+}
+function isType(type, value) {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number";
+		case "integer": return typeof value === "number" && Number.isInteger(value);
+		case "boolean": return typeof value === "boolean";
+		case "object": return isObject(value);
+		case "array": return Array.isArray(value);
+		case "null": return value === null;
+		default: return true;
+	}
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+//#endregion
 //#region src/client.ts
 /**
 * Names we recognise, matched as substrings of what a client reports.
@@ -966,7 +1066,8 @@ function recordRefusedCall(refused) {
 			sdkVersion: SDK_VERSION,
 			...refused.sessionId !== void 0 && { sessionId: refused.sessionId },
 			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName),
-			...refused.repeated === true && { repeated: true }
+			...refused.repeated === true && { repeated: true },
+			...refused.errorSource === "arguments" ? refusedNames(refused.toolName, refused.arguments) : {}
 		});
 	} catch {}
 }
@@ -1004,6 +1105,11 @@ function recordPrimitiveCall(call) {
 function isRecording() {
 	return sink !== void 0;
 }
+/** Which declared arguments a refusal was over (contract, 3.10), as event fields. */
+function refusedNames(toolName, args) {
+	const names = invalidArguments(schemaOf(toolName), args).map((name) => truncate(name, MAX_TOOL_NAME_LENGTH));
+	return names.length === 0 ? {} : { invalidArguments: names };
+}
 /** The fingerprint of a tool as last listed (contract, 3.8), as event fields. */
 function definition(toolName) {
 	const hash = definitionOf(toolName);
@@ -1100,7 +1206,8 @@ function configure(config = {}) {
 	};
 	setCaptureParameterNames(config.captureParameterNames ?? false);
 	setServerVersion(firstNonEmpty(config.serverVersion, process.env["MCPSPAN_SERVER_VERSION"]));
-	setEventSink((event) => reporter?.record(event));
+	const captureErrorMessages = config.captureErrorMessages ?? true;
+	setEventSink((event) => reporter?.record(captureErrorMessages ? event : withoutErrorMessage(event)));
 	if (config.flushOnExit ?? true) installExitHook();
 	reporter.announce();
 }
@@ -1162,9 +1269,16 @@ function describeSettings(config) {
 		config.maxBatchSize ?? null,
 		config.maxQueueSize ?? null,
 		config.captureParameterNames ?? false,
+		config.captureErrorMessages ?? true,
 		firstNonEmpty(config.serverVersion, process.env["MCPSPAN_SERVER_VERSION"]) ?? null
 	]);
 }
+/** The event as it is, less the text of its failure (contract, 5). */
+function withoutErrorMessage(event) {
+	if (event.errorMessage === void 0) return event;
+	const { errorMessage: _left, ...rest } = event;
+	return rest;
+}
 function firstNonEmpty(...values) {
 	for (const value of values) {
 		const trimmed = value?.trim();

package/dist/index.d.cts

@@ -60,6 +60,17 @@ interface McpspanConfig {
    * `departureDate`, which usually means a tool description is not landing.
    */
   captureParameterNames?: boolean;
+  /**
+   * Sends the text of a failure: what a tool returned with `isError`, cut to
+   * 200 characters, or an exception's message, cut to 500.
+   *
+   * On by default, since that text is usually what says why a call failed.
+   * Turn it off when your tools can fail with something you would not send
+   * anywhere, as one that runs commands or reads files might quote a path or
+   * a token. Every failure is still recorded, with where it came from and
+   * the exception's type; only the text is left out.
+   */
+  captureErrorMessages?: boolean;
 }
 /**
  * Starts collecting, or stops if there is nothing to collect with.
@@ -201,6 +212,8 @@ interface ToolCallEvent {
   responseBytes?: number;
   /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
   definitionHash?: string;
+  /** For refused arguments: which ones did not match the tool's schema, by declared name (contract, 3.10). */
+  invalidArguments?: 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. */

package/dist/index.d.mts

@@ -60,6 +60,17 @@ interface McpspanConfig {
    * `departureDate`, which usually means a tool description is not landing.
    */
   captureParameterNames?: boolean;
+  /**
+   * Sends the text of a failure: what a tool returned with `isError`, cut to
+   * 200 characters, or an exception's message, cut to 500.
+   *
+   * On by default, since that text is usually what says why a call failed.
+   * Turn it off when your tools can fail with something you would not send
+   * anywhere, as one that runs commands or reads files might quote a path or
+   * a token. Every failure is still recorded, with where it came from and
+   * the exception's type; only the text is left out.
+   */
+  captureErrorMessages?: boolean;
 }
 /**
  * Starts collecting, or stops if there is nothing to collect with.
@@ -201,6 +212,8 @@ interface ToolCallEvent {
   responseBytes?: number;
   /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
   definitionHash?: string;
+  /** For refused arguments: which ones did not match the tool's schema, by declared name (contract, 3.10). */
+  invalidArguments?: 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. */

package/dist/index.mjs

@@ -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.4.0";
+const SDK_VERSION = "0.5.0";
 //#endregion
 //#region src/transport.ts
 /** Path the ingest API accepts batches on, appended to the configured endpoint. */
@@ -509,10 +509,16 @@ function currentCall() {
 * the same tools as on any other.
 */
 const listed = /* @__PURE__ */ new Map();
+/** Each tool's input schema as last listed, to tell which arguments a refusal was over (contract, 3.10). */
+const schemas = /* @__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);
 }
+/** The latest input schema listed for a tool, if any listing in this process named it. */
+function schemaOf(toolName) {
+	return schemas.get(toolName);
+}
 /** Notes every tool in an answer to `tools/list`. Never throws. */
 function noteListing(result) {
 	try {
@@ -523,6 +529,7 @@ function noteListing(result) {
 			if (typeof name !== "string") continue;
 			const hash = definitionHash(tool);
 			if (hash !== void 0) listed.set(name, hash);
+			schemas.set(name, tool.inputSchema);
 		}
 	} catch {}
 }
@@ -579,6 +586,99 @@ function text(value) {
 	return `${out}"`;
 }
 //#endregion
+//#region src/arguments.ts
+/**
+* Which top-level arguments of a refused call did not match the tool's input
+* schema (contract, 3.10).
+*
+* The server's own refusal is not read: each validation library words it
+* differently, and some quote the value the agent sent. The arguments are
+* checked here instead, against the schema the server listed, by a small set
+* of rules that never fail what they do not understand. Only names the schema
+* declares come out, so nothing the client made up, and no value, is sent.
+*/
+/** Names sent at most, per call. */
+const MAX_NAMES = 20;
+/** The declared names whose arguments fail the schema, sorted, at most twenty. Never throws. */
+function invalidArguments(schema, args) {
+	try {
+		if (!isObject(schema)) return [];
+		const values = args ?? {};
+		if (!isObject(values)) return [];
+		const names = /* @__PURE__ */ new Set();
+		if (Array.isArray(schema["required"])) {
+			for (const name of schema["required"]) if (typeof name === "string" && !Object.hasOwn(values, name)) names.add(name);
+		}
+		const properties = schema["properties"];
+		if (isObject(properties)) {
+			for (const [name, property] of Object.entries(properties)) if (Object.hasOwn(values, name) && !matches(property, values[name])) names.add(name);
+		}
+		return [...names].sort((a, b) => a < b ? -1 : a > b ? 1 : 0).slice(0, MAX_NAMES);
+	} catch {
+		return [];
+	}
+}
+/** Whether a value passes a schema under the checks the contract lists, and only those. */
+function matches(schema, value) {
+	if (schema === false) return false;
+	if (!isObject(schema)) return true;
+	const type = schema["type"];
+	if (typeof type === "string" && !isType(type, value)) return false;
+	if (Array.isArray(type) && type.every((name) => typeof name === "string") && !type.some((name) => isType(name, value))) return false;
+	if (Array.isArray(schema["enum"])) {
+		const sent = canonical(value);
+		if (!schema["enum"].some((allowed) => canonical(allowed) === sent)) return false;
+	}
+	if (Object.hasOwn(schema, "const") && canonical(schema["const"]) !== canonical(value)) return false;
+	if (typeof value === "number") {
+		if (isNumber(schema["minimum"]) && value < schema["minimum"]) return false;
+		if (isNumber(schema["maximum"]) && value > schema["maximum"]) return false;
+		if (isNumber(schema["exclusiveMinimum"]) && value <= schema["exclusiveMinimum"]) return false;
+		if (isNumber(schema["exclusiveMaximum"]) && value >= schema["exclusiveMaximum"]) return false;
+	}
+	if (typeof value === "string") {
+		const length = [...value].length;
+		if (isNumber(schema["minLength"]) && length < schema["minLength"]) return false;
+		if (isNumber(schema["maxLength"]) && length > schema["maxLength"]) return false;
+	}
+	if (Array.isArray(value)) {
+		if (isNumber(schema["minItems"]) && value.length < schema["minItems"]) return false;
+		if (isNumber(schema["maxItems"]) && value.length > schema["maxItems"]) return false;
+		const items = schema["items"];
+		if (isObject(items) || typeof items === "boolean") {
+			if (!value.every((item) => matches(items, item))) return false;
+		}
+	}
+	if (isObject(value)) {
+		if (Array.isArray(schema["required"])) {
+			for (const name of schema["required"]) if (typeof name === "string" && !Object.hasOwn(value, name)) return false;
+		}
+		const properties = schema["properties"];
+		if (isObject(properties)) {
+			for (const [name, property] of Object.entries(properties)) if (Object.hasOwn(value, name) && !matches(property, value[name])) return false;
+		}
+	}
+	return true;
+}
+function isType(type, value) {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number";
+		case "integer": return typeof value === "number" && Number.isInteger(value);
+		case "boolean": return typeof value === "boolean";
+		case "object": return isObject(value);
+		case "array": return Array.isArray(value);
+		case "null": return value === null;
+		default: return true;
+	}
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+//#endregion
 //#region src/client.ts
 /**
 * Names we recognise, matched as substrings of what a client reports.
@@ -965,7 +1065,8 @@ function recordRefusedCall(refused) {
 			sdkVersion: SDK_VERSION,
 			...refused.sessionId !== void 0 && { sessionId: refused.sessionId },
 			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName),
-			...refused.repeated === true && { repeated: true }
+			...refused.repeated === true && { repeated: true },
+			...refused.errorSource === "arguments" ? refusedNames(refused.toolName, refused.arguments) : {}
 		});
 	} catch {}
 }
@@ -1003,6 +1104,11 @@ function recordPrimitiveCall(call) {
 function isRecording() {
 	return sink !== void 0;
 }
+/** Which declared arguments a refusal was over (contract, 3.10), as event fields. */
+function refusedNames(toolName, args) {
+	const names = invalidArguments(schemaOf(toolName), args).map((name) => truncate(name, MAX_TOOL_NAME_LENGTH));
+	return names.length === 0 ? {} : { invalidArguments: names };
+}
 /** The fingerprint of a tool as last listed (contract, 3.8), as event fields. */
 function definition(toolName) {
 	const hash = definitionOf(toolName);
@@ -1099,7 +1205,8 @@ function configure(config = {}) {
 	};
 	setCaptureParameterNames(config.captureParameterNames ?? false);
 	setServerVersion(firstNonEmpty(config.serverVersion, process.env["MCPSPAN_SERVER_VERSION"]));
-	setEventSink((event) => reporter?.record(event));
+	const captureErrorMessages = config.captureErrorMessages ?? true;
+	setEventSink((event) => reporter?.record(captureErrorMessages ? event : withoutErrorMessage(event)));
 	if (config.flushOnExit ?? true) installExitHook();
 	reporter.announce();
 }
@@ -1161,9 +1268,16 @@ function describeSettings(config) {
 		config.maxBatchSize ?? null,
 		config.maxQueueSize ?? null,
 		config.captureParameterNames ?? false,
+		config.captureErrorMessages ?? true,
 		firstNonEmpty(config.serverVersion, process.env["MCPSPAN_SERVER_VERSION"]) ?? null
 	]);
 }
+/** The event as it is, less the text of its failure (contract, 5). */
+function withoutErrorMessage(event) {
+	if (event.errorMessage === void 0) return event;
+	const { errorMessage: _left, ...rest } = event;
+	return rest;
+}
 function firstNonEmpty(...values) {
 	for (const value of values) {
 		const trimmed = value?.trim();

package/package.json

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