@mcploom/analytics 0.2.0

package/dist/index.js

@@ -0,0 +1,685 @@
+import { appendFile } from "node:fs/promises";
+
+//#region src/utils.ts
+/**
+* Returns the byte length of a string (UTF-8).
+*/
+function byteSize(value) {
+	if (value === void 0 || value === null) return 0;
+	const str = typeof value === "string" ? value : JSON.stringify(value);
+	return new TextEncoder().encode(str).byteLength;
+}
+/**
+* Compute a percentile from a sorted array of numbers.
+* Uses linear interpolation between the closest ranks.
+*/
+function percentile(sorted, p) {
+	if (sorted.length === 0) return 0;
+	if (sorted.length === 1) return sorted[0];
+	const index = p / 100 * (sorted.length - 1);
+	const lower = Math.floor(index);
+	const upper = Math.ceil(index);
+	if (lower === upper) return sorted[lower];
+	const weight = index - lower;
+	return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+
+//#endregion
+//#region src/collector.ts
+/**
+* In-memory ring buffer that collects ToolCallEvents, computes stats,
+* and periodically flushes to an exporter.
+*/
+var Collector = class {
+	buffer = [];
+	accumulators = /* @__PURE__ */ new Map();
+	sessionAccumulators = /* @__PURE__ */ new Map();
+	totalCalls = 0;
+	totalErrors = 0;
+	startTime = Date.now();
+	flushTimer;
+	/** Events accumulated since last flush, to be sent to the exporter */
+	pending = [];
+	flushInFlight;
+	toolWindowSize;
+	onFlushError;
+	constructor(maxBufferSize, exporter, flushIntervalMs, options = {}) {
+		this.maxBufferSize = maxBufferSize;
+		this.exporter = exporter;
+		this.toolWindowSize = Math.max(1, options.toolWindowSize ?? 2048);
+		this.onFlushError = options.onFlushError ?? ((error) => {
+			console.error("[McpAnalytics] Exporter flush failed:", error);
+		});
+		if (flushIntervalMs > 0) {
+			this.flushTimer = setInterval(() => {
+				this.flush().catch((error) => {
+					this.onFlushError(error);
+				});
+			}, flushIntervalMs);
+			if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) this.flushTimer.unref();
+		}
+	}
+	/**
+	* Record a new tool call event.
+	*/
+	record(event) {
+		if (this.maxBufferSize > 0) {
+			if (this.buffer.length >= this.maxBufferSize) this.buffer.shift();
+			this.buffer.push(event);
+		}
+		this.pending.push(event);
+		this.totalCalls++;
+		if (!event.success) this.totalErrors++;
+		this.updateToolAccumulator(this.accumulators, event.toolName, event);
+		const sessionKey = event.sessionId ?? "unknown";
+		let sessionAcc = this.sessionAccumulators.get(sessionKey);
+		if (!sessionAcc) {
+			sessionAcc = {
+				...this.newAccumulator(),
+				tools: /* @__PURE__ */ new Map()
+			};
+			this.sessionAccumulators.set(sessionKey, sessionAcc);
+		}
+		this.updateAccumulator(sessionAcc, event);
+		this.updateToolAccumulator(sessionAcc.tools, event.toolName, event);
+	}
+	/**
+	* Get aggregated stats for all tools.
+	*/
+	getStats() {
+		const tools = {};
+		for (const [name, acc] of this.accumulators) tools[name] = this.accToStats(acc);
+		const sessions = {};
+		for (const [sessionId, acc] of this.sessionAccumulators) sessions[sessionId] = this.sessionAccToStats(acc);
+		return {
+			totalCalls: this.totalCalls,
+			totalErrors: this.totalErrors,
+			errorRate: this.totalCalls > 0 ? this.totalErrors / this.totalCalls : 0,
+			uptimeMs: Date.now() - this.startTime,
+			tools,
+			sessions
+		};
+	}
+	/**
+	* Get stats for a single tool.
+	*/
+	getToolStats(toolName) {
+		const acc = this.accumulators.get(toolName);
+		if (!acc) return void 0;
+		return this.accToStats(acc);
+	}
+	/**
+	* Get stats for a single session.
+	*/
+	getSessionStats(sessionId) {
+		const acc = this.sessionAccumulators.get(sessionId);
+		if (!acc) return void 0;
+		return this.sessionAccToStats(acc);
+	}
+	/**
+	* Get top sessions ordered by total call count.
+	*/
+	getTopSessions(limit = 10) {
+		if (limit <= 0) return [];
+		return [...this.sessionAccumulators.entries()].sort((a, b) => {
+			const byCount = b[1].count - a[1].count;
+			if (byCount !== 0) return byCount;
+			return b[1].lastCalledAt - a[1].lastCalledAt;
+		}).slice(0, limit).map(([sessionId, acc]) => ({
+			sessionId,
+			stats: this.sessionAccToStats(acc)
+		}));
+	}
+	/**
+	* Flush pending events to the exporter.
+	*/
+	async flush() {
+		if (this.flushInFlight) {
+			await this.flushInFlight;
+			return;
+		}
+		const run = this.flushPending();
+		this.flushInFlight = run;
+		try {
+			await run;
+		} finally {
+			if (this.flushInFlight === run) this.flushInFlight = void 0;
+		}
+	}
+	/**
+	* Reset all collected data.
+	*/
+	reset() {
+		this.buffer.length = 0;
+		this.pending.length = 0;
+		this.accumulators.clear();
+		this.sessionAccumulators.clear();
+		this.totalCalls = 0;
+		this.totalErrors = 0;
+	}
+	/**
+	* Stop the flush timer and flush remaining events.
+	*/
+	async destroy() {
+		if (this.flushTimer) {
+			clearInterval(this.flushTimer);
+			this.flushTimer = void 0;
+		}
+		await this.flush();
+	}
+	async flushPending() {
+		while (this.pending.length > 0) {
+			const batch = this.pending;
+			this.pending = [];
+			try {
+				await this.exporter(batch);
+			} catch (error) {
+				this.pending = batch.concat(this.pending);
+				throw error;
+			}
+		}
+	}
+	newAccumulator() {
+		return {
+			count: 0,
+			errorCount: 0,
+			totalMs: 0,
+			durations: [],
+			lastCalledAt: 0
+		};
+	}
+	updateToolAccumulator(map, toolName, event) {
+		let acc = map.get(toolName);
+		if (!acc) {
+			acc = this.newAccumulator();
+			map.set(toolName, acc);
+		}
+		this.updateAccumulator(acc, event);
+	}
+	updateAccumulator(acc, event) {
+		acc.count++;
+		if (!event.success) acc.errorCount++;
+		acc.totalMs += event.durationMs;
+		acc.durations.push(event.durationMs);
+		if (acc.durations.length > this.toolWindowSize) acc.durations.shift();
+		acc.lastCalledAt = event.timestamp;
+	}
+	accToStats(acc) {
+		const sortedDurations = [...acc.durations].sort((a, b) => a - b);
+		return {
+			count: acc.count,
+			errorCount: acc.errorCount,
+			errorRate: acc.count > 0 ? acc.errorCount / acc.count : 0,
+			p50Ms: percentile(sortedDurations, 50),
+			p95Ms: percentile(sortedDurations, 95),
+			p99Ms: percentile(sortedDurations, 99),
+			avgMs: acc.count > 0 ? acc.totalMs / acc.count : 0,
+			lastCalledAt: acc.lastCalledAt
+		};
+	}
+	sessionAccToStats(acc) {
+		const tools = {};
+		for (const [toolName, toolAcc] of acc.tools) tools[toolName] = this.accToStats(toolAcc);
+		return {
+			count: acc.count,
+			errorCount: acc.errorCount,
+			errorRate: acc.count > 0 ? acc.errorCount / acc.count : 0,
+			avgMs: acc.count > 0 ? acc.totalMs / acc.count : 0,
+			lastCalledAt: acc.lastCalledAt,
+			tools
+		};
+	}
+};
+
+//#endregion
+//#region src/exporters/console.ts
+/**
+* Console exporter: pretty-prints each batch of events to stdout.
+*/
+function createConsoleExporter() {
+	return async (events) => {
+		if (events.length === 0) return;
+		const lines = ["[McpAnalytics] Flushing batch:"];
+		for (const e of events) {
+			const errorSuffix = e.errorCode ? ` (${e.errorCode})` : "";
+			const status = e.success ? "OK" : `ERR${errorSuffix}`;
+			const meta = e.sessionId ? ` session=${e.sessionId}` : "";
+			lines.push(`  ${e.toolName} ${status} ${e.durationMs}ms in=${e.inputSize}B out=${e.outputSize}B${meta}`);
+		}
+		console.log(lines.join("\n"));
+	};
+}
+
+//#endregion
+//#region src/exporters/custom.ts
+/**
+* Wraps a user-provided export function, catching errors to prevent
+* exporter failures from disrupting the MCP server.
+*/
+function createCustomExporter(fn) {
+	return async (events) => {
+		try {
+			await fn(events);
+		} catch (err) {
+			console.error("[McpAnalytics] Custom exporter error:", err);
+		}
+	};
+}
+
+//#endregion
+//#region src/exporters/json.ts
+/**
+* JSON exporter: appends events as JSONL (one JSON object per line) to a file.
+*/
+function createJsonExporter(config) {
+	return async (events) => {
+		if (events.length === 0) return;
+		const lines = events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+		await appendFile(config.path, lines, "utf-8");
+	};
+}
+
+//#endregion
+//#region src/exporters/otlp.ts
+/**
+* OTLP exporter: sends tool call events as OpenTelemetry spans.
+*
+* Uses dynamic imports so that @opentelemetry/* packages are only loaded
+* when this exporter is actually used.
+*/
+function createOtlpExporter(config) {
+	let tracerPromise;
+	return async (events) => {
+		if (events.length === 0) return;
+		if (!tracerPromise) tracerPromise = initTracer(config);
+		const tracer = await tracerPromise;
+		for (const event of events) tracer.exportEvent(event);
+		await tracer.flush();
+	};
+}
+async function initTracer(config) {
+	const { SpanStatusCode } = await import("@opentelemetry/api");
+	const { BasicTracerProvider, SimpleSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
+	const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+	const otlpExporter = new OTLPTraceExporter({
+		url: config.endpoint,
+		headers: config.headers
+	});
+	const tracer = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(otlpExporter)] }).getTracer("@mcploom/analytics");
+	return {
+		exportEvent(event) {
+			const span = tracer.startSpan("mcp.tool_call", {
+				startTime: new Date(event.timestamp),
+				attributes: {
+					"mcp.tool.name": event.toolName,
+					"mcp.tool.duration_ms": event.durationMs,
+					"mcp.tool.success": event.success,
+					"mcp.tool.input_size": event.inputSize,
+					"mcp.tool.output_size": event.outputSize,
+					...event.sessionId && { "mcp.session.id": event.sessionId },
+					...event.errorMessage && { "mcp.tool.error_message": event.errorMessage },
+					...event.errorCode !== void 0 && { "mcp.tool.error_code": event.errorCode },
+					...Object.fromEntries(Object.entries(event.metadata ?? {}).map(([k, v]) => [`mcp.meta.${k}`, v]))
+				}
+			});
+			if (!event.success) span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: event.errorMessage
+			});
+			span.end(new Date(event.timestamp + event.durationMs));
+		},
+		async flush() {
+			await otlpExporter?.forceFlush?.();
+		}
+	};
+}
+
+//#endregion
+//#region src/tracing.ts
+let otelApi;
+let otelLoadFailed = false;
+/**
+* Lazily load @opentelemetry/api. Returns undefined if the package is not installed.
+*/
+async function getOtelApi() {
+	if (otelApi) return otelApi;
+	if (otelLoadFailed) return void 0;
+	try {
+		otelApi = await import("@opentelemetry/api");
+		return otelApi;
+	} catch {
+		otelLoadFailed = true;
+		return;
+	}
+}
+/**
+* Start an OpenTelemetry span for a tool call using the global tracer provider.
+* Returns undefined if @opentelemetry/api is not available.
+*/
+async function startToolSpan(toolName, attributes) {
+	const api = await getOtelApi();
+	if (!api) return void 0;
+	const span = api.trace.getTracer("@mcploom/analytics").startSpan("mcp.tool_call", { attributes: {
+		"mcp.tool.name": toolName,
+		...attributes
+	} });
+	return {
+		span,
+		context: api.trace.setSpan(api.context.active(), span)
+	};
+}
+/**
+* End a tool span, setting error status if the call failed.
+*/
+function endToolSpan(tracing, success, errorMessage) {
+	if (!success && otelApi) tracing.span.setStatus({
+		code: otelApi.SpanStatusCode.ERROR,
+		message: errorMessage
+	});
+	tracing.span.end();
+}
+/**
+* Run a function within the context of a span, so downstream OTel-instrumented
+* calls become children of this span.
+*/
+async function withSpanContext(tracing, fn) {
+	const api = otelApi;
+	if (!api) return fn();
+	return api.context.with(tracing.context, fn);
+}
+
+//#endregion
+//#region src/middleware.ts
+/**
+* Checks if a JSON-RPC message is a request (has `id` and `method`).
+*/
+function isRequest(msg) {
+	return "id" in msg && "method" in msg;
+}
+/**
+* Checks if a JSON-RPC message is a response with a result.
+*/
+function isResultResponse(msg) {
+	return "id" in msg && "result" in msg;
+}
+/**
+* Checks if a JSON-RPC message is an error response.
+*/
+function isErrorResponse(msg) {
+	return "id" in msg && "error" in msg;
+}
+/**
+* Wraps a Transport to intercept tools/call requests and their responses,
+* recording metrics to the Collector.
+*/
+function instrumentTransport(transport, collector, sampleRate, globalMetadata, tracing, samplingStrategy = "per_call") {
+	const pending = /* @__PURE__ */ new Map();
+	const sessionSamplingDecisions = /* @__PURE__ */ new Map();
+	const origOnMessage = transport.onmessage;
+	const origOnClose = transport.onclose;
+	const sampleForSession = (sessionKey) => {
+		if (samplingStrategy !== "per_session") return Math.random() < sampleRate;
+		const cached = sessionSamplingDecisions.get(sessionKey);
+		if (cached !== void 0) return cached;
+		const decision = Math.random() < sampleRate;
+		sessionSamplingDecisions.set(sessionKey, decision);
+		return decision;
+	};
+	const closePendingCall = (call, success, errorMessage) => {
+		if (call.tracing) {
+			endToolSpan(call.tracing, success, errorMessage);
+			return;
+		}
+		if (call.tracingInit) call.tracingInit.then((span) => {
+			if (span) endToolSpan(span, success, errorMessage);
+		}).catch(() => {});
+	};
+	const cleanupPendingCalls = (reason) => {
+		for (const call of pending.values()) closePendingCall(call, false, reason);
+		pending.clear();
+		sessionSamplingDecisions.clear();
+	};
+	const proxy = new Proxy(transport, {
+		set(target, prop, value) {
+			if (prop === "onmessage" && typeof value === "function") {
+				const userHandler = value;
+				target.onmessage = (message, extra) => {
+					if (isRequest(message) && message.method === "tools/call") {
+						if (sampleForSession(target.sessionId ?? "unknown")) {
+							const params = message.params;
+							const toolName = params?.name ?? "unknown";
+							const inputSize = byteSize(params?.arguments);
+							const pendingCall = {
+								toolName,
+								startTime: Date.now(),
+								inputSize
+							};
+							if (tracing) pendingCall.tracingInit = startToolSpan(toolName, { "mcp.tool.input_size": inputSize }).then((span) => {
+								pendingCall.tracing = span;
+								return span;
+							}).catch(() => void 0);
+							pending.set(message.id, pendingCall);
+						}
+					}
+					userHandler(message, extra);
+				};
+				return true;
+			}
+			if (prop === "onclose" && typeof value === "function") {
+				const userOnClose = value;
+				target.onclose = (...args) => {
+					cleanupPendingCalls("Transport closed before tool response");
+					userOnClose(...args);
+				};
+				return true;
+			}
+			target[prop] = value;
+			return true;
+		},
+		get(target, prop, receiver) {
+			if (prop === "send") return async (message, options) => {
+				if ("id" in message) {
+					const id = message.id;
+					const call = pending.get(id);
+					if (call) {
+						pending.delete(id);
+						const success = isResultResponse(message);
+						const errorMessage = isErrorResponse(message) ? message.error.message : void 0;
+						let outputPayload;
+						if (isResultResponse(message)) outputPayload = message.result;
+						else if (isErrorResponse(message)) outputPayload = message.error;
+						const event = {
+							toolName: call.toolName,
+							sessionId: target.sessionId,
+							timestamp: call.startTime,
+							durationMs: Date.now() - call.startTime,
+							success,
+							inputSize: call.inputSize,
+							outputSize: byteSize(outputPayload),
+							...isErrorResponse(message) && {
+								errorMessage,
+								errorCode: message.error.code
+							},
+							...globalMetadata && { metadata: globalMetadata }
+						};
+						collector.record(event);
+						closePendingCall(call, success, errorMessage);
+					}
+				}
+				return target.send.call(target, message, options);
+			};
+			if (prop === "close") return async (...args) => {
+				try {
+					return await target.close(...args);
+				} finally {
+					cleanupPendingCalls("Transport closed before tool response");
+				}
+			};
+			const value = Reflect.get(target, prop, receiver);
+			if (typeof value === "function") return value.bind(target);
+			return value;
+		}
+	});
+	if (origOnMessage) proxy.onmessage = origOnMessage;
+	if (origOnClose) proxy.onclose = origOnClose;
+	return proxy;
+}
+/**
+* Wraps a tool handler function to record metrics.
+* Works with McpServer.tool() callback pattern.
+*/
+function wrapToolHandler(toolName, handler, collector, sampleRate, globalMetadata, tracing) {
+	return async (...args) => {
+		if (!(Math.random() < sampleRate)) return handler(...args);
+		const startTime = Date.now();
+		const inputSize = byteSize(args[0]);
+		const tracingSpan = tracing ? await startToolSpan(toolName, { "mcp.tool.input_size": inputSize }) : void 0;
+		try {
+			const result = tracingSpan ? await withSpanContext(tracingSpan, () => handler(...args)) : await handler(...args);
+			const event = {
+				toolName,
+				timestamp: startTime,
+				durationMs: Date.now() - startTime,
+				success: true,
+				inputSize,
+				outputSize: byteSize(result),
+				...globalMetadata && { metadata: globalMetadata }
+			};
+			collector.record(event);
+			if (tracingSpan) endToolSpan(tracingSpan, true);
+			return result;
+		} catch (err) {
+			const errorMessage = err instanceof Error ? err.message : String(err);
+			const event = {
+				toolName,
+				timestamp: startTime,
+				durationMs: Date.now() - startTime,
+				success: false,
+				errorMessage,
+				inputSize,
+				outputSize: 0,
+				...globalMetadata && { metadata: globalMetadata }
+			};
+			collector.record(event);
+			if (tracingSpan) endToolSpan(tracingSpan, false, errorMessage);
+			throw err;
+		}
+	};
+}
+
+//#endregion
+//#region src/analytics.ts
+/**
+* MCP Analytics — lightweight observability for MCP servers.
+*
+* @example
+* ```ts
+* const analytics = new McpAnalytics({ exporter: "console" });
+*
+* // Instrument a transport
+* const tracked = analytics.instrument(transport);
+* await server.connect(tracked);
+*
+* // Or wrap individual handlers
+* server.tool("search", schema, analytics.track(handler));
+*
+* // Get stats
+* console.log(analytics.getStats());
+*
+* // Shutdown
+* await analytics.flush();
+* ```
+*/
+var McpAnalytics = class {
+	collector;
+	sampleRate;
+	metadata;
+	tracing;
+	samplingStrategy;
+	constructor(config) {
+		this.sampleRate = config.sampleRate ?? 1;
+		this.metadata = config.metadata;
+		this.tracing = config.tracing ?? false;
+		this.samplingStrategy = config.samplingStrategy ?? "per_call";
+		const exporter = this.resolveExporter(config);
+		this.collector = new Collector(config.maxBufferSize ?? 1e4, exporter, config.flushIntervalMs ?? 5e3, { toolWindowSize: config.toolWindowSize });
+	}
+	/**
+	* Instrument an MCP transport to automatically track all tool calls.
+	* Returns proxy transport that can be used in place of the original.
+	*/
+	instrument(transport) {
+		return instrumentTransport(transport, this.collector, this.sampleRate, this.metadata, this.tracing, this.samplingStrategy);
+	}
+	/**
+	* Wrap a tool handler function to track its execution.
+	*
+	* @example
+	* ```ts
+	* server.tool("search", schema, analytics.track(async (params) => {
+	*   return await doSearch(params);
+	* }, "search"));
+	* ```
+	*/
+	track(handler, toolName) {
+		return wrapToolHandler(toolName ?? (handler.name || "anonymous"), handler, this.collector, this.sampleRate, this.metadata, this.tracing);
+	}
+	/**
+	* Get a snapshot of all analytics data.
+	*/
+	getStats() {
+		return this.collector.getStats();
+	}
+	/**
+	* Get stats for a specific tool.
+	*/
+	getToolStats(toolName) {
+		return this.collector.getToolStats(toolName);
+	}
+	/**
+	* Get stats for a specific session.
+	*/
+	getSessionStats(sessionId) {
+		return this.collector.getSessionStats(sessionId);
+	}
+	/**
+	* Get top sessions ranked by total call count.
+	*/
+	getTopSessions(limit = 10) {
+		return this.collector.getTopSessions(limit);
+	}
+	/**
+	* Flush all pending events to the exporter.
+	*/
+	async flush() {
+		await this.collector.flush();
+	}
+	/**
+	* Reset all collected data.
+	*/
+	reset() {
+		this.collector.reset();
+	}
+	/**
+	* Stop the analytics instance (clears flush timer and flushes remaining events).
+	*/
+	async shutdown() {
+		await this.collector.destroy();
+	}
+	resolveExporter(config) {
+		if (typeof config.exporter === "function") return createCustomExporter(config.exporter);
+		switch (config.exporter) {
+			case "console": return createConsoleExporter();
+			case "json":
+				if (!config.json) throw new Error("McpAnalytics: \"json\" exporter requires a \"json\" config with \"path\"");
+				return createJsonExporter(config.json);
+			case "otlp":
+				if (!config.otlp) throw new Error("McpAnalytics: \"otlp\" exporter requires an \"otlp\" config with \"endpoint\"");
+				return createOtlpExporter(config.otlp);
+		}
+	}
+};
+
+//#endregion
+export { McpAnalytics };
+//# sourceMappingURL=index.js.map