mcpfy-pulse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcpfy
+
+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,88 @@
+# mcpfy-pulse
+
+Telemetry for MCP servers. Captures method names, payload sizes, durations, and outcomes
+for every JSON-RPC request an MCP server handles — never argument values, never resource
+content. See [`telemetry-master-plan.md`](../../../../telemetry-master-plan.md) for the
+full design.
+
+There are exactly three ways to use this. Pick the one that matches your situation — none
+of them edit your files for you.
+
+## 1. You're using `mcpfy-sdk`
+
+Nothing to install or import. Set one environment variable:
+
+```bash
+MCPFY_API_KEY=mk_live_xxx node dist/server.js
+```
+
+`mcpfy-sdk` checks for `MCPFY_API_KEY` internally and wraps its own transport
+automatically. Unset the variable and nothing changes — no code path is even touched.
+
+## 2. You have a raw `@modelcontextprotocol/sdk` server (source available)
+
+```ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { withMcpfyTelemetry } from "mcpfy-pulse";
+
+const transport = new StdioServerTransport();
+await server.connect(
+  withMcpfyTelemetry(transport, { apiKey: process.env.MCPFY_API_KEY })
+);
+```
+
+`withMcpfyTelemetry` wraps the `Transport`'s `onmessage`/`send` seam — the two points
+every JSON-RPC message passes through regardless of which SDK built the server. If
+`apiKey` is unset, it returns the original transport unchanged.
+
+## 3. You're running someone else's server locally (no source access)
+
+Edit your MCP client's config (`claude_desktop_config.json`, Cursor's `mcp.json`, etc.)
+to route the command through the proxy:
+
+```jsonc
+// before:
+"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
+
+// after:
+"github": {
+  "command": "npx",
+  "args": ["-y", "mcpfy-proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"],
+  "env": { "MCPFY_API_KEY": "mk_live_xxx" }
+}
+```
+
+`mcpfy-proxy` becomes the process your client spawns. It spawns the real command as its
+own child, sits in that child's stdin/stdout, and forwards every byte unchanged while
+classifying JSON-RPC messages on the side. Works for any language — Python, Go, Rust,
+anything — since it only ever reads newline-delimited JSON off a pipe.
+
+## What gets sent
+
+One event per completed request:
+
+```json
+{
+  "method": "tools/call",
+  "toolName": "create_pull_request",
+  "argsBytes": 312,
+  "resultBytes": 1024,
+  "durationMs": 1840,
+  "outcome": "ok",
+  "timestamp": "2026-08-06T10:23:15.000Z"
+}
+```
+
+Batched and POSTed every 5 seconds (or every 500 events, whichever comes first) to
+`MCPFY_TELEMETRY_ENDPOINT` (defaults to the MCPFY ingest URL). If the request fails —
+including "the endpoint doesn't exist yet," which is currently true, see the master
+plan §4/§7 — the batch is silently dropped. Telemetry never throws, never retries
+indefinitely, and never delays or blocks the actual MCP traffic it's observing.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MCPFY_API_KEY` | Required for any telemetry to be sent. Unset = no-op everywhere. |
+| `MCPFY_TELEMETRY_ENDPOINT` | Override the ingest URL (e.g. for local testing). |
+| `MCPFY_GATEWAY` | Set internally by MCP-backend for gateway-routed servers, which already log through `McpGatewayLogger` — `mcpfy-sdk` skips wrapping when this is set, to avoid double-counting. Not something you set yourself. |

package/dist/bin/mcpfy-proxy.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+// src/proxy/run.ts
+import { spawn } from "child_process";
+
+// src/config.ts
+var DEFAULT_ENDPOINT = "https://api.mcpfy.ai/v1/telemetry/ingest";
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+var DEFAULT_MAX_BATCH_SIZE = 500;
+function resolveConfig(options) {
+  return {
+    apiKey: options?.apiKey ?? process.env.MCPFY_API_KEY,
+    endpoint: options?.endpoint ?? process.env.MCPFY_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT,
+    flushIntervalMs: options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+    maxBatchSize: options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE
+  };
+}
+
+// src/core/classify.ts
+function byteLength(value) {
+  if (value === void 0) return 0;
+  try {
+    return Buffer.byteLength(JSON.stringify(value));
+  } catch {
+    return 0;
+  }
+}
+function extractLabel(method, params) {
+  switch (method) {
+    case "tools/call":
+      return { toolName: params?.name };
+    case "prompts/get":
+      return { promptName: params?.name };
+    case "resources/read":
+      return { resourceUri: params?.uri };
+    case "initialize":
+      return {
+        clientName: params?.clientInfo?.name,
+        clientVersion: params?.clientInfo?.version,
+        protocolVersion: params?.protocolVersion
+      };
+    default:
+      return {};
+  }
+}
+var MessageClassifier = class {
+  pending = /* @__PURE__ */ new Map();
+  onIncoming(message) {
+    if (!message || typeof message !== "object") return;
+    const { id, method, params } = message;
+    if (id === void 0 || !method) return;
+    this.pending.set(id, {
+      method,
+      startedAt: Date.now(),
+      argsBytes: byteLength(params),
+      extra: extractLabel(method, params)
+    });
+  }
+  onOutgoing(message) {
+    if (!message || typeof message !== "object") return void 0;
+    const { id, method, result, error } = message;
+    if (method || id === void 0) return void 0;
+    const pending = this.pending.get(id);
+    if (!pending) return void 0;
+    this.pending.delete(id);
+    const event = {
+      type: "request",
+      method: pending.method,
+      argsBytes: pending.argsBytes,
+      resultBytes: byteLength(error ?? result),
+      durationMs: Date.now() - pending.startedAt,
+      outcome: error ? "error" : "ok",
+      errorCode: error?.code,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...pending.extra
+    };
+    if (pending.method === "initialize" && result?.serverInfo) {
+      event.serverName = result.serverInfo.name;
+      event.serverVersion = result.serverInfo.version;
+    }
+    return event;
+  }
+};
+
+// src/core/batcher.ts
+var TelemetryBatcher = class {
+  constructor(config, meta) {
+    this.config = config;
+    this.meta = meta;
+    this.timer = setInterval(() => void this.flush(), config.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  config;
+  meta;
+  queue = [];
+  timer;
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= this.config.maxBatchSize) void this.flush();
+  }
+  async flush() {
+    if (this.queue.length === 0) return;
+    const events = this.queue.splice(0, this.queue.length);
+    try {
+      await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.config.apiKey ?? ""}`
+        },
+        body: JSON.stringify({
+          serverName: this.meta.serverName,
+          serverVersion: this.meta.serverVersion,
+          sdkName: this.meta.sdkName,
+          sdkVersion: this.meta.sdkVersion,
+          installMode: this.meta.installMode,
+          events
+        })
+      });
+    } catch {
+    }
+  }
+  async close() {
+    clearInterval(this.timer);
+    await this.flush();
+  }
+};
+
+// src/proxy/run.ts
+function tryParse(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+}
+function pipeLines(source, dest, onLine) {
+  let buffer = "";
+  source.on("data", (chunk) => {
+    dest.write(chunk);
+    buffer += chunk.toString("utf8");
+    let newlineIndex;
+    while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIndex);
+      buffer = buffer.slice(newlineIndex + 1);
+      onLine(line);
+    }
+  });
+}
+async function runProxy(argv) {
+  const sepIndex = argv.indexOf("--");
+  if (sepIndex === -1 || sepIndex === argv.length - 1) {
+    process.stderr.write(
+      "Usage: mcpfy-proxy -- <command> [args...]\nExample: mcpfy-proxy -- npx -y @modelcontextprotocol/server-github\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const [command, ...args] = argv.slice(sepIndex + 1);
+  const config = resolveConfig();
+  const classifier = new MessageClassifier();
+  const batcher = config.apiKey ? new TelemetryBatcher(config, { sdkName: "unknown", installMode: "stdio-proxy" }) : void 0;
+  const child = spawn(command, args, {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: process.env
+  });
+  child.on("error", (err) => {
+    process.stderr.write(`mcpfy-proxy: failed to start "${command}": ${err.message}
+`);
+    process.exitCode = 1;
+  });
+  pipeLines(process.stdin, child.stdin, (line) => {
+    const message = tryParse(line);
+    if (message) classifier.onIncoming(message);
+  });
+  pipeLines(child.stdout, process.stdout, (line) => {
+    const message = tryParse(line);
+    if (!message) return;
+    const event = classifier.onOutgoing(message);
+    if (event && batcher) batcher.push(event);
+  });
+  process.on("SIGINT", () => child.kill("SIGINT"));
+  process.on("SIGTERM", () => child.kill("SIGTERM"));
+  await new Promise((resolvePromise) => {
+    child.on("exit", (code, signal) => {
+      void batcher?.close().finally(() => {
+        if (signal) {
+          process.kill(process.pid, signal);
+        } else {
+          process.exitCode = code ?? 0;
+        }
+        resolvePromise();
+      });
+    });
+  });
+}
+
+// src/bin/mcpfy-proxy.ts
+runProxy(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`mcpfy-proxy: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=mcpfy-proxy.js.map

package/dist/bin/mcpfy-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/proxy/run.ts","../../src/config.ts","../../src/core/classify.ts","../../src/core/batcher.ts","../../src/bin/mcpfy-proxy.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\nimport { resolveConfig } from \"../config.js\";\nimport { MessageClassifier } from \"../core/classify.js\";\nimport { TelemetryBatcher } from \"../core/batcher.js\";\n\nfunction tryParse(line: string): any {\n  const trimmed = line.trim();\n  if (!trimmed) return undefined;\n  try {\n    return JSON.parse(trimmed);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Forwards raw chunks to `dest` immediately and unchanged, then independently\n * re-buffers a copy into newline-delimited lines for classification. The pass-through\n * path never waits on parsing — a bug in classification can never corrupt or delay\n * the actual MCP traffic.\n */\nfunction pipeLines(source: NodeJS.ReadableStream, dest: NodeJS.WritableStream, onLine: (line: string) => void): void {\n  let buffer = \"\";\n  source.on(\"data\", (chunk: Buffer) => {\n    dest.write(chunk);\n    buffer += chunk.toString(\"utf8\");\n    let newlineIndex: number;\n    while ((newlineIndex = buffer.indexOf(\"\\n\")) !== -1) {\n      const line = buffer.slice(0, newlineIndex);\n      buffer = buffer.slice(newlineIndex + 1);\n      onLine(line);\n    }\n  });\n}\n\n/**\n * `mcpfy-proxy -- <command> [args...]`\n *\n * Spawns <command> as a child process and sits in its stdin/stdout pipe. Client-to-server\n * messages (parent stdin -> child stdin) are classified as \"incoming\"; server-to-client\n * messages (child stdout -> parent stdout) are classified as \"outgoing\", mirroring\n * onmessage/send in the in-process wrapper. Works for any language — the proxy never\n * parses anything beyond newline-delimited JSON-RPC framing.\n */\nexport async function runProxy(argv: string[]): Promise<void> {\n  const sepIndex = argv.indexOf(\"--\");\n  if (sepIndex === -1 || sepIndex === argv.length - 1) {\n    process.stderr.write(\n      \"Usage: mcpfy-proxy -- <command> [args...]\\n\" +\n        \"Example: mcpfy-proxy -- npx -y @modelcontextprotocol/server-github\\n\"\n    );\n    process.exitCode = 1;\n    return;\n  }\n\n  const [command, ...args] = argv.slice(sepIndex + 1);\n  const config = resolveConfig();\n  const classifier = new MessageClassifier();\n  const batcher = config.apiKey\n    ? new TelemetryBatcher(config, { sdkName: \"unknown\", installMode: \"stdio-proxy\" })\n    : undefined;\n\n  const child = spawn(command, args, {\n    stdio: [\"pipe\", \"pipe\", \"inherit\"],\n    env: process.env,\n  });\n\n  child.on(\"error\", (err) => {\n    process.stderr.write(`mcpfy-proxy: failed to start \"${command}\": ${err.message}\\n`);\n    process.exitCode = 1;\n  });\n\n  pipeLines(process.stdin, child.stdin!, (line) => {\n    const message = tryParse(line);\n    if (message) classifier.onIncoming(message);\n  });\n\n  pipeLines(child.stdout!, process.stdout, (line) => {\n    const message = tryParse(line);\n    if (!message) return;\n    const event = classifier.onOutgoing(message);\n    if (event && batcher) batcher.push(event);\n  });\n\n  process.on(\"SIGINT\", () => child.kill(\"SIGINT\"));\n  process.on(\"SIGTERM\", () => child.kill(\"SIGTERM\"));\n\n  await new Promise<void>((resolvePromise) => {\n    child.on(\"exit\", (code, signal) => {\n      void batcher?.close().finally(() => {\n        if (signal) {\n          process.kill(process.pid, signal);\n        } else {\n          process.exitCode = code ?? 0;\n        }\n        resolvePromise();\n      });\n    });\n  });\n}\n","import type { TelemetryOptions } from \"./types.js\";\n\n// Path matches the real route on cloudmcp-nest: POST /v1/telemetry/ingest.\nconst DEFAULT_ENDPOINT = \"https://api.mcpfy.ai/v1/telemetry/ingest\";\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000;\nconst DEFAULT_MAX_BATCH_SIZE = 500;\n\nexport interface ResolvedConfig {\n  apiKey: string | undefined;\n  endpoint: string;\n  flushIntervalMs: number;\n  maxBatchSize: number;\n}\n\nexport function resolveConfig(options?: TelemetryOptions): ResolvedConfig {\n  return {\n    apiKey: options?.apiKey ?? process.env.MCPFY_API_KEY,\n    endpoint: options?.endpoint ?? process.env.MCPFY_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT,\n    flushIntervalMs: options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,\n    maxBatchSize: options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE,\n  };\n}\n","import type { TelemetryEvent } from \"../types.js\";\n\ninterface PendingEntry {\n  method: string;\n  startedAt: number;\n  argsBytes: number;\n  extra: Partial<TelemetryEvent>;\n}\n\nfunction byteLength(value: unknown): number {\n  if (value === undefined) return 0;\n  try {\n    return Buffer.byteLength(JSON.stringify(value));\n  } catch {\n    return 0;\n  }\n}\n\nfunction extractLabel(method: string, params: any): Partial<TelemetryEvent> {\n  switch (method) {\n    case \"tools/call\":\n      return { toolName: params?.name };\n    case \"prompts/get\":\n      return { promptName: params?.name };\n    case \"resources/read\":\n      return { resourceUri: params?.uri };\n    case \"initialize\":\n      // Protocol handshake metadata, not user data — same fields the spec itself exchanges in the clear.\n      return {\n        clientName: params?.clientInfo?.name,\n        clientVersion: params?.clientInfo?.version,\n        protocolVersion: params?.protocolVersion,\n      };\n    default:\n      return {};\n  }\n}\n\n/**\n * Tracks request/response pairs across the two seams every Transport exposes\n * (onmessage = incoming, send = outgoing) and emits one event per completed\n * request. Only method names, byte counts, timing, and outcome are captured —\n * argument values and result content are never read beyond their byte length.\n *\n * Server-initiated requests/notifications (sampling, elicitation, logging,\n * progress) are intentionally not tracked yet — out of scope for this pass.\n */\nexport class MessageClassifier {\n  private pending = new Map<string | number, PendingEntry>();\n\n  onIncoming(message: any): void {\n    if (!message || typeof message !== \"object\") return;\n    const { id, method, params } = message;\n    if (id === undefined || !method) return; // only requests carry both an id and a method\n    this.pending.set(id, {\n      method,\n      startedAt: Date.now(),\n      argsBytes: byteLength(params),\n      extra: extractLabel(method, params),\n    });\n  }\n\n  onOutgoing(message: any): TelemetryEvent | undefined {\n    if (!message || typeof message !== \"object\") return undefined;\n    const { id, method, result, error } = message;\n    if (method || id === undefined) return undefined;\n\n    const pending = this.pending.get(id);\n    if (!pending) return undefined;\n    this.pending.delete(id);\n\n    const event: TelemetryEvent = {\n      type: \"request\",\n      method: pending.method,\n      argsBytes: pending.argsBytes,\n      resultBytes: byteLength(error ?? result),\n      durationMs: Date.now() - pending.startedAt,\n      outcome: error ? \"error\" : \"ok\",\n      errorCode: error?.code,\n      timestamp: new Date().toISOString(),\n      ...pending.extra,\n    };\n\n    if (pending.method === \"initialize\" && result?.serverInfo) {\n      event.serverName = result.serverInfo.name;\n      event.serverVersion = result.serverInfo.version;\n    }\n\n    return event;\n  }\n}\n","import type { TelemetryEvent, SdkName, InstallMode } from \"../types.js\";\nimport type { ResolvedConfig } from \"../config.js\";\n\nexport interface BatchMeta {\n  serverName?: string;\n  serverVersion?: string;\n  sdkName: SdkName;\n  sdkVersion?: string;\n  installMode: InstallMode;\n}\n\n/**\n * Ring-buffer batcher: queues events, flushes on a timer or when full, and never\n * throws or retries indefinitely — a failed or unreachable ingest endpoint is a\n * silent no-op, by design (telemetry must never affect the server's own behavior,\n * and the endpoint may not exist yet — see telemetry-master-plan.md §4/§7).\n */\nexport class TelemetryBatcher {\n  private queue: TelemetryEvent[] = [];\n  private timer: ReturnType<typeof setInterval>;\n\n  constructor(\n    private readonly config: ResolvedConfig,\n    private readonly meta: BatchMeta\n  ) {\n    this.timer = setInterval(() => void this.flush(), config.flushIntervalMs);\n    this.timer.unref?.(); // telemetry must never be the reason a process stays alive\n  }\n\n  push(event: TelemetryEvent): void {\n    this.queue.push(event);\n    if (this.queue.length >= this.config.maxBatchSize) void this.flush();\n  }\n\n  async flush(): Promise<void> {\n    if (this.queue.length === 0) return;\n    const events = this.queue.splice(0, this.queue.length);\n    try {\n      await fetch(this.config.endpoint, {\n        method: \"POST\",\n        headers: {\n          \"content-type\": \"application/json\",\n          authorization: `Bearer ${this.config.apiKey ?? \"\"}`,\n        },\n        body: JSON.stringify({\n          serverName: this.meta.serverName,\n          serverVersion: this.meta.serverVersion,\n          sdkName: this.meta.sdkName,\n          sdkVersion: this.meta.sdkVersion,\n          installMode: this.meta.installMode,\n          events,\n        }),\n      });\n    } catch {\n      // silent drop\n    }\n  }\n\n  async close(): Promise<void> {\n    clearInterval(this.timer);\n    await this.flush();\n  }\n}\n","#!/usr/bin/env node\nimport { runProxy } from \"../proxy/run.js\";\n\nrunProxy(process.argv.slice(2)).catch((err) => {\n  process.stderr.write(`mcpfy-proxy: ${err instanceof Error ? err.message : String(err)}\\n`);\n  process.exitCode = 1;\n});\n"],"mappings":"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","names":[]}

package/dist/src/bin/mcpfy-proxy.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=mcpfy-proxy.d.ts.map

package/dist/src/bin/mcpfy-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpfy-proxy.d.ts","sourceRoot":"","sources":["../../../src/bin/mcpfy-proxy.ts"],"names":[],"mappings":""}

package/dist/src/config.d.ts

@@ -0,0 +1,9 @@
+import type { TelemetryOptions } from "./types.js";
+export interface ResolvedConfig {
+    apiKey: string | undefined;
+    endpoint: string;
+    flushIntervalMs: number;
+    maxBatchSize: number;
+}
+export declare function resolveConfig(options?: TelemetryOptions): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAOnD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAOxE"}

package/dist/src/core/batcher.d.ts

@@ -0,0 +1,26 @@
+import type { TelemetryEvent, SdkName, InstallMode } from "../types.js";
+import type { ResolvedConfig } from "../config.js";
+export interface BatchMeta {
+    serverName?: string;
+    serverVersion?: string;
+    sdkName: SdkName;
+    sdkVersion?: string;
+    installMode: InstallMode;
+}
+/**
+ * Ring-buffer batcher: queues events, flushes on a timer or when full, and never
+ * throws or retries indefinitely — a failed or unreachable ingest endpoint is a
+ * silent no-op, by design (telemetry must never affect the server's own behavior,
+ * and the endpoint may not exist yet — see telemetry-master-plan.md §4/§7).
+ */
+export declare class TelemetryBatcher {
+    private readonly config;
+    private readonly meta;
+    private queue;
+    private timer;
+    constructor(config: ResolvedConfig, meta: BatchMeta);
+    push(event: TelemetryEvent): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=batcher.d.ts.map

package/dist/src/core/batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.d.ts","sourceRoot":"","sources":["../../../src/core/batcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAAiC;gBAG3B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,SAAS;IAMlC,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAK3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/src/core/classify.d.ts

@@ -0,0 +1,16 @@
+import type { TelemetryEvent } from "../types.js";
+/**
+ * Tracks request/response pairs across the two seams every Transport exposes
+ * (onmessage = incoming, send = outgoing) and emits one event per completed
+ * request. Only method names, byte counts, timing, and outcome are captured —
+ * argument values and result content are never read beyond their byte length.
+ *
+ * Server-initiated requests/notifications (sampling, elicitation, logging,
+ * progress) are intentionally not tracked yet — out of scope for this pass.
+ */
+export declare class MessageClassifier {
+    private pending;
+    onIncoming(message: any): void;
+    onOutgoing(message: any): TelemetryEvent | undefined;
+}
+//# sourceMappingURL=classify.d.ts.map

package/dist/src/core/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../../src/core/classify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAsClD;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA4C;IAE3D,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAY9B,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,cAAc,GAAG,SAAS;CA4BrD"}

package/dist/src/index.cjs

@@ -0,0 +1,204 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  withMcpfyTelemetry: () => withMcpfyTelemetry
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/config.ts
+var DEFAULT_ENDPOINT = "https://api.mcpfy.ai/v1/telemetry/ingest";
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+var DEFAULT_MAX_BATCH_SIZE = 500;
+function resolveConfig(options) {
+  return {
+    apiKey: options?.apiKey ?? process.env.MCPFY_API_KEY,
+    endpoint: options?.endpoint ?? process.env.MCPFY_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT,
+    flushIntervalMs: options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+    maxBatchSize: options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE
+  };
+}
+
+// src/core/classify.ts
+function byteLength(value) {
+  if (value === void 0) return 0;
+  try {
+    return Buffer.byteLength(JSON.stringify(value));
+  } catch {
+    return 0;
+  }
+}
+function extractLabel(method, params) {
+  switch (method) {
+    case "tools/call":
+      return { toolName: params?.name };
+    case "prompts/get":
+      return { promptName: params?.name };
+    case "resources/read":
+      return { resourceUri: params?.uri };
+    case "initialize":
+      return {
+        clientName: params?.clientInfo?.name,
+        clientVersion: params?.clientInfo?.version,
+        protocolVersion: params?.protocolVersion
+      };
+    default:
+      return {};
+  }
+}
+var MessageClassifier = class {
+  pending = /* @__PURE__ */ new Map();
+  onIncoming(message) {
+    if (!message || typeof message !== "object") return;
+    const { id, method, params } = message;
+    if (id === void 0 || !method) return;
+    this.pending.set(id, {
+      method,
+      startedAt: Date.now(),
+      argsBytes: byteLength(params),
+      extra: extractLabel(method, params)
+    });
+  }
+  onOutgoing(message) {
+    if (!message || typeof message !== "object") return void 0;
+    const { id, method, result, error } = message;
+    if (method || id === void 0) return void 0;
+    const pending = this.pending.get(id);
+    if (!pending) return void 0;
+    this.pending.delete(id);
+    const event = {
+      type: "request",
+      method: pending.method,
+      argsBytes: pending.argsBytes,
+      resultBytes: byteLength(error ?? result),
+      durationMs: Date.now() - pending.startedAt,
+      outcome: error ? "error" : "ok",
+      errorCode: error?.code,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...pending.extra
+    };
+    if (pending.method === "initialize" && result?.serverInfo) {
+      event.serverName = result.serverInfo.name;
+      event.serverVersion = result.serverInfo.version;
+    }
+    return event;
+  }
+};
+
+// src/core/batcher.ts
+var TelemetryBatcher = class {
+  constructor(config, meta) {
+    this.config = config;
+    this.meta = meta;
+    this.timer = setInterval(() => void this.flush(), config.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  config;
+  meta;
+  queue = [];
+  timer;
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= this.config.maxBatchSize) void this.flush();
+  }
+  async flush() {
+    if (this.queue.length === 0) return;
+    const events = this.queue.splice(0, this.queue.length);
+    try {
+      await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.config.apiKey ?? ""}`
+        },
+        body: JSON.stringify({
+          serverName: this.meta.serverName,
+          serverVersion: this.meta.serverVersion,
+          sdkName: this.meta.sdkName,
+          sdkVersion: this.meta.sdkVersion,
+          installMode: this.meta.installMode,
+          events
+        })
+      });
+    } catch {
+    }
+  }
+  async close() {
+    clearInterval(this.timer);
+    await this.flush();
+  }
+};
+
+// src/wrap-transport.ts
+function withMcpfyTelemetry(transport, options) {
+  const config = resolveConfig(options);
+  if (!config.apiKey) return transport;
+  const classifier = new MessageClassifier();
+  const batcher = new TelemetryBatcher(config, {
+    serverName: options?.serverName,
+    serverVersion: options?.serverVersion,
+    sdkName: options?.sdkName ?? "@modelcontextprotocol/sdk",
+    sdkVersion: options?.sdkVersion,
+    installMode: options?.installMode ?? "sdk-wrapper"
+  });
+  const wrapped = {
+    start: () => transport.start(),
+    close: () => {
+      void batcher.close();
+      return transport.close();
+    },
+    send: (message, sendOptions) => {
+      const event = classifier.onOutgoing(message);
+      if (event) batcher.push(event);
+      return transport.send(message, sendOptions);
+    },
+    get sessionId() {
+      return transport.sessionId;
+    },
+    get onclose() {
+      return transport.onclose;
+    },
+    set onclose(fn) {
+      transport.onclose = fn;
+    },
+    get onerror() {
+      return transport.onerror;
+    },
+    set onerror(fn) {
+      transport.onerror = fn;
+    },
+    get onmessage() {
+      return transport.onmessage;
+    },
+    set onmessage(handler) {
+      transport.onmessage = (message, extra) => {
+        classifier.onIncoming(message);
+        handler?.(message, extra);
+      };
+    }
+  };
+  return wrapped;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  withMcpfyTelemetry
+});
+//# sourceMappingURL=index.cjs.map

package/dist/src/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts","../../src/config.ts","../../src/core/classify.ts","../../src/core/batcher.ts","../../src/wrap-transport.ts"],"sourcesContent":["export { withMcpfyTelemetry } from \"./wrap-transport.js\";\nexport type { TelemetryOptions, TelemetryEvent, MinimalTransport, SdkName, InstallMode } from \"./types.js\";\n","import type { TelemetryOptions } from \"./types.js\";\n\n// Path matches the real route on cloudmcp-nest: POST /v1/telemetry/ingest.\nconst DEFAULT_ENDPOINT = \"https://api.mcpfy.ai/v1/telemetry/ingest\";\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000;\nconst DEFAULT_MAX_BATCH_SIZE = 500;\n\nexport interface ResolvedConfig {\n  apiKey: string | undefined;\n  endpoint: string;\n  flushIntervalMs: number;\n  maxBatchSize: number;\n}\n\nexport function resolveConfig(options?: TelemetryOptions): ResolvedConfig {\n  return {\n    apiKey: options?.apiKey ?? process.env.MCPFY_API_KEY,\n    endpoint: options?.endpoint ?? process.env.MCPFY_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT,\n    flushIntervalMs: options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,\n    maxBatchSize: options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE,\n  };\n}\n","import type { TelemetryEvent } from \"../types.js\";\n\ninterface PendingEntry {\n  method: string;\n  startedAt: number;\n  argsBytes: number;\n  extra: Partial<TelemetryEvent>;\n}\n\nfunction byteLength(value: unknown): number {\n  if (value === undefined) return 0;\n  try {\n    return Buffer.byteLength(JSON.stringify(value));\n  } catch {\n    return 0;\n  }\n}\n\nfunction extractLabel(method: string, params: any): Partial<TelemetryEvent> {\n  switch (method) {\n    case \"tools/call\":\n      return { toolName: params?.name };\n    case \"prompts/get\":\n      return { promptName: params?.name };\n    case \"resources/read\":\n      return { resourceUri: params?.uri };\n    case \"initialize\":\n      // Protocol handshake metadata, not user data — same fields the spec itself exchanges in the clear.\n      return {\n        clientName: params?.clientInfo?.name,\n        clientVersion: params?.clientInfo?.version,\n        protocolVersion: params?.protocolVersion,\n      };\n    default:\n      return {};\n  }\n}\n\n/**\n * Tracks request/response pairs across the two seams every Transport exposes\n * (onmessage = incoming, send = outgoing) and emits one event per completed\n * request. Only method names, byte counts, timing, and outcome are captured —\n * argument values and result content are never read beyond their byte length.\n *\n * Server-initiated requests/notifications (sampling, elicitation, logging,\n * progress) are intentionally not tracked yet — out of scope for this pass.\n */\nexport class MessageClassifier {\n  private pending = new Map<string | number, PendingEntry>();\n\n  onIncoming(message: any): void {\n    if (!message || typeof message !== \"object\") return;\n    const { id, method, params } = message;\n    if (id === undefined || !method) return; // only requests carry both an id and a method\n    this.pending.set(id, {\n      method,\n      startedAt: Date.now(),\n      argsBytes: byteLength(params),\n      extra: extractLabel(method, params),\n    });\n  }\n\n  onOutgoing(message: any): TelemetryEvent | undefined {\n    if (!message || typeof message !== \"object\") return undefined;\n    const { id, method, result, error } = message;\n    if (method || id === undefined) return undefined;\n\n    const pending = this.pending.get(id);\n    if (!pending) return undefined;\n    this.pending.delete(id);\n\n    const event: TelemetryEvent = {\n      type: \"request\",\n      method: pending.method,\n      argsBytes: pending.argsBytes,\n      resultBytes: byteLength(error ?? result),\n      durationMs: Date.now() - pending.startedAt,\n      outcome: error ? \"error\" : \"ok\",\n      errorCode: error?.code,\n      timestamp: new Date().toISOString(),\n      ...pending.extra,\n    };\n\n    if (pending.method === \"initialize\" && result?.serverInfo) {\n      event.serverName = result.serverInfo.name;\n      event.serverVersion = result.serverInfo.version;\n    }\n\n    return event;\n  }\n}\n","import type { TelemetryEvent, SdkName, InstallMode } from \"../types.js\";\nimport type { ResolvedConfig } from \"../config.js\";\n\nexport interface BatchMeta {\n  serverName?: string;\n  serverVersion?: string;\n  sdkName: SdkName;\n  sdkVersion?: string;\n  installMode: InstallMode;\n}\n\n/**\n * Ring-buffer batcher: queues events, flushes on a timer or when full, and never\n * throws or retries indefinitely — a failed or unreachable ingest endpoint is a\n * silent no-op, by design (telemetry must never affect the server's own behavior,\n * and the endpoint may not exist yet — see telemetry-master-plan.md §4/§7).\n */\nexport class TelemetryBatcher {\n  private queue: TelemetryEvent[] = [];\n  private timer: ReturnType<typeof setInterval>;\n\n  constructor(\n    private readonly config: ResolvedConfig,\n    private readonly meta: BatchMeta\n  ) {\n    this.timer = setInterval(() => void this.flush(), config.flushIntervalMs);\n    this.timer.unref?.(); // telemetry must never be the reason a process stays alive\n  }\n\n  push(event: TelemetryEvent): void {\n    this.queue.push(event);\n    if (this.queue.length >= this.config.maxBatchSize) void this.flush();\n  }\n\n  async flush(): Promise<void> {\n    if (this.queue.length === 0) return;\n    const events = this.queue.splice(0, this.queue.length);\n    try {\n      await fetch(this.config.endpoint, {\n        method: \"POST\",\n        headers: {\n          \"content-type\": \"application/json\",\n          authorization: `Bearer ${this.config.apiKey ?? \"\"}`,\n        },\n        body: JSON.stringify({\n          serverName: this.meta.serverName,\n          serverVersion: this.meta.serverVersion,\n          sdkName: this.meta.sdkName,\n          sdkVersion: this.meta.sdkVersion,\n          installMode: this.meta.installMode,\n          events,\n        }),\n      });\n    } catch {\n      // silent drop\n    }\n  }\n\n  async close(): Promise<void> {\n    clearInterval(this.timer);\n    await this.flush();\n  }\n}\n","import { resolveConfig } from \"./config.js\";\nimport { MessageClassifier } from \"./core/classify.js\";\nimport { TelemetryBatcher } from \"./core/batcher.js\";\nimport type { MinimalTransport, TelemetryOptions } from \"./types.js\";\n\n/**\n * Wraps a Transport's `onmessage`/`send` seam to capture telemetry, then delegates\n * everything through to the real transport unchanged. If no API key is configured\n * (via `options.apiKey` or the MCPFY_API_KEY env var), this is a complete no-op —\n * the original transport is returned untouched.\n *\n * Usage (add these lines yourself — nothing here edits your files for you):\n *\n *   import { withMcpfyTelemetry } from \"mcpfy-pulse\";\n *   const transport = new StdioServerTransport();\n *   await server.connect(withMcpfyTelemetry(transport, { apiKey: process.env.MCPFY_API_KEY }));\n */\nexport function withMcpfyTelemetry<T extends MinimalTransport>(transport: T, options?: TelemetryOptions): T {\n  const config = resolveConfig(options);\n  if (!config.apiKey) return transport;\n\n  const classifier = new MessageClassifier();\n  const batcher = new TelemetryBatcher(config, {\n    serverName: options?.serverName,\n    serverVersion: options?.serverVersion,\n    sdkName: options?.sdkName ?? \"@modelcontextprotocol/sdk\",\n    sdkVersion: options?.sdkVersion,\n    installMode: options?.installMode ?? \"sdk-wrapper\",\n  });\n\n  const wrapped: MinimalTransport = {\n    start: () => transport.start(),\n    close: () => {\n      void batcher.close();\n      return transport.close();\n    },\n    send: (message: any, sendOptions?: any) => {\n      const event = classifier.onOutgoing(message);\n      if (event) batcher.push(event);\n      return transport.send(message, sendOptions);\n    },\n    get sessionId() {\n      return transport.sessionId;\n    },\n    get onclose() {\n      return transport.onclose;\n    },\n    set onclose(fn) {\n      transport.onclose = fn;\n    },\n    get onerror() {\n      return transport.onerror;\n    },\n    set onerror(fn) {\n      transport.onerror = fn;\n    },\n    get onmessage() {\n      return transport.onmessage;\n    },\n    set onmessage(handler) {\n      transport.onmessage = (message: any, extra?: any) => {\n        classifier.onIncoming(message);\n        handler?.(message, extra);\n      };\n    },\n  };\n\n  return wrapped as T;\n}\n"],"mappings":"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","names":[]}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { withMcpfyTelemetry } from "./wrap-transport.js";
+export type { TelemetryOptions, TelemetryEvent, MinimalTransport, SdkName, InstallMode } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,177 @@
+// src/config.ts
+var DEFAULT_ENDPOINT = "https://api.mcpfy.ai/v1/telemetry/ingest";
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+var DEFAULT_MAX_BATCH_SIZE = 500;
+function resolveConfig(options) {
+  return {
+    apiKey: options?.apiKey ?? process.env.MCPFY_API_KEY,
+    endpoint: options?.endpoint ?? process.env.MCPFY_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT,
+    flushIntervalMs: options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+    maxBatchSize: options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE
+  };
+}
+
+// src/core/classify.ts
+function byteLength(value) {
+  if (value === void 0) return 0;
+  try {
+    return Buffer.byteLength(JSON.stringify(value));
+  } catch {
+    return 0;
+  }
+}
+function extractLabel(method, params) {
+  switch (method) {
+    case "tools/call":
+      return { toolName: params?.name };
+    case "prompts/get":
+      return { promptName: params?.name };
+    case "resources/read":
+      return { resourceUri: params?.uri };
+    case "initialize":
+      return {
+        clientName: params?.clientInfo?.name,
+        clientVersion: params?.clientInfo?.version,
+        protocolVersion: params?.protocolVersion
+      };
+    default:
+      return {};
+  }
+}
+var MessageClassifier = class {
+  pending = /* @__PURE__ */ new Map();
+  onIncoming(message) {
+    if (!message || typeof message !== "object") return;
+    const { id, method, params } = message;
+    if (id === void 0 || !method) return;
+    this.pending.set(id, {
+      method,
+      startedAt: Date.now(),
+      argsBytes: byteLength(params),
+      extra: extractLabel(method, params)
+    });
+  }
+  onOutgoing(message) {
+    if (!message || typeof message !== "object") return void 0;
+    const { id, method, result, error } = message;
+    if (method || id === void 0) return void 0;
+    const pending = this.pending.get(id);
+    if (!pending) return void 0;
+    this.pending.delete(id);
+    const event = {
+      type: "request",
+      method: pending.method,
+      argsBytes: pending.argsBytes,
+      resultBytes: byteLength(error ?? result),
+      durationMs: Date.now() - pending.startedAt,
+      outcome: error ? "error" : "ok",
+      errorCode: error?.code,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...pending.extra
+    };
+    if (pending.method === "initialize" && result?.serverInfo) {
+      event.serverName = result.serverInfo.name;
+      event.serverVersion = result.serverInfo.version;
+    }
+    return event;
+  }
+};
+
+// src/core/batcher.ts
+var TelemetryBatcher = class {
+  constructor(config, meta) {
+    this.config = config;
+    this.meta = meta;
+    this.timer = setInterval(() => void this.flush(), config.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  config;
+  meta;
+  queue = [];
+  timer;
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= this.config.maxBatchSize) void this.flush();
+  }
+  async flush() {
+    if (this.queue.length === 0) return;
+    const events = this.queue.splice(0, this.queue.length);
+    try {
+      await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.config.apiKey ?? ""}`
+        },
+        body: JSON.stringify({
+          serverName: this.meta.serverName,
+          serverVersion: this.meta.serverVersion,
+          sdkName: this.meta.sdkName,
+          sdkVersion: this.meta.sdkVersion,
+          installMode: this.meta.installMode,
+          events
+        })
+      });
+    } catch {
+    }
+  }
+  async close() {
+    clearInterval(this.timer);
+    await this.flush();
+  }
+};
+
+// src/wrap-transport.ts
+function withMcpfyTelemetry(transport, options) {
+  const config = resolveConfig(options);
+  if (!config.apiKey) return transport;
+  const classifier = new MessageClassifier();
+  const batcher = new TelemetryBatcher(config, {
+    serverName: options?.serverName,
+    serverVersion: options?.serverVersion,
+    sdkName: options?.sdkName ?? "@modelcontextprotocol/sdk",
+    sdkVersion: options?.sdkVersion,
+    installMode: options?.installMode ?? "sdk-wrapper"
+  });
+  const wrapped = {
+    start: () => transport.start(),
+    close: () => {
+      void batcher.close();
+      return transport.close();
+    },
+    send: (message, sendOptions) => {
+      const event = classifier.onOutgoing(message);
+      if (event) batcher.push(event);
+      return transport.send(message, sendOptions);
+    },
+    get sessionId() {
+      return transport.sessionId;
+    },
+    get onclose() {
+      return transport.onclose;
+    },
+    set onclose(fn) {
+      transport.onclose = fn;
+    },
+    get onerror() {
+      return transport.onerror;
+    },
+    set onerror(fn) {
+      transport.onerror = fn;
+    },
+    get onmessage() {
+      return transport.onmessage;
+    },
+    set onmessage(handler) {
+      transport.onmessage = (message, extra) => {
+        classifier.onIncoming(message);
+        handler?.(message, extra);
+      };
+    }
+  };
+  return wrapped;
+}
+export {
+  withMcpfyTelemetry
+};
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config.ts","../../src/core/classify.ts","../../src/core/batcher.ts","../../src/wrap-transport.ts"],"sourcesContent":["import type { TelemetryOptions } from \"./types.js\";\n\n// Path matches the real route on cloudmcp-nest: POST /v1/telemetry/ingest.\nconst DEFAULT_ENDPOINT = \"https://api.mcpfy.ai/v1/telemetry/ingest\";\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000;\nconst DEFAULT_MAX_BATCH_SIZE = 500;\n\nexport interface ResolvedConfig {\n  apiKey: string | undefined;\n  endpoint: string;\n  flushIntervalMs: number;\n  maxBatchSize: number;\n}\n\nexport function resolveConfig(options?: TelemetryOptions): ResolvedConfig {\n  return {\n    apiKey: options?.apiKey ?? process.env.MCPFY_API_KEY,\n    endpoint: options?.endpoint ?? process.env.MCPFY_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT,\n    flushIntervalMs: options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,\n    maxBatchSize: options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE,\n  };\n}\n","import type { TelemetryEvent } from \"../types.js\";\n\ninterface PendingEntry {\n  method: string;\n  startedAt: number;\n  argsBytes: number;\n  extra: Partial<TelemetryEvent>;\n}\n\nfunction byteLength(value: unknown): number {\n  if (value === undefined) return 0;\n  try {\n    return Buffer.byteLength(JSON.stringify(value));\n  } catch {\n    return 0;\n  }\n}\n\nfunction extractLabel(method: string, params: any): Partial<TelemetryEvent> {\n  switch (method) {\n    case \"tools/call\":\n      return { toolName: params?.name };\n    case \"prompts/get\":\n      return { promptName: params?.name };\n    case \"resources/read\":\n      return { resourceUri: params?.uri };\n    case \"initialize\":\n      // Protocol handshake metadata, not user data — same fields the spec itself exchanges in the clear.\n      return {\n        clientName: params?.clientInfo?.name,\n        clientVersion: params?.clientInfo?.version,\n        protocolVersion: params?.protocolVersion,\n      };\n    default:\n      return {};\n  }\n}\n\n/**\n * Tracks request/response pairs across the two seams every Transport exposes\n * (onmessage = incoming, send = outgoing) and emits one event per completed\n * request. Only method names, byte counts, timing, and outcome are captured —\n * argument values and result content are never read beyond their byte length.\n *\n * Server-initiated requests/notifications (sampling, elicitation, logging,\n * progress) are intentionally not tracked yet — out of scope for this pass.\n */\nexport class MessageClassifier {\n  private pending = new Map<string | number, PendingEntry>();\n\n  onIncoming(message: any): void {\n    if (!message || typeof message !== \"object\") return;\n    const { id, method, params } = message;\n    if (id === undefined || !method) return; // only requests carry both an id and a method\n    this.pending.set(id, {\n      method,\n      startedAt: Date.now(),\n      argsBytes: byteLength(params),\n      extra: extractLabel(method, params),\n    });\n  }\n\n  onOutgoing(message: any): TelemetryEvent | undefined {\n    if (!message || typeof message !== \"object\") return undefined;\n    const { id, method, result, error } = message;\n    if (method || id === undefined) return undefined;\n\n    const pending = this.pending.get(id);\n    if (!pending) return undefined;\n    this.pending.delete(id);\n\n    const event: TelemetryEvent = {\n      type: \"request\",\n      method: pending.method,\n      argsBytes: pending.argsBytes,\n      resultBytes: byteLength(error ?? result),\n      durationMs: Date.now() - pending.startedAt,\n      outcome: error ? \"error\" : \"ok\",\n      errorCode: error?.code,\n      timestamp: new Date().toISOString(),\n      ...pending.extra,\n    };\n\n    if (pending.method === \"initialize\" && result?.serverInfo) {\n      event.serverName = result.serverInfo.name;\n      event.serverVersion = result.serverInfo.version;\n    }\n\n    return event;\n  }\n}\n","import type { TelemetryEvent, SdkName, InstallMode } from \"../types.js\";\nimport type { ResolvedConfig } from \"../config.js\";\n\nexport interface BatchMeta {\n  serverName?: string;\n  serverVersion?: string;\n  sdkName: SdkName;\n  sdkVersion?: string;\n  installMode: InstallMode;\n}\n\n/**\n * Ring-buffer batcher: queues events, flushes on a timer or when full, and never\n * throws or retries indefinitely — a failed or unreachable ingest endpoint is a\n * silent no-op, by design (telemetry must never affect the server's own behavior,\n * and the endpoint may not exist yet — see telemetry-master-plan.md §4/§7).\n */\nexport class TelemetryBatcher {\n  private queue: TelemetryEvent[] = [];\n  private timer: ReturnType<typeof setInterval>;\n\n  constructor(\n    private readonly config: ResolvedConfig,\n    private readonly meta: BatchMeta\n  ) {\n    this.timer = setInterval(() => void this.flush(), config.flushIntervalMs);\n    this.timer.unref?.(); // telemetry must never be the reason a process stays alive\n  }\n\n  push(event: TelemetryEvent): void {\n    this.queue.push(event);\n    if (this.queue.length >= this.config.maxBatchSize) void this.flush();\n  }\n\n  async flush(): Promise<void> {\n    if (this.queue.length === 0) return;\n    const events = this.queue.splice(0, this.queue.length);\n    try {\n      await fetch(this.config.endpoint, {\n        method: \"POST\",\n        headers: {\n          \"content-type\": \"application/json\",\n          authorization: `Bearer ${this.config.apiKey ?? \"\"}`,\n        },\n        body: JSON.stringify({\n          serverName: this.meta.serverName,\n          serverVersion: this.meta.serverVersion,\n          sdkName: this.meta.sdkName,\n          sdkVersion: this.meta.sdkVersion,\n          installMode: this.meta.installMode,\n          events,\n        }),\n      });\n    } catch {\n      // silent drop\n    }\n  }\n\n  async close(): Promise<void> {\n    clearInterval(this.timer);\n    await this.flush();\n  }\n}\n","import { resolveConfig } from \"./config.js\";\nimport { MessageClassifier } from \"./core/classify.js\";\nimport { TelemetryBatcher } from \"./core/batcher.js\";\nimport type { MinimalTransport, TelemetryOptions } from \"./types.js\";\n\n/**\n * Wraps a Transport's `onmessage`/`send` seam to capture telemetry, then delegates\n * everything through to the real transport unchanged. If no API key is configured\n * (via `options.apiKey` or the MCPFY_API_KEY env var), this is a complete no-op —\n * the original transport is returned untouched.\n *\n * Usage (add these lines yourself — nothing here edits your files for you):\n *\n *   import { withMcpfyTelemetry } from \"mcpfy-pulse\";\n *   const transport = new StdioServerTransport();\n *   await server.connect(withMcpfyTelemetry(transport, { apiKey: process.env.MCPFY_API_KEY }));\n */\nexport function withMcpfyTelemetry<T extends MinimalTransport>(transport: T, options?: TelemetryOptions): T {\n  const config = resolveConfig(options);\n  if (!config.apiKey) return transport;\n\n  const classifier = new MessageClassifier();\n  const batcher = new TelemetryBatcher(config, {\n    serverName: options?.serverName,\n    serverVersion: options?.serverVersion,\n    sdkName: options?.sdkName ?? \"@modelcontextprotocol/sdk\",\n    sdkVersion: options?.sdkVersion,\n    installMode: options?.installMode ?? \"sdk-wrapper\",\n  });\n\n  const wrapped: MinimalTransport = {\n    start: () => transport.start(),\n    close: () => {\n      void batcher.close();\n      return transport.close();\n    },\n    send: (message: any, sendOptions?: any) => {\n      const event = classifier.onOutgoing(message);\n      if (event) batcher.push(event);\n      return transport.send(message, sendOptions);\n    },\n    get sessionId() {\n      return transport.sessionId;\n    },\n    get onclose() {\n      return transport.onclose;\n    },\n    set onclose(fn) {\n      transport.onclose = fn;\n    },\n    get onerror() {\n      return transport.onerror;\n    },\n    set onerror(fn) {\n      transport.onerror = fn;\n    },\n    get onmessage() {\n      return transport.onmessage;\n    },\n    set onmessage(handler) {\n      transport.onmessage = (message: any, extra?: any) => {\n        classifier.onIncoming(message);\n        handler?.(message, extra);\n      };\n    },\n  };\n\n  return wrapped as T;\n}\n"],"mappings":"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","names":[]}

package/dist/src/proxy/run.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `mcpfy-proxy -- <command> [args...]`
+ *
+ * Spawns <command> as a child process and sits in its stdin/stdout pipe. Client-to-server
+ * messages (parent stdin -> child stdin) are classified as "incoming"; server-to-client
+ * messages (child stdout -> parent stdout) are classified as "outgoing", mirroring
+ * onmessage/send in the in-process wrapper. Works for any language — the proxy never
+ * parses anything beyond newline-delimited JSON-RPC framing.
+ */
+export declare function runProxy(argv: string[]): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/src/proxy/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/proxy/run.ts"],"names":[],"mappings":"AAmCA;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5D"}

package/dist/src/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Structural stand-in for the MCP SDK's `Transport` interface. Kept local (rather than
+ * depending on @modelcontextprotocol/sdk) so this package stays dependency-free — any
+ * real Transport (stdio, StreamableHTTP, or a third-party SDK's own transport) already
+ * satisfies this shape.
+ */
+export interface MinimalTransport {
+    start(): Promise<void>;
+    close(): Promise<void>;
+    send(message: any, options?: any): Promise<void>;
+    onmessage?: (message: any, extra?: any) => void;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    sessionId?: string;
+}
+export type SdkName = "mcpfy-sdk" | "@modelcontextprotocol/sdk" | "unknown";
+export type InstallMode = "sdk-env" | "sdk-wrapper" | "stdio-proxy";
+export interface TelemetryOptions {
+    /** Defaults to the MCPFY_API_KEY env var. Unset (in either form) = no-op, nothing is sent. */
+    apiKey?: string;
+    /** Defaults to MCPFY_TELEMETRY_ENDPOINT env var, then the MCPFY ingest URL. */
+    endpoint?: string;
+    serverName?: string;
+    serverVersion?: string;
+    sdkName?: SdkName;
+    sdkVersion?: string;
+    installMode?: InstallMode;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+}
+/**
+ * What actually crosses the wire. Method names, byte counts, timing, and outcome only —
+ * never argument values or result content. See telemetry-master-plan.md §2-3.
+ */
+export interface TelemetryEvent {
+    type: "request";
+    method: string;
+    toolName?: string;
+    promptName?: string;
+    resourceUri?: string;
+    clientName?: string;
+    clientVersion?: string;
+    protocolVersion?: string;
+    serverName?: string;
+    serverVersion?: string;
+    argsBytes?: number;
+    resultBytes?: number;
+    durationMs?: number;
+    outcome?: "ok" | "error";
+    errorCode?: number;
+    timestamp: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,2BAA2B,GAAG,SAAS,CAAC;AAC5E,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/src/wrap-transport.d.ts

@@ -0,0 +1,15 @@
+import type { MinimalTransport, TelemetryOptions } from "./types.js";
+/**
+ * Wraps a Transport's `onmessage`/`send` seam to capture telemetry, then delegates
+ * everything through to the real transport unchanged. If no API key is configured
+ * (via `options.apiKey` or the MCPFY_API_KEY env var), this is a complete no-op —
+ * the original transport is returned untouched.
+ *
+ * Usage (add these lines yourself — nothing here edits your files for you):
+ *
+ *   import { withMcpfyTelemetry } from "mcpfy-pulse";
+ *   const transport = new StdioServerTransport();
+ *   await server.connect(withMcpfyTelemetry(transport, { apiKey: process.env.MCPFY_API_KEY }));
+ */
+export declare function withMcpfyTelemetry<T extends MinimalTransport>(transport: T, options?: TelemetryOptions): T;
+//# sourceMappingURL=wrap-transport.d.ts.map

package/dist/src/wrap-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-transport.d.ts","sourceRoot":"","sources":["../../src/wrap-transport.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,gBAAgB,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAmD1G"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "mcpfy-pulse",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Telemetry for MCP servers: wrap any Transport, or proxy any command over stdio, to capture method/size/duration/outcome metrics for the MCPFY dashboard. Never sends argument values or resource content.",
+  "author": "mcpfy",
+  "license": "MIT",
+  "homepage": "https://github.com/mcpfyy/mcpfy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcpfyy/mcpfy.git",
+    "directory": "typescript/packages/mcpfy-pulse"
+  },
+  "bugs": {
+    "url": "https://github.com/mcpfyy/mcpfy/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcpfy",
+    "model-context-protocol",
+    "telemetry",
+    "observability",
+    "proxy"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "bin": {
+    "mcpfy-proxy": "dist/bin/mcpfy-proxy.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.cjs"
+    }
+  },
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsup && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}