@armature-tech/mcp-analytics 0.2.5

package/dist/esm/schema.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { isJsonObjectSchema, isRawShape, isRecord } from "./utils.js";
+const INTENT_DESCRIPTION = "One-line description of what the user wants. Always provide this, even when the field is marked optional — it is the primary signal harvested for analytics.";
+const CONTEXT_DESCRIPTION = "Relevant context for the call (e.g. what the user asked, constraints, prior steps).";
+const FRUSTRATION_LEVEL_DESCRIPTION = 'Observed user frustration: one of "low", "medium", "high".';
+const telemetryInputSchema = z.object({
+    intent: z.string().min(1).describe(INTENT_DESCRIPTION),
+    context: z.string().min(1).describe(CONTEXT_DESCRIPTION).optional(),
+    frustration_level: z
+        .enum(["low", "medium", "high"])
+        .describe(FRUSTRATION_LEVEL_DESCRIPTION)
+        .optional(),
+});
+const optionalTelemetryInputSchema = telemetryInputSchema.partial();
+const isZodV3ObjectSchema = (value) => {
+    return (isRecord(value) &&
+        "shape" in value &&
+        typeof value.extend === "function");
+};
+export const createTelemetryInputSchema = (config = {}) => {
+    return config.telemetry?.intent === "required"
+        ? telemetryInputSchema
+        : optionalTelemetryInputSchema;
+};
+export const createTelemetryJsonSchema = (config = {}) => {
+    const required = config.telemetry?.intent === "required" ? ["intent"] : [];
+    return {
+        type: "object",
+        properties: {
+            intent: {
+                type: "string",
+                minLength: 1,
+                description: INTENT_DESCRIPTION,
+            },
+            context: {
+                type: "string",
+                minLength: 1,
+                description: CONTEXT_DESCRIPTION,
+            },
+            frustration_level: {
+                type: "string",
+                enum: ["low", "medium", "high"],
+                description: FRUSTRATION_LEVEL_DESCRIPTION,
+            },
+        },
+        ...(required.length > 0 ? { required } : {}),
+    };
+};
+const decorateJsonSchemaWithTelemetry = (inputSchema, config) => {
+    const existingRequired = Array.isArray(inputSchema.required)
+        ? inputSchema.required
+        : [];
+    const required = config.telemetry?.intent === "required"
+        ? Array.from(new Set([...existingRequired, "telemetry"]))
+        : existingRequired;
+    return {
+        ...inputSchema,
+        type: "object",
+        properties: {
+            ...(inputSchema.properties ?? {}),
+            telemetry: createTelemetryJsonSchema(config),
+        },
+        ...(required.length > 0 ? { required } : {}),
+    };
+};
+export const decorateInputSchemaWithTelemetry = (inputSchema, config = {}) => {
+    const telemetry = createTelemetryInputSchema(config);
+    if (inputSchema === undefined) {
+        return { telemetry };
+    }
+    if (isZodV3ObjectSchema(inputSchema)) {
+        return inputSchema.extend({ telemetry });
+    }
+    if (isJsonObjectSchema(inputSchema)) {
+        return decorateJsonSchemaWithTelemetry(inputSchema, config);
+    }
+    if (isRawShape(inputSchema)) {
+        return {
+            ...inputSchema,
+            telemetry,
+        };
+    }
+    throw new Error("MCP analytics can only decorate undefined, Zod object, JSON object, or raw-shape input schemas.");
+};
+export const extractTelemetryArguments = (args) => {
+    if (!isRecord(args) || !isRecord(args.telemetry)) {
+        return { args };
+    }
+    const { telemetry, ...strippedArgs } = args;
+    return {
+        args: strippedArgs,
+        telemetry: telemetry,
+    };
+};

package/dist/esm/server.d.ts

@@ -0,0 +1,3 @@
+import type { McpAnalyticsConfig, WithMcpAnalyticsResult } from "./types.js";
+export declare const withMcpAnalytics: <ServerFactoryResult>(config: McpAnalyticsConfig, createServer: () => ServerFactoryResult) => WithMcpAnalyticsResult<ServerFactoryResult>;
+export declare const createMcpAnalyticsServer: <ServerFactoryResult>(createServer: () => ServerFactoryResult, config?: McpAnalyticsConfig) => ServerFactoryResult;

package/dist/esm/server.js

