@upstash/context7-mcp 4.0.6 → 4.1.0

package/dist/lib/telemetry-contracts.js

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

package/dist/lib/telemetry-provider.js

@@ -0,0 +1,72 @@
+import { metrics } from "@opentelemetry/api";
+import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
+import { RuntimeNodeInstrumentation } from "@opentelemetry/instrumentation-runtime-node";
+import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { embeddedPrometheusIsEnabled } from "./telemetry-config.js";
+const DEFAULT_PROMETHEUS_HOST = "127.0.0.1";
+const DEFAULT_PROMETHEUS_PORT = 9464;
+let embeddedRuntimeInstrumentation;
+function prometheusPort(environment) {
+    const configuredPort = environment.OTEL_EXPORTER_PROMETHEUS_PORT;
+    if (!configuredPort)
+        return DEFAULT_PROMETHEUS_PORT;
+    const port = Number(configuredPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error(`Invalid OTEL_EXPORTER_PROMETHEUS_PORT: '${configuredPort}'`);
+    }
+    return port;
+}
+/**
+ * Installs the embedded Prometheus MetricReader for HTTP serving. A provider
+ * installed by an OpenTelemetry preload script wins, so no second SDK is
+ * installed. This module is dynamically imported only when the embedded
+ * exporter is enabled; stdio and SDK-disabled processes never load it.
+ */
+export async function startPrometheusMetrics(serviceVersion, environment = process.env) {
+    if (!embeddedPrometheusIsEnabled(environment))
+        return undefined;
+    let provider;
+    let providerWasRegistered = false;
+    try {
+        const host = environment.OTEL_EXPORTER_PROMETHEUS_HOST || DEFAULT_PROMETHEUS_HOST;
+        const port = prometheusPort(environment);
+        const exporter = new PrometheusExporter({ host, port, preventServerStart: true });
+        provider = new MeterProvider({
+            resource: defaultResource().merge(resourceFromAttributes({
+                "service.name": "context7-mcp",
+                "service.version": serviceVersion,
+            })),
+            readers: [exporter],
+        });
+        providerWasRegistered = metrics.setGlobalMeterProvider(provider);
+        if (!providerWasRegistered) {
+            await provider.shutdown();
+            console.error("Embedded Prometheus exporter not started because a global OpenTelemetry MeterProvider is already registered");
+            return undefined;
+        }
+        await exporter.startServer();
+        try {
+            // Keep the native 10 ms precision. The same setting controls the
+            // monitorEventLoopDelay resolution, so increasing it to the scrape
+            // interval would make healthy delay percentiles appear artificially high.
+            embeddedRuntimeInstrumentation = new RuntimeNodeInstrumentation();
+            embeddedRuntimeInstrumentation.setMeterProvider(provider);
+            embeddedRuntimeInstrumentation.enable();
+        }
+        catch (error) {
+            embeddedRuntimeInstrumentation?.disable();
+            embeddedRuntimeInstrumentation = undefined;
+            console.error("OpenTelemetry Node runtime metrics failed to start:", error);
+        }
+        console.error(`OpenTelemetry metrics available at http://${host}:${port}/metrics`);
+        return provider;
+    }
+    catch (error) {
+        if (providerWasRegistered)
+            metrics.disable();
+        await provider?.shutdown().catch(() => undefined);
+        console.error("Embedded Prometheus exporter failed to start; MCP serving will continue:", error);
+        return undefined;
+    }
+}

package/dist/lib/telemetry-runtime.js

