@gomcp/analytics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mouaad Aallam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# @gomcp/analytics
+
+Lightweight analytics and observability for [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers. Zero required dependencies, framework-agnostic, works at the JSON-RPC transport level.
+
+## Features
+
+- **Transport-level interception** — works with any MCP server (official SDK, FastMCP, custom)
+- **Handler wrapping** — instrument individual tool handlers for granular control
+- **Multiple exporters** — console, JSON file, OpenTelemetry OTLP, or custom functions
+- **In-memory stats** — p50/p95/p99 latencies, error rates, call counts per tool
+- **Sampling** — configurable sample rate to control overhead
+- **Zero required deps** — only `@modelcontextprotocol/sdk` as a peer dependency
+
+## Installation
+
+```bash
+npm install @gomcp/analytics
+```
+
+## Quick Start
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { McpAnalytics } from "@gomcp/analytics";
+
+// 1. Create analytics instance
+const analytics = new McpAnalytics({
+  exporter: "console",
+});
+
+// 2. Create your server and transport
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => crypto.randomUUID() });
+
+// 3. Instrument the transport (intercepts all tool calls automatically)
+const trackedTransport = analytics.instrument(transport);
+await server.connect(trackedTransport);
+
+// 4. Access stats at any time
+console.log(analytics.getStats());
+// { totalCalls: 42, errorRate: 0.02, tools: { search: { count: 30, p50Ms: 120, ... } } }
+
+// 5. Clean shutdown
+await analytics.shutdown();
+```
+
+## API
+
+### `new McpAnalytics(config)`
+
+Create an analytics instance.
+
+| Option            | Type                                                     | Default | Description                                               |
+|-------------------|----------------------------------------------------------|---------|-----------------------------------------------------------|
+| `exporter`        | `"console" \| "json" \| "otlp" \| Function`              | —       | Where to send metrics (required)                          |
+| `json`            | `{ path: string }`                                       | —       | JSON file config (required when `exporter: "json"`)       |
+| `otlp`            | `{ endpoint: string, headers?: Record<string, string> }` | —       | OTLP config (required when `exporter: "otlp"`)            |
+| `sampleRate`      | `number`                                                 | `1.0`   | Fraction of calls to sample (0.0 to 1.0)                  |
+| `flushIntervalMs` | `number`                                                 | `5000`  | How often to flush events to the exporter                 |
+| `maxBufferSize`   | `number`                                                 | `10000` | Max events in the ring buffer                             |
+| `metadata`        | `Record<string, string>`                                 | —       | Metadata added to every event                             |
+| `tracing`         | `boolean`                                                | `false` | Create OpenTelemetry spans via the global tracer provider |
+
+### `analytics.instrument(transport)`
+
+Wrap an MCP transport to automatically intercept all `tools/call` requests and responses. Returns a proxy transport that can be used in place of the original.
+
+```typescript
+const trackedTransport = analytics.instrument(transport);
+await server.connect(trackedTransport);
+```
+
+### `analytics.track(handler, toolName?)`
+
+Wrap a tool handler function to record metrics. Use this when you want per-handler control instead of transport-level interception.
+
+```typescript
+server.tool("search", schema, analytics.track(async (params) => {
+  return await doSearch(params);
+}, "search"));
+```
+
+### `analytics.getStats()`
+
+Returns an `AnalyticsSnapshot` with aggregated metrics:
+
+```typescript
+interface AnalyticsSnapshot {
+  totalCalls: number;
+  totalErrors: number;
+  errorRate: number;
+  uptimeMs: number;
+  tools: Record<string, ToolStats>;
+}
+
+interface ToolStats {
+  count: number;
+  errorCount: number;
+  errorRate: number;
+  p50Ms: number;
+  p95Ms: number;
+  p99Ms: number;
+  avgMs: number;
+  lastCalledAt: number;  // Unix timestamp ms
+}
+```
+
+### `analytics.getToolStats(toolName)`
+
+Get stats for a specific tool. Returns `undefined` if the tool hasn't been called.
+
+### `analytics.flush()`
+
+Force-flush all pending events to the exporter.
+
+### `analytics.reset()`
+
+Clear all collected data.
+
+### `analytics.shutdown()`
+
+Stop the flush timer and flush remaining events. Call this on process exit.
+
+## Exporters
+
+### Console
+
+Pretty-prints batches to stdout:
+
+```typescript
+new McpAnalytics({ exporter: "console" });
+```
+
+### JSON File
+
+Appends events as JSONL (one JSON object per line):
+
+```typescript
+new McpAnalytics({
+  exporter: "json",
+  json: { path: "./analytics.jsonl" },
+});
+```
+
+### OpenTelemetry OTLP
+
+Sends events as OpenTelemetry spans. Requires `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`, and `@opentelemetry/exporter-trace-otlp-http` as peer dependencies (dynamically imported only when used):
+
+```bash
+npm install @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http
+```
+
+```typescript
+new McpAnalytics({
+  exporter: "otlp",
+  otlp: {
+    endpoint: "http://localhost:4318/v1/traces",
+    headers: { "Authorization": "Bearer ..." },
+  },
+});
+```
+
+### Custom Function
+
+Provide your own export function:
+
+```typescript
+new McpAnalytics({
+  exporter: async (events) => {
+    await fetch("https://my-analytics.example.com/ingest", {
+      method: "POST",
+      body: JSON.stringify(events),
+    });
+  },
+});
+```
+
+## Tracing (dd-trace / OpenTelemetry)
+
+When you use an APM like [dd-trace](https://github.com/DataDog/dd-trace-js) that registers itself as the global OpenTelemetry provider, you can make MCP tool calls appear as spans in your existing traces with zero extra configuration:
+
+```typescript
+import "dd-trace/init"; // sets up dd-trace as global OTel provider
+
+import { McpAnalytics } from "@gomcp/analytics";
+
+const analytics = new McpAnalytics({
+  exporter: "console",
+  tracing: true, // creates spans via the global tracer provider
+});
+
+const tracked = analytics.instrument(transport);
+await server.connect(tracked);
+// Tool calls now appear as "mcp.tool_call" spans in Datadog
+```
+
+This works with any OTel-compatible provider (Datadog, New Relic, Honeycomb, etc.). The `tracing` flag dynamically imports `@opentelemetry/api` and uses the global tracer — no OTLP exporter setup needed.
+
+When using `analytics.track()` (handler wrapping), the handler executes inside the span context, so any downstream OTel-instrumented calls (HTTP, DB, etc.) become children of the MCP tool span.
+
+### OTLP exporter with global provider
+
+If you're already using the OTLP exporter and want it to send spans through your global provider instead of creating an isolated one:
+
+```typescript
+new McpAnalytics({
+  exporter: "otlp",
+  otlp: {
+    endpoint: "unused-when-global", // ignored when useGlobalProvider is true
+    useGlobalProvider: true,
+  },
+});
+```
+
+### Span attributes
+
+Each `mcp.tool_call` span includes these attributes:
+
+| Attribute                | Description                                     |
+|--------------------------|-------------------------------------------------|
+| `mcp.tool.name`          | Tool name                                       |
+| `mcp.tool.input_size`    | Input size in bytes                             |
+| `mcp.tool.duration_ms`   | Duration (OTLP exporter only)                   |
+| `mcp.tool.success`       | Whether the call succeeded (OTLP exporter only) |
+| `mcp.tool.output_size`   | Output size in bytes (OTLP exporter only)       |
+| `mcp.tool.error_message` | Error message if failed (OTLP exporter only)    |
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,68 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { AnalyticsConfig, AnalyticsSnapshot, InstrumentedTransport, ToolStats } from "./types.js";
+/**
+ * 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();
+ * ```
+ */
+export declare class McpAnalytics {
+    private readonly collector;
+    private readonly sampleRate;
+    private readonly metadata?;
+    private readonly tracing;
+    constructor(config: AnalyticsConfig);
+    /**
+     * Instrument an MCP transport to automatically track all tool calls.
+     * Returns proxy transport that can be used in place of the original.
+     */
+    instrument(transport: Transport): InstrumentedTransport;
+    /**
+     * 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<TArgs extends unknown[], TResult>(handler: (...args: TArgs) => TResult | Promise<TResult>, toolName?: string): (...args: TArgs) => Promise<TResult>;
+    /**
+     * Get a snapshot of all analytics data.
+     */
+    getStats(): AnalyticsSnapshot;
+    /**
+     * Get stats for a specific tool.
+     */
+    getToolStats(toolName: string): ToolStats | undefined;
+    /**
+     * Flush all pending events to the exporter.
+     */
+    flush(): Promise<void>;
+    /**
+     * Reset all collected data.
+     */
+    reset(): void;
+    /**
+     * Stop the analytics instance (clears flush timer and flushes remaining events).
+     */
+    shutdown(): Promise<void>;
+    private resolveExporter;
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAQ/E,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAEjB,qBAAqB,EACrB,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,MAAM,EAAE,eAAe;IAanC;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,qBAAqB;IAUvD;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EACpC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACvD,QAAQ,CAAC,EAAE,MAAM,GAChB,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC;IAYvC;;OAEG;IACH,QAAQ,IAAI,iBAAiB;IAI7B;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIrD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,OAAO,CAAC,eAAe;CA0BxB"}

package/dist/analytics.js

@@ -0,0 +1,113 @@
+import { Collector } from "./collector.js";
+import { createConsoleExporter } from "./exporters/console.js";
+import { createCustomExporter } from "./exporters/custom.js";
+import { createJsonExporter } from "./exporters/json.js";
+import { createOtlpExporter } from "./exporters/otlp.js";
+import { instrumentTransport, wrapToolHandler } from "./middleware.js";
+/**
+ * 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();
+ * ```
+ */
+export class McpAnalytics {
+    collector;
+    sampleRate;
+    metadata;
+    tracing;
+    constructor(config) {
+        this.sampleRate = config.sampleRate ?? 1;
+        this.metadata = config.metadata;
+        this.tracing = config.tracing ?? false;
+        const exporter = this.resolveExporter(config);
+        this.collector = new Collector(config.maxBufferSize ?? 10_000, exporter, config.flushIntervalMs ?? 5_000);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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) {
+        const name = toolName ?? (handler.name || "anonymous");
+        return wrapToolHandler(name, 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);
+    }
+    /**
+     * 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);
+            }
+        }
+    }
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/collector.d.ts

@@ -0,0 +1,44 @@
+import type { AnalyticsSnapshot, ExporterFn, ToolCallEvent, ToolStats } from "./types.js";
+/**
+ * In-memory ring buffer that collects ToolCallEvents, computes stats,
+ * and periodically flushes to an exporter.
+ */
+export declare class Collector {
+    private readonly maxBufferSize;
+    private readonly exporter;
+    private readonly buffer;
+    private readonly accumulators;
+    private totalCalls;
+    private totalErrors;
+    private readonly startTime;
+    private flushTimer;
+    /** Events accumulated since last flush, to be sent to the exporter */
+    private pending;
+    constructor(maxBufferSize: number, exporter: ExporterFn, flushIntervalMs: number);
+    /**
+     * Record a new tool call event.
+     */
+    record(event: ToolCallEvent): void;
+    /**
+     * Get aggregated stats for all tools.
+     */
+    getStats(): AnalyticsSnapshot;
+    /**
+     * Get stats for a single tool.
+     */
+    getToolStats(toolName: string): ToolStats | undefined;
+    /**
+     * Flush pending events to the exporter.
+     */
+    flush(): Promise<void>;
+    /**
+     * Reset all collected data.
+     */
+    reset(): void;
+    /**
+     * Stop the flush timer and flush remaining events.
+     */
+    destroy(): Promise<void>;
+    private accToStats;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AAepB;;;GAGG;AACH,qBAAa,SAAS;IAYlB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAZ3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,OAAO,CAAC,UAAU,CAA6C;IAC/D,sEAAsE;IACtE,OAAO,CAAC,OAAO,CAAuB;gBAGnB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,EACrC,eAAe,EAAE,MAAM;IAiBzB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IA8BlC;;OAEG;IACH,QAAQ,IAAI,iBAAiB;IAc7B;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAMrD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,UAAU;CAYnB"}

package/dist/collector.js

@@ -0,0 +1,132 @@
+import { percentile, sortedInsert } from "./utils.js";
+/**
+ * In-memory ring buffer that collects ToolCallEvents, computes stats,
+ * and periodically flushes to an exporter.
+ */
+export class Collector {
+    maxBufferSize;
+    exporter;
+    buffer = [];
+    accumulators = new Map();
+    totalCalls = 0;
+    totalErrors = 0;
+    startTime = Date.now();
+    flushTimer;
+    /** Events accumulated since last flush, to be sent to the exporter */
+    pending = [];
+    constructor(maxBufferSize, exporter, flushIntervalMs) {
+        this.maxBufferSize = maxBufferSize;
+        this.exporter = exporter;
+        if (flushIntervalMs > 0) {
+            this.flushTimer = setInterval(() => {
+                void this.flush();
+            }, flushIntervalMs);
+            // Don't hold the process open for analytics flushing
+            if (this.flushTimer &&
+                typeof this.flushTimer === "object" &&
+                "unref" in this.flushTimer) {
+                this.flushTimer.unref();
+            }
+        }
+    }
+    /**
+     * Record a new tool call event.
+     */
+    record(event) {
+        // Ring buffer: drop oldest when full
+        if (this.buffer.length >= this.maxBufferSize) {
+            this.buffer.shift();
+        }
+        this.buffer.push(event);
+        this.pending.push(event);
+        this.totalCalls++;
+        if (!event.success)
+            this.totalErrors++;
+        // Update per-tool accumulator
+        let acc = this.accumulators.get(event.toolName);
+        if (!acc) {
+            acc = {
+                count: 0,
+                errorCount: 0,
+                totalMs: 0,
+                durations: [],
+                lastCalledAt: 0,
+            };
+            this.accumulators.set(event.toolName, acc);
+        }
+        acc.count++;
+        if (!event.success)
+            acc.errorCount++;
+        acc.totalMs += event.durationMs;
+        sortedInsert(acc.durations, event.durationMs);
+        acc.lastCalledAt = event.timestamp;
+    }
+    /**
+     * Get aggregated stats for all tools.
+     */
+    getStats() {
+        const tools = {};
+        for (const [name, acc] of this.accumulators) {
+            tools[name] = this.accToStats(acc);
+        }
+        return {
+            totalCalls: this.totalCalls,
+            totalErrors: this.totalErrors,
+            errorRate: this.totalCalls > 0 ? this.totalErrors / this.totalCalls : 0,
+            uptimeMs: Date.now() - this.startTime,
+            tools,
+        };
+    }
+    /**
+     * Get stats for a single tool.
+     */
+    getToolStats(toolName) {
+        const acc = this.accumulators.get(toolName);
+        if (!acc)
+            return undefined;
+        return this.accToStats(acc);
+    }
+    /**
+     * Flush pending events to the exporter.
+     */
+    async flush() {
+        if (this.pending.length === 0)
+            return;
+        const batch = this.pending;
+        this.pending = [];
+        await this.exporter(batch);
+    }
+    /**
+     * Reset all collected data.
+     */
+    reset() {
+        this.buffer.length = 0;
+        this.pending.length = 0;
+        this.accumulators.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 = undefined;
+        }
+        await this.flush();
+    }
+    accToStats(acc) {
+        return {
+            count: acc.count,
+            errorCount: acc.errorCount,
+            errorRate: acc.count > 0 ? acc.errorCount / acc.count : 0,
+            p50Ms: percentile(acc.durations, 50),
+            p95Ms: percentile(acc.durations, 95),
+            p99Ms: percentile(acc.durations, 99),
+            avgMs: acc.count > 0 ? acc.totalMs / acc.count : 0,
+            lastCalledAt: acc.lastCalledAt,
+        };
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AActD;;;GAGG;AACH,MAAM,OAAO,SAAS;IAYD;IACA;IAZF,MAAM,GAAoB,EAAE,CAAC;IAC7B,YAAY,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC3D,UAAU,GAAG,CAAC,CAAC;IACf,WAAW,GAAG,CAAC,CAAC;IACP,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEhC,UAAU,CAA6C;IAC/D,sEAAsE;IAC9D,OAAO,GAAoB,EAAE,CAAC;IAEtC,YACmB,aAAqB,EACrB,QAAoB,EACrC,eAAuB;QAFN,kBAAa,GAAb,aAAa,CAAQ;QACrB,aAAQ,GAAR,QAAQ,CAAY;QAGrC,IAAI,eAAe,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;gBACjC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,CAAC,EAAE,eAAe,CAAC,CAAC;YACpB,qDAAqD;YACrD,IACE,IAAI,CAAC,UAAU;gBACf,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;gBACnC,OAAO,IAAI,IAAI,CAAC,UAAU,EAC1B,CAAC;gBACD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAoB;QACzB,qCAAqC;QACrC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEzB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAEvC,8BAA8B;QAC9B,IAAI,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG;gBACJ,KAAK,EAAE,CAAC;gBACR,UAAU,EAAE,CAAC;gBACb,OAAO,EAAE,CAAC;gBACV,SAAS,EAAE,EAAE;gBACb,YAAY,EAAE,CAAC;aAChB,CAAC;YACF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;QACD,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,GAAG,CAAC,UAAU,EAAE,CAAC;QACrC,GAAG,CAAC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC;QAChC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9C,GAAG,CAAC,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,KAAK,GAA8B,EAAE,CAAC;QAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC;QACD,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACvE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS;YACrC,KAAK;SACN,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAAgB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC9B,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAEO,UAAU,CAAC,GAAoB;QACrC,OAAO;YACL,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,SAAS,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzD,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;YACpC,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;YACpC,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;YACpC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAClD,YAAY,EAAE,GAAG,CAAC,YAAY;SAC/B,CAAC;IACJ,CAAC;CACF"}

package/dist/exporters/console.d.ts

@@ -0,0 +1,6 @@
+import type { ToolCallEvent } from "../types.js";
+/**
+ * Console exporter: pretty-prints each batch of events to stdout.
+ */
+export declare function createConsoleExporter(): (events: ToolCallEvent[]) => Promise<void>;
+//# sourceMappingURL=console.d.ts.map

package/dist/exporters/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/exporters/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,CACvC,MAAM,EAAE,aAAa,EAAE,KACpB,OAAO,CAAC,IAAI,CAAC,CAiBjB"}

package/dist/exporters/console.js

@@ -0,0 +1,18 @@
+/**
+ * Console exporter: pretty-prints each batch of events to stdout.
+ */
+export 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"));
+    };
+}
+//# sourceMappingURL=console.js.map

package/dist/exporters/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/exporters/console.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,qBAAqB;IAGnC,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEhC,MAAM,KAAK,GAAa,CAAC,gCAAgC,CAAC,CAAC;QAE3D,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,MAAM,WAAW,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,CAAC,QAAQ,IAAI,MAAM,IAAI,CAAC,CAAC,UAAU,SAAS,CAAC,CAAC,SAAS,SAAS,CAAC,CAAC,UAAU,IAAI,IAAI,EAAE,CAC7F,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/exporters/custom.d.ts

@@ -0,0 +1,7 @@
+import type { ExporterFn, ToolCallEvent } from "../types.js";
+/**
+ * Wraps a user-provided export function, catching errors to prevent
+ * exporter failures from disrupting the MCP server.
+ */
+export declare function createCustomExporter(fn: ExporterFn): (events: ToolCallEvent[]) => Promise<void>;
+//# sourceMappingURL=custom.d.ts.map