@mapbox/mcp-docs-server 0.2.1 → 0.3.0

package/dist/esm/utils/index.js

@@ -2,4 +2,5 @@
 // Licensed under the MIT License.
 export { systemHttpPipeline, httpRequest, UserAgentPolicy } from './httpPipeline.js';
 export { getVersionInfo } from './versionUtils.js';
+export { initializeTracing, shutdownTracing, isTracingInitialized, getTracer, withToolSpan } from './tracing.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,kCAAkC;AAElC,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,kCAAkC;AAElC,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,SAAS,EACT,YAAY,EACb,MAAM,cAAc,CAAC"}

package/dist/esm/utils/tracing.d.ts

@@ -0,0 +1,18 @@
+import { type Span } from '@opentelemetry/api';
+/**
+ * Initialize OpenTelemetry tracing. Call once at application startup.
+ * No-ops in test environments or when OTEL_TRACING_ENABLED=false.
+ */
+export declare function initializeTracing(): Promise<void>;
+/**
+ * Shutdown tracing gracefully. Call on process exit.
+ */
+export declare function shutdownTracing(): Promise<void>;
+export declare function isTracingInitialized(): boolean;
+export declare function getTracer(): import("@opentelemetry/api").Tracer;
+/**
+ * Create a span for tool execution and run the callback within its context.
+ * Automatically marks the span success or error and ends it.
+ */
+export declare function withToolSpan<T>(toolName: string, fn: (span: Span) => Promise<T>): Promise<T>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/esm/utils/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../../src/utils/tracing.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,IAAI,EAGV,MAAM,oBAAoB,CAAC;AA+B5B;;;GAGG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgEvD;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAMrD;AAED,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,wBAAgB,SAAS,wCAExB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CA0BZ"}

package/dist/esm/utils/tracing.js

@@ -0,0 +1,135 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { trace, context, SpanStatusCode, SpanKind, diag, DiagLogLevel } from '@opentelemetry/api';
+import { ATTR_SERVICE_INSTANCE_ID } from '@opentelemetry/semantic-conventions/incubating';
+import { getVersionInfo } from './versionUtils.js';
+// Suppress OpenTelemetry diagnostic logging IMMEDIATELY to avoid polluting stdio.
+// This must happen at module load time, before any OTEL operations.
+// Use OTEL_LOG_LEVEL env var to override if needed for debugging.
+const configureOtelDiagnostics = () => {
+    const logLevel = process.env.OTEL_LOG_LEVEL
+        ? DiagLogLevel[process.env.OTEL_LOG_LEVEL.toUpperCase()]
+        : DiagLogLevel.NONE;
+    diag.setLogger({
+        verbose: () => { },
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { }
+    }, logLevel);
+};
+configureOtelDiagnostics();
+let sdk = null;
+let isTracingEnabled = false;
+/**
+ * Initialize OpenTelemetry tracing. Call once at application startup.
+ * No-ops in test environments or when OTEL_TRACING_ENABLED=false.
+ */
+export async function initializeTracing() {
+    if (sdk || process.env.NODE_ENV === 'test' || process.env.VITEST) {
+        return;
+    }
+    if (process.env.OTEL_TRACING_ENABLED === 'false') {
+        return;
+    }
+    const versionInfo = getVersionInfo();
+    try {
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || versionInfo.name,
+            [ATTR_SERVICE_VERSION]: versionInfo.version,
+            [ATTR_SERVICE_INSTANCE_ID]: process.env.HOSTNAME || 'unknown',
+            'service.git.sha': versionInfo.sha,
+            'service.git.branch': versionInfo.branch,
+            'service.git.tag': versionInfo.tag
+        });
+        const exporters = [];
+        if (process.env.OTEL_EXPORTER_CONSOLE_ENABLED === 'true') {
+            const { ConsoleSpanExporter } = await import('@opentelemetry/sdk-trace-base');
+            exporters.push(new ConsoleSpanExporter());
+        }
+        const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+        if (otlpEndpoint) {
+            exporters.push(new OTLPTraceExporter({
+                url: `${otlpEndpoint}/v1/traces`,
+                headers: process.env.OTEL_EXPORTER_OTLP_HEADERS
+                    ? JSON.parse(process.env.OTEL_EXPORTER_OTLP_HEADERS)
+                    : {}
+            }));
+        }
+        if (exporters.length === 0) {
+            return;
+        }
+        sdk = new NodeSDK({
+            resource,
+            traceExporter: exporters[0],
+            instrumentations: [
+                getNodeAutoInstrumentations({
+                    '@opentelemetry/instrumentation-fs': { enabled: false },
+                    '@opentelemetry/instrumentation-dns': { enabled: false },
+                    '@opentelemetry/instrumentation-http': { enabled: true },
+                    '@opentelemetry/instrumentation-undici': { enabled: true }
+                })
+            ]
+        });
+        sdk.start();
+        isTracingEnabled = true;
+    }
+    catch {
+        // Silently handle initialization errors to avoid breaking MCP stdio
+        isTracingEnabled = false;
+    }
+}
+/**
+ * Shutdown tracing gracefully. Call on process exit.
+ */
+export async function shutdownTracing() {
+    if (sdk) {
+        await sdk.shutdown();
+        sdk = null;
+        isTracingEnabled = false;
+    }
+}
+export function isTracingInitialized() {
+    return isTracingEnabled;
+}
+export function getTracer() {
+    return trace.getTracer('mapbox-mcp-docs-server');
+}
+/**
+ * Create a span for tool execution and run the callback within its context.
+ * Automatically marks the span success or error and ends it.
+ */
+export async function withToolSpan(toolName, fn) {
+    const tracer = getTracer();
+    const span = tracer.startSpan(`tool.${toolName}`, {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+            'tool.name': toolName,
+            'operation.type': 'tool_execution'
+        }
+    });
+    return context.with(trace.setSpan(context.active(), span), async () => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (error instanceof Error) {
+                span.recordException(error);
+            }
+            span.setStatus({ code: SpanStatusCode.ERROR, message });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+//# sourceMappingURL=tracing.js.map

package/dist/esm/utils/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../../src/utils/tracing.ts"],"names":[],"mappings":"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"}

package/dist/esm/version.json

@@ -1,6 +1,6 @@
 {
-  "sha": "8e335ea0e22638f334fabd55d5465b4ef04598de",
-  "tag": "v0.2.0-6-g8e335ea",
+  "sha": "ec5991be3207d8fcedb7fdf95278f941c48a129f",
+  "tag": "v0.2.1-26-gec5991b",
   "branch": "HEAD",
-  "version": "0.2.1"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapbox/mcp-docs-server",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Mapbox MCP documentation server",
   "mcpName": "io.github.mapbox/mcp-docs-server",
   "main": "./dist/commonjs/index.js",
@@ -47,13 +47,21 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/instrumentation": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.5",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
     "@vitest/coverage-istanbul": "^4.0.18",
     "cspell": "^9.7.0",
     "eslint": "^10.0.2",
@@ -65,10 +73,10 @@
     "husky": "^9.0.0",
     "lint-staged": "^16.3.2",
     "prettier": "^3.0.0",
-    "tshy": "^3.0.2",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.56.1",
-    "vitest": "^4.0.18"
+    "tshy": "^4.1.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.1.4"
   },
   "prettier": {
     "singleQuote": true,