mcpspan 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1561 @@
+import { 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);
+}
+/** Cuts text to a limit, leaving a visible sign that something was removed. */
+function truncate(text, limit) {
+	return text.length <= limit ? text : `${text.slice(0, limit - 3)}...`;
+}
+/**
+* Whether a tool reported its own failure through the result.
+*
+* MCP asks tools to answer with `isError` rather than throwing, so that the
+* model can see what went wrong and react. A wrapper that only watched for
+* exceptions would record a correctly written server as having no errors at
+* all.
+*/
+function isErrorResult(result) {
+	return typeof result === "object" && result !== null && result.isError === true;
+}
+/**
+* Pulls a short description out of a tool result that reported an error.
+*
+* Reads only text blocks. Images and binary attachments carry no message
+* worth storing, and copying them anywhere would be indefensible.
+*/
+function describeErrorResult(result) {
+	const content = result?.content;
+	if (!Array.isArray(content)) return void 0;
+	const text = content.filter((block) => typeof block === "object" && block !== null && block.type === "text" && typeof block.text === "string").map((block) => block.text).join(" ").trim();
+	return text.length > 0 ? truncate(text, 200) : void 0;
+}
+/** Names and summarises a thrown value, whatever it turned out to be. */
+function describeException(error) {
+	if (error instanceof Error) return {
+		errorType: truncate(error.name, 200),
+		errorMessage: error.message.length > 0 ? truncate(error.message, 500) : void 0
+	};
+	return {
+		errorType: typeof error,
+		errorMessage: truncate(String(error), 500)
+	};
+}
+//#endregion
+//#region src/queue.ts
+/**
+* How many events the buffer holds before it starts discarding.
+*
+* The buffer has to be bounded: if the ingest endpoint is unreachable while
+* tools keep being called, an unbounded buffer grows until the host process
+* runs out of memory, and taking down the developer's server is the one thing
+* this SDK must never do.
+*
+* The bound is a ceiling rather than a reservation. While ingest is healthy
+* the queue drains every few seconds and holds a few dozen events, so the
+* figure below only matters during an outage - which is exactly when we want
+* the headroom. A measured event costs 233 B when it succeeds and 595 B when
+* it carries a unique error message, putting the worst case here under 6 MB.
+*
+* At ten calls per second that covers roughly seventeen minutes of downtime,
+* which is long enough to survive a backend restart or a network blip. A
+* thousand would cover a hundred seconds, and lose data during an ordinary
+* deploy.
+*/
+const DEFAULT_MAX_QUEUE_SIZE = 1e4;
+/**
+* In-memory buffer of events waiting to be sent.
+*
+* This holds events and nothing else. Deciding when to send them, and sending
+* them, belongs to the flush mechanism that drains the queue.
+*/
+var EventQueue = class {
+	/** Capacity at which the oldest buffered event starts being discarded. */
+	maxSize;
+	events = [];
+	dropped = 0;
+	constructor(maxSize = DEFAULT_MAX_QUEUE_SIZE) {
+		if (!Number.isInteger(maxSize) || maxSize < 1) throw new TypeError(`maxSize must be a positive integer, received ${maxSize}`);
+		this.maxSize = maxSize;
+	}
+	/** How many events are currently buffered. */
+	get size() {
+		return this.events.length;
+	}
+	/** How many events have been discarded because the buffer was full. */
+	get droppedCount() {
+		return this.dropped;
+	}
+	/**
+	* Buffers an event, discarding the oldest one when the buffer is full.
+	*
+	* Newest wins on purpose: once the backend comes back, a developer wants to
+	* see what their server is doing now, not a snapshot frozen at the moment
+	* the outage started.
+	*/
+	add(event) {
+		if (this.events.length >= this.maxSize) {
+			this.events.shift();
+			this.dropped += 1;
+		}
+		this.events.push(event);
+	}
+	/**
+	* Removes and returns buffered events, oldest first.
+	*
+	* Without a limit this empties the queue. With one it takes at most that
+	* many, which is what keeps a backlog from being posted as a single huge
+	* request: after an outage the queue can hold thousands of events, and one
+	* request carrying all of them would be refused for size and thrown away
+	* whole.
+	*/
+	drain(limit) {
+		if (limit === void 0 || limit >= this.events.length) {
+			const drained = this.events;
+			this.events = [];
+			return drained;
+		}
+		if (!Number.isInteger(limit) || limit < 1) throw new TypeError(`limit must be a positive integer, received ${limit}`);
+		return this.events.splice(0, limit);
+	}
+	/**
+	* Puts a batch that failed to deliver back at the front of the queue.
+	*
+	* These events are older than anything queued since, so they go ahead of it
+	* and keep the stream in order. If that pushes the queue past capacity the
+	* usual rule still applies and the oldest go - which may well be the ones
+	* just restored, because an outage long enough to overflow the queue has
+	* already made them the least interesting events we hold.
+	*/
+	restore(events) {
+		if (events.length === 0) return;
+		this.events = events.concat(this.events);
+		const overflow = this.events.length - this.maxSize;
+		if (overflow > 0) {
+			this.events.splice(0, overflow);
+			this.dropped += overflow;
+		}
+	}
+};
+//#endregion
+//#region src/version.ts
+/**
+* Version this build of the SDK reports, in telemetry and in its User-Agent.
+*
+* 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";
+//#endregion
+//#region src/transport.ts
+/** Path the ingest API accepts batches on, appended to the configured endpoint. */
+const EVENTS_PATH = "/v1/events";
+/**
+* A delivery attempt that did not succeed.
+*
+* `retryable` says whether sending the same batch again could plausibly work.
+* A refused API key or a malformed payload will be refused identically every
+* time, so repeating those attempts only burns the developer's bandwidth.
+*/
+var TransportError = class extends Error {
+	name = "TransportError";
+	/** HTTP status the ingest API answered with, absent when the request never completed. */
+	status;
+	retryable;
+	/** How long the ingest API asked to be left alone, from `Retry-After`, when it said. */
+	retryAfterMs;
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.status = options.status;
+		this.retryable = options.retryable;
+		this.retryAfterMs = options.retryAfterMs;
+	}
+};
+/**
+* Whether a batch rejected with this status is worth sending again.
+*
+* Retry on the statuses that describe a passing condition: the server asked us
+* to slow down, timed the request out, or failed on its own side. Anything else
+* in the 4xx range is a verdict on the request itself and will not change.
+*/
+function isRetryableStatus(status) {
+	return status === 408 || status === 429 || status >= 500;
+}
+/** Joins the configured endpoint with the events path, tolerating a trailing slash. */
+function buildEventsUrl(endpoint) {
+	return `${endpoint.replace(/\/+$/, "")}${EVENTS_PATH}`;
+}
+/**
+* Delivers one batch of events to the ingest API.
+*
+* Throws {@link TransportError} on any outcome that is not an accepted batch.
+* Callers are expected to decide what to do about that; this function neither
+* retries nor swallows.
+*/
+async function sendEvents(events, config) {
+	const url = buildEventsUrl(config.endpoint);
+	const timeoutMs = config.timeoutMs ?? 1e4;
+	let response;
+	try {
+		response = await fetch(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`,
+				"user-agent": `mcpspan/${SDK_VERSION} (typescript)`
+			},
+			body: JSON.stringify({ events }),
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (cause) {
+		throw new TransportError(`Failed to reach ${url}`, {
+			retryable: true,
+			cause
+		});
+	}
+	if (!response.ok) {
+		const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+		throw new TransportError(`Ingest API rejected the batch with ${response.status}`, {
+			status: response.status,
+			retryable: isRetryableStatus(response.status),
+			...retryAfterMs !== void 0 && { retryAfterMs }
+		});
+	}
+}
+/**
+* Longest wait a `Retry-After` is followed to.
+*
+* A server asking for longer is either wrong or unwell, and a telemetry queue
+* that stops for a day on its word loses the day. Past this the SDK waits
+* this long and asks again.
+*/
+const MAX_RETRY_AFTER_MS = 3e5;
+/**
+* Reads `Retry-After`, in either of its forms: whole seconds, or a date.
+*
+* Undefined when absent or unreadable, which leaves the SDK's own backoff to
+* decide.
+*/
+function parseRetryAfter(header, now = Date.now()) {
+	if (header === null) return void 0;
+	const trimmed = header.trim();
+	let ms;
+	if (/^\d+$/.test(trimmed)) ms = Number(trimmed) * 1e3;
+	else {
+		const at = Date.parse(trimmed);
+		if (Number.isNaN(at)) return void 0;
+		ms = at - now;
+	}
+	return Math.min(Math.max(ms, 0), MAX_RETRY_AFTER_MS);
+}
+/** Delay before the first retry, doubling with each further failure. */
+const INITIAL_RETRY_DELAY_MS = 1e3;
+/** Ceiling for the retry delay, so a long outage settles into steady polling. */
+const MAX_RETRY_DELAY_MS = 6e4;
+/**
+* How long to wait before attempting delivery again.
+*
+* Doubles per consecutive failure up to a ceiling, then spreads each client's
+* attempt across the second half of that window. The spread matters once many
+* servers report to the same endpoint: without it they would all have failed
+* at the same moment, and would all come back at the same moment, turning one
+* outage into a second one at the point of recovery.
+*/
+function computeBackoffMs(consecutiveFailures, random = Math.random) {
+	const ceiling = Math.min(MAX_RETRY_DELAY_MS, INITIAL_RETRY_DELAY_MS * 2 ** (consecutiveFailures - 1));
+	return Math.round(ceiling / 2 + random() * (ceiling / 2));
+}
+/**
+* Collects events and delivers them in the background.
+*
+* `record` is the only method a tool call touches, and it does nothing beyond
+* appending to an in-memory queue: the calling handler returns to the agent
+* without waiting on the network. Delivery happens on an interval, or as soon
+* as a full batch has accumulated, whichever comes first.
+*
+* Nothing that happens during delivery is allowed to surface anywhere near the
+* developer's code. A failure is contained, logged when asked for, and either
+* retried or abandoned depending on whether repeating it could ever work.
+*/
+var EventReporter = class {
+	queue;
+	transport;
+	flushIntervalMs;
+	maxBatchSize;
+	debug;
+	onDiagnostic;
+	timer;
+	inFlight;
+	stopped = false;
+	consecutiveFailures = 0;
+	nextAttemptAt = 0;
+	/** Discards already mentioned, so the same loss is not reported twice. */
+	reportedDrops = 0;
+	/** Set when the endpoint rejected our credentials, which no retry can fix. */
+	rejected = false;
+	constructor(options) {
+		this.queue = new EventQueue(options.maxQueueSize ?? 1e4);
+		this.transport = {
+			endpoint: options.endpoint,
+			apiKey: options.apiKey,
+			...options.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs }
+		};
+		this.flushIntervalMs = options.flushIntervalMs ?? 5e3;
+		this.maxBatchSize = options.maxBatchSize ?? 100;
+		this.debug = options.debug ?? false;
+		this.onDiagnostic = options.onDiagnostic;
+	}
+	/** How many events are waiting to be delivered. */
+	get queueSize() {
+		return this.queue.size;
+	}
+	/**
+	* Queues an event for delivery and returns immediately.
+	*
+	* Synchronous and non-blocking by contract: this sits on the path of every
+	* tool call, so anything slower would show up as latency in the developer's
+	* own product.
+	*/
+	record(event) {
+		if (this.stopped || this.rejected) return;
+		this.queue.add(event);
+		this.startTimer();
+		if (this.queue.size >= this.maxBatchSize) this.flush();
+	}
+	/**
+	* Tells the ingest API this process has started, before any tool is called.
+	*
+	* An empty batch, sent once. It carries nothing, but it proves the endpoint
+	* and the key work, which is otherwise unknowable until the first tool call:
+	* a server nobody has used yet and a server pointed at the wrong address
+	* look identical from the dashboard. It also means a wrong key is reported
+	* when the server starts, rather than whenever somebody first calls a tool.
+	*
+	* An empty batch rather than a new endpoint, because every version of the
+	* ingest API has accepted one, so this works against an installation older
+	* than the SDK talking to it.
+	*
+	* Never retried and never rejects. Missing the announcement costs a line on
+	* a status page, and the first real batch says the same thing anyway.
+	*/
+	async announce() {
+		if (this.stopped || this.rejected) return;
+		try {
+			await sendEvents([], this.transport);
+		} catch (error) {
+			const status = error instanceof TransportError ? error.status : void 0;
+			if (status === 401 || status === 403) {
+				this.reject(status);
+				return;
+			}
+			this.log(`mcpspan: could not announce this server to ${this.transport.endpoint} (${formatError(error)}). Events will still be delivered once it answers.`);
+		}
+	}
+	/**
+	* Delivers everything queued, in batches.
+	*
+	* Does nothing while a retry delay is still running. Concurrent calls join
+	* the flush already in progress rather than starting a second one, so the
+	* same events are never posted twice.
+	*/
+	flush() {
+		return this.runFlush(false);
+	}
+	/**
+	* Stops background delivery and makes a final attempt at whatever is queued.
+	*
+	* Ignores any pending retry delay: this is the last chance these events get,
+	* and without it the final partly filled batch dies with the process - which
+	* on a short-lived stdio server can mean most of a session.
+	*/
+	async stop() {
+		this.stopped = true;
+		this.clearTimer();
+		await this.runFlush(true);
+	}
+	runFlush(force) {
+		if (this.rejected) return Promise.resolve();
+		if (!force && Date.now() < this.nextAttemptAt) return Promise.resolve();
+		this.inFlight ??= this.drainQueue().finally(() => {
+			this.inFlight = void 0;
+		});
+		return this.inFlight;
+	}
+	async drainQueue() {
+		this.reportDrops();
+		while (this.queue.size > 0) {
+			const batch = this.queue.drain(this.maxBatchSize);
+			try {
+				await sendEvents(batch, this.transport);
+				this.onDelivered();
+			} catch (error) {
+				this.onFailed(batch, error);
+				return;
+			}
+		}
+	}
+	/**
+	* Mentions events the queue had to throw away since the last time we looked.
+	*
+	* A full queue means the dashboard is about to under-report, and a developer
+	* chasing a discrepancy has no other way to find that out. Counting drops
+	* without ever saying so would make the count a decoration.
+	*/
+	reportDrops() {
+		const dropped = this.queue.droppedCount - this.reportedDrops;
+		if (dropped <= 0) return;
+		this.reportedDrops = this.queue.droppedCount;
+		this.log(`mcpspan: discarded ${dropped} events, the queue was full`);
+	}
+	onDelivered() {
+		this.consecutiveFailures = 0;
+		this.nextAttemptAt = 0;
+	}
+	onFailed(batch, error) {
+		const retryable = error instanceof TransportError ? error.retryable : true;
+		const status = error instanceof TransportError ? error.status : void 0;
+		if (status === 401 || status === 403) {
+			this.reject(status);
+			return;
+		}
+		if (retryable) this.queue.restore(batch);
+		else this.log(`mcpspan: dropped ${batch.length} events, rejected as ${String(status)}`);
+		this.consecutiveFailures += 1;
+		const asked = error instanceof TransportError ? error.retryAfterMs ?? 0 : 0;
+		const backoff = computeBackoffMs(this.consecutiveFailures);
+		this.nextAttemptAt = Date.now() + Math.max(backoff, asked);
+		this.log(`mcpspan: delivery failed (${formatError(error)}), attempt ${this.consecutiveFailures}`);
+	}
+	/**
+	* Gives up on a key the endpoint refused.
+	*
+	* The key will be refused identically until the developer changes it and
+	* restarts, so keeping events for it only wastes their memory. This one
+	* warns without being asked: a silent SDK that collects nothing because of a
+	* mistyped key is the worst way for someone to spend an afternoon.
+	*/
+	reject(status) {
+		if (this.rejected) return;
+		this.rejected = true;
+		this.clearTimer();
+		this.queue.drain();
+		this.warn(`mcpspan: the ingest endpoint rejected the API key (HTTP ${status}). Telemetry is now disabled for this process.`);
+	}
+	startTimer() {
+		if (this.timer !== void 0 || this.stopped || this.rejected) return;
+		this.timer = setInterval(() => {
+			this.flush();
+		}, this.flushIntervalMs);
+		this.timer.unref?.();
+	}
+	clearTimer() {
+		if (this.timer === void 0) return;
+		clearInterval(this.timer);
+		this.timer = void 0;
+	}
+	log(message) {
+		if (this.debug) this.warn(message);
+	}
+	/**
+	* The developer's own logger if they gave us one, otherwise stderr.
+	*
+	* Never stdout. On a stdio transport stdout carries the MCP protocol itself,
+	* so a stray line printed there does not just look untidy - it corrupts the
+	* stream and breaks the developer's server.
+	*/
+	warn(message) {
+		try {
+			if (this.onDiagnostic) {
+				this.onDiagnostic(message);
+				return;
+			}
+			console.error(message);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/call.ts
+let current;
+/**
+* Runs a handler with its call context known to `track`.
+*
+* `track` reads the context synchronously, as the call begins, before anything
+* the handler does could start another call, so a plain variable is exact here
+* and needs nothing like async context tracking.
+*/
+function withCall(call, run) {
+	const previous = current;
+	current = call;
+	try {
+		return run();
+	} finally {
+		current = previous;
+	}
+}
+/** The context of the call now starting, if it arrived through `instrument`. */
+function currentCall() {
+	return current;
+}
+//#endregion
+//#region src/client.ts
+/**
+* Names we recognise, matched as substrings of what a client reports.
+*
+* Substring rather than exact: clients append platform and channel suffixes to
+* their names, and an exact list would quietly rot into a table of `other`
+* with every release someone else ships. That is not a hypothetical - the
+* official Inspector reports itself as `inspector-cli`, which an exact list
+* of the obvious names would have missed on the first try.
+*
+* Order matters. More specific entries come first, so a client calling itself
+* "claude-code" is not read as plain Claude.
+*/
+const KNOWN_CLIENTS = [
+	["claude-code", "claude-code"],
+	["claude code", "claude-code"],
+	["claude", "claude"],
+	["cursor", "cursor"],
+	["chatgpt", "chatgpt"],
+	["openai", "chatgpt"],
+	["inspector", "mcp-inspector"]
+];
+/**
+* Works out which application a tool call came from.
+*
+* Returns `unknown` when nothing identified itself: a call not made through
+* `instrument`, or a request that named no client. A name we
+* do not have in the table gives `other` - the client is there, we just have
+* not met it.
+*/
+function detectClient(info) {
+	const name = info?.name?.trim().toLowerCase();
+	if (!name) return "unknown";
+	for (const [pattern, type] of KNOWN_CLIENTS) if (name.includes(pattern)) return type;
+	return "other";
+}
+/**
+* The name a client reported, as it reported it.
+*
+* Kept alongside the recognised type so an unfamiliar client is a lead rather
+* than a dead end: a dashboard showing forty percent `other` is useless if
+* nobody can find out what `other` was. This is an application's own
+* self-description, the MCP equivalent of a User-Agent, and carries nothing
+* about whoever is using it.
+*/
+function clientName(info) {
+	const name = info?.name?.trim();
+	return name && name.length > 0 ? truncate(name, 200) : void 0;
+}
+/**
+* Where a request on the 2026-07-28 protocol names its client. There is no
+* `initialize` handshake on that revision; a client identifies itself on every
+* request instead, in the request's `_meta`.
+*/
+const CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo";
+/**
+* The client that sent one call, from what the MCP server knows about it.
+*
+* On the 2026-07-28 protocol the request says so itself, and that is read
+* first. Otherwise it comes from the `initialize` handshake, held by the
+* server instance the call arrived on - that instance, not whichever server
+* was instrumented last, because one process can serve several clients at
+* once.
+*
+* A stateless HTTP server on the 2025 protocol may build a fresh instance for
+* each request, one that never saw the handshake, and there nothing names the
+* client at all. The call is recorded as coming from an unknown client rather
+* than from a guess.
+*/
+function clientFor(server, context) {
+	const request = context ?? {};
+	const declared = request.mcpReq?.envelope?.[CLIENT_INFO_META_KEY] ?? request.mcpReq?._meta?.[CLIENT_INFO_META_KEY] ?? request._meta?.[CLIENT_INFO_META_KEY];
+	if (isClientInfo(declared)) return declared;
+	try {
+		return server.server?.getClientVersion?.();
+	} catch {
+		return;
+	}
+}
+/**
+* The version an MCP server gives itself, as it was built: `new McpServer({
+* name, version })`. Both major versions of the official SDK keep it in the
+* same private field of the protocol-level server; if a version moves it, calls
+* go without one rather than with a guess.
+*/
+function serverVersionOf(server) {
+	try {
+		const inner = server.server;
+		const own = server._serverInfo;
+		const version = inner?._serverInfo?.version ?? own?.version;
+		return typeof version === "string" && version.trim().length > 0 ? version.trim() : void 0;
+	} catch {
+		return;
+	}
+}
+function isClientInfo(value) {
+	return typeof value === "object" && value !== null && (typeof value.name === "string" || typeof value.version === "string");
+}
+//#endregion
+//#region src/marks.ts
+/**
+* Handlers that instrumentation should leave alone.
+*
+* Two different situations land here. A handler already wrapped by `track` is
+* marked so that wrapping a whole server afterwards does not count every call
+* twice. A handler passed through `exclude` is marked so that it is never
+* counted at all.
+*
+* A weak set rather than a property on the function itself: these are the
+* developer's own functions, and a telemetry library has no business writing
+* anything onto them. Entries disappear with the handlers they refer to.
+*/
+const marked = /* @__PURE__ */ new WeakSet();
+/** Records that this function should not be wrapped again. */
+function markHandler(handler) {
+	marked.add(handler);
+	return handler;
+}
+/** Whether this function has already been spoken for. */
+function isMarked(handler) {
+	return typeof handler === "function" && marked.has(handler);
+}
+/**
+* Handlers passed through `exclude`, as opposed to already tracked.
+*
+* The difference only matters for calls the server refuses before any handler
+* runs: a call to a tracked tool with bad arguments is counted, while one to
+* an excluded tool is not, in that form or any other.
+*/
+const excluded = /* @__PURE__ */ new WeakSet();
+function markExcluded(handler) {
+	excluded.add(handler);
+	return markHandler(handler);
+}
+function isExcluded(handler) {
+	return typeof handler === "function" && excluded.has(handler);
+}
+/**
+* Names the shape of a value without touching what is in it.
+*
+* Deliberately coarse. Anything finer starts describing content, and the
+* distance between "this is a 34 character string" and "this is a credit card
+* number" is shorter than it looks.
+*/
+function describeType(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* Lists the parameters a tool was called with, by name and type only.
+*
+* Values never leave the handler. This exists so a developer can see that
+* `search_flights` is being called with `destination` but never with
+* `departureDate`, which is a real debugging need, without any of the answers
+* to those parameters reaching a server.
+*
+* Only the first argument is read, which is where MCP puts a tool's parameter
+* object. Anything else in the signature belongs to the protocol, not the
+* tool.
+*/
+function describeParameters(args) {
+	const [params] = args;
+	if (typeof params !== "object" || params === null || Array.isArray(params)) return;
+	const described = {};
+	let count = 0;
+	for (const [name, value] of Object.entries(params)) {
+		if (count >= 50) break;
+		described[truncate(name, 200)] = describeType(value);
+		count += 1;
+	}
+	return count > 0 ? described : void 0;
+}
+//#endregion
+//#region src/track.ts
+let sink;
+let captureParameterNames = false;
+let configuredServerVersion;
+/** The API takes a version of at most this many characters; longer is cut rather than lose the batch. */
+const MAX_VERSION_LENGTH = 100;
+/**
+* Records every call under this version, whatever the server gives itself.
+*
+* Internal: set by configuration from its `serverVersion` setting.
+*/
+function setServerVersion(version) {
+	configuredServerVersion = version;
+}
+/**
+* Who called and which version answered, as every kind of event carries it.
+* In one place, so a tool call, a refusal and a resource read cannot drift.
+*/
+function identity(client, serverVersion) {
+	const name = clientName(client);
+	const clientVersion = client?.version?.trim();
+	const version = configuredServerVersion ?? serverVersion;
+	return {
+		clientType: detectClient(client),
+		...name !== void 0 && { clientName: name },
+		...clientVersion ? { clientVersion: truncate(clientVersion, MAX_VERSION_LENGTH) } : {},
+		...version ? { serverVersion: truncate(version, MAX_VERSION_LENGTH) } : {}
+	};
+}
+/**
+* Turns on recording of parameter names and types.
+*
+* Off unless a developer asks for it, and even then values are never read.
+*
+* Internal, not part of the package's public API.
+*/
+function setCaptureParameterNames(enabled) {
+	captureParameterNames = enabled;
+}
+/**
+* Points recorded events somewhere, or nowhere.
+*
+* Passing `undefined` turns collection off: wrapped handlers then run through
+* an early return, without a timestamp, an identifier or an event ever being
+* built. That is the state an unconfigured SDK sits in, and it has to cost
+* nothing.
+*
+* Internal: this is how configuration attaches a reporter to the wrapper, and
+* how tests observe what a wrapped call produced. It is not part of the
+* package's public API.
+*/
+function setEventSink(next) {
+	sink = next;
+}
+function isPromiseLike(value) {
+	return typeof value === "object" && value !== null && typeof value.then === "function";
+}
+/**
+* Wraps a tool handler so its calls are recorded.
+*
+* The returned function keeps the handler's exact signature, including its
+* `this`, and passes the result back untouched. Whatever the handler is to the
+* code around it, the wrapper has to be indistinguishable - the moment using
+* this changes how a tool behaves, it stops being an observability library and
+* becomes a liability.
+*
+* Synchronous handlers are measured as they return. Asynchronous ones are
+* measured when their promise settles, since the time a tool takes is the time
+* the agent waits for it, not the time spent building the promise.
+*
+* Failure is recognised in both of its MCP forms: a result the tool marked
+* with `isError`, which the specification treats as the ordinary way to report
+* a problem, and a thrown exception, which usually means the handler broke.
+*
+* Arguments are never read. Nothing a caller passes to a tool reaches an
+* event.
+*/
+function track(toolName, handler) {
+	const recordedName = truncate(toolName, MAX_TOOL_NAME_LENGTH);
+	return markHandler(function tracked(...args) {
+		const active = sink;
+		if (active === void 0) return handler.apply(this, args);
+		const call = currentCall();
+		const session = call?.sessionId;
+		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		const startedAt = performance.now();
+		let recorded = false;
+		const emit = (outcome) => {
+			if (recorded) return;
+			recorded = true;
+			const parameters = captureParameterNames ? describeParameters(args) : void 0;
+			try {
+				active({
+					id: randomUUID(),
+					toolName: recordedName,
+					durationMs: performance.now() - startedAt,
+					...identity(call?.client, call?.serverVersion),
+					...parameters !== void 0 && { parameters },
+					timestamp,
+					sdkVersion: SDK_VERSION,
+					...session !== void 0 && { sessionId: session },
+					...outcome
+				});
+			} catch {}
+		};
+		const settle = (value) => {
+			if (isInputRequired(value)) {
+				recorded = true;
+				return;
+			}
+			if (!isErrorResult(value)) {
+				emit({ success: true });
+				return;
+			}
+			const errorMessage = describeErrorResult(value);
+			emit({
+				success: false,
+				errorSource: "result",
+				...errorMessage !== void 0 && { errorMessage }
+			});
+		};
+		const fail = (error) => {
+			const { errorType, errorMessage } = describeException(error);
+			emit({
+				success: false,
+				errorSource: "exception",
+				errorType,
+				...errorMessage !== void 0 && { errorMessage }
+			});
+		};
+		let result;
+		try {
+			result = handler.apply(this, args);
+		} catch (error) {
+			fail(error);
+			throw error;
+		}
+		if (isPromiseLike(result)) return result.then((value) => {
+			settle(value);
+			return value;
+		}, (error) => {
+			fail(error);
+			throw error;
+		});
+		settle(result);
+		return result;
+	});
+}
+/**
+* Keeps a tool out of the numbers entirely.
+*
+* The counterpart to {@link track}: where that one records a handler, this one
+* marks it so that wrapping the server never touches it.
+*
+* ```ts
+* server.registerTool('health_check', schema, exclude(handler));
+* ```
+*
+* Meant for tools that are called by machinery rather than by an agent - a
+* health check polled every few seconds would outnumber everything a person
+* actually did, and would drag the error rate and response time of the whole
+* server towards its own.
+*
+* Takes no tool name on purpose. A name repeated here could drift from the
+* real one during a rename, and the exclusion would quietly stop applying.
+*
+* Does nothing on its own: without instrumentation there was nothing about to
+* record this handler anyway. The handler is returned exactly as given.
+*/
+function exclude(handler) {
+	return markExcluded(handler);
+}
+/** Longest tool name recorded, for handlers and refused calls alike. */
+const MAX_TOOL_NAME_LENGTH = 200;
+/**
+* Records a call the MCP server answered without a handler's own result: one
+* it turned away before any handler ran, or one whose handler asked the client
+* for more when the server had no way to ask.
+*
+* A refusal carries no message on purpose. The server's text for a refusal is written
+* by a validation library, not by the developer, and some versions quote the
+* offending argument back - "received 'xyz'" - which would put a parameter
+* value into an event. Names and types of what was sent are recorded instead,
+* when the developer asked for them, since those are what say which argument
+* the agent got wrong.
+*/
+function recordRefusedCall(refused) {
+	const active = sink;
+	if (active === void 0) return;
+	try {
+		const parameters = captureParameterNames ? describeParameters([refused.arguments]) : void 0;
+		active({
+			id: randomUUID(),
+			toolName: truncate(refused.toolName, MAX_TOOL_NAME_LENGTH),
+			durationMs: refused.durationMs,
+			success: false,
+			errorSource: refused.errorSource,
+			...refused.errorMessage !== void 0 && { errorMessage: refused.errorMessage },
+			...identity(refused.client, refused.serverVersion),
+			...parameters !== void 0 && { parameters },
+			timestamp: refused.timestamp,
+			sdkVersion: SDK_VERSION,
+			...refused.sessionId !== void 0 && { sessionId: refused.sessionId }
+		});
+	} catch {}
+}
+/**
+* Records a resource read or a prompt got (contract, 3.5), however it ended.
+*
+* Built here beside tool calls so the two cannot drift: the same client, the
+* same session, the same limits, the same rule that arguments are described by
+* name and type and never kept.
+*/
+function recordPrimitiveCall(call) {
+	const active = sink;
+	if (active === void 0) return;
+	try {
+		const parameters = captureParameterNames ? describeParameters([call.arguments]) : void 0;
+		active({
+			id: randomUUID(),
+			kind: call.kind,
+			toolName: truncate(call.name, MAX_TOOL_NAME_LENGTH),
+			durationMs: call.durationMs,
+			success: call.success,
+			...call.errorSource !== void 0 && { errorSource: call.errorSource },
+			...call.errorType !== void 0 && { errorType: call.errorType },
+			...call.errorMessage !== void 0 && { errorMessage: call.errorMessage },
+			...identity(call.client, call.serverVersion),
+			...parameters !== void 0 && { parameters },
+			timestamp: call.timestamp,
+			sdkVersion: SDK_VERSION,
+			...call.sessionId !== void 0 && { sessionId: call.sessionId }
+		});
+	} catch {}
+}
+/** Whether anything is currently collecting, so callers can skip the work entirely. */
+function isRecording() {
+	return sink !== void 0;
+}
+/** 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";
+}
+//#endregion
+//#region src/config.ts
+/**
+* Said when there is a key and nowhere to send: somebody meant to collect.
+* There is no default endpoint, since mcpspan runs wherever its user runs it,
+* and a default would send their data somewhere they did not choose.
+*/
+const NO_ENDPOINT = "mcpspan: an API key is set but no endpoint, so nothing is collected. Set MCPSPAN_ENDPOINT (or the endpoint option) to your mcpspan installation, for example http://localhost:6271.";
+/** Whether NO_ENDPOINT has been said in this process: once is enough. */
+let saidNoEndpoint = false;
+let reporter;
+let exitHook;
+/**
+* What the running reporter was configured with, to recognise the same
+* configuration arriving again.
+*/
+let active;
+/**
+* Starts collecting, or stops if there is nothing to collect with.
+*
+* Calling this again with a different configuration replaces the previous
+* one, sending whatever the old one still held. Calling it again with the same
+* configuration changes nothing. That is the common case, not an edge: an HTTP
+* server that builds a fresh MCP server for every request - the stateless
+* pattern, and how v2 of the official SDK serves the 2026-07-28 protocol -
+* calls instrument() on each of them, and starting over each time would
+* announce the server once per request and throw away the batching.
+*
+* **Never throws.** This runs inside a developer's server during startup, so a
+* mistyped option must not be the reason their server fails to boot. Bad
+* values are reported on stderr and replaced with defaults.
+*/
+function configure(config = {}) {
+	const settings = describeSettings(config);
+	if (reporter !== void 0 && active !== void 0 && active.settings === settings && active.onDiagnostic === config.onDiagnostic) return;
+	active = void 0;
+	const previous = reporter;
+	reporter = void 0;
+	setEventSink(void 0);
+	setCaptureParameterNames(false);
+	setServerVersion(void 0);
+	removeExitHook();
+	if (previous) previous.stop();
+	const debug = config.debug ?? config.onDiagnostic !== void 0;
+	const apiKey = firstNonEmpty(config.apiKey, process.env["MCPSPAN_API_KEY"]);
+	if (apiKey === void 0) return;
+	const endpoint = firstNonEmpty(config.endpoint, process.env["MCPSPAN_ENDPOINT"]);
+	if (endpoint === void 0) {
+		if (!saidNoEndpoint) {
+			saidNoEndpoint = true;
+			try {
+				(config.onDiagnostic ?? console.error)(NO_ENDPOINT);
+			} catch {}
+		}
+		return;
+	}
+	const options = {
+		apiKey,
+		endpoint,
+		debug,
+		...config.onDiagnostic !== void 0 && { onDiagnostic: config.onDiagnostic }
+	};
+	assignPositive(options, "flushIntervalMs", config.flushIntervalMs, debug);
+	assignPositive(options, "maxBatchSize", config.maxBatchSize, debug);
+	assignPositive(options, "maxQueueSize", config.maxQueueSize, debug);
+	reporter = new EventReporter(options);
+	active = {
+		settings,
+		onDiagnostic: config.onDiagnostic
+	};
+	setCaptureParameterNames(config.captureParameterNames ?? false);
+	setServerVersion(firstNonEmpty(config.serverVersion, process.env["MCPSPAN_SERVER_VERSION"]));
+	setEventSink((event) => reporter?.record(event));
+	if (config.flushOnExit ?? true) installExitHook();
+	reporter.announce();
+}
+/**
+* Arranges one last delivery attempt as the process winds down.
+*
+* `beforeExit` fires when the event loop has emptied and Node is about to
+* leave. Scheduling work there is allowed and keeps the process alive just
+* long enough to finish it. Signals and explicit exits are deliberately not
+* intercepted: those belong to the server, and a telemetry library reaching
+* into them would be overstepping.
+*/
+function installExitHook() {
+	if (exitHook !== void 0) return;
+	exitHook = () => {
+		shutdown();
+	};
+	process.once("beforeExit", exitHook);
+}
+function removeExitHook() {
+	if (exitHook === void 0) return;
+	process.removeListener("beforeExit", exitHook);
+	exitHook = void 0;
+}
+/**
+* Stops collecting and makes a final attempt to deliver what is queued.
+*
+* Worth calling from a server's own shutdown path. Without it the last partly
+* filled batch dies with the process, which on a short-lived stdio server can
+* be most of a session.
+*/
+async function shutdown() {
+	const current = reporter;
+	reporter = void 0;
+	active = void 0;
+	setEventSink(void 0);
+	setCaptureParameterNames(false);
+	setServerVersion(void 0);
+	removeExitHook();
+	await current?.stop();
+}
+/** Whether the SDK is currently recording tool calls. */
+function isCollecting() {
+	return reporter !== void 0;
+}
+/**
+* Everything a configuration decides, resolved the way configure() resolves
+* it, as one comparable string. The key and endpoint are read through the
+* environment fallbacks, so the same effective setup compares equal however it
+* was spelt. The diagnostic callback is compared separately, by identity.
+*/
+function describeSettings(config) {
+	return JSON.stringify([
+		firstNonEmpty(config.apiKey, process.env["MCPSPAN_API_KEY"]) ?? null,
+		firstNonEmpty(config.endpoint, process.env["MCPSPAN_ENDPOINT"]) ?? null,
+		config.debug ?? null,
+		config.flushOnExit ?? true,
+		config.flushIntervalMs ?? null,
+		config.maxBatchSize ?? null,
+		config.maxQueueSize ?? null,
+		config.captureParameterNames ?? false,
+		firstNonEmpty(config.serverVersion, process.env["MCPSPAN_SERVER_VERSION"]) ?? null
+	]);
+}
+function firstNonEmpty(...values) {
+	for (const value of values) {
+		const trimmed = value?.trim();
+		if (trimmed) return trimmed;
+	}
+}
+function assignPositive(options, name, value, debug) {
+	if (value === void 0) return;
+	if (!Number.isInteger(value) || value < 1) {
+		if (debug) console.error(`mcpspan: ignoring ${name}=${String(value)}, expected a positive integer`);
+		return;
+	}
+	options[name] = value;
+}
+//#endregion
+//#region src/session.ts
+/**
+* Which conversation a tool call belongs to.
+*
+* A single call says little; the order of them says how an agent actually uses
+* a server - that it always searches before it books, or pages through a list
+* three times, or retries the same call after an error. That needs calls
+* grouped by the connection they arrived on.
+*
+* The identifier is ours, random, and made fresh for each connection. It is
+* deliberately not the transport's own session identifier, which travels in
+* HTTP headers and would let anyone holding the server's logs join our events
+* to them. Nothing in it says anything about who is on the other end.
+*/
+/** Connections remembered per server. Past this the oldest is forgotten. */
+const MAX_SESSIONS_PER_SERVER = 1e3;
+/** Per server instance, the transport's session key mapped to our identifier. */
+const sessions = /* @__PURE__ */ new WeakMap();
+/**
+* Our identifier for the connection a request arrived on, or none.
+*
+* - The transport names a session (HTTP with sessions, on the 2025 protocol):
+*   one identifier per transport session.
+* - HTTP without one (a stateless server, and every server on the 2026-07-28
+*   protocol, which removed sessions): none. Each request there may reach a
+*   fresh server instance, and calling each call its own session would fill
+*   the session views with sessions of one call that no agent had.
+* - Anything else - stdio, an in-process transport - is one connection for
+*   the life of the server instance, so the instance is the session. On the
+*   2026 protocol over stdio the official SDK pins one instance per
+*   connection, which keeps this true.
+*
+* The request context is the MCP SDK's own: `extra` in v1, `ctx` in v2. Both
+* put the transport session at `sessionId`; v1 marks an HTTP request with
+* `requestInfo`, v2 with `http`.
+*/
+function sessionFor(server, context) {
+	const request = context ?? {};
+	const transportSession = request.sessionId;
+	const overHttp = request.requestInfo !== void 0 || request.http !== void 0;
+	if (typeof transportSession !== "string" && overHttp) return void 0;
+	const key = typeof transportSession === "string" ? transportSession : "";
+	let known = sessions.get(server);
+	if (known === void 0) {
+		known = /* @__PURE__ */ new Map();
+		sessions.set(server, known);
+	}
+	const existing = known.get(key);
+	if (existing !== void 0) {
+		known.delete(key);
+		known.set(key, existing);
+		return existing;
+	}
+	const created = randomUUID();
+	known.set(key, created);
+	if (known.size > MAX_SESSIONS_PER_SERVER) {
+		const oldest = known.keys().next().value;
+		if (oldest !== void 0) known.delete(oldest);
+	}
+	return created;
+}
+//#endregion
+//#region src/primitives.ts
+const PRIMITIVE_METHODS = ["resources/read", "prompts/get"];
+function isPrimitiveMethod(method) {
+	return method === "resources/read" || method === "prompts/get";
+}
+/**
+* Whether an MCP SDK refused a prompt's arguments before its callback ran:
+* invalid params, in the words both major versions use (v1 prefixes them with
+* `MCP error -32602: `). A callback's own error with that code and other words
+* is left as the exception it is.
+*/
+function refusedArguments(error) {
+	const { code, message } = error ?? {};
+	return code === -32602 && typeof message === "string" && message.includes("Invalid arguments for prompt");
+}
+/** The scheme of an address, which is all of an unknown one that may be kept: `db://`. */
+function schemeOf(uri) {
+	const colon = uri.indexOf(":");
+	const scheme = colon > 0 ? uri.slice(0, colon) : "";
+	return /^[a-z][a-z0-9+.-]*$/i.test(scheme) ? `${scheme}://` : "unknown://";
+}
+function resolve(server, request) {
+	const registry = server;
+	if (request.method === "prompts/get") {
+		const name = request.params?.name;
+		if (typeof name !== "string") return void 0;
+		const prompt = registry._registeredPrompts?.[name];
+		return {
+			kind: "prompt",
+			name,
+			exists: prompt !== void 0 && prompt.enabled !== false,
+			arguments: request.params?.arguments
+		};
+	}
+	const uri = request.params?.uri;
+	if (typeof uri !== "string") return void 0;
+	let normalised = uri;
+	try {
+		normalised = new URL(uri).toString();
+	} catch {}
+	const fixed = registry._registeredResources?.[normalised];
+	if (fixed !== void 0) return {
+		kind: "resource",
+		name: normalised,
+		exists: fixed.enabled !== false,
+		arguments: void 0
+	};
+	for (const template of Object.values(registry._registeredResourceTemplates ?? {})) {
+		const uriTemplate = template.resourceTemplate?.uriTemplate;
+		const variables = uriTemplate?.match?.(normalised);
+		if (variables !== null && variables !== void 0) return {
+			kind: "resource",
+			name: String(uriTemplate),
+			exists: template.enabled !== false,
+			arguments: variables
+		};
+	}
+	return {
+		kind: "resource",
+		name: schemeOf(uri),
+		exists: false,
+		arguments: void 0
+	};
+}
+/**
+* Wraps the handler the server installed for `resources/read` or
+* `prompts/get`. What it answers or throws goes back unchanged; this only
+* looks at it on its way past.
+*/
+function watchPrimitive(handler, server) {
+	return async function watchedPrimitiveHandler(request, context) {
+		const call = handler.bind(this, request, context);
+		if (!isRecording() || !isPrimitiveMethod(request?.method)) return call();
+		let resolved;
+		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		const startedAt = performance.now();
+		try {
+			resolved = resolve(server, request);
+		} catch {
+			resolved = void 0;
+		}
+		if (resolved === void 0) return call();
+		const record = (outcome) => {
+			try {
+				const exception = outcome.errorSource === "exception" ? describeException(outcome.error) : void 0;
+				recordPrimitiveCall({
+					kind: resolved.kind,
+					name: resolved.name,
+					success: outcome.success,
+					...outcome.errorSource !== void 0 && { errorSource: outcome.errorSource },
+					...exception !== void 0 && { errorType: exception.errorType },
+					...exception?.errorMessage !== void 0 && { errorMessage: exception.errorMessage },
+					arguments: resolved.arguments,
+					timestamp,
+					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)
+				});
+			} catch {}
+		};
+		let result;
+		try {
+			result = await call();
+		} catch (error) {
+			if (!resolved.exists) record({
+				success: false,
+				errorSource: resolved.kind === "prompt" ? "unknown_prompt" : "unknown_resource"
+			});
+			else if (resolved.kind === "prompt" && refusedArguments(error)) record({
+				success: false,
+				errorSource: "arguments"
+			});
+			else record({
+				success: false,
+				errorSource: "exception",
+				error
+			});
+			throw error;
+		}
+		if (!(typeof result === "object" && result !== null && result.resultType === "input_required")) record({ success: true });
+		return result;
+	};
+}
+//#endregion
+//#region src/instrument.ts
+/**
+* Methods an MCP server registers tools through.
+*
+* `registerTool` is the current one, in both major versions of the official
+* SDK. `tool` is deprecated in v1 and gone from v2, but it is what most v1
+* servers written so far actually call, and instrumenting only the modern
+* name would silently miss them.
+*/
+const REGISTRATION_METHODS = ["registerTool", "tool"];
+/**
+* The inner servers whose `tools/call` handler is already watched, so a
+* second instrument() on the same server does not watch it twice.
+*/
+const intercepted = /* @__PURE__ */ new WeakSet();
+/** Marks a wrapped method, so instrumenting the same server twice is harmless. */
+const INSTRUMENTED = Symbol.for("mcpspan.instrumented");
+/** The tools each instrumented server registered, by name. */
+const registries = /* @__PURE__ */ new WeakMap();
+/**
+* Request contexts whose call reached a tool handler.
+*
+* The server hands the same context object to the request handler and to the
+* tool handler it calls, so a call whose context is not in here by the time
+* the request is answered never got as far as the handler: the server refused
+* it on its own. A weak set, so contexts leave with their requests.
+*/
+const reachedHandler = /* @__PURE__ */ new WeakSet();
+/**
+* Request contexts whose handler last answered with an interim
+* `input_required` result (the 2026-07-28 protocol's way to ask the client for
+* more). `track` does not count that answer, because the retry that follows is
+* the call that completes. But where the SDK cannot serve the interim answer -
+* a stateless 2025-era endpoint has no way to put a question to the client -
+* it turns it into an error for the client instead, after the handler has
+* returned, and without this the call would be counted nowhere at all.
+*/
+const endedInterim = /* @__PURE__ */ new WeakSet();
+/**
+* Records every tool a server registers from this point on.
+*
+* This is the whole integration:
+*
+* ```ts
+* const server = new McpServer({ name: 'flights', version: '1.0.0' });
+* instrument(server, { apiKey: process.env.MCPSPAN_API_KEY });
+* ```
+*
+* Tools registered afterwards are wrapped as they are registered, and tools
+* registered before it are wrapped where they already are, so nothing about
+* how they are declared, or where this line sits, has to change.
+*
+* **Never throws.** An unfamiliar server object, or one with no registration
+* method at all, leaves the server exactly as it was and collects nothing. A
+* telemetry library that can stop somebody's server from starting has failed
+* at the only thing it truly must not do.
+*/
+function instrument(server, config) {
+	const debug = config?.debug ?? false;
+	try {
+		if (config !== void 0 || !isCollecting()) configure(config ?? {});
+		const registry = registries.get(server) ?? /* @__PURE__ */ new Map();
+		registries.set(server, registry);
+		wrapRegistration(server, registry, debug);
+		wrapRegistered(server, registry);
+		interceptToolCalls(server, registry);
+	} catch (error) {
+		if (debug) console.error(`mcpspan: could not instrument this server (${formatError(error)})`);
+	}
+	return server;
+}
+function wrapRegistration(server, registry, debug) {
+	const target = server;
+	let wrapped = false;
+	for (const method of REGISTRATION_METHODS) {
+		const original = target[method];
+		if (typeof original !== "function") continue;
+		if (original[INSTRUMENTED] === true) {
+			wrapped = true;
+			continue;
+		}
+		target[method] = createWrapper(original, server, registry);
+		wrapped = true;
+	}
+	if (!wrapped && debug) console.error("mcpspan: this server has no registerTool or tool method, so nothing was instrumented");
+}
+/**
+* Measures tools the server already had when instrument() ran.
+*
+* Both major versions of the official SDK keep registered tools by name, and
+* give each an `update` that swaps its handler: `update({ callback })` is
+* public API, and in v2 it also rebuilds what actually calls the handler, so
+* replacing the field alone would change nothing there. Only finding the
+* tools reads the SDK's private registry; if a version moves it, tools
+* registered before instrument() go unmeasured, as they did before.
+*
+* Swapping a handler on a connected server makes the SDK tell the client
+* the tool list changed. It did not, and a client lists the same tools again.
+*/
+function wrapRegistered(server, registry) {
+	const tools = server._registeredTools;
+	if (typeof tools !== "object" || tools === null) return;
+	for (const [name, tool] of Object.entries(tools)) {
+		if (registry.has(name)) continue;
+		const entry = tool;
+		const handler = entry?.handler;
+		if (typeof handler !== "function" || typeof entry?.update !== "function") continue;
+		try {
+			if (isExcluded(handler)) {
+				registry.set(name, {
+					excluded: true,
+					registered: tool
+				});
+				continue;
+			}
+			const tracked = isMarked(handler) ? handler : track(name, handler);
+			entry.update.call(entry, { callback: noteReached(tracked, server) });
+			registry.set(name, {
+				excluded: false,
+				registered: tool
+			});
+		} catch {}
+	}
+}
+/**
+* Wraps a registration method without needing to know its overloads.
+*
+* Both `tool` and `registerTool` have several shapes - with a description,
+* with a schema, with annotations - and across every one of them the name is
+* the first argument and the handler is the last. Leaning on that is far
+* sturdier than trying to work out which overload was called, and it survives
+* the SDK adding another.
+*/
+function createWrapper(original, server, registry) {
+	const wrapper = function instrumentedRegistration(...args) {
+		const name = args[0];
+		const lastIndex = args.length - 1;
+		const handler = args[lastIndex];
+		if (typeof name !== "string" || typeof handler !== "function" || lastIndex < 1) return original.apply(this, args);
+		if (isExcluded(handler)) {
+			const registered = original.apply(this, args);
+			registry.set(name, {
+				excluded: true,
+				registered
+			});
+			return registered;
+		}
+		const tracked = isMarked(handler) ? handler : track(name, handler);
+		const instrumented = [...args];
+		instrumented[lastIndex] = noteReached(tracked, server);
+		const registered = original.apply(this, instrumented);
+		registry.set(name, {
+			excluded: false,
+			registered
+		});
+		return registered;
+	};
+	Object.defineProperty(wrapper, INSTRUMENTED, { value: true });
+	return wrapper;
+}
+/**
+* Remembers that a call got as far as its handler, and tells `track` which
+* connection and client it came from.
+*
+* The context is the last argument whatever the tool's shape: `(args, extra)`
+* for a tool with a schema, `(extra)` for one without; `ctx` in place of
+* `extra` in v2 of the official SDK.
+*/
+function noteReached(handler, server) {
+	return function reachedToolHandler(...args) {
+		const context = args.at(-1);
+		const run = () => handler.apply(this, args);
+		const hasContext = typeof context === "object" && context !== null;
+		if (hasContext) reachedHandler.add(context);
+		const sessionId = hasContext ? sessionFor(server, context) : void 0;
+		const client = clientFor(server, hasContext ? context : void 0);
+		const serverVersion = serverVersionOf(server);
+		const result = withCall({
+			...sessionId !== void 0 && { sessionId },
+			...client !== void 0 && { client },
+			...serverVersion !== void 0 && { serverVersion }
+		}, run);
+		if (hasContext) noteInterim(context, result);
+		return result;
+	};
+}
+/** Keeps `endedInterim` in step with how the handler's latest answer ended. */
+function noteInterim(context, result) {
+	const settle = (value) => {
+		if (typeof value === "object" && value !== null && value.resultType === "input_required") endedInterim.add(context);
+		else endedInterim.delete(context);
+	};
+	if (result instanceof Promise) result.then(settle, () => endedInterim.delete(context));
+	else settle(result);
+}
+/**
+* Sees the calls a server refuses before any handler runs.
+*
+* Wrapping handlers only sees calls that reach them. An MCP server validates
+* arguments against the tool's schema first, and answers a call to a tool it
+* does not have, and both come back to the model as ordinary error results.
+* Bad arguments are the commonest way an agent fails, and none of it was
+* counted: a server's error rate read lower than what agents experienced.
+*
+* Hooks the request handler the server installs for `tools/call`, the layer
+* that answers the client. Every handler set on the connection passes through
+* here, and all but that one are handed over untouched.
+*/
+function interceptToolCalls(server, registry) {
+	const inner = server.server;
+	const original = inner?.setRequestHandler;
+	if (inner === void 0 || typeof original !== "function") return;
+	if (intercepted.has(inner)) return;
+	intercepted.add(inner);
+	const handlers = inner._requestHandlers;
+	if (handlers instanceof Map) for (const method of ["tools/call", ...PRIMITIVE_METHODS]) {
+		const installed = handlers.get(method);
+		if (typeof installed === "function") handlers.set(method, watch(installed, server, registry));
+	}
+	const wrapped = function instrumentedSetRequestHandler(schema, handler) {
+		const replacement = typeof handler === "function" ? watch(handler, server, registry) : handler;
+		return original.call(this, schema, replacement);
+	};
+	Object.defineProperty(wrapped, INSTRUMENTED, { value: true });
+	inner.setRequestHandler = wrapped;
+}
+/**
+* Watches a request handler for the calls this SDK records: tool calls, and
+* resource reads and prompt gets (see primitives.ts). Each watcher looks at
+* the request's method when it arrives and passes anything else straight on,
+* so the handler for any other method runs exactly as it did.
+*/
+function watch(handler, server, registry) {
+	return watchPrimitive(watchToolCalls(handler, server, registry), server);
+}
+function watchToolCalls(handler, server, registry) {
+	return async function watchedRequestHandler(request, context) {
+		const call = handler.bind(this, request, context);
+		if (!isRecording() || request?.method !== "tools/call") return call();
+		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		const startedAt = performance.now();
+		const noteRefusal = (message) => {
+			try {
+				const reached = typeof context === "object" && context !== null && reachedHandler.has(context);
+				const name = request.params?.name;
+				if (typeof name !== "string") return;
+				if (reached) {
+					if (endedInterim.has(context)) recordRefusedCall({
+						toolName: name,
+						errorSource: "result",
+						...message !== void 0 && { errorMessage: message },
+						arguments: request.params?.arguments,
+						timestamp,
+						durationMs: performance.now() - startedAt,
+						sessionId: sessionFor(server, context),
+						client: clientFor(server, context),
+						serverVersion: serverVersionOf(server)
+					});
+					return;
+				}
+				const errorSource = classifyRefusal(registry.get(name), message);
+				if (errorSource === void 0) return;
+				recordRefusedCall({
+					toolName: name,
+					errorSource,
+					arguments: request.params?.arguments,
+					timestamp,
+					durationMs: performance.now() - startedAt,
+					sessionId: sessionFor(server, context),
+					client: clientFor(server, context),
+					serverVersion: serverVersionOf(server)
+				});
+			} catch {}
+		};
+		let result;
+		try {
+			result = await call();
+		} catch (error) {
+			noteRefusal(error instanceof Error ? error.message : void 0);
+			throw error;
+		}
+		if (isErrorResult(result)) noteRefusal(describeErrorResult(result));
+		return result;
+	};
+}
+/**
+* Names the reason a call never reached its handler, or declines to guess.
+*
+* Which tool it was decides most of it: one we registered and is enabled was
+* refused over its arguments; one we never saw, or that is disabled, does not
+* exist as far as the client is concerned. The server's wording is checked as
+* well, so that anything else refused on the way - a misconfigured task tool,
+* a tool renamed after registration - is left out rather than miscounted. If
+* that wording ever changes, the effect is that fewer refusals are recorded,
+* never that the wrong ones are.
+*/
+function classifyRefusal(entry, message) {
+	if (entry?.excluded === true) return void 0;
+	const registered = entry?.registered;
+	const enabled = entry !== void 0 && registered?.enabled !== false;
+	const text = message ?? "";
+	if (enabled) return /validation/i.test(text) ? "arguments" : void 0;
+	return /not found|disabled/i.test(text) ? "unknown_tool" : void 0;
+}
+//#endregion
+export { configure, exclude, instrument, shutdown, track };