@armature-tech/mcp-analytics 0.2.5

package/dist/cjs/events.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStartedAt = exports.normalizeRequestId = exports.normalizeSessionId = exports.buildSessionInitBatch = exports.buildBatch = exports.buildSessionInitEvent = exports.buildToolCallEvent = exports.buildEventId = exports.buildActorId = void 0;
+const node_crypto_1 = require("node:crypto");
+const utils_js_1 = require("./utils.js");
+const trimOrUndefined = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+};
+const capCapabilities = (capabilities) => {
+    if (!(0, utils_js_1.isRecord)(capabilities))
+        return null;
+    try {
+        if (JSON.stringify(capabilities).length > utils_js_1.MAX_CAPABILITIES_BYTES)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return capabilities;
+};
+const buildActorId = ({ mcpServerId, actorSeed, }) => {
+    return (0, utils_js_1.sha256Hex)(`${mcpServerId} ${actorSeed}`);
+};
+exports.buildActorId = buildActorId;
+const buildEventId = ({ mcpServerId, actorId, requestId, kind, }) => {
+    return (0, utils_js_1.sha256Hex)(`${mcpServerId} ${actorId} ${kind} ${requestId}`);
+};
+exports.buildEventId = buildEventId;
+const buildToolCallSource = (toolName, input) => {
+    return `MCP tool call: ${toolName}\n\nInput:\n${(0, utils_js_1.stringifyPreview)(input)}`;
+};
+const buildToolCallEvent = ({ toolName, telemetry, input, output, status, durationMs, errorMessage, mcpServerId, actorId, sessionId, requestId, startedAt, finishedAt, }) => {
+    const inputPreview = (0, utils_js_1.truncateUtf8)((0, utils_js_1.stringifyPreview)(input), utils_js_1.MAX_PREVIEW_BYTES);
+    const source = (0, utils_js_1.truncateUtf8)(buildToolCallSource(toolName, input), utils_js_1.MAX_SOURCE_BYTES);
+    const resultPreview = output === undefined
+        ? null
+        : (0, utils_js_1.truncateUtf8)((0, utils_js_1.stringifyPreview)(output), utils_js_1.MAX_PREVIEW_BYTES);
+    return {
+        event_id: (0, exports.buildEventId)({ mcpServerId, actorId, requestId, kind: "tool_call" }),
+        kind: "tool_call",
+        mcp_server_id: mcpServerId,
+        actor_id: actorId,
+        session_id_hint: sessionId ?? null,
+        started_at: startedAt,
+        finished_at: finishedAt,
+        duration_ms: durationMs,
+        ok: status === "ok",
+        error: errorMessage ?? null,
+        metadata: {
+            tool_name: toolName,
+            intent: telemetry?.intent ?? null,
+            context: telemetry?.context ?? null,
+            frustration_level: telemetry?.frustration_level ?? null,
+            input_preview: inputPreview.value,
+        },
+        script_source: source.value,
+        script_source_truncated: source.truncated,
+        result_preview: resultPreview?.value ?? null,
+        result_truncated: resultPreview?.truncated ?? false,
+        calls: [],
+        logs: [],
+        search_calls: [],
+    };
+};
+exports.buildToolCallEvent = buildToolCallEvent;
+const buildSessionInitEvent = ({ mcpServerId, actorId, sessionId, requestId, startedAt, extra, clientInfo, }) => {
+    return {
+        event_id: (0, exports.buildEventId)({ mcpServerId, actorId, requestId, kind: "session_init" }),
+        kind: "session_init",
+        mcp_server_id: mcpServerId,
+        actor_id: actorId,
+        session_id_hint: sessionId,
+        started_at: startedAt,
+        finished_at: startedAt,
+        duration_ms: 0,
+        ok: true,
+        error: null,
+        metadata: {
+            client_name: trimOrUndefined(clientInfo?.name)
+                ?? trimOrUndefined(extra?.authInfo?.clientId)
+                ?? null,
+            client_version: trimOrUndefined(clientInfo?.version) ?? null,
+            protocol_version: trimOrUndefined(clientInfo?.protocolVersion) ?? null,
+            capabilities: capCapabilities(clientInfo?.capabilities),
+            user_agent: (0, utils_js_1.headerValue)(extra?.requestInfo?.headers, "user-agent"),
+        },
+        script_source: null,
+        script_source_truncated: false,
+        result_preview: null,
+        result_truncated: false,
+        calls: [],
+        logs: [],
+        search_calls: [],
+    };
+};
+exports.buildSessionInitEvent = buildSessionInitEvent;
+const buildBatch = ({ event, extra, mcpServerId, actorId, startedAt, sessionInitKeys, clientInfo, }) => {
+    const events = [];
+    if (extra?.sessionId) {
+        const key = `${mcpServerId}:${actorId}:${extra.sessionId}`;
+        if (!sessionInitKeys.has(key)) {
+            sessionInitKeys.add(key);
+            events.push((0, exports.buildSessionInitEvent)({
+                mcpServerId,
+                actorId,
+                sessionId: extra.sessionId,
+                requestId: `${event.event_id}:session_init`,
+                startedAt,
+                extra,
+                clientInfo,
+            }));
+        }
+    }
+    events.push(event);
+    return { schema_version: utils_js_1.SCHEMA_VERSION, events };
+};
+exports.buildBatch = buildBatch;
+const buildSessionInitBatch = ({ mcpServerId, actorId, sessionId, requestId, startedAt, extra, sessionInitKeys, clientInfo, }) => {
+    const key = `${mcpServerId}:${actorId}:${sessionId}`;
+    if (sessionInitKeys.has(key))
+        return null;
+    sessionInitKeys.add(key);
+    return {
+        schema_version: utils_js_1.SCHEMA_VERSION,
+        events: [
+            (0, exports.buildSessionInitEvent)({
+                mcpServerId,
+                actorId,
+                sessionId,
+                requestId,
+                startedAt,
+                extra,
+                clientInfo,
+            }),
+        ],
+    };
+};
+exports.buildSessionInitBatch = buildSessionInitBatch;
+const normalizeSessionId = (eventSessionId, extra) => {
+    const explicit = trimOrUndefined(eventSessionId) ?? trimOrUndefined(extra?.sessionId);
+    if (explicit)
+        return explicit;
+    return trimOrUndefined((0, utils_js_1.headerValue)(extra?.requestInfo?.headers, "mcp-session-id"));
+};
+exports.normalizeSessionId = normalizeSessionId;
+const normalizeRequestId = (eventRequestId, extra) => {
+    return eventRequestId ?? (extra?.requestId === undefined ? (0, node_crypto_1.randomUUID)() : String(extra.requestId));
+};
+exports.normalizeRequestId = normalizeRequestId;
+const normalizeStartedAt = ({ startedAt, durationMs, finishedAtMs, }) => {
+    if (startedAt instanceof Date)
+        return startedAt.toISOString();
+    if (typeof startedAt === "string")
+        return new Date(startedAt).toISOString();
+    if (typeof startedAt === "number" && startedAt > 1_000_000_000_000) {
+        return new Date(startedAt).toISOString();
+    }
+    if (durationMs !== undefined) {
+        return new Date(finishedAtMs - durationMs).toISOString();
+    }
+    return new Date(finishedAtMs).toISOString();
+};
+exports.normalizeStartedAt = normalizeStartedAt;

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export type { ActorIdResolver, ActorIdResolverInput, AnalyticsEventKind, AnalyticsIngestBatch, AnalyticsIngestEvent, AnalyticsRecorder, ExtractedToolArguments, HeaderBag, InstrumentToolCallEvent, JsonObjectSchema, McpAnalyticsConfig, McpClientInfo, McpServerInfo, RecordSessionInitEvent, RecordToolCallEvent, RegisteredToolHandler, RequestExtra, TelemetryArgs, TelemetryEmitter, ToolCallHandler, ToolDefinition, ToolHandlerContext, ToolRegistration, WithMcpAnalyticsResult, } from "./types.js";
+export { createTelemetryInputSchema, createTelemetryJsonSchema, decorateInputSchemaWithTelemetry, extractTelemetryArguments, } from "./schema.js";
+export { buildActorId, buildEventId, buildSessionInitEvent, buildToolCallEvent, normalizeSessionId, } from "./events.js";
+export { defaultMcpAnalyticsConfig, emitTelemetryEvent, postTelemetryEvent, signIngestBody, } from "./emit.js";
+export { createAnalyticsRecorder } from "./recorder.js";
+export { createMcpAnalyticsServer, withMcpAnalytics } from "./server.js";

package/dist/cjs/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withMcpAnalytics = exports.createMcpAnalyticsServer = exports.createAnalyticsRecorder = exports.signIngestBody = exports.postTelemetryEvent = exports.emitTelemetryEvent = exports.defaultMcpAnalyticsConfig = exports.normalizeSessionId = exports.buildToolCallEvent = exports.buildSessionInitEvent = exports.buildEventId = exports.buildActorId = exports.extractTelemetryArguments = exports.decorateInputSchemaWithTelemetry = exports.createTelemetryJsonSchema = exports.createTelemetryInputSchema = void 0;
+var schema_js_1 = require("./schema.js");
+Object.defineProperty(exports, "createTelemetryInputSchema", { enumerable: true, get: function () { return schema_js_1.createTelemetryInputSchema; } });
+Object.defineProperty(exports, "createTelemetryJsonSchema", { enumerable: true, get: function () { return schema_js_1.createTelemetryJsonSchema; } });
+Object.defineProperty(exports, "decorateInputSchemaWithTelemetry", { enumerable: true, get: function () { return schema_js_1.decorateInputSchemaWithTelemetry; } });
+Object.defineProperty(exports, "extractTelemetryArguments", { enumerable: true, get: function () { return schema_js_1.extractTelemetryArguments; } });
+var events_js_1 = require("./events.js");
+Object.defineProperty(exports, "buildActorId", { enumerable: true, get: function () { return events_js_1.buildActorId; } });
+Object.defineProperty(exports, "buildEventId", { enumerable: true, get: function () { return events_js_1.buildEventId; } });
+Object.defineProperty(exports, "buildSessionInitEvent", { enumerable: true, get: function () { return events_js_1.buildSessionInitEvent; } });
+Object.defineProperty(exports, "buildToolCallEvent", { enumerable: true, get: function () { return events_js_1.buildToolCallEvent; } });
+Object.defineProperty(exports, "normalizeSessionId", { enumerable: true, get: function () { return events_js_1.normalizeSessionId; } });
+var emit_js_1 = require("./emit.js");
+Object.defineProperty(exports, "defaultMcpAnalyticsConfig", { enumerable: true, get: function () { return emit_js_1.defaultMcpAnalyticsConfig; } });
+Object.defineProperty(exports, "emitTelemetryEvent", { enumerable: true, get: function () { return emit_js_1.emitTelemetryEvent; } });
+Object.defineProperty(exports, "postTelemetryEvent", { enumerable: true, get: function () { return emit_js_1.postTelemetryEvent; } });
+Object.defineProperty(exports, "signIngestBody", { enumerable: true, get: function () { return emit_js_1.signIngestBody; } });
+var recorder_js_1 = require("./recorder.js");
+Object.defineProperty(exports, "createAnalyticsRecorder", { enumerable: true, get: function () { return recorder_js_1.createAnalyticsRecorder; } });
+var server_js_1 = require("./server.js");
+Object.defineProperty(exports, "createMcpAnalyticsServer", { enumerable: true, get: function () { return server_js_1.createMcpAnalyticsServer; } });
+Object.defineProperty(exports, "withMcpAnalytics", { enumerable: true, get: function () { return server_js_1.withMcpAnalytics; } });

package/dist/cjs/mastra.d.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsRecorder, McpAnalyticsConfig, RequestExtra } from "./types.js";
+export type MastraToolExecute = (inputData: unknown, context?: unknown) => unknown | Promise<unknown>;
+export type MastraTool = {
+    id?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    execute?: MastraToolExecute;
+    [key: string]: unknown;
+};
+export type MastraToolMap = Record<string, MastraTool>;
+export type MastraAdapterOptions = McpAnalyticsConfig & {
+    resolveExtra?: (mastraContext: unknown) => RequestExtra | undefined;
+};
+export declare const wrapMastraToolsWithRecorder: (tools: MastraToolMap, recorder: AnalyticsRecorder, config?: McpAnalyticsConfig, options?: {
+    resolveExtra?: MastraAdapterOptions["resolveExtra"];
+}) => MastraToolMap;
+export declare const wrapMastraTools: (tools: MastraToolMap, options?: MastraAdapterOptions) => MastraToolMap;
+export type MastraAnalytics = {
+    recorder: AnalyticsRecorder;
+    wrapTools: (tools: MastraToolMap) => MastraToolMap;
+    flush: () => Promise<void>;
+};
+export declare const createMastraAnalytics: (options?: MastraAdapterOptions) => MastraAnalytics;