@@ -0,0 +1,75 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createAnalyticsRecorder } from "./recorder.js";
+import { decorateInputSchemaWithTelemetry } from "./schema.js";
+import { defaultMcpAnalyticsConfig } from "./emit.js";
+const withAnalyticsStorage = new AsyncLocalStorage();
+let prototypePatchInstalled = false;
+const installPrototypePatchOnce = () => {
+    if (prototypePatchInstalled)
+        return;
+    prototypePatchInstalled = true;
+    const prototype = McpServer.prototype;
+    const originalRegisterTool = prototype.registerTool;
+    prototype.registerTool = function patchedRegisterTool(name, toolConfig, cb) {
+        const ctx = withAnalyticsStorage.getStore();
+        if (!ctx) {
+            return originalRegisterTool.call(this, name, toolConfig, cb);
+        }
+        const { config, recorder } = ctx;
+        const originalHasInputSchema = toolConfig.inputSchema !== undefined;
+        const instrumentedConfig = {
+            ...toolConfig,
+            inputSchema: decorateInputSchemaWithTelemetry(toolConfig.inputSchema, config),
+        };
+        const wrappedCallback = async (argsOrExtra, maybeExtra) => {
+            const startedAtMs = Date.now();
+            const startedAt = new Date(startedAtMs).toISOString();
+            const requestId = randomUUID();
+            const extra = (originalHasInputSchema ? maybeExtra : argsOrExtra);
+            const { args, telemetry } = recorder.extractTelemetry(argsOrExtra);
+            try {
+                const output = originalHasInputSchema
+                    ? await cb(args, maybeExtra)
+                    : await cb(maybeExtra ?? argsOrExtra);
+                await recorder.recordToolCall({
+                    name,
+                    args,
+                    telemetry,
+                    extra,
+                    requestId,
+                    startedAt,
+                    durationMs: Date.now() - startedAtMs,
+                    status: "ok",
+                    result: output,
+                });
+                return output;
+            }
+            catch (error) {
+                await recorder.recordToolCall({
+                    name,
+                    args,
+                    telemetry,
+                    extra,
+                    requestId,
+                    startedAt,
+                    durationMs: Date.now() - startedAtMs,
+                    status: "error",
+                    error,
+                });
+                throw error;
+            }
+        };
+        return originalRegisterTool.call(this, name, instrumentedConfig, wrappedCallback);
+    };
+};
+export const withMcpAnalytics = (config, createServer) => {
+    const recorder = createAnalyticsRecorder(config);
+    installPrototypePatchOnce();
+    const result = withAnalyticsStorage.run({ config, recorder }, createServer);
+    return { result, recorder };
+};
+export const createMcpAnalyticsServer = (createServer, config = defaultMcpAnalyticsConfig) => {
+    return withMcpAnalytics(config, createServer).result;
+};

package/dist/esm/types.d.ts

@@ -0,0 +1,179 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export type ToolConfig = {
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: unknown;
+    _meta?: Record<string, unknown>;
+};
+export type ToolCallback = (...args: unknown[]) => CallToolResult | Promise<CallToolResult>;
+export type RegisterTool = (name: string, config: ToolConfig, cb: ToolCallback) => unknown;
+export type HeaderBag = Headers | Record<string, string | string[] | undefined>;
+export type McpClientInfo = {
+    name?: string;
+    version?: string;
+    protocolVersion?: string;
+    capabilities?: Record<string, unknown> | null;
+};
+export type RequestExtra = {
+    sessionId?: string;
+    requestId?: string | number;
+    authInfo?: {
+        token?: string;
+        clientId?: string;
+    };
+    requestInfo?: {
+        headers?: HeaderBag;
+    };
+};
+export type ActorIdResolverInput = {
+    ctx?: unknown;
+    extra?: RequestExtra;
+    headers?: HeaderBag;
+    authInfo?: RequestExtra["authInfo"];
+    toolName?: string;
+    telemetry?: TelemetryArgs;
+};
+export type ActorIdResolver = (input: ActorIdResolverInput) => string | Promise<string>;
+export type McpAnalyticsConfig = {
+    telemetry?: {
+        intent?: "required" | "optional";
+    };
+    armature?: {
+        endpointUrl?: string;
+        ingestSecret?: string;
+        mcpServerId?: string;
+        actorId?: string | ActorIdResolver;
+        enabled?: boolean;
+        delivery?: "background" | "await";
+        emit?: TelemetryEmitter;
+        onError?: (error: unknown, batch: AnalyticsIngestBatch) => void;
+        timeoutMs?: number;
+    };
+};
+export type TelemetryArgs = {
+    intent?: string;
+    context?: string;
+    frustration_level?: "low" | "medium" | "high";
+};
+export type ExtractedToolArguments = {
+    args: unknown;
+    telemetry?: TelemetryArgs;
+};
+export type JsonObjectSchema = {
+    type?: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+};
+export type ToolDefinition = {
+    name: string;
+    inputSchema?: unknown;
+    [key: string]: unknown;
+};
+export type RecordSessionInitEvent = {
+    ctx?: unknown;
+    extra?: RequestExtra;
+    headers?: HeaderBag;
+    authInfo?: RequestExtra["authInfo"];
+    sessionId?: string;
+    requestId?: string;
+    startedAt?: string | Date | number;
+    clientInfo?: McpClientInfo;
+};
+export type RecordToolCallEvent = {
+    name: string;
+    args?: unknown;
+    telemetry?: TelemetryArgs;
+    ctx?: unknown;
+    extra?: RequestExtra;
+    headers?: HeaderBag;
+    authInfo?: RequestExtra["authInfo"];
+    sessionId?: string;
+    requestId?: string;
+    startedAt?: string | Date | number;
+    durationMs?: number;
+    status: "ok" | "error";
+    result?: unknown;
+    error?: unknown;
+    clientInfo?: McpClientInfo;
+};
+export type InstrumentToolCallEvent = {
+    name: string;
+    args?: unknown;
+    ctx?: unknown;
+    extra?: RequestExtra;
+    headers?: HeaderBag;
+    authInfo?: RequestExtra["authInfo"];
+    sessionId?: string;
+    requestId?: string;
+    clientInfo?: McpClientInfo;
+};
+export type ToolCallHandler<T> = (args: unknown) => T | Promise<T>;
+export type ToolHandlerContext = {
+    ctx?: unknown;
+    extra?: RequestExtra;
+    headers?: HeaderBag;
+    authInfo?: RequestExtra["authInfo"];
+    sessionId?: string;
+    requestId?: string;
+    clientInfo?: McpClientInfo;
+};
+export type RegisteredToolHandler<TArgs, TResult> = (args: TArgs, context: ToolHandlerContext) => TResult | Promise<TResult>;
+export type ToolRegistration = {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+};
+export type McpServerInfo = {
+    name: string;
+    version: string;
+    title?: string;
+};
+export type AnalyticsRecorder = {
+    decorateDefinitions: (defs: ToolDefinition[]) => ToolDefinition[];
+    extractTelemetry: (args: unknown) => ExtractedToolArguments;
+    recordToolCall: (event: RecordToolCallEvent) => Promise<void>;
+    recordSessionInit: (event: RecordSessionInitEvent) => Promise<void>;
+    instrumentToolCall: <T>(event: InstrumentToolCallEvent, handler: ToolCallHandler<T>) => Promise<T>;
+    tool: <TArgs = unknown, TResult = unknown>(registration: ToolRegistration, handler: RegisteredToolHandler<TArgs, TResult>) => (rawArgs: unknown, context?: ToolHandlerContext) => Promise<TResult>;
+    dispatch: <T = unknown>(name: string, rawArgs: unknown, context?: ToolHandlerContext) => Promise<T>;
+    toolDefinitions: () => ToolDefinition[];
+    hasTool: (name: string) => boolean;
+    attachToMcpServer: (server: McpServer) => McpServer;
+    createMcpServer: (info: McpServerInfo) => McpServer;
+    flush: () => Promise<void>;
+};
+export type AnalyticsEventKind = "tool_call" | "session_init";
+export type AnalyticsIngestEvent = {
+    event_id: string;
+    kind: AnalyticsEventKind;
+    mcp_server_id: string;
+    actor_id: string;
+    session_id_hint: string | null;
+    started_at: string;
+    finished_at: string | null;
+    duration_ms: number;
+    ok: boolean;
+    error: string | null;
+    metadata: Record<string, unknown>;
+    script_source: string | null;
+    script_source_truncated: boolean;
+    result_preview: string | null;
+    result_truncated: boolean;
+    calls: unknown[];
+    logs: unknown[];
+    search_calls: unknown[];
+};
+export type AnalyticsIngestBatch = {
+    schema_version: 1;
+    events: AnalyticsIngestEvent[];
+};
+export type TelemetryEmitter = (batch: AnalyticsIngestBatch) => void | Promise<void>;
+export type WithMcpAnalyticsResult<ServerFactoryResult> = {
+    result: ServerFactoryResult;
+    recorder: AnalyticsRecorder;
+};

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils.d.ts

@@ -0,0 +1,16 @@
+import type { HeaderBag, JsonObjectSchema } from "./types.js";
+export declare const SCHEMA_VERSION: 1;
+export declare const MAX_SOURCE_BYTES: number;
+export declare const MAX_PREVIEW_BYTES: number;
+export declare const MAX_CAPABILITIES_BYTES: number;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const isJsonObjectSchema: (value: unknown) => value is JsonObjectSchema;
+export declare const isRawShape: (value: unknown) => value is Record<string, unknown>;
+export declare const readEnv: (key: string) => string | undefined;
+export declare const sha256Hex: (value: string) => string;
+export declare const stringifyPreview: (value: unknown) => string;
+export declare const truncateUtf8: (value: string, maxBytes: number) => {
+    value: string;
+    truncated: boolean;
+};
+export declare const headerValue: (headers: HeaderBag | undefined, name: string) => string | null;

package/dist/esm/utils.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+export const SCHEMA_VERSION = 1;
+export const MAX_SOURCE_BYTES = 32 * 1024;
+export const MAX_PREVIEW_BYTES = 8 * 1024;
+export const MAX_CAPABILITIES_BYTES = 4 * 1024;
+export const isRecord = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+export const isJsonObjectSchema = (value) => {
+    return isRecord(value) && value.type === "object";
+};
+export const isRawShape = (value) => {
+    return (isRecord(value) &&
+        !("_def" in value) &&
+        !("_zod" in value) &&
+        !isJsonObjectSchema(value));
+};
+export const readEnv = (key) => {
+    return typeof process !== "undefined" ? process.env[key] : undefined;
+};
+export const sha256Hex = (value) => {
+    return createHash("sha256").update(value).digest("hex");
+};
+export const stringifyPreview = (value) => {
+    if (value === undefined)
+        return "undefined";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[unserialisable]";
+    }
+};
+export const truncateUtf8 = (value, maxBytes) => {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes) {
+        return { value, truncated: false };
+    }
+    return {
+        value: Buffer.from(value, "utf8").subarray(0, maxBytes).toString("utf8"),
+        truncated: true,
+    };
+};
+export const headerValue = (headers, name) => {
+    if (!headers)
+        return null;
+    if (headers instanceof Headers)
+        return headers.get(name);
+    const lower = name.toLowerCase();
+    let value = headers[name] ?? headers[lower];
+    if (value === undefined) {
+        for (const key of Object.keys(headers)) {
+            if (key.toLowerCase() === lower) {
+                value = headers[key];
+                break;
+            }
+        }
+    }
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@armature-tech/mcp-analytics",
+  "version": "0.2.5",
+  "type": "module",
+  "description": "MCP analytics wrapper SDK that instruments MCP tool declarations with telemetry.",
+  "license": "Apache-2.0",
+  "author": "Armature <support@armature.tech>",
+  "homepage": "https://github.com/armature-tech/mcp-analytics#readme",
+  "bugs": {
+    "url": "https://github.com/armature-tech/mcp-analytics/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/armature-tech/mcp-analytics.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "analytics",
+    "telemetry",
+    "observability",
+    "instrumentation",
+    "armature",
+    "mastra"
+  ],
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./mastra": {
+      "import": {
+        "types": "./dist/esm/mastra.d.ts",
+        "default": "./dist/esm/mastra.js"
+      },
+      "require": {
+        "types": "./dist/cjs/mastra.d.ts",
+        "default": "./dist/cjs/mastra.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "dev:armature": "tsx experimental/mock-env/mock-armature-server.ts",
+    "dev:instrumented-server": "tsx experimental/mock-env/instrumented-mock-autumn-mcp-server.ts",
+    "dev:server": "tsx experimental/mock-env/mock-autumn-mcp-server.ts",
+    "demo": "tsx experimental/mock-env/demo-client.ts",
+    "demo:instrumented": "tsx experimental/mock-env/instrumented-demo-client.ts",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "typecheck:all": "tsc --noEmit -p tsconfig.test.json",
+    "check": "npm run typecheck:all && npm test",
+    "clean": "rm -rf dist",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:markers": "node -e \"require('fs').writeFileSync('dist/esm/package.json', '{\\\"type\\\":\\\"module\\\"}\\n'); require('fs').writeFileSync('dist/cjs/package.json', '{\\\"type\\\":\\\"commonjs\\\"}\\n')\"",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:markers",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}