@armature-tech/mcp-analytics 0.4.0 → 0.4.2

package/README.md

@@ -11,9 +11,13 @@ It also exposes recorder primitives for dispatcher-style MCP servers that hand-r
 ## Install
 
 ```sh
-npm install @armature-tech/mcp-analytics @modelcontextprotocol/sdk zod
+npx skills add armature-tech/mcp-analytics --global && npm install @armature-tech/mcp-analytics @modelcontextprotocol/sdk zod
 ```
 
+Then ask your coding agent (Claude Code, Cursor, Codex, Gemini, …): *"install Armature analytics on this MCP server"*. The `install-mcp-analytics` skill ([`SKILL.md`](SKILL.md)) detects which of the four integration shapes fits your repo (registry-style `McpServer`, drop-in factory, dispatcher, or Mastra `MCPServer`), makes the edits, and verifies the wiring.
+
+Not using an agent? Just run the `npm install` part and follow the [Quick start](#quick-start) below. The `skills` CLI in the first half of the command is the open [`vercel-labs/skills`](https://github.com/vercel-labs/skills) installer — it copies `SKILL.md` into your agent's skill directory.
+
 ## Quick start
 
 Two ways to wire this in, depending on whether you're adopting it on a new server or layering it on top of an existing `McpServer` factory.
@@ -254,7 +258,7 @@ Notes:
 
 | Variable | Purpose |
 | --- | --- |
-| `ANALYTICS_INGEST_URL` | Ingest endpoint (defaults to the local mock at `http://127.0.0.1:8787/api/mcp-analytics/ingest`) |
+| `ANALYTICS_INGEST_URL` | Ingest endpoint (defaults to `https://app.armature.tech/api/mcp-analytics/ingest`; override for a local mock or staging environment) |
 | `ANALYTICS_INGEST_API_KEY` | Your Armature API key — identifies the MCP server and signs each batch |
 
 ## Lower-level exports

package/SKILL.md

@@ -60,7 +60,7 @@ The SDK needs one credential, plus an optional URL override:
 | Variable | What it is |
 | --- | --- |
 | `ANALYTICS_INGEST_API_KEY` | Your Armature API key (created in the dashboard). Identifies the MCP server and signs each batch. |
-| `ANALYTICS_INGEST_URL` | Optional. Defaults to the prod endpoint `https://app.armature.tech/api/mcp-analytics/ingest`. Override for a local mock or staging environment. |
+| `ANALYTICS_INGEST_URL` | Optional. Defaults to the prod endpoint `https://app.armature.tech/api/mcp-analytics/ingest` (SDK ≥ 0.4.2). Override for a local mock or staging environment. On 0.4.1 and earlier the default was `http://127.0.0.1:8787/...` — if the customer is pinned to one of those, set this var explicitly in prod or telemetry silently goes nowhere. |
 
 Add `ANALYTICS_INGEST_API_KEY` to whatever env mechanism the project uses (`.env.example`,
 `wrangler.toml`, `vercel.json`, fly secrets, k8s manifests). Do **not** commit real values;
@@ -296,6 +296,14 @@ common cause: tools registered outside the factory in Shape A).
 A passing typecheck is not verification. The schema decoration and the authenticated batch are
 what matter — verify both.
 
+**Check 3 — Confirm the resolved endpoint URL.** Especially on serverless: log or inspect the
+`resolveEndpointUrl(config)` result (or just `process.env.ANALYTICS_INGEST_URL` if the customer
+set it) and confirm it points where they expect. On older SDK versions (≤ 0.4.1) the default
+silently fell through to `127.0.0.1:8787`, which means a successful build can still ship
+telemetry into the void in prod. If the customer is on the latest SDK and hasn't overridden,
+say "defaulting to `https://app.armature.tech/api/mcp-analytics/ingest`" out loud so they can
+catch it if that's wrong for their environment.
+
 ## Step 7: Mention the gotchas, then stop
 
 Tell the user, briefly:

package/dist/cjs/emit.js

@@ -7,7 +7,7 @@ exports.defaultMcpAnalyticsConfig = {
         intent: "optional",
     },
     armature: {
-        endpointUrl: "http://127.0.0.1:8787/api/mcp-analytics/ingest",
+        endpointUrl: "https://app.armature.tech/api/mcp-analytics/ingest",
         enabled: true,
         timeoutMs: 4_000,
     },

package/dist/cjs/mastra.d.ts

@@ -1,5 +1,5 @@
 import type { AnalyticsRecorder, McpAnalyticsConfig, RequestExtra } from "./types.js";