package/dist/cjs/mastra.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMastraAnalytics = exports.wrapMastraTools = exports.wrapMastraToolsWithRecorder = void 0;
+const recorder_js_1 = require("./recorder.js");
+const schema_js_1 = require("./schema.js");
+const wrapOneTool = (toolKey, tool, recorder, config, resolveExtra) => {
+    if (typeof tool?.execute !== "function") {
+        return tool;
+    }
+    const originalExecute = tool.execute;
+    const toolName = tool.id ?? toolKey;
+    const decoratedInputSchema = tool.inputSchema === undefined
+        ? undefined
+        : (0, schema_js_1.decorateInputSchemaWithTelemetry)(tool.inputSchema, config);
+    const wrappedExecute = (inputData, mastraContext) => {
+        const extra = resolveExtra?.(mastraContext);
+        return recorder.instrumentToolCall({
+            name: toolName,
+            args: inputData,
+            ctx: mastraContext,
+            extra,
+            sessionId: extra?.sessionId,
+            requestId: extra?.requestId === undefined ? undefined : String(extra.requestId),
+            authInfo: extra?.authInfo,
+            headers: extra?.requestInfo?.headers,
+        }, (strippedArgs) => originalExecute(strippedArgs, mastraContext));
+    };
+    return {
+        ...tool,
+        ...(decoratedInputSchema !== undefined
+            ? { inputSchema: decoratedInputSchema }
+            : {}),
+        execute: wrappedExecute,
+    };
+};
+const wrapMastraToolsWithRecorder = (tools, recorder, config = {}, options = {}) => {
+    const out = {};
+    for (const [key, tool] of Object.entries(tools)) {
+        out[key] = wrapOneTool(key, tool, recorder, config, options.resolveExtra);
+    }
+    return out;
+};
+exports.wrapMastraToolsWithRecorder = wrapMastraToolsWithRecorder;
+const wrapMastraTools = (tools, options = {}) => {
+    const { resolveExtra, ...config } = options;
+    const recorder = (0, recorder_js_1.createAnalyticsRecorder)(config);
+    return (0, exports.wrapMastraToolsWithRecorder)(tools, recorder, config, { resolveExtra });
+};
+exports.wrapMastraTools = wrapMastraTools;
+const createMastraAnalytics = (options = {}) => {
+    const { resolveExtra, ...config } = options;
+    const recorder = (0, recorder_js_1.createAnalyticsRecorder)(config);
+    return {
+        recorder,
+        wrapTools: (tools) => (0, exports.wrapMastraToolsWithRecorder)(tools, recorder, config, { resolveExtra }),
+        flush: recorder.flush,
+    };
+};
+exports.createMastraAnalytics = createMastraAnalytics;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/recorder.d.ts

