@upstash/context7-mcp 4.0.6 → 4.1.0

package/README.md

@@ -1490,6 +1490,133 @@ CONTEXT7_API_KEY=your_api_key_here
 }
 ```
 
+### OpenTelemetry observability
+
+Context7 instruments individual MCP requests and notifications at the SDK transport boundary,
+including messages inside a valid batch and MCP v2 `subscriptions/listen` operations handled by the
+SDK entry layer. Requests rejected by the SDK's HTTP envelope and protocol-version validation before
+dispatch remain visible in normal HTTP/gateway telemetry, but are not reported as MCP operations.
+Observed operations follow the
+development-status [OpenTelemetry MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md)
+for server metrics and spans. Trace context is extracted from the `traceparent`, `tracestate`, and
+`baggage` fields in MCP `params._meta` as defined by
+[SEP-414](https://modelcontextprotocol.io/seps/414-request-meta).
+
+The HTTP transport exposes metrics in Prometheus format on a dedicated listener at
+`127.0.0.1:9464/metrics` by default. The production Docker image explicitly binds that listener to
+`0.0.0.0` so an internal Prometheus pod scraper or `PodMonitor` can reach it. The stdio transport
+does not open a telemetry port. Keeping this listener separate from the public MCP port prevents
+the metrics endpoint from being routed through a catch-all gateway rule. On SIGTERM, SIGINT, or
+SIGHUP, both transports use a bounded shutdown path that stops serving, closes active MCP
+connections and subscriptions, and best-effort flushes externally installed SDK metric and trace
+providers before exit. Stdio EOF triggers the same path.
+
+The exporter uses the standard OpenTelemetry Prometheus settings:
+
+- `OTEL_EXPORTER_PROMETHEUS_HOST` changes the bind address (default `127.0.0.1`; the Docker image
+  sets `0.0.0.0`).
+- `OTEL_EXPORTER_PROMETHEUS_PORT` changes the port (default `9464`).
+- `OTEL_METRICS_EXPORTER=none` or `OTEL_SDK_DISABLED=true` disables the embedded exporter.
+
+`OTEL_SDK_DISABLED=true` is the hard-off switch: provider modules are not loaded and MCP
+transports and handlers are not wrapped, preserving the baseline request path. In contrast,
+`OTEL_METRICS_EXPORTER=none` disables only the embedded Prometheus bootstrap, so a provider
+installed by a Node preload can still receive the MCP signals.
+
+Exporter bind or configuration failures are logged but do not prevent the MCP endpoint from
+starting. If a Node preload has already registered global OpenTelemetry providers, they take
+precedence. The embedded Prometheus listener is not started when a global `MeterProvider` exists,
+and MCP spans are exported through the preload's `TracerProvider`. This supports an OpenTelemetry
+Node SDK or Kubernetes auto-instrumentation without creating a second provider in the application.
+When an external SDK owns the provider, configure its Node runtime instrumentation there as well;
+the application does not register a duplicate collector.
+
+It reports bounded-cardinality counters, histograms, and in-flight gauges for MCP methods,
+subscriptions, tool outcomes, authentication outcomes, Context7 upstream requests, and Node runtime
+saturation.
+Prometheus receives these metric families:
+
+- `mcp_server_operation_duration` (its `_count` series is the MCP operation count, and tool-call
+  series include the `context7_mcp_tool_outcome` label)
+- `mcp_server_session_duration` for real stateful stdio sessions (stateless HTTP request transports
+  are intentionally excluded)
+- `context7_mcp_operations_active`
+- `context7_mcp_subscriptions_active` and `context7_mcp_subscription_duration`
+- `context7_mcp_upstream_requests_total` and `context7_mcp_upstream_request_duration`
+- `context7_mcp_authentication_attempts_total` and `context7_mcp_authentication_duration`
+- `context7_mcp_upstream_requests_active` and `context7_mcp_authentication_active`
+- `nodejs_eventloop_*`, `v8js_gc_duration`, `v8js_memory_heap_*`, and
+  `v8js_resource_active` from the official OpenTelemetry Node runtime instrumentation
+
+Tool outcomes on the standard MCP operation metric distinguish `success`, `not_found`, and
+`error`. An acknowledged `subscriptions/listen` operation is timed through its acknowledgement;
+the separate subscription metrics track the active stream and its bounded terminal outcome.
+Upstream outcomes distinguish
+HTTP, response-decoding, network, timeout, and cancellation failures and include both the bounded
+status-code class and the exact numeric HTTP status. Authentication reports accepted, missing,
+invalid, and unexpected-error outcomes. The OAuth authorization-server metadata proxy caps its
+upstream fetch at 10 seconds and returns `502` if that dependency times out.
+
+The labels intentionally exclude API keys, client IPs, queries, library IDs, session IDs, and raw
+error text. Expose port `9464` only to your Prometheus scraper or `ServiceMonitor`, not through the
+public MCP ingress.
+
+#### Signal ownership with an Envoy gateway
+
+Do not treat `mcp_server_operation_duration_count` as another HTTP request counter. An Envoy
+Gateway observes HTTP envelopes, while this metric observes JSON-RPC requests and notifications
+after SDK dispatch. A valid batch is one HTTP request but several MCP operations, and HTTP requests
+rejected before MCP dispatch never increment the MCP metric.
+
+Context7 deliberately does **not** register generic inbound HTTP server metrics. Keep the following
+signals in the existing Envoy scrape instead of collecting them again from the application:
+
+- downstream HTTP request/response totals, status classes, duration, active requests, connections,
+  resets, and gateway timeouts (`envoy_http_*_downstream_*`)
+- Envoy-to-MCP backend request totals, status codes, duration, active/pending requests, connection
+  failures, retries, resets, timeouts, and circuit-breaker overflows (`envoy_cluster_upstream_*`)
+- Envoy process health and resource metrics
+
+The application exporter owns only signals the ingress gateway cannot provide: MCP method and
+protocol semantics (including batches, notifications, and active MCP v2 subscriptions), tool and
+authentication outcomes, MCP-to-Context7 API calls, and Node event-loop/V8 health. In the
+Kubernetes deployment Envoy is a
+Gateway API proxy rather than a sidecar in the MCP pod, so `context7_mcp_upstream_*` describes the
+MCP server's outbound Context7 API dependency, not Envoy's inbound MCP backend cluster. Pod and
+container CPU, memory, network, and restart metrics should continue to come from the Kubernetes
+monitoring stack.
+
+See the [Envoy HTTP connection manager statistics](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/stats)
+and [upstream cluster statistics](https://www.envoyproxy.io/docs/envoy/latest/configuration/upstream/cluster_manager/cluster_stats.html)
+for the proxy-owned metric families.
+
+For a replicated Kubernetes deployment, discover and scrape every MCP pod directly. Do not use one
+static, load-balanced Service target: successive scrapes can reach different replicas and produce
+incomplete per-process counters and runtime series. For an annotation-based `kubernetes-pods`
+scrape job, add the following fields to the MCP workload's pod template:
+
+```yaml
+spec:
+  template:
+    metadata:
+      annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: "9464"
+        prometheus.io/path: /metrics
+    spec:
+      containers:
+        - name: mcp
+          ports:
+            - name: metrics
+              containerPort: 9464
+              protocol: TCP
+```
+
+Prometheus will then scrape `http://<mcp-pod-ip>:9464/metrics` for each replica. Declaring
+`EXPOSE 9464` in the image does not add the Kubernetes `containerPort` metadata. The scrape interval
+is controlled by Prometheus; the exporter does not impose one. If the monitoring stack uses the
+Prometheus Operator instead, configure the equivalent per-pod endpoint with a `PodMonitor`.
+
 <details>
 <summary><b>Local Configuration Example</b></summary>
 

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { toNodeHandler } from "@modelcontextprotocol/node";
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { McpServer, createMcpHandler } from "@modelcontextprotocol/server";
+import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
+import { McpServer, createMcpHandler, } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { searchLibraries, fetchLibraryContext } from "./lib/api.js";
 import { formatSearchResults, extractClientInfoFromUserAgent, envelopeClientInfo, } from "./lib/utils.js";