-export type MastraToolExecute = (inputData: unknown, context?: unknown) => unknown | Promise<unknown>;
+export type MastraToolExecute = (inputData: any, context?: any) => unknown | Promise<unknown>;
 export type MastraTool = {
     id?: string;
     description?: string;

package/dist/cjs/schema.d.ts

@@ -14,16 +14,16 @@ export declare const createTelemetryInputSchema: (config?: McpAnalyticsConfig) =
     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"]>>>;
+    context: z.ZodOptional<z.ZodString>;
+    frustration_level: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     intent?: string | undefined;
     context?: string | undefined;
-    frustration_level?: "low" | "medium" | "high" | undefined;
+    frustration_level?: string | undefined;
 }, {
     intent?: string | undefined;
     context?: string | undefined;
-    frustration_level?: "low" | "medium" | "high" | undefined;
+    frustration_level?: string | undefined;
 }>;
 export declare const createTelemetryJsonSchema: (config?: McpAnalyticsConfig) => JsonObjectSchema;
 export declare const decorateInputSchemaWithTelemetry: (inputSchema: unknown, config?: McpAnalyticsConfig) => JsonObjectSchema | z.ZodObject<{
@@ -43,16 +43,16 @@ export declare const decorateInputSchemaWithTelemetry: (inputSchema: unknown, co
         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"]>>>;
+        context: z.ZodOptional<z.ZodString>;
+        frustration_level: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         intent?: string | undefined;
         context?: string | undefined;
-        frustration_level?: "low" | "medium" | "high" | undefined;
+        frustration_level?: string | undefined;
     }, {
         intent?: string | undefined;
         context?: string | undefined;
-        frustration_level?: "low" | "medium" | "high" | undefined;
+        frustration_level?: string | undefined;
     }>;
 }, any, any, {
     [x: string]: any;

package/dist/cjs/schema.js

@@ -6,7 +6,7 @@ const utils_js_1 = require("./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 = zod_1.z.object({
+const strictTelemetryInputSchema = zod_1.z.object({
     intent: zod_1.z.string().min(1).describe(INTENT_DESCRIPTION),
     context: zod_1.z.string().min(1).describe(CONTEXT_DESCRIPTION).optional(),
     frustration_level: zod_1.z
@@ -14,7 +14,11 @@ const telemetryInputSchema = zod_1.z.object({
         .describe(FRUSTRATION_LEVEL_DESCRIPTION)
         .optional(),
 });
-const optionalTelemetryInputSchema = telemetryInputSchema.partial();
+const looseTelemetryInputSchema = zod_1.z.object({
+    intent: zod_1.z.string().describe(INTENT_DESCRIPTION).optional(),
+    context: zod_1.z.string().describe(CONTEXT_DESCRIPTION).optional(),
+    frustration_level: zod_1.z.string().describe(FRUSTRATION_LEVEL_DESCRIPTION).optional(),
+});
 const isZodV3ObjectSchema = (value) => {
     return ((0, utils_js_1.isRecord)(value) &&
         "shape" in value &&
@@ -22,32 +26,32 @@ const isZodV3ObjectSchema = (value) => {
 };
 const createTelemetryInputSchema = (config = {}) => {
     return config.telemetry?.intent === "required"
-        ? telemetryInputSchema
-        : optionalTelemetryInputSchema;
+        ? strictTelemetryInputSchema
+        : looseTelemetryInputSchema;
 };
 exports.createTelemetryInputSchema = createTelemetryInputSchema;
 const createTelemetryJsonSchema = (config = {}) => {
-    const required = config.telemetry?.intent === "required" ? ["intent"] : [];
+    const strict = config.telemetry?.intent === "required";
     return {
         type: "object",
         properties: {
             intent: {
                 type: "string",
-                minLength: 1,
+                ...(strict ? { minLength: 1 } : {}),
                 description: INTENT_DESCRIPTION,
             },
             context: {
                 type: "string",
-                minLength: 1,
+                ...(strict ? { minLength: 1 } : {}),
                 description: CONTEXT_DESCRIPTION,
             },
             frustration_level: {
                 type: "string",
-                enum: ["low", "medium", "high"],
+                ...(strict ? { enum: ["low", "medium", "high"] } : {}),
                 description: FRUSTRATION_LEVEL_DESCRIPTION,
             },
         },
-        ...(required.length > 0 ? { required } : {}),
+        ...(strict ? { required: ["intent"] } : {}),
     };
 };
 exports.createTelemetryJsonSchema = createTelemetryJsonSchema;

package/dist/esm/emit.js

@@ -4,7 +4,7 @@ export const defaultMcpAnalyticsConfig = {
         intent: "optional",
     },
     armature: {
-        endpointUrl: "http://127.0.0.1:8787/api/mcp-analytics/ingest",
+        endpointUrl: "https://app.armature.tech/api/mcp-analytics/ingest",
         enabled: true,
         timeoutMs: 4_000,
     },

package/dist/esm/mastra.d.ts

@@ -1,5 +1,5 @@
 import type { AnalyticsRecorder, McpAnalyticsConfig, RequestExtra } from "./types.js";
-export type MastraToolExecute = (inputData: unknown, context?: unknown) => unknown | Promise<unknown>;
+export type MastraToolExecute = (inputData: any, context?: any) => unknown | Promise<unknown>;
 export type MastraTool = {
     id?: string;
     description?: string;

package/dist/esm/schema.d.ts

@@ -14,16 +14,16 @@ export declare const createTelemetryInputSchema: (config?: McpAnalyticsConfig) =
     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"]>>>;
+    context: z.ZodOptional<z.ZodString>;
+    frustration_level: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     intent?: string | undefined;
     context?: string | undefined;
-    frustration_level?: "low" | "medium" | "high" | undefined;
+    frustration_level?: string | undefined;
 }, {
     intent?: string | undefined;
     context?: string | undefined;
-    frustration_level?: "low" | "medium" | "high" | undefined;
+    frustration_level?: string | undefined;
 }>;
 export declare const createTelemetryJsonSchema: (config?: McpAnalyticsConfig) => JsonObjectSchema;
 export declare const decorateInputSchemaWithTelemetry: (inputSchema: unknown, config?: McpAnalyticsConfig) => JsonObjectSchema | z.ZodObject<{
@@ -43,16 +43,16 @@ export declare const decorateInputSchemaWithTelemetry: (inputSchema: unknown, co
         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"]>>>;
+        context: z.ZodOptional<z.ZodString>;
+        frustration_level: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         intent?: string | undefined;
         context?: string | undefined;
-        frustration_level?: "low" | "medium" | "high" | undefined;
+        frustration_level?: string | undefined;
     }, {
         intent?: string | undefined;
         context?: string | undefined;
-        frustration_level?: "low" | "medium" | "high" | undefined;
+        frustration_level?: string | undefined;
     }>;
 }, any, any, {
     [x: string]: any;

package/dist/esm/schema.js

@@ -3,7 +3,7 @@ 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({
+const strictTelemetryInputSchema = z.object({
     intent: z.string().min(1).describe(INTENT_DESCRIPTION),
     context: z.string().min(1).describe(CONTEXT_DESCRIPTION).optional(),
     frustration_level: z
@@ -11,7 +11,11 @@ const telemetryInputSchema = z.object({
         .describe(FRUSTRATION_LEVEL_DESCRIPTION)
         .optional(),
 });
-const optionalTelemetryInputSchema = telemetryInputSchema.partial();
+const looseTelemetryInputSchema = z.object({
+    intent: z.string().describe(INTENT_DESCRIPTION).optional(),
+    context: z.string().describe(CONTEXT_DESCRIPTION).optional(),
+    frustration_level: z.string().describe(FRUSTRATION_LEVEL_DESCRIPTION).optional(),
+});
 const isZodV3ObjectSchema = (value) => {
     return (isRecord(value) &&
         "shape" in value &&
@@ -19,31 +23,31 @@ const isZodV3ObjectSchema = (value) => {
 };
 export const createTelemetryInputSchema = (config = {}) => {
     return config.telemetry?.intent === "required"
-        ? telemetryInputSchema
-        : optionalTelemetryInputSchema;
+        ? strictTelemetryInputSchema
+        : looseTelemetryInputSchema;
 };
 export const createTelemetryJsonSchema = (config = {}) => {
-    const required = config.telemetry?.intent === "required" ? ["intent"] : [];
+    const strict = config.telemetry?.intent === "required";
     return {
         type: "object",
         properties: {
             intent: {
                 type: "string",
-                minLength: 1,
+                ...(strict ? { minLength: 1 } : {}),
                 description: INTENT_DESCRIPTION,
             },
             context: {
                 type: "string",
-                minLength: 1,
+                ...(strict ? { minLength: 1 } : {}),
                 description: CONTEXT_DESCRIPTION,
             },
             frustration_level: {
                 type: "string",
-                enum: ["low", "medium", "high"],
+                ...(strict ? { enum: ["low", "medium", "high"] } : {}),
                 description: FRUSTRATION_LEVEL_DESCRIPTION,
             },
         },
-        ...(required.length > 0 ? { required } : {}),
+        ...(strict ? { required: ["intent"] } : {}),
     };
 };
 const decorateJsonSchemaWithTelemetry = (inputSchema, config) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armature-tech/mcp-analytics",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "MCP analytics wrapper SDK that instruments MCP tool declarations with telemetry.",
   "license": "Apache-2.0",