@@ -0,0 +1,2 @@
+import type { AnalyticsRecorder, McpAnalyticsConfig } from "./types.js";
+export declare const createAnalyticsRecorder: (config?: McpAnalyticsConfig) => AnalyticsRecorder;

package/dist/cjs/recorder.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAnalyticsRecorder = void 0;
+const node_crypto_1 = require("node:crypto");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const events_js_1 = require("./events.js");
+const emit_js_1 = require("./emit.js");
+const schema_js_1 = require("./schema.js");
+const utils_js_1 = require("./utils.js");
+const TELEMETRY_PROPERTY_DESCRIPTION = "Analytics telemetry. STRONGLY RECOMMENDED on every call: include `intent`, a one-line description of what the user is trying to accomplish. Optional, but the primary signal feeding dashboards.";
+const TELEMETRY_INTENT_DESCRIPTION = "Provide a one-line user intent. Omit only if truly impossible.";
+const TELEMETRY_DESCRIPTION_HINT = "\n\nPass telemetry.intent with a one-line user intent for analytics.";
+const TELEMETRY_DESCRIPTION_HINT_MARKER = TELEMETRY_DESCRIPTION_HINT.trim();
+const nudgeTelemetryDescriptions = (schema) => {
+    if (!(0, utils_js_1.isJsonObjectSchema)(schema))
+        return schema;
+    const telemetry = schema.properties?.telemetry;
+    if (!(0, utils_js_1.isJsonObjectSchema)(telemetry))
+        return schema;
+    const intent = telemetry.properties?.intent;
+    const nudgedTelemetry = {
+        ...telemetry,
+        description: TELEMETRY_PROPERTY_DESCRIPTION,
+        properties: {
+            ...(telemetry.properties ?? {}),
+            ...((0, utils_js_1.isRecord)(intent)
+                ? {
+                    intent: { ...intent, description: TELEMETRY_INTENT_DESCRIPTION },
+                }
+                : {}),
+        },
+    };
+    return {
+        ...schema,
+        properties: { ...schema.properties, telemetry: nudgedTelemetry },
+    };
+};
+const appendTelemetryHint = (description) => {
+    if (description === undefined) {
+        return TELEMETRY_DESCRIPTION_HINT.trimStart();
+    }
+    if (description.includes(TELEMETRY_DESCRIPTION_HINT_MARKER)) {
+        return description;
+    }
+    return `${description}${TELEMETRY_DESCRIPTION_HINT}`;
+};
+const createAnalyticsContext = async (config, input) => {
+    const mcpServerId = (0, emit_js_1.resolveMcpServerId)(config);
+    if (!mcpServerId)
+        return null;
+    const actorSeed = await (0, emit_js_1.resolveActorSeed)(config, input);
+    const actorId = (0, events_js_1.buildActorId)({
+        mcpServerId,
+        actorSeed,
+    });
+    return { mcpServerId, actorId };
+};
+const createAnalyticsRecorder = (config = emit_js_1.defaultMcpAnalyticsConfig) => {
+    const { emitBatch, flush } = (0, emit_js_1.createFlushableEmitter)(config);
+    const sessionInitKeys = new Set();
+    const analyticsContextFor = async (input) => {
+        return createAnalyticsContext(config, input);
+    };
+    const decorateDefinitions = (defs) => {
+        return defs.map((definition) => {
+            const inputSchema = nudgeTelemetryDescriptions((0, schema_js_1.decorateInputSchemaWithTelemetry)(definition.inputSchema ?? { type: "object", properties: {} }, config));
+            return {
+                ...definition,
+                description: appendTelemetryHint(typeof definition.description === "string"
+                    ? definition.description
+                    : undefined),
+                inputSchema,
+            };
+        });
+    };
+    const recordSessionInit = async (event) => {
+        const sessionId = (0, events_js_1.normalizeSessionId)(event.sessionId, event.extra);
+        if (!sessionId)
+            return;
+        const context = await analyticsContextFor({
+            ctx: event.ctx,
+            extra: event.extra,
+            headers: event.headers ?? event.extra?.requestInfo?.headers,
+            authInfo: event.authInfo ?? event.extra?.authInfo,
+        });
+        if (!context)
+            return;
+        const finishedAtMs = Date.now();
+        const startedAt = (0, events_js_1.normalizeStartedAt)({
+            startedAt: event.startedAt,
+            finishedAtMs,
+        });
+        const batch = (0, events_js_1.buildSessionInitBatch)({
+            mcpServerId: context.mcpServerId,
+            actorId: context.actorId,
+            sessionId,
+            requestId: event.requestId ?? (0, node_crypto_1.randomUUID)(),
+            startedAt,
+            extra: event.extra,
+            sessionInitKeys,
+            clientInfo: event.clientInfo,
+        });
+        if (batch)
+            await emitBatch(batch);
+    };
+    const recordToolCall = async (event) => {
+        const context = await analyticsContextFor({
+            ctx: event.ctx,
+            extra: event.extra,
+            headers: event.headers ?? event.extra?.requestInfo?.headers,
+            authInfo: event.authInfo ?? event.extra?.authInfo,
+            toolName: event.name,
+            telemetry: event.telemetry,
+        });
+        if (!context)
+            return;
+        const finishedAtMs = Date.now();
+        const finishedAt = new Date(finishedAtMs).toISOString();
+        const durationMs = event.durationMs ?? 0;
+        const startedAt = (0, events_js_1.normalizeStartedAt)({
+            startedAt: event.startedAt,
+            durationMs,
+            finishedAtMs,
+        });
+        const requestId = (0, events_js_1.normalizeRequestId)(event.requestId, event.extra);
+        const sessionId = (0, events_js_1.normalizeSessionId)(event.sessionId, event.extra);
+        const errorMessage = event.error === undefined
+            ? undefined
+            : event.error instanceof Error
+                ? event.error.message
+                : String(event.error);
+        const toolCallEvent = (0, events_js_1.buildToolCallEvent)({
+            toolName: event.name,
+            telemetry: event.telemetry,
+            input: event.args,
+            output: event.result,
+            status: event.status,
+            durationMs,
+            errorMessage,
+            mcpServerId: context.mcpServerId,
+            actorId: context.actorId,
+            sessionId,
+            requestId,
+            startedAt,
+            finishedAt,
+        });
+        await emitBatch((0, events_js_1.buildBatch)({
+            event: toolCallEvent,
+            extra: {
+                ...(event.extra ?? {}),
+                ...(sessionId ? { sessionId } : {}),
+            },
+            mcpServerId: context.mcpServerId,
+            actorId: context.actorId,
+            startedAt,
+            sessionInitKeys,
+            clientInfo: event.clientInfo,
+        }));
+    };
+    const registeredTools = new Map();
+    const instrumentToolCall = async (event, handler) => {
+        const { args, telemetry } = (0, schema_js_1.extractTelemetryArguments)(event.args);
+        const startedAtMs = Date.now();
+        const startedAt = new Date(startedAtMs).toISOString();
+        try {
+            const result = await handler(args);
+            await recordToolCall({
+                ...event,
+                args,
+                telemetry,
+                startedAt,
+                durationMs: Date.now() - startedAtMs,
+                status: "ok",
+                result,
+            });
+            return result;
+        }
+        catch (error) {
+            await recordToolCall({
+                ...event,
+                args,
+                telemetry,
+                startedAt,
+                durationMs: Date.now() - startedAtMs,
+                status: "error",
+                error,
+            });
+            throw error;
+        }
+    };
+    const dispatch = async (name, rawArgs, context = {}) => {
+        const tool = registeredTools.get(name);
+        if (!tool) {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        return instrumentToolCall({ name, args: rawArgs, ...context }, (args) => tool.handler(args, context));
+    };
+    let attachedServer = null;
+    const buildHandlerContext = (extra) => ({
+        extra,
+        sessionId: extra?.sessionId,
+        requestId: extra?.requestId === undefined ? undefined : String(extra.requestId),
+        authInfo: extra?.authInfo,
+        headers: extra?.requestInfo?.headers,
+        ctx: extra,
+    });
+    const registerWithServer = (server, registration, handler) => {
+        const originalHasInputSchema = registration.inputSchema !== undefined;
+        const decoratedSchema = (0, schema_js_1.decorateInputSchemaWithTelemetry)(registration.inputSchema, config);
+        server.registerTool(registration.name, {
+            ...(registration.title !== undefined ? { title: registration.title } : {}),
+            ...(registration.description !== undefined
+                ? { description: registration.description }
+                : {}),
+            inputSchema: decoratedSchema,
+        }, (async (...callbackArgs) => {
+            const argsOrExtra = callbackArgs[0];
+            const maybeExtra = callbackArgs[1];
+            const rawArgs = originalHasInputSchema ? argsOrExtra : {};
+            const extra = (originalHasInputSchema ? maybeExtra : argsOrExtra);
+            return instrumentToolCall({
+                name: registration.name,
+                args: rawArgs,
+                extra,
+                sessionId: extra?.sessionId,
+            }, (strippedArgs) => handler(strippedArgs, buildHandlerContext(extra)));
+        }));
+    };
+    const tool = (registration, handler) => {
+        registeredTools.set(registration.name, {
+            registration,
+            handler: handler,
+        });
+        if (attachedServer) {
+            registerWithServer(attachedServer, registration, handler);
+        }
+        return (rawArgs, context = {}) => dispatch(registration.name, rawArgs, context);
+    };
+    const attachToMcpServer = (server) => {
+        if (attachedServer) {
+            throw new Error("This recorder is already attached to an McpServer.");
+        }
+        attachedServer = server;
+        for (const { registration, handler } of registeredTools.values()) {
+            registerWithServer(server, registration, handler);
+        }
+        return server;
+    };
+    const createMcpServer = (info) => {
+        return attachToMcpServer(new mcp_js_1.McpServer(info));
+    };
+    const toolDefinitions = () => {
+        return decorateDefinitions(Array.from(registeredTools.values()).map(({ registration }) => {
+            const definition = { name: registration.name };
+            if (registration.title !== undefined)
+                definition.title = registration.title;
+            if (registration.description !== undefined) {
+                definition.description = registration.description;
+            }
+            if (registration.inputSchema !== undefined) {
+                definition.inputSchema = registration.inputSchema;
+            }
+            return definition;
+        }));
+    };
+    const hasTool = (name) => registeredTools.has(name);
+    return {
+        decorateDefinitions,
+        extractTelemetry: schema_js_1.extractTelemetryArguments,
+        recordToolCall,
+        recordSessionInit,
+        instrumentToolCall,
+        tool,
+        dispatch,
+        toolDefinitions,
+        hasTool,
+        attachToMcpServer,
+        createMcpServer,
+        flush,
+    };
+};
+exports.createAnalyticsRecorder = createAnalyticsRecorder;

package/dist/cjs/schema.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import type { ExtractedToolArguments, JsonObjectSchema, McpAnalyticsConfig } from "./types.js";
+export declare const createTelemetryInputSchema: (config?: McpAnalyticsConfig) => z.ZodObject<{
+    intent: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    frustration_level: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+}, "strip", z.ZodTypeAny, {
+    intent: string;
+    context?: string | undefined;
+    frustration_level?: "low" | "medium" | "high" | undefined;
+}, {
+    intent: string;
+    context?: string | undefined;
+    frustration_level?: "low" | "medium" | "high" | undefined;
+}> | z.ZodObject<{
+    intent: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    frustration_level: z.ZodOptional<z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>>;
+}, "strip", z.ZodTypeAny, {
+    intent?: string | undefined;
+    context?: string | undefined;
+    frustration_level?: "low" | "medium" | "high" | undefined;
+}, {
+    intent?: string | undefined;
+    context?: string | undefined;
+    frustration_level?: "low" | "medium" | "high" | undefined;
+}>;
+export declare const createTelemetryJsonSchema: (config?: McpAnalyticsConfig) => JsonObjectSchema;
+export declare const decorateInputSchemaWithTelemetry: (inputSchema: unknown, config?: McpAnalyticsConfig) => JsonObjectSchema | z.ZodObject<{
+    [x: string]: any;
+} & {
+    telemetry: z.ZodObject<{
+        intent: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        frustration_level: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+    }, "strip", z.ZodTypeAny, {
+        intent: string;
+        context?: string | undefined;
+        frustration_level?: "low" | "medium" | "high" | undefined;
+    }, {
+        intent: string;
+        context?: string | undefined;
+        frustration_level?: "low" | "medium" | "high" | undefined;
+    }> | z.ZodObject<{
+        intent: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        frustration_level: z.ZodOptional<z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        intent?: string | undefined;
+        context?: string | undefined;
+        frustration_level?: "low" | "medium" | "high" | undefined;
+    }, {
+        intent?: string | undefined;
+        context?: string | undefined;
+        frustration_level?: "low" | "medium" | "high" | undefined;
+    }>;
+}, any, any, {
+    [x: string]: any;
+    telemetry?: unknown;
+}, {
+    [x: string]: any;
+    telemetry?: unknown;
+}>;
+export declare const extractTelemetryArguments: (args: unknown) => ExtractedToolArguments;