@@ -12,17 +12,25 @@ import { AsyncLocalStorage } from "async_hooks";
 import { randomUUID } from "node:crypto";
 import { SERVER_VERSION, RESOURCE_URL, OAUTH_AUTH_SERVER_URL, EMA_ISSUER, OPENAI_APPS_CHALLENGE_TOKEN, } from "./lib/constants.js";
 import { maybeElicitAuthSignIn } from "./lib/auth/auth-prompt.js";
+import { QUERY_DOCS_TOOL, RESOLVE_LIBRARY_ID_TOOL } from "./lib/tool-names.js";
+import { installProcessShutdown } from "./lib/process-shutdown.js";
 import { getMaxSubscriptions } from "./lib/subscriptions.js";
+import { forceFlushTelemetry, initializeTelemetry, observeAuthentication, observeUpstreamRequest, recordToolCallOutcome, } from "./lib/telemetry-runtime.js";
 import { mcpBodyErrorHandler } from "./lib/mcp-body-error-handler.js";
 /** Default HTTP server port */
 const DEFAULT_PORT = 3000;
+const OAUTH_METADATA_TIMEOUT_MS = 10_000;
 const CLAUDE_CODE_PLUGIN = "claude-code-plugin";
+let mcpInstrumentation;
 function getPluginFromRequest(req) {
     return req.query.client === CLAUDE_CODE_PLUGIN ? CLAUDE_CODE_PLUGIN : undefined;
 }
 function requiresAuthentication(req, plugin) {
     // The MCP routes live on a router mounted at /mcp, so req.path is relative to it.
-    return `${req.baseUrl}${req.path}` === "/mcp/oauth" || Boolean(plugin);
+    const isOAuthEndpoint = `${req.baseUrl}${req.path}` === "/mcp/oauth";
+    // The current official Claude plugin expands an unset API key to an empty header.
+    const hasEmptyPluginAuthorization = plugin === CLAUDE_CODE_PLUGIN && req.headers.authorization === "";
+    return isOAuthEndpoint || (Boolean(plugin) && !hasEmptyPluginAuthorization);
 }
 // Parse CLI arguments using commander
 const program = new Command()
@@ -113,8 +121,8 @@ function aliasArgs(aliases) {
         return args;
     };
 }
-function createMcpServer() {
-    const server = new McpServer({
+function createMcpServer(mcpContext) {
+    const serverInfo = {
         name: "Context7",
         version: SERVER_VERSION,
         websiteUrl: "https://context7.com",
@@ -125,7 +133,8 @@ function createMcpServer() {
                 mimeType: "image/png",
             },
         ],
-    }, {
+    };
+    const serverOptions = {
         // Declaring the capabilities makes the SDK install prompts/list,
         // resources/list, and resources/templates/list handlers that answer
         // with the registered (i.e. empty) collections, for clients that
@@ -134,8 +143,11 @@ function createMcpServer() {
         instructions: `Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service — even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs.
 
 Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.`,
-    });
-    server.registerTool("resolve-library-id", {
+    };
+    const server = mcpInstrumentation
+        ? mcpInstrumentation.createServer(serverInfo, serverOptions, mcpContext)
+        : new McpServer(serverInfo, serverOptions);
+    server.registerTool(RESOLVE_LIBRARY_ID_TOOL, {
         title: "Resolve Context7 Library ID",
         description: `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
 
@@ -190,6 +202,7 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
         if (!searchResponse.results || searchResponse.results.length === 0) {
             const text = searchResponse.error ?? "No libraries found matching the provided name.";
             maybeElicitAuthSignIn(server, ctx);
+            recordToolCallOutcome(searchResponse.error ? "error" : "not_found");
             return {
                 content: [
                     {
@@ -202,6 +215,7 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
         const resultsText = formatSearchResults(searchResponse);
         const responseText = `Available Libraries:\n\n${resultsText}`;
         maybeElicitAuthSignIn(server, ctx);
+        recordToolCallOutcome("success");
         return {
             content: [
                 {
@@ -211,7 +225,7 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
             ],
         };
     });
-    server.registerTool("query-docs", {
+    server.registerTool(QUERY_DOCS_TOOL, {
         title: "Query Documentation",
         description: `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.
 
@@ -236,6 +250,7 @@ Do not call this tool more than 3 times per question.`,
         const ctx = getClientContext(toolCtx);
         const response = await fetchLibraryContext({ query, libraryId }, ctx);
         maybeElicitAuthSignIn(server, ctx);
+        recordToolCallOutcome(response.outcome);
         return {
             content: [
                 {
@@ -248,6 +263,10 @@ Do not call this tool more than 3 times per question.`,
     return server;
 }
 async function main() {
+    mcpInstrumentation = await initializeTelemetry({
+        allowEmbeddedPrometheus: TRANSPORT_TYPE === "http",
+        serviceVersion: SERVER_VERSION,
+    });
     if (TRANSPORT_TYPE === "http") {
         const initialPort = CLI_PORT ?? DEFAULT_PORT;
         const app = express();
@@ -306,11 +325,14 @@ async function main() {
         // then never closes the stream, and with heartbeats it survived until the
         // gateway's 1200s hard cap (the 2026-08-11 outage). Silent hangs instead
         // go idle and the gateway reaps them at streamIdleTimeout (300s).
-        const mcpHandler = createMcpHandler(() => createMcpServer(), {
+        const rawMcpHandler = createMcpHandler((mcpContext) => createMcpServer(mcpContext), {
             keepAliveMs: 0,
             maxSubscriptions: getMaxSubscriptions(),
             onerror: (error) => console.error("MCP handler error:", error),
         });
+        const mcpHandler = mcpInstrumentation
+            ? mcpInstrumentation.instrumentHttpHandler(rawMcpHandler)
+            : rawMcpHandler;
         // Without onerror, request-conversion / handler.fetch throws are answered
         // with a bare 500 inside the adapter and never reach our express handler.
         const nodeHandler = toNodeHandler(mcpHandler, {
@@ -322,34 +344,42 @@ async function main() {
                 const apiKey = extractApiKey(req);
                 const baseUrl = new URL(RESOURCE_URL).origin;
                 // OAuth discovery info header, used by MCP clients to discover the authorization server
-                // TODO: @modelcontextprotocol/server now ships canonical OAuth helpers
-                // (bearerAuthChallengeResponse, buildOAuthProtectedResourceMetadata,
-                // oauthMetadataResponse) — replace this hand-rolled header and the
-                // /.well-known/oauth-protected-resource route with them.
                 res.set("WWW-Authenticate", `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"`);
                 if (requiresAuthentication(req, plugin)) {
-                    if (!apiKey) {
-                        return res.status(401).json({
+                    const authentication = await observeAuthentication(async () => {
+                        if (!apiKey) {
+                            return {
+                                outcome: "missing",
+                                value: {
+                                    accepted: false,
+                                    error: "Authentication required. Please authenticate to use this MCP server.",
+                                },
+                            };
+                        }
+                        if (isJWT(apiKey)) {
+                            const validationResult = await validateJWT(apiKey);
+                            if (!validationResult.valid) {
+                                return {
+                                    outcome: "invalid",
+                                    value: {
+                                        accepted: false,
+                                        error: validationResult.error || "Invalid token. Please re-authenticate.",
+                                    },
+                                };
+                            }
+                        }
+                        return { outcome: "accepted", value: { accepted: true } };
+                    });
+                    if (!authentication.accepted) {
+                        res.status(401).json({
                             jsonrpc: "2.0",
                             error: {
                                 code: -32001,
-                                message: "Authentication required. Please authenticate to use this MCP server.",
+                                message: authentication.error,
                             },
                             id: null,
                         });
-                    }
-                    if (isJWT(apiKey)) {
-                        const validationResult = await validateJWT(apiKey);
-                        if (!validationResult.valid) {
-                            return res.status(401).json({
-                                jsonrpc: "2.0",
-                                error: {
-                                    code: -32001,
-                                    message: validationResult.error || "Invalid token. Please re-authenticate.",
-                                },
-                                id: null,
-                            });
-                        }
+                        return;
                     }
                 }
                 const context = {
@@ -403,16 +433,22 @@ async function main() {
         app.get("/.well-known/oauth-authorization-server", async (_req, res) => {
             const authServerUrl = OAUTH_AUTH_SERVER_URL;
             try {
-                const response = await fetch(`${authServerUrl}/.well-known/oauth-authorization-server`);
-                if (!response.ok) {
-                    console.error("[OAuth] Upstream error:", response.status);
-                    return res.status(response.status).json({
+                const abortSignal = AbortSignal.timeout(OAUTH_METADATA_TIMEOUT_MS);
+                const upstream = await observeUpstreamRequest("oauth_metadata", () => fetch(`${authServerUrl}/.well-known/oauth-authorization-server`, {
+                    signal: abortSignal,
+                }), async (response) => {
+                    if (!response.ok)
+                        return { ok: false, status: response.status };
+                    return { ok: true, metadata: await response.json() };
+                }, { abortSignal });
+                if (!upstream.ok) {
+                    console.error("[OAuth] Upstream error:", upstream.status);
+                    return res.status(upstream.status).json({
                         error: "upstream_error",
                         message: "Failed to fetch authorization server metadata",
                     });
                 }
-                const metadata = await response.json();
-                res.json(metadata);
+                res.json(upstream.metadata);
             }
             catch (error) {
                 console.error("[OAuth] Error fetching OAuth metadata:", error);
@@ -439,8 +475,36 @@ async function main() {
                 message: "Endpoint not found. Use /mcp for MCP protocol communication.",
             });
         });
+        let activeHttpServer;
+        installProcessShutdown({
+            close: async () => {
+                const server = activeHttpServer;
+                const operations = [mcpHandler.close()];
+                if (server) {
+                    operations.unshift(new Promise((resolve, reject) => {
+                        server.close((error) => {
+                            if (error)
+                                reject(error);
+                            else
+                                resolve();
+                        });
+                    }));
+                }
+                const results = await Promise.allSettled(operations);
+                const failures = results
+                    .filter((result) => result.status === "rejected")
+                    .map((result) => result.reason);
+                if (failures.length > 0) {
+                    throw new AggregateError(failures, "MCP HTTP server failed to close cleanly");
+                }
+            },
+        }, {
+            flush: forceFlushTelemetry,
+            onerror: (error) => console.error("Failed to close MCP HTTP server:", error),
+        });
         const startServer = (port, maxAttempts = 10) => {
             const httpServer = app.listen(port);
+            activeHttpServer = httpServer;
             httpServer.once("error", (err) => {
                 if (err.code === "EADDRINUSE" && port < initialPort + maxAttempts) {
                     console.warn(`Port ${port} is in use, trying port ${port + 1}...`);
@@ -460,11 +524,12 @@ async function main() {
     else {
         stdioApiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY;
         stdioSessionId = randomUUID();
-        process.stdin.on("end", () => process.exit(0));
-        process.stdin.on("close", () => process.exit(0));
-        process.on("SIGHUP", () => process.exit(0));
-        serveStdio(() => {
-            const server = createMcpServer();
+        const rawStdioTransport = new StdioServerTransport();
+        const stdioTransport = mcpInstrumentation
+            ? mcpInstrumentation.instrumentStdioTransport(rawStdioTransport)
+            : rawStdioTransport;
+        const stdioHandle = serveStdio((mcpContext) => {
+            const server = createMcpServer(mcpContext);
             // Capture client info from MCP initialize handshake (stdio only — HTTP
             // mode plumbs client info through requestContext per request).
             server.server.oninitialized = () => {
@@ -478,8 +543,14 @@ async function main() {
             };
             return server;
         }, {
+            transport: stdioTransport,
             onerror: (error) => console.error("MCP stdio error:", error),
         });
+        installProcessShutdown(stdioHandle, {
+            flush: forceFlushTelemetry,
+            input: process.stdin,
+            onerror: (error) => console.error("Failed to close MCP stdio server:", error),
+        });
         console.error(`Context7 Documentation MCP Server v${SERVER_VERSION} running on stdio`);
     }
 }

package/dist/lib/api.js

@@ -3,6 +3,7 @@ import { Agent, ProxyAgent, setGlobalDispatcher } from "undici";
 import { CONTEXT7_API_BASE_URL } from "./constants.js";
 import { readFileSync } from "fs";
 import tls from "tls";
+import { observeUpstreamRequest } from "./telemetry-runtime.js";
 /**
  * Ceiling on a single Context7 API call. Without a signal a stalled backend
  * call rides undici's ~300s default before failing. 60s is generous for these
@@ -106,15 +107,17 @@ export async function searchLibraries(query, libraryName, context = {}) {
         url.searchParams.set("query", query);
         url.searchParams.set("libraryName", libraryName);
         const headers = generateHeaders(context);
-        const response = await fetch(url, { headers, signal: AbortSignal.timeout(API_TIMEOUT_MS) });
-        readPromptSignal(response, context);
-        if (!response.ok) {
-            const errorMessage = await parseErrorResponse(response, context.apiKey);
-            console.error(errorMessage);
-            return { results: [], error: errorMessage };
-        }
-        const searchData = await response.json();
-        return searchData;
+        const abortSignal = AbortSignal.timeout(API_TIMEOUT_MS);
+        return await observeUpstreamRequest("search_libraries", () => fetch(url, { headers, signal: abortSignal }), async (response) => {
+            readPromptSignal(response, context);
+            if (!response.ok) {
+                const errorMessage = await parseErrorResponse(response, context.apiKey);
+                console.error(errorMessage);
+                return { results: [], error: errorMessage };
+            }
+            const searchData = await response.json();
+            return searchData;
+        }, { abortSignal });
     }
     catch (error) {
         const errorMessage = `Error searching libraries: ${error}`;
@@ -134,24 +137,27 @@ export async function fetchLibraryContext(request, context = {}) {
         url.searchParams.set("query", request.query);
         url.searchParams.set("libraryId", request.libraryId);
         const headers = generateHeaders(context);
-        const response = await fetch(url, { headers, signal: AbortSignal.timeout(API_TIMEOUT_MS) });
-        readPromptSignal(response, context);
-        if (!response.ok) {
-            const errorMessage = await parseErrorResponse(response, context.apiKey);
-            console.error(errorMessage);
-            return { data: errorMessage };
-        }
-        const text = await response.text();
-        if (!text) {
-            return {
-                data: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolve-library-id' with the package name you wish to retrieve documentation for.",
-            };
-        }
-        return { data: text };
+        const abortSignal = AbortSignal.timeout(API_TIMEOUT_MS);
+        return await observeUpstreamRequest("fetch_context", () => fetch(url, { headers, signal: abortSignal }), async (response) => {
+            readPromptSignal(response, context);
+            if (!response.ok) {
+                const errorMessage = await parseErrorResponse(response, context.apiKey);
+                console.error(errorMessage);
+                return { data: errorMessage, outcome: "error" };
+            }
+            const text = await response.text();
+            if (!text) {
+                return {
+                    data: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolve-library-id' with the package name you wish to retrieve documentation for.",
+                    outcome: "not_found",
+                };
+            }
+            return { data: text, outcome: "success" };
+        }, { abortSignal });
     }
     catch (error) {
         const errorMessage = `Error fetching library context. Please try again later. ${error}`;
         console.error(errorMessage);
-        return { data: errorMessage };
+        return { data: errorMessage, outcome: "error" };
     }
 }

package/dist/lib/mcp-operation-scope.js

@@ -0,0 +1,15 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const operationScope = new AsyncLocalStorage();
+export function runInMcpOperationScope(target, callback) {
+    return operationScope.run(target, callback);
+}
+export function markCurrentMcpOperationError(errorType = "tool_error") {
+    const target = operationScope.getStore();
+    if (target)
+        target.errorType = errorType;
+}
+export function markCurrentMcpToolOutcome(outcome) {
+    const target = operationScope.getStore();
+    if (target)
+        target.toolOutcome = outcome;
+}