@@ -0,0 +1,67 @@
+import { embeddedPrometheusIsEnabled, telemetryIsDisabled } from "./telemetry-config.js";
+const TELEMETRY_DISABLED = telemetryIsDisabled();
+let implementation;
+let implementationPromise;
+let mcpImplementationPromise;
+let prometheusStartup;
+function loadImplementation() {
+    implementationPromise ??= import("./telemetry.js")
+        .then((loaded) => {
+        implementation = loaded;
+        return loaded;
+    })
+        .catch((error) => {
+        implementationPromise = undefined;
+        throw error;
+    });
+    return implementationPromise;
+}
+function loadMcpImplementation() {
+    mcpImplementationPromise ??= import("./mcp-telemetry.js").catch((error) => {
+        mcpImplementationPromise = undefined;
+        throw error;
+    });
+    return mcpImplementationPromise;
+}
+async function startEmbeddedPrometheus(serviceVersion) {
+    prometheusStartup ??= import("./telemetry-provider.js")
+        .then(({ startPrometheusMetrics }) => startPrometheusMetrics(serviceVersion))
+        .catch((error) => {
+        prometheusStartup = undefined;
+        throw error;
+    });
+    await prometheusStartup;
+}
+export async function initializeTelemetry(options) {
+    if (TELEMETRY_DISABLED)
+        return undefined;
+    const [loadedTelemetry, loadedMcpTelemetry] = await Promise.all([
+        loadImplementation(),
+        loadMcpImplementation(),
+    ]);
+    implementation = loadedTelemetry;
+    if (options.allowEmbeddedPrometheus && embeddedPrometheusIsEnabled()) {
+        await startEmbeddedPrometheus(options.serviceVersion);
+    }
+    return {
+        createServer: (serverInfo, serverOptions, requestContext) => new loadedMcpTelemetry.InstrumentedMcpServer(serverInfo, serverOptions, requestContext),
+        instrumentHttpHandler: loadedMcpTelemetry.instrumentMcpHttpHandler,
+        instrumentStdioTransport: loadedMcpTelemetry.instrumentStdioTransport,
+    };
+}
+export async function observeAuthentication(operation) {
+    if (TELEMETRY_DISABLED)
+        return (await operation()).value;
+    return (await loadImplementation()).observeAuthentication(operation);
+}
+export async function observeUpstreamRequest(operationName, request, consumeResponse, options = {}) {
+    if (TELEMETRY_DISABLED)
+        return consumeResponse(await request());
+    return (await loadImplementation()).observeUpstreamRequest(operationName, request, consumeResponse, options);
+}
+export function recordToolCallOutcome(outcome) {
+    implementation?.recordToolCallOutcome(outcome);
+}
+export async function forceFlushTelemetry() {
+    await implementation?.forceFlushTelemetry();
+}

package/dist/lib/telemetry.js

@@ -0,0 +1,189 @@
+import { metrics, trace } from "@opentelemetry/api";
+import { markCurrentMcpOperationError, markCurrentMcpToolOutcome } from "./mcp-operation-scope.js";
+const METER_NAME = "io.github.upstash.context7.mcp";
+const DURATION_BUCKETS_SECONDS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
+const TIMEOUT_ERROR_CODES = new Set([
+    "ETIMEDOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+]);
+const NETWORK_ERROR_CODES = new Set([
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EPIPE",
+]);
+function createInstruments() {
+    const meter = metrics.getMeter(METER_NAME);
+    return {
+        upstreamRequests: meter.createCounter("context7.mcp.upstream.requests", {
+            description: "Number of requests made to Context7 dependencies",
+            unit: "{request}",
+        }),
+        upstreamRequestDuration: meter.createHistogram("context7.mcp.upstream.request.duration", {
+            description: "Duration of requests made to Context7 dependencies",
+            unit: "s",
+            advice: { explicitBucketBoundaries: DURATION_BUCKETS_SECONDS },
+        }),
+        activeUpstreamRequests: meter.createUpDownCounter("context7.mcp.upstream.requests.active", {
+            description: "Number of requests to Context7 dependencies currently in flight",
+            unit: "{request}",
+        }),
+        authenticationAttempts: meter.createCounter("context7.mcp.authentication.attempts", {
+            description: "Number of authentication attempts on the OAuth-protected MCP endpoint",
+            unit: "{attempt}",
+        }),
+        authenticationDuration: meter.createHistogram("context7.mcp.authentication.duration", {
+            description: "Duration of authentication on the OAuth-protected MCP endpoint",
+            unit: "s",
+            advice: { explicitBucketBoundaries: DURATION_BUCKETS_SECONDS },
+        }),
+        activeAuthentications: meter.createUpDownCounter("context7.mcp.authentication.active", {
+            description: "Number of OAuth-protected MCP requests currently authenticating",
+            unit: "{request}",
+        }),
+    };
+}
+let instruments;
+function getInstruments() {
+    instruments ??= createInstruments();
+    return instruments;
+}
+function elapsedSeconds(startedAt) {
+    return (performance.now() - startedAt) / 1_000;
+}
+function statusClass(statusCode) {
+    if (statusCode >= 100 && statusCode <= 599) {
+        return `${Math.floor(statusCode / 100)}xx`;
+    }
+    return "unknown";
+}
+export function classifyUpstreamError(error, abortSignal, fallback = "network_error") {
+    let timeout = false;
+    let cancelled = false;
+    let networkError = false;
+    const rootCount = abortSignal?.aborted ? 2 : 1;
+    for (let rootIndex = 0; rootIndex < rootCount; rootIndex += 1) {
+        let value = rootIndex === 0 ? error : abortSignal?.reason;
+        for (let depth = 0; value && typeof value === "object" && depth < 8; depth += 1) {
+            const current = value;
+            const name = current.name;
+            const code = current.code;
+            if (name === "TimeoutError" || (typeof code === "string" && TIMEOUT_ERROR_CODES.has(code))) {
+                timeout = true;
+            }
+            else if (name === "AbortError" || code === "ABORT_ERR") {
+                cancelled = true;
+            }
+            else if (typeof code === "string" &&
+                (code.startsWith("UND_ERR_") || NETWORK_ERROR_CODES.has(code))) {
+                networkError = true;
+            }
+            value = current.cause;
+        }
+    }
+    if (timeout)
+        return "timeout";
+    if (cancelled || abortSignal?.aborted)
+        return "cancelled";
+    if (networkError)
+        return "network_error";
+    return fallback;
+}
+export function recordToolCallOutcome(outcome) {
+    if (outcome === "error")
+        markCurrentMcpOperationError();
+    markCurrentMcpToolOutcome(outcome);
+}
+export async function observeUpstreamRequest(operationName, request, consumeResponse, options = {}) {
+    const { activeUpstreamRequests, upstreamRequestDuration, upstreamRequests } = getInstruments();
+    const activeAttributes = { "context7.upstream.operation": operationName };
+    const startedAt = performance.now();
+    let outcome = "network_error";
+    let responseStatus;
+    let responseStatusClass = "none";
+    activeUpstreamRequests.add(1, activeAttributes);
+    try {
+        let response;
+        try {
+            response = await request();
+        }
+        catch (error) {
+            outcome = classifyUpstreamError(error, options.abortSignal);
+            throw error;
+        }
+        responseStatus = response.status;
+        responseStatusClass = statusClass(response.status);
+        outcome = response.ok ? "success" : "http_error";
+        try {
+            return await consumeResponse(response);
+        }
+        catch (error) {
+            outcome = classifyUpstreamError(error, options.abortSignal, "response_error");
+            throw error;
+        }
+    }
+    finally {
+        const attributes = {
+            ...activeAttributes,
+            "http.response.status_code_class": responseStatusClass,
+            "context7.upstream.outcome": outcome,
+        };
+        if (responseStatus !== undefined) {
+            attributes["http.response.status_code"] = responseStatus;
+        }
+        activeUpstreamRequests.add(-1, activeAttributes);
+        upstreamRequests.add(1, attributes);
+        upstreamRequestDuration.record(elapsedSeconds(startedAt), attributes);
+    }
+}
+function flushableProvider(provider) {
+    let current = provider;
+    for (let depth = 0; current && typeof current === "object" && depth < 4; depth += 1) {
+        if ("forceFlush" in current && typeof current.forceFlush === "function") {
+            return current;
+        }
+        if (!("getDelegate" in current) || typeof current.getDelegate !== "function")
+            return undefined;
+        const delegate = current.getDelegate();
+        if (delegate === current)
+            return undefined;
+        current = delegate;
+    }
+    return undefined;
+}
+export async function forceFlushTelemetry() {
+    const providers = [
+        flushableProvider(metrics.getMeterProvider()),
+        flushableProvider(trace.getTracerProvider()),
+    ].filter((provider) => provider !== undefined);
+    const results = await Promise.allSettled(providers.map((provider) => provider.forceFlush.call(provider)));
+    const failures = results
+        .filter((result) => result.status === "rejected")
+        .map((result) => result.reason);
+    if (failures.length > 0) {
+        throw new AggregateError(failures, "OpenTelemetry providers failed to flush during shutdown");
+    }
+}
+export async function observeAuthentication(operation) {
+    const { activeAuthentications, authenticationAttempts, authenticationDuration } = getInstruments();
+    const activeAttributes = { "context7.mcp.route": "oauth" };
+    const startedAt = performance.now();
+    let outcome = "error";
+    activeAuthentications.add(1, activeAttributes);
+    try {
+        const observed = await operation();
+        outcome = observed.outcome;
+        return observed.value;
+    }
+    finally {
+        const attributes = { "context7.authentication.outcome": outcome };
+        activeAuthentications.add(-1, activeAttributes);
+        authenticationAttempts.add(1, attributes);
+        authenticationDuration.record(elapsedSeconds(startedAt), attributes);
+    }
+}

package/dist/lib/tool-names.js

@@ -0,0 +1,3 @@
+export const QUERY_DOCS_TOOL = "query-docs";
+export const RESOLVE_LIBRARY_ID_TOOL = "resolve-library-id";
+export const MCP_TOOL_NAMES = [QUERY_DOCS_TOOL, RESOLVE_LIBRARY_ID_TOOL];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/context7-mcp",
-  "version": "4.0.6",
+  "version": "4.1.0",
   "mcpName": "io.github.upstash/context7",
   "description": "MCP server for Context7",
   "repository": {
@@ -35,6 +35,11 @@
   "dependencies": {
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-prometheus": "^0.221.0",
+    "@opentelemetry/instrumentation-runtime-node": "^0.34.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-metrics": "^2.10.0",
     "@types/express": "^5.0.4",
     "commander": "^13.1.0",
     "express": "^5.1.0",
@@ -44,6 +49,9 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.0.0",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/core": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@types/node": "^25.0.3",
     "esbuild": "^0.28.2",
     "typescript": "^5.8.2",