toad-eye 2.5.0 → 2.6.1

package/dist/mcp/middleware.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP Server Middleware — wraps McpServer handler registration
+ * to automatically instrument tool calls, resource reads, and prompt gets.
+ *
+ * Uses Wrapper Pattern: intercepts .tool(), .resource(), .prompt() methods
+ * on the McpServer instance. Each handler is wrapped with OTel span creation.
+ *
+ * Why not monkey-patching: MCP SDK uses private class members (_requestHandlers)
+ * and strict TypeScript. Wrapping the public API is the stable path.
+ */
+import type { ToadMcpOptions } from "./types.js";
+export declare function toadEyeMiddleware(server: any, options?: ToadMcpOptions): void;
+/**
+ * Trace a sampling/createMessage call (server → client LLM request).
+ *
+ * Sampling is an outgoing request from the MCP server to the client,
+ * asking the client's LLM to generate a response. This cannot be
+ * auto-intercepted via wrapper pattern, so wrap manually.
+ *
+ * @example
+ * ```ts
+ * import { traceSampling } from "toad-eye/mcp";
+ *
+ * server.tool("summarize", { text: z.string() }, async ({ text }, ctx) => {
+ *   const response = await traceSampling(
+ *     () => ctx.mcpReq.requestSampling({
+ *       messages: [{ role: "user", content: { type: "text", text } }],
+ *       maxTokens: 500,
+ *     }),
+ *     { model: "gpt-4" }
+ *   );
+ *   return { content: [{ type: "text", text: response.content.text }] };
+ * });
+ * ```
+ */
+export declare function traceSampling<T>(fn: () => Promise<T>, options: TraceSamplingOptions): Promise<T>;
+export interface TraceSamplingOptions {
+    /** The model being requested for sampling. */
+    readonly model?: string | undefined;
+    /** Max tokens requested. */
+    readonly maxTokens?: number | undefined;
+    /** MCP server name for span attributes. */
+    readonly serverName?: string | undefined;
+    /** MCP server version for span attributes. */
+    readonly serverVersion?: string | undefined;
+    /** Parent OTel context. */
+    readonly parentContext?: import("@opentelemetry/api").Context | undefined;
+}

package/dist/mcp/middleware.js

@@ -0,0 +1,253 @@
+/**
+ * MCP Server Middleware — wraps McpServer handler registration
+ * to automatically instrument tool calls, resource reads, and prompt gets.
+ *
+ * Uses Wrapper Pattern: intercepts .tool(), .resource(), .prompt() methods
+ * on the McpServer instance. Each handler is wrapped with OTel span creation.
+ *
+ * Why not monkey-patching: MCP SDK uses private class members (_requestHandlers)
+ * and strict TypeScript. Wrapping the public API is the stable path.
+ */
+import { context, diag, DiagConsoleLogger, DiagLogLevel, } from "@opentelemetry/api";
+import { extractContextFromMeta } from "./context.js";
+import { startToolSpan, startResourceSpan, startPromptSpan, startSamplingSpan, endSpanSuccess, endSpanError, } from "./spans.js";
+import { recordMcpToolCall, recordMcpToolError, recordMcpResourceRead, recordMcpSessionStart, } from "./metrics.js";
+const DEFAULT_MAX_PAYLOAD_SIZE = 4096;
+function truncate(value, maxBytes) {
+    if (value.length <= maxBytes)
+        return value;
+    return value.slice(0, maxBytes) + "...[truncated]";
+}
+function redactObject(obj, keys) {
+    if (typeof obj !== "object" || obj === null)
+        return {};
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        result[k] = keys.includes(k) ? "[REDACTED]" : v;
+    }
+    return result;
+}
+/**
+ * Instrument an MCP server with OpenTelemetry tracing.
+ *
+ * Wraps .tool(), .resource(), .prompt() registration methods so every
+ * handler execution produces an OTel span with correct GenAI semconv attributes.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+ * import { toadEyeMiddleware } from "toad-eye/mcp";
+ *
+ * const server = new McpServer({ name: "my-server", version: "1.0.0" });
+ * toadEyeMiddleware(server);
+ *
+ * server.tool("calculate", { expression: z.string() }, async ({ expression }) => {
+ *   return { content: [{ type: "text", text: String(eval(expression)) }] };
+ * });
+ * ```
+ */
+/**
+ * Redirect OTel diagnostics to stderr to avoid polluting stdout.
+ * In stdio MCP transport, stdout IS the JSON-RPC channel —
+ * any stray console.log or OTel diagnostic would crash the connection.
+ */
+function ensureStdioSafe() {
+    const stderrLogger = new DiagConsoleLogger();
+    // Override the logger to use stderr-only methods
+    const safeLogger = {
+        verbose: (...args) => stderrLogger.verbose(String(args[0])),
+        debug: (...args) => stderrLogger.debug(String(args[0])),
+        info: (...args) => stderrLogger.info(String(args[0])),
+        warn: (...args) => stderrLogger.warn(String(args[0])),
+        error: (...args) => stderrLogger.error(String(args[0])),
+    };
+    diag.setLogger(safeLogger, DiagLogLevel.WARN);
+}
+export function toadEyeMiddleware(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+server, options = {}) {
+    ensureStdioSafe();
+    recordMcpSessionStart();
+    const serverName = server.name ?? server._name ?? "mcp-server";
+    const serverVersion = server.version ?? server._version ?? "unknown";
+    const recordInputs = options.recordInputs ?? false;
+    const recordOutputs = options.recordOutputs ?? false;
+    const redactKeys = options.redactKeys ?? [];
+    const maxPayload = options.maxPayloadSize ?? DEFAULT_MAX_PAYLOAD_SIZE;
+    const propagate = options.propagateContext ?? true;
+    const spanOpts = { serverName, serverVersion };
+    // --- Wrap .tool() ---
+    const originalTool = server.tool.bind(server);
+    server.tool = function wrappedTool(name, ...rest) {
+        // Find the handler — last function argument
+        const handlerIndex = rest.findIndex((arg) => typeof arg === "function");
+        if (handlerIndex === -1) {
+            return originalTool(name, ...rest);
+        }
+        const originalHandler = rest[handlerIndex];
+        rest[handlerIndex] = async function wrappedHandler(...handlerArgs) {
+            // Extract _meta for context propagation
+            const firstArg = handlerArgs[0];
+            const meta = propagate
+                ? firstArg?._meta
+                : undefined;
+            const parentCtx = propagate
+                ? extractContextFromMeta(meta)
+                : context.active();
+            const span = startToolSpan(name, {
+                ...spanOpts,
+                parentContext: parentCtx,
+            });
+            // Record inputs if enabled
+            if (recordInputs && firstArg) {
+                const sanitized = redactKeys.length > 0 ? redactObject(firstArg, redactKeys) : firstArg;
+                const serialized = truncate(JSON.stringify(sanitized), maxPayload);
+                span.setAttribute("gen_ai.tool.call.arguments", serialized);
+            }
+            // Custom hook
+            if (options.onToolCall) {
+                options.onToolCall(span, name, firstArg);
+            }
+            const start = performance.now();
+            try {
+                const result = await context.with(context.active(), () => originalHandler(...handlerArgs));
+                const durationMs = performance.now() - start;
+                // Record outputs if enabled
+                if (recordOutputs && result) {
+                    const serialized = truncate(JSON.stringify(result), maxPayload);
+                    span.setAttribute("gen_ai.tool.call.result", serialized);
+                }
+                endSpanSuccess(span);
+                recordMcpToolCall(name, durationMs, "success");
+                return result;
+            }
+            catch (error) {
+                const durationMs = performance.now() - start;
+                const errorType = error instanceof Error ? error.constructor.name : "UnknownError";
+                endSpanError(span, error);
+                recordMcpToolCall(name, durationMs, "error");
+                recordMcpToolError(name, errorType);
+                throw error;
+            }
+        };
+        return originalTool(name, ...rest);
+    };
+    // --- Wrap .resource() ---
+    const originalResource = server.resource?.bind(server);
+    if (originalResource) {
+        server.resource = function wrappedResource(name, ...rest) {
+            const handlerIndex = rest.findIndex((arg) => typeof arg === "function");
+            if (handlerIndex === -1) {
+                return originalResource(name, ...rest);
+            }
+            const originalHandler = rest[handlerIndex];
+            rest[handlerIndex] = async function wrappedHandler(...handlerArgs) {
+                const uri = handlerArgs[0]?.uri ?? name;
+                const parentCtx = propagate
+                    ? extractContextFromMeta(handlerArgs[0]?._meta)
+                    : context.active();
+                const span = startResourceSpan(uri, {
+                    ...spanOpts,
+                    parentContext: parentCtx,
+                });
+                if (options.onResourceRead) {
+                    options.onResourceRead(span, uri);
+                }
+                try {
+                    const result = await originalHandler(...handlerArgs);
+                    endSpanSuccess(span);
+                    recordMcpResourceRead(uri);
+                    return result;
+                }
+                catch (error) {
+                    endSpanError(span, error);
+                    throw error;
+                }
+            };
+            return originalResource(name, ...rest);
+        };
+    }
+    // --- Wrap .prompt() ---
+    const originalPrompt = server.prompt?.bind(server);
+    if (originalPrompt) {
+        server.prompt = function wrappedPrompt(name, ...rest) {
+            const handlerIndex = rest.findIndex((arg) => typeof arg === "function");
+            if (handlerIndex === -1) {
+                return originalPrompt(name, ...rest);
+            }
+            const originalHandler = rest[handlerIndex];
+            rest[handlerIndex] = async function wrappedHandler(...handlerArgs) {
+                const parentCtx = propagate
+                    ? extractContextFromMeta(handlerArgs[0]?._meta)
+                    : context.active();
+                const span = startPromptSpan(name, {
+                    ...spanOpts,
+                    parentContext: parentCtx,
+                });
+                try {
+                    const result = await originalHandler(...handlerArgs);
+                    endSpanSuccess(span);
+                    return result;
+                }
+                catch (error) {
+                    endSpanError(span, error);
+                    throw error;
+                }
+            };
+            return originalPrompt(name, ...rest);
+        };
+    }
+}
+/**
+ * Trace a sampling/createMessage call (server → client LLM request).
+ *
+ * Sampling is an outgoing request from the MCP server to the client,
+ * asking the client's LLM to generate a response. This cannot be
+ * auto-intercepted via wrapper pattern, so wrap manually.
+ *
+ * @example
+ * ```ts
+ * import { traceSampling } from "toad-eye/mcp";
+ *
+ * server.tool("summarize", { text: z.string() }, async ({ text }, ctx) => {
+ *   const response = await traceSampling(
+ *     () => ctx.mcpReq.requestSampling({
+ *       messages: [{ role: "user", content: { type: "text", text } }],
+ *       maxTokens: 500,
+ *     }),
+ *     { model: "gpt-4" }
+ *   );
+ *   return { content: [{ type: "text", text: response.content.text }] };
+ * });
+ * ```
+ */
+export async function traceSampling(fn, options) {
+    const model = options.model ?? "unknown";
+    const span = startSamplingSpan(model, {
+        serverName: options.serverName ?? "mcp-server",
+        serverVersion: options.serverVersion ?? "unknown",
+        parentContext: options.parentContext,
+    });
+    if (options.maxTokens !== undefined) {
+        span.setAttribute("gen_ai.request.max_tokens", options.maxTokens);
+    }
+    const start = performance.now();
+    try {
+        const result = await fn();
+        const durationMs = performance.now() - start;
+        // Extract token usage from response if available
+        const response = result;
+        if (response && typeof response === "object") {
+            if (response["model"]) {
+                span.setAttribute("gen_ai.response.model", String(response["model"]));
+            }
+        }
+        span.setAttribute("gen_ai.mcp.sampling.duration_ms", durationMs);
+        endSpanSuccess(span);
+        return result;
+    }
+    catch (error) {
+        endSpanError(span, error);
+        throw error;
+    }
+}

package/dist/mcp/spans.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OTel span creation for MCP operations.
+ *
+ * Maps MCP methods to OTel GenAI semantic conventions:
+ * - tools/call              → execute_tool {tool_name}
+ * - resources/read          → retrieval {uri}
+ * - prompts/get             → prompt {name}
+ * - sampling/createMessage  → chat {model}
+ */
+import { type Context } from "@opentelemetry/api";
+declare const tracer: import("@opentelemetry/api").Tracer;
+export interface SpanOptions {
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly parentContext: Context;
+}
+export declare function startToolSpan(toolName: string, options: SpanOptions): import("@opentelemetry/api").Span;
+export declare function startResourceSpan(uri: string, options: SpanOptions): import("@opentelemetry/api").Span;
+export declare function startPromptSpan(promptName: string, options: SpanOptions): import("@opentelemetry/api").Span;
+export interface SamplingSpanOptions {
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly parentContext?: Context | undefined;
+}
+export declare function startSamplingSpan(model: string, options: SamplingSpanOptions): import("@opentelemetry/api").Span;
+export declare function endSpanSuccess(span: ReturnType<typeof tracer.startSpan>): void;
+export declare function endSpanError(span: ReturnType<typeof tracer.startSpan>, error: unknown): void;
+export {};

package/dist/mcp/spans.js

@@ -0,0 +1,67 @@
+/**
+ * OTel span creation for MCP operations.
+ *
+ * Maps MCP methods to OTel GenAI semantic conventions:
+ * - tools/call              → execute_tool {tool_name}
+ * - resources/read          → retrieval {uri}
+ * - prompts/get             → prompt {name}
+ * - sampling/createMessage  → chat {model}
+ */
+import { trace, SpanStatusCode, SpanKind, } from "@opentelemetry/api";
+const TRACER_NAME = "toad-eye-mcp";
+const tracer = trace.getTracer(TRACER_NAME);
+export function startToolSpan(toolName, options) {
+    return tracer.startSpan(`execute_tool ${toolName}`, {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": toolName,
+            "mcp.server.name": options.serverName,
+            "mcp.server.version": options.serverVersion,
+        },
+    }, options.parentContext);
+}
+export function startResourceSpan(uri, options) {
+    return tracer.startSpan(`retrieval ${uri}`, {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+            "gen_ai.operation.name": "retrieval",
+            "gen_ai.data_source.id": uri,
+            "mcp.server.name": options.serverName,
+            "mcp.server.version": options.serverVersion,
+        },
+    }, options.parentContext);
+}
+export function startPromptSpan(promptName, options) {
+    return tracer.startSpan(`prompt ${promptName}`, {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+            "gen_ai.operation.name": "prompt",
+            "gen_ai.prompt.name": promptName,
+            "mcp.server.name": options.serverName,
+            "mcp.server.version": options.serverVersion,
+        },
+    }, options.parentContext);
+}
+export function startSamplingSpan(model, options) {
+    return tracer.startSpan(`chat ${model}`, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            "gen_ai.operation.name": "chat",
+            "gen_ai.request.model": model,
+            "mcp.server.name": options.serverName,
+            "mcp.server.version": options.serverVersion,
+        },
+    }, options.parentContext);
+}
+export function endSpanSuccess(span) {
+    span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+}
+export function endSpanError(span, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const errorType = error instanceof Error ? error.constructor.name : "UnknownError";
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    span.setAttribute("error.type", errorType);
+    span.end();
+}

package/dist/mcp/types.d.ts

@@ -0,0 +1,34 @@
+import type { Span } from "@opentelemetry/api";
+/** Configuration for toadEyeMiddleware(). */
+export interface ToadMcpOptions {
+    /** Service name for OTel resource. Defaults to MCP server name. */
+    readonly serviceName?: string | undefined;
+    /** OTLP endpoint. Uses existing OTel config if initObservability() was called. */
+    readonly endpoint?: string | undefined;
+    /** Record tool call arguments in spans. Default: false (privacy). */
+    readonly recordInputs?: boolean | undefined;
+    /** Record tool call results in spans. Default: false (privacy). */
+    readonly recordOutputs?: boolean | undefined;
+    /** Keys to redact from recorded arguments. */
+    readonly redactKeys?: readonly string[] | undefined;
+    /** Max payload size in bytes before truncation. Default: 4096. */
+    readonly maxPayloadSize?: number | undefined;
+    /** Extract W3C traceparent from _meta field. Default: true. */
+    readonly propagateContext?: boolean | undefined;
+    /** Hook called on each tool call span. Add custom attributes here. */
+    readonly onToolCall?: ((span: Span, toolName: string, args: unknown) => void) | undefined;
+    /** Hook called on each resource read span. */
+    readonly onResourceRead?: ((span: Span, uri: string) => void) | undefined;
+}
+/** OTel attributes set on MCP spans. */
+export interface McpSpanAttributes {
+    readonly "gen_ai.operation.name": string;
+    readonly "gen_ai.tool.name"?: string;
+    readonly "gen_ai.tool.call.id"?: string;
+    readonly "gen_ai.data_source.id"?: string;
+    readonly "gen_ai.prompt.name"?: string;
+    readonly "mcp.server.name": string;
+    readonly "mcp.server.version": string;
+    readonly "mcp.transport"?: "stdio" | "sse" | "streamable-http";
+    readonly "mcp.session.id"?: string;
+}

package/dist/mcp/types.js

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

package/dist/types/config.d.ts

@@ -38,6 +38,8 @@ export interface ToadEyeConfig {
     readonly redactDefaults?: boolean | undefined;
     /** Log what was masked to console (for debugging redaction config). No data is sent externally. */
     readonly auditMasking?: boolean | undefined;
+    /** Record content for only this fraction of calls (0.0–1.0). E.g., 0.01 = 1%. Enables debugging without full storage/privacy cost. */
+    readonly contentSamplingRate?: number | undefined;
     /** Configure trace sampling. Tail sampling happens in OTel Collector, not SDK. */
     readonly sampling?: SamplingConfig | undefined;
     readonly instrument?: readonly InstrumentTarget[] | undefined;
@@ -47,12 +49,12 @@ export interface ToadEyeConfig {
     readonly onBudgetExceeded?: BudgetExceededMode | undefined;
     /** Callback for 'downgrade' mode — receives original provider/model, returns replacement. */
     readonly downgradeCallback?: DowngradeCallback | undefined;
-    /** Warn or block when context window utilization exceeds thresholds. */
+    /** Warn when context window utilization exceeds thresholds (post-call). */
     readonly contextGuard?: {
         /** Warn when utilization exceeds this ratio (0.0–1.0). Default: none. */
         readonly warnAt?: number | undefined;
-        /** Block (throw ToadContextExceededError) when utilization exceeds this ratio. Default: none. */
-        readonly blockAt?: number | undefined;
+        /** Alert (span event + metric + warning) when utilization exceeds this ratio. Default: none. */
+        readonly alertAt?: number | undefined;
     } | undefined;
     /** Static session ID — all spans will carry this value as `session.id`. */
     readonly sessionId?: string | undefined;

package/dist/types/metrics.d.ts

@@ -26,6 +26,11 @@ export declare const GEN_AI_METRICS: {
     readonly RESPONSE_LATENCY_PER_TOKEN: "gen_ai.toad_eye.response.latency_per_token";
     readonly CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization";
     readonly CONTEXT_BLOCKED: "gen_ai.toad_eye.context.blocked";
+    readonly MCP_TOOL_DURATION: "gen_ai.mcp.tool.duration";
+    readonly MCP_TOOL_CALLS: "gen_ai.mcp.tool.calls";
+    readonly MCP_TOOL_ERRORS: "gen_ai.mcp.tool.errors";
+    readonly MCP_RESOURCE_READS: "gen_ai.mcp.resource.reads";
+    readonly MCP_SESSION_ACTIVE: "gen_ai.mcp.session.active";
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export declare const LLM_METRICS: {

package/dist/types/metrics.js

@@ -33,6 +33,12 @@ export const GEN_AI_METRICS = {
     // Context utilization
     CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization",
     CONTEXT_BLOCKED: "gen_ai.toad_eye.context.blocked",
+    // MCP metrics
+    MCP_TOOL_DURATION: "gen_ai.mcp.tool.duration",
+    MCP_TOOL_CALLS: "gen_ai.mcp.tool.calls",
+    MCP_TOOL_ERRORS: "gen_ai.mcp.tool.errors",
+    MCP_RESOURCE_READS: "gen_ai.mcp.resource.reads",
+    MCP_SESSION_ACTIVE: "gen_ai.mcp.session.active",
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export const LLM_METRICS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toad-eye",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Auto-instrumentation, cost tracking, budget guards, and observability for LLM services",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,11 @@
       "types": "./dist/vercel.d.ts",
       "import": "./dist/vercel.js",
       "default": "./dist/vercel.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js",
+      "default": "./dist/mcp/index.js"
     }
   },
   "bin": {
@@ -87,7 +92,8 @@
     "@anthropic-ai/sdk": ">=0.30.0",
     "@google/generative-ai": ">=0.20.0",
     "nodemailer": ">=8.0.0",
-    "openai": ">=4.0.0"
+    "openai": ">=4.0.0",
+    "@modelcontextprotocol/sdk": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "openai": {
@@ -101,6 +107,9 @@
     },
     "nodemailer": {
       "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
     }
   },
   "devDependencies": {

package/templates/docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   collector:
-    image: otel/opentelemetry-collector-contrib:latest
+    image: otel/opentelemetry-collector-contrib:0.102.0
     volumes:
       - ./otel-collector.yml:/etc/otelcol-contrib/config.yaml
     ports:
@@ -10,14 +10,14 @@ services:
       - prometheus
 
   prometheus:
-    image: prom/prometheus:latest
+    image: prom/prometheus:v2.53.0
     volumes:
       - ./prometheus.yml:/etc/prometheus/prometheus.yml
     ports:
       - "9090:9090"
 
   jaeger:
-    image: jaegertracing/all-in-one:latest
+    image: jaegertracing/all-in-one:1.58
     environment:
       - COLLECTOR_OTLP_ENABLED=true
     ports:
@@ -25,7 +25,7 @@ services:
       - "4317:4317"
 
   grafana:
-    image: grafana/grafana:latest
+    image: grafana/grafana:11.1.0
     volumes:
       - ./grafana/datasources.yml:/etc/grafana/provisioning/datasources/datasources.yml
       - ./grafana/dashboards:/etc/grafana/provisioning/dashboards