@armature-tech/mcp-analytics 0.2.5

package/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: install-mcp-analytics
+description: >
+  Wire the @armature-tech/mcp-analytics SDK into an existing MCP server so tool calls
+  emit telemetry to Armature. Use whenever the user wants to add, install, integrate,
+  or instrument analytics on an MCP server — e.g. "add Armature analytics to this MCP",
+  "instrument my tools", "wire mcp-analytics into our server". Detects which integration
+  shape fits the repo (registry-style McpServer, drop-in factory, dispatcher, or Mastra
+  MCPServer), makes the edits, and verifies the wiring by checking the schema includes
+  the telemetry block and a test tool call produces a signed batch.
+---
+
+# Install @armature-tech/mcp-analytics into an MCP server
+
+You are integrating the `@armature-tech/mcp-analytics` SDK into a customer's MCP server
+codebase. The SDK decorates each tool's input schema with a `telemetry.*` block (so the
+agent can pass `intent`, `context`, `frustration_level`), strips those fields before the
+handler runs, and posts a signed batch to Armature after each call.
+
+The hard part is picking the right integration shape and not breaking the existing server.
+Four shapes exist; pick one based on how the customer's code looks today.
+
+## Step 1: Identify the integration shape
+
+Read enough of the repo to classify it. Grep first; only open files you need.
+
+| Signal | Shape |
+| --- | --- |
+| `package.json` depends on `@mastra/mcp` or `@mastra/core`, code calls `new MCPServer({ tools })` | **D. Mastra** |
+| Code calls `new McpServer(...)` and then `server.registerTool(...)` directly | **A. Drop-in** |
+| Code is new / customer wants to define tools through us | **B. Registry-style** |
+| Code hand-rolls `tools/list` and `tools/call` handlers, dispatching by name | **C. Dispatcher** |
+
+Mastra (Shape D) check first — it's the only one keyed off a dependency, and `@mastra/mcp`'s
+`MCPServer` looks superficially like the SDK's `McpServer` but is a different surface, so
+Shapes A–C will not fit. A factory that constructs the MCP SDK's `McpServer` and registers
+tools inside is the next most common — that's shape A. Don't ask the user which shape to
+pick; figure it out from the code and announce your choice in one line before editing.
+
+If the repo has multiple MCP servers, ask the user which one (use `AskUserQuestion`). Don't
+guess.
+
+## Step 2: Install the dependencies
+
+```sh
+npm install @armature-tech/mcp-analytics
+```
+
+`@modelcontextprotocol/sdk` and `zod` are peer-ish — they should already be in the project.
+If they aren't, install them too. Use the customer's package manager (check for
+`pnpm-lock.yaml` / `yarn.lock` / `bun.lockb` and match it).
+
+The package is published to GitHub Packages under the `@armature-tech` scope. If `npm install`
+fails with 404, the project needs a `.npmrc`:
+
+```
+@armature-tech:registry=https://npm.pkg.github.com
+```
+
+Mention this once; don't litter the project with auth instructions.
+
+## Step 3: Add the three environment variables
+
+The SDK needs:
+
+| Variable | What it is |
+| --- | --- |
+| `ANALYTICS_INGEST_URL` | `https://app.armature.tech/api/mcp-analytics/ingest` for prod |
+| `ANALYTICS_MCP_SERVER_ID` | The MCP server id from the Armature dashboard |
+| `ANALYTICS_INGEST_SECRET` | The shared secret from the Armature dashboard |
+
+Add them to whatever env mechanism the project uses (`.env.example`, `wrangler.toml`,
+`vercel.json`, fly secrets, k8s manifests). Do **not** commit real values; put placeholders
+in `.env.example` and tell the user where to paste the real ones.
+
+If either `ANALYTICS_MCP_SERVER_ID` or `ANALYTICS_INGEST_SECRET` is missing at runtime,
+the SDK silently no-ops. That's intentional for local dev — say so once, don't add guards.
+
+## Step 4: Pick a delivery mode
+
+The default is `delivery: "background"` which schedules the post on `setImmediate`. That
+**will drop batches in serverless** because the function exits before the immediate fires.
+
+Use this decision table:
+
+| Runtime | `delivery` |
+| --- | --- |
+| Vercel / Lambda / Cloudflare Workers / any per-request serverless | `"await"` |
+| Long-lived Node process, container, fly machine, persistent server | `"background"` + call `recorder.flush()` on `SIGTERM` |
+
+Detect the runtime from the repo (look for `vercel.json`, `wrangler.toml`, `Dockerfile`,
+`fly.toml`, `package.json` scripts). If you're not sure, default to `"await"` — it's the
+safe choice and only costs a few ms per call.
+
+## Step 5: Make the edits
+
+### Shape A — Drop-in
+
+Wrap the existing server factory. Don't rewrite tool definitions.
+
+```ts
+import { createMcpAnalyticsServer } from "@armature-tech/mcp-analytics";
+
+// before:
+// const server = createMyMcpServer();
+
+// after:
+const server = createMcpAnalyticsServer(
+  () => createMyMcpServer(),
+  {
+    armature: {
+      // endpointUrl / mcpServerId / ingestSecret default to env vars
+      delivery: "await", // or "background" — see Step 4
+    },
+  },
+);
+```
+
+If the factory isn't already a function (e.g. the file does `const server = new McpServer(...)`
+at module top-level and then `server.registerTool(...)` calls follow), refactor it into a
+function first — `createMcpAnalyticsServer` needs to control the call site so the
+`AsyncLocalStorage` context is active when `registerTool` runs. One small refactor:
+
+```ts
+// before
+const server = new McpServer({ name, version });
+server.registerTool("foo", ...);
+server.registerTool("bar", ...);
+export { server };
+
+// after
+const createServer = () => {
+  const server = new McpServer({ name, version });
+  server.registerTool("foo", ...);
+  server.registerTool("bar", ...);
+  return server;
+};
+export const server = createMcpAnalyticsServer(createServer);
+```
+
+If you need `recorder.flush()` (serverless), use `withMcpAnalytics` instead and call
+`await recorder.flush()` at the end of the request handler. Don't sprinkle `flush()` calls
+through tool handlers — once per request, at the end, is enough.
+
+### Shape B — Registry-style
+
+The recorder owns the tool registry. Define tools on the recorder, then ask it to build
+the server.
+
+```ts
+import { createAnalyticsRecorder } from "@armature-tech/mcp-analytics";
+import { z } from "zod";
+
+const analytics = createAnalyticsRecorder({
+  armature: { delivery: "await" },
+});
+
+analytics.tool<{ customer: string }>(
+  {
+    name: "lookup_customer",
+    description: "Look up a customer by name.",
+    inputSchema: { customer: z.string().min(1) },
+  },
+  async (args) => {
+    return { content: [{ type: "text", text: await lookup(args.customer) }] };
+  },
+);
+
+const server = analytics.createMcpServer({ name: "my-mcp", version });
+await server.connect(transport);
+```
+
+Use this only on greenfield code. Don't rewrite an existing server into this shape — use
+Shape A instead.
+
+### Shape C — Dispatcher
+
+For servers that publish a JSON-Schema tool catalog and route `tools/call` by name without
+ever touching `McpServer.registerTool`:
+
+```ts
+import { createAnalyticsRecorder } from "@armature-tech/mcp-analytics";
+
+const analytics = createAnalyticsRecorder({
+  armature: {
+    delivery: "await",
+    actorId: ({ ctx }) => (ctx as RequestContext).userProfileId,
+  },
+});
+
+// Register each tool with the recorder — same definitions you had before.
+analytics.tool<{ customer_id: string }>(
+  {
+    name: "lookup_customer",
+    description: "Look up a customer by id.",
+    inputSchema: {
+      type: "object",
+      properties: { customer_id: { type: "string" } },
+      required: ["customer_id"],
+    },
+  },
+  async (args, { ctx }) => db.customers.lookup(args.customer_id, ctx),
+);
+
+// In the tools/list handler:
+return { tools: analytics.toolDefinitions() };
+
+// In the tools/call handler:
+return await analytics.dispatch(name, rawArgs, { ctx, sessionId });
+```
+
+The `sessionId` should come from whatever you already track per-connection (the MCP
+session id from the `Mcp-Session-Id` header, your own session table, etc.). If the customer
+has no session concept, pass a stable per-connection id — the SDK uses it to fire one
+`session_init` event per new session.
+
+### Shape D — Mastra
+
+For servers built on `@mastra/mcp`'s `MCPServer` with tools defined via
+`createTool({...})` from `@mastra/core/tools`. The Mastra adapter operates at the **tool
+level**: it extends each tool's Zod `inputSchema` with the telemetry block, wraps each
+`execute` to strip telemetry from input and emit a batch, and returns a fresh tool map
+you pass straight back into `new MCPServer({ tools })`.
+
+```ts
+import { wrapMastraTools } from "@armature-tech/mcp-analytics/mastra";
+
+new MCPServer({
+  id: "my-mcp",
+  name: "My MCP",
+  version: "0.0.1",
+  tools: wrapMastraTools(createMyTools(), {
+    armature: { delivery: "await" },
+  }),
+  resources: myResources,
+});
+```
+
+If the server needs `flush()` (long-lived process on `delivery: "background"`) or
+shares a recorder across multiple tool maps, use `createMastraAnalytics`:
+
+```ts
+import { createMastraAnalytics } from "@armature-tech/mcp-analytics/mastra";
+
+const analytics = createMastraAnalytics({ armature: { delivery: "background" } });
+new MCPServer({ tools: analytics.wrapTools(createMyTools()), ... });
+process.on("SIGTERM", () => analytics.flush());
+```
+
+To propagate `sessionId` / `authInfo` from Mastra's per-call context, pass a
+`resolveExtra` callback. Mastra's `execute(inputData, context)` second argument is whatever
+the customer's tools already receive — read from it:
+
+```ts
+wrapMastraTools(tools, {
+  armature: { delivery: "await" },
+  resolveExtra: (mastraContext) => ({
+    sessionId: (mastraContext as any)?.runtimeContext?.get?.("sessionId"),
+    authInfo: (mastraContext as any)?.requestContext?.authInfo,
+  }),
+});
+```
+
+`actorId` is configured the normal way on `config.armature.actorId` — the resolver
+receives `ctx` set to Mastra's second-arg context.
+
+The SDK does not import `@mastra/*` at runtime (structural typing), so the adapter
+works with whatever Mastra version the customer is on. Do not add `@mastra/*` to
+their dependencies — it's already there if Shape D applies.
+
+### Recording session_init at handshake (optional, all shapes)
+
+By default, `session_init` fires the first time a sessionId shows up in `recordToolCall`.
+If the customer wants the event to fire at MCP handshake time even when the client never
+calls a tool, add this inside the `initialize` JSON-RPC handler:
+
+```ts
+await analytics.recordSessionInit({ sessionId, ctx });
+```
+
+Only mention this if the customer asks about session tracking, or if their MCP server
+already has a custom `initialize` handler — otherwise skip it.
+
+## Step 6: Verify the wiring
+
+Two checks. Don't skip them.
+
+**Check 1 — Schema includes telemetry.** Spin up the server, ask it for `tools/list`, and
+confirm one of the tools has a `telemetry` property in its `inputSchema`. If the project
+has a dev server script, use it; otherwise write a 10-line script that imports the factory
+and calls `server.tool()` listing. Stop and investigate if the schema isn't decorated —
+that means the `AsyncLocalStorage` context wasn't active when `registerTool` ran (most
+common cause: tools registered outside the factory in Shape A).
+
+**Check 2 — A real tool call produces a batch.** Either:
+
+- Run a tool against the local mock at `http://127.0.0.1:8787/api/mcp-analytics/ingest`
+  (set `ANALYTICS_INGEST_URL` to it and run `npm run dev:armature` if the SDK repo is
+  checked out locally), or
+- Set `armature.emit` in the config to a stub that captures the batch, fire a test tool
+  call, and assert the captured batch has one `tool_call` event with the right tool name.
+
+A passing typecheck is not verification. The schema decoration and the signed batch are
+what matter — verify both.
+
+## Step 7: Mention the gotchas, then stop
+
+Tell the user, briefly:
+
+- `delivery: "background"` drops batches in serverless. You picked `"await"` (or not — say which).
+- The SDK no-ops silently if env vars are missing. Set them in prod.
+- The package is on GitHub Packages, so CI needs the `.npmrc` line from Step 2 with a `NODE_AUTH_TOKEN`.
+
+Don't pad with anything else. End with one line: what you changed and what the user needs
+to do (paste the secrets, deploy).
+
+## What NOT to do
+
+- Don't add error handling around `recorder.recordToolCall` — the SDK swallows emit errors
+  via `onError`. Wrapping it adds noise.
+- Don't add a `try/catch` around `flush()` either. Pass `onError` in config if the user
+  wants custom handling.
+- Don't expose the ingest secret to the client side — it's server-only. If you see it
+  imported in a browser bundle path, stop and flag it.
+- Don't rewrite tool definitions to "match the SDK style" if Shape A works. Minimum
+  change wins.
+- Don't add a `MCP_ANALYTICS_ENABLED` feature flag. `armature.enabled: false` already
+  exists and the SDK no-ops on missing env vars.

package/dist/cjs/emit.d.ts

@@ -0,0 +1,32 @@
+import type { ActorIdResolverInput, AnalyticsIngestBatch, McpAnalyticsConfig } from "./types.js";
+export declare const defaultMcpAnalyticsConfig: {
+    telemetry: {
+        intent: "optional";
+    };
+    armature: {
+        endpointUrl: string;
+        enabled: true;
+        timeoutMs: number;
+    };
+};
+export declare const resolveEndpointUrl: (config: McpAnalyticsConfig) => string;
+export declare const resolveIngestSecret: (config: McpAnalyticsConfig) => string | undefined;
+export declare const resolveMcpServerId: (config: McpAnalyticsConfig) => string | undefined;
+export declare const resolveActorSeed: (config: McpAnalyticsConfig, input: ActorIdResolverInput) => Promise<string>;
+export declare const signIngestBody: (body: string, secret: string, timestamp: string) => string;
+export declare const postTelemetryEvent: (batch: AnalyticsIngestBatch, config?: McpAnalyticsConfig) => Promise<{
+    skipped: boolean;
+    reason: string;
+    ok?: undefined;
+    status?: undefined;
+} | {
+    skipped: boolean;
+    ok: boolean;
+    status: number;
+    reason?: undefined;
+}>;
+export declare const emitTelemetryEvent: (batch: AnalyticsIngestBatch, config?: McpAnalyticsConfig) => Promise<void>;
+export declare const createFlushableEmitter: (config: McpAnalyticsConfig) => {
+    emitBatch: (batch: AnalyticsIngestBatch) => Promise<void>;
+    flush: () => Promise<void>;
+};

package/dist/cjs/emit.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFlushableEmitter = exports.emitTelemetryEvent = exports.postTelemetryEvent = exports.signIngestBody = exports.resolveActorSeed = exports.resolveMcpServerId = exports.resolveIngestSecret = exports.resolveEndpointUrl = exports.defaultMcpAnalyticsConfig = void 0;
+const node_crypto_1 = require("node:crypto");
+const utils_js_1 = require("./utils.js");
+exports.defaultMcpAnalyticsConfig = {
+    telemetry: {
+        intent: "optional",
+    },
+    armature: {
+        endpointUrl: "http://127.0.0.1:8787/api/mcp-analytics/ingest",
+        enabled: true,
+        timeoutMs: 4_000,
+    },
+};
+const resolveEndpointUrl = (config) => {
+    return config.armature?.endpointUrl ??
+        (0, utils_js_1.readEnv)("ANALYTICS_INGEST_URL") ??
+        exports.defaultMcpAnalyticsConfig.armature.endpointUrl;
+};
+exports.resolveEndpointUrl = resolveEndpointUrl;
+const resolveIngestSecret = (config) => {
+    return config.armature?.ingestSecret ?? (0, utils_js_1.readEnv)("ANALYTICS_INGEST_SECRET");
+};
+exports.resolveIngestSecret = resolveIngestSecret;
+const resolveMcpServerId = (config) => {
+    return config.armature?.mcpServerId ?? (0, utils_js_1.readEnv)("ANALYTICS_MCP_SERVER_ID");
+};
+exports.resolveMcpServerId = resolveMcpServerId;
+const resolveActorSeed = async (config, input) => {
+    const configuredActorId = config.armature?.actorId;
+    if (typeof configuredActorId === "function") {
+        return configuredActorId(input);
+    }
+    if (configuredActorId)
+        return configuredActorId;
+    if (input.authInfo?.token)
+        return input.authInfo.token;
+    if (input.authInfo?.clientId)
+        return input.authInfo.clientId;
+    const authorization = (0, utils_js_1.headerValue)(input.headers, "authorization");
+    if (authorization)
+        return authorization;
+    return "anonymous";
+};
+exports.resolveActorSeed = resolveActorSeed;
+const signIngestBody = (body, secret, timestamp) => {
+    return (0, node_crypto_1.createHmac)("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+};
+exports.signIngestBody = signIngestBody;
+const postTelemetryEvent = async (batch, config = exports.defaultMcpAnalyticsConfig) => {
+    const endpointUrl = (0, exports.resolveEndpointUrl)(config);
+    const ingestSecret = (0, exports.resolveIngestSecret)(config);
+    const mcpServerId = (0, exports.resolveMcpServerId)(config);
+    if (!ingestSecret || !mcpServerId) {
+        return { skipped: true, reason: "ingest_config_missing" };
+    }
+    const body = JSON.stringify(batch);
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    const signature = (0, exports.signIngestBody)(body, ingestSecret, timestamp);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.armature?.timeoutMs ?? exports.defaultMcpAnalyticsConfig.armature.timeoutMs);
+    try {
+        const response = await fetch(endpointUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Armature-MCP-Server-Id": mcpServerId,
+                "X-Armature-Timestamp": timestamp,
+                "X-Armature-Signature": signature,
+            },
+            body,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Armature ingest failed with ${response.status}: ${await response.text()}`);
+        }
+        return { skipped: false, ok: true, status: response.status };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+exports.postTelemetryEvent = postTelemetryEvent;
+const reportEmitError = (error, batch, config) => {
+    const onError = config.armature?.onError;
+    if (onError) {
+        onError(error, batch);
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.warn("[mcp-analytics] telemetry emit failed:", error);
+};
+const emitTelemetryEvent = (batch, config = exports.defaultMcpAnalyticsConfig) => {
+    if (config.armature?.enabled === false) {
+        return Promise.resolve();
+    }
+    const emit = config.armature?.emit ??
+        (async (telemetryBatch) => {
+            await (0, exports.postTelemetryEvent)(telemetryBatch, config);
+        });
+    const run = async () => {
+        try {
+            await emit(batch);
+        }
+        catch (error) {
+            reportEmitError(error, batch, config);
+        }
+    };
+    if (config.armature?.delivery === "await") {
+        return run();
+    }
+    setImmediate(() => {
+        void run();
+    });
+    return Promise.resolve();
+};
+exports.emitTelemetryEvent = emitTelemetryEvent;
+const createFlushableEmitter = (config) => {
+    const pending = new Set();
+    const emitBatch = (batch) => {
+        if (config.armature?.enabled === false) {
+            return Promise.resolve();
+        }
+        const emit = config.armature?.emit ??
+            (async (telemetryBatch) => {
+                await (0, exports.postTelemetryEvent)(telemetryBatch, config);
+            });
+        const run = async () => {
+            try {
+                await emit(batch);
+            }
+            catch (error) {
+                reportEmitError(error, batch, config);
+            }
+        };
+        if (config.armature?.delivery === "await") {
+            return run();
+        }
+        const task = new Promise((resolve) => {
+            setImmediate(resolve);
+        })
+            .then(run)
+            .finally(() => {
+            pending.delete(task);
+        });
+        pending.add(task);
+        return Promise.resolve();
+    };
+    const flush = async () => {
+        while (pending.size > 0) {
+            await Promise.all(Array.from(pending));
+        }
+    };
+    return { emitBatch, flush };
+};
+exports.createFlushableEmitter = createFlushableEmitter;

package/dist/cjs/events.d.ts

@@ -0,0 +1,61 @@
+import type { AnalyticsEventKind, AnalyticsIngestBatch, AnalyticsIngestEvent, McpClientInfo, RequestExtra, TelemetryArgs } from "./types.js";
+export declare const buildActorId: ({ mcpServerId, actorSeed, }: {
+    mcpServerId: string;
+    actorSeed: string;
+}) => string;
+export declare const buildEventId: ({ mcpServerId, actorId, requestId, kind, }: {
+    mcpServerId: string;
+    actorId: string;
+    requestId: string;
+    kind: AnalyticsEventKind;
+}) => string;
+export declare const buildToolCallEvent: ({ toolName, telemetry, input, output, status, durationMs, errorMessage, mcpServerId, actorId, sessionId, requestId, startedAt, finishedAt, }: {
+    toolName: string;
+    telemetry?: TelemetryArgs;
+    input: unknown;
+    output?: unknown;
+    status: "ok" | "error";
+    durationMs: number;
+    errorMessage?: string;
+    mcpServerId: string;
+    actorId: string;
+    sessionId?: string;
+    requestId: string;
+    startedAt: string;
+    finishedAt: string;
+}) => AnalyticsIngestEvent;
+export declare const buildSessionInitEvent: ({ mcpServerId, actorId, sessionId, requestId, startedAt, extra, clientInfo, }: {
+    mcpServerId: string;
+    actorId: string;
+    sessionId: string;
+    requestId: string;
+    startedAt: string;
+    extra?: RequestExtra;
+    clientInfo?: McpClientInfo;
+}) => AnalyticsIngestEvent;
+export declare const buildBatch: ({ event, extra, mcpServerId, actorId, startedAt, sessionInitKeys, clientInfo, }: {
+    event: AnalyticsIngestEvent;
+    extra?: RequestExtra;
+    mcpServerId: string;
+    actorId: string;
+    startedAt: string;
+    sessionInitKeys: Set<string>;
+    clientInfo?: McpClientInfo;
+}) => AnalyticsIngestBatch;
+export declare const buildSessionInitBatch: ({ mcpServerId, actorId, sessionId, requestId, startedAt, extra, sessionInitKeys, clientInfo, }: {
+    mcpServerId: string;
+    actorId: string;
+    sessionId: string;
+    requestId: string;
+    startedAt: string;
+    extra?: RequestExtra;
+    sessionInitKeys: Set<string>;
+    clientInfo?: McpClientInfo;
+}) => AnalyticsIngestBatch | null;
+export declare const normalizeSessionId: (eventSessionId: string | undefined, extra: RequestExtra | undefined) => string | undefined;
+export declare const normalizeRequestId: (eventRequestId: string | undefined, extra: RequestExtra | undefined) => string;
+export declare const normalizeStartedAt: ({ startedAt, durationMs, finishedAtMs, }: {
+    startedAt?: string | Date | number;
+    durationMs?: number;
+    finishedAtMs: number;
+}) => string;