@mapbox/mcp-docs-server 0.2.1 → 0.3.1

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

@@ -1 +1 @@
-{"version":3,"file":"docFetcher.js","sourceRoot":"","sources":["../../../src/utils/docFetcher.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,kCAAkC;AAElC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGnE,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAExC;;;GAGG;AACH,SAAS,eAAe;IACtB,OAAO,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,aAAa,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QACnD,MAAM,CAAC,QAAQ,GAAG,eAAe,EAAE,CAAC;QACpC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC;QAC7D,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IACvD,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;YACtC,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC7B,CAAC;QACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAW,EACX,WAAwB;IAExB,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAEjC,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,iBAAiB,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE;QAC3C,OAAO,EAAE,EAAE,MAAM,EAAE,4CAA4C,EAAE;KAClE,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,iBAAiB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AACtD,CAAC"}
+{"version":3,"file":"docFetcher.js","sourceRoot":"","sources":["../../../src/utils/docFetcher.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,25 @@
+import type { HttpRequest } from './types.js';
+export interface DocEntry {
+    title: string;
+    url: string;
+    description: string;
+    product: string;
+}
+/**
+ * Parse a product-level llms.txt file into searchable entries.
+ * Each `- [Title](URL): description` line becomes one entry.
+ * Lines that don't match (headers, blanks, root index links) are skipped.
+ */
+export declare function parseLlmsTxtEntries(content: string, product: string): DocEntry[];
+/**
+ * Search across all indexed llms.txt files.
+ *
+ * All source files are fetched in parallel and cached via docCache.
+ * First call may take ~500ms while files are fetched; subsequent calls
+ * are instant since all content is in-memory.
+ *
+ * Failed sources are skipped gracefully so a single unavailable file
+ * doesn't break the entire search.
+ */
+export declare function searchDocs(query: string, limit: number, httpRequest: HttpRequest): Promise<DocEntry[]>;
+//# sourceMappingURL=docsSearchIndex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docsSearchIndex.d.ts","sourceRoot":"","sources":["../../../src/utils/docsSearchIndex.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AA8DD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,QAAQ,EAAE,CAYZ;AAoBD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAoCrB"}

package/dist/esm/utils/docsSearchIndex.js

@@ -0,0 +1,142 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+import { fetchCachedText } from './docFetcher.js';
+/**
+ * Curated set of product llms.txt files to include in the search index.
+ * Each file is fetched once and cached for the duration of the TTL.
+ * Files are fetched in parallel on first search then served from cache.
+ */
+const INDEX_SOURCES = [
+    {
+        url: 'https://docs.mapbox.com/api/llms.txt',
+        product: 'API Reference'
+    },
+    {
+        url: 'https://docs.mapbox.com/mapbox-gl-js/llms.txt',
+        product: 'Mapbox GL JS'
+    },
+    {
+        url: 'https://docs.mapbox.com/help/llms.txt',
+        product: 'Help Center'
+    },
+    {
+        url: 'https://docs.mapbox.com/style-spec/llms.txt',
+        product: 'Style Specification'
+    },
+    {
+        url: 'https://docs.mapbox.com/studio-manual/llms.txt',
+        product: 'Studio Manual'
+    },
+    {
+        url: 'https://docs.mapbox.com/mapbox-search-js/llms.txt',
+        product: 'Mapbox Search JS'
+    },
+    {
+        url: 'https://docs.mapbox.com/ios/maps/llms.txt',
+        product: 'Maps SDK for iOS'
+    },
+    {
+        url: 'https://docs.mapbox.com/android/maps/llms.txt',
+        product: 'Maps SDK for Android'
+    },
+    {
+        url: 'https://docs.mapbox.com/ios/navigation/llms.txt',
+        product: 'Navigation SDK for iOS'
+    },
+    {
+        url: 'https://docs.mapbox.com/android/navigation/llms.txt',
+        product: 'Navigation SDK for Android'
+    },
+    {
+        url: 'https://docs.mapbox.com/mapbox-tiling-service/llms.txt',
+        product: 'Mapbox Tiling Service'
+    },
+    {
+        url: 'https://docs.mapbox.com/data/tilesets/llms.txt',
+        product: 'Tilesets'
+    }
+];
+// Matches: - [Title](URL): optional description
+// or:      - [Title](URL)
+const ENTRY_RE = /^-\s+\[([^\]]+)\]\(([^)]+)\)(?::\s*(.+))?$/;
+/**
+ * Parse a product-level llms.txt file into searchable entries.
+ * Each `- [Title](URL): description` line becomes one entry.
+ * Lines that don't match (headers, blanks, root index links) are skipped.
+ */
+export function parseLlmsTxtEntries(content, product) {
+    const entries = [];
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        const match = ENTRY_RE.exec(line);
+        if (!match)
+            continue;
+        const [, title, url, description = ''] = match;
+        // Skip links to other llms.txt files (those are index links, not doc pages)
+        if (url.endsWith('/llms.txt') || url.endsWith('/llms-full.txt'))
+            continue;
+        entries.push({ title, url, description, product });
+    }
+    return entries;
+}
+/**
+ * Score an entry against the query words.
+ * Title matches are weighted 3x, description and URL path matches 1x each.
+ */
+function scoreEntry(entry, queryWords) {
+    const titleLower = entry.title.toLowerCase();
+    const descLower = entry.description.toLowerCase();
+    const urlLower = entry.url.toLowerCase();
+    let score = 0;
+    for (const word of queryWords) {
+        if (titleLower.includes(word))
+            score += 3;
+        if (descLower.includes(word))
+            score += 1;
+        if (urlLower.includes(word))
+            score += 1;
+    }
+    return score;
+}
+/**
+ * Search across all indexed llms.txt files.
+ *
+ * All source files are fetched in parallel and cached via docCache.
+ * First call may take ~500ms while files are fetched; subsequent calls
+ * are instant since all content is in-memory.
+ *
+ * Failed sources are skipped gracefully so a single unavailable file
+ * doesn't break the entire search.
+ */
+export async function searchDocs(query, limit, httpRequest) {
+    const allEntries = (await Promise.all(INDEX_SOURCES.map(async ({ url, product }) => {
+        try {
+            const content = await fetchCachedText(url, httpRequest);
+            return parseLlmsTxtEntries(content, product);
+        }
+        catch {
+            return [];
+        }
+    }))).flat();
+    const queryWords = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 1); // skip single-char words
+    const scored = allEntries
+        .map((entry) => ({ entry, score: scoreEntry(entry, queryWords) }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score);
+    // Deduplicate by URL (same page can appear across multiple sources)
+    const seen = new Set();
+    const results = [];
+    for (const { entry } of scored) {
+        if (!seen.has(entry.url)) {
+            seen.add(entry.url);
+            results.push(entry);
+            if (results.length >= limit)
+                break;
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=docsSearchIndex.js.map

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

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

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

@@ -1,4 +1,5 @@
 export { systemHttpPipeline, httpRequest, UserAgentPolicy } from './httpPipeline.js';
 export { getVersionInfo } from './versionUtils.js';
 export type { VersionInfo } from './versionUtils.js';
+export { initializeTracing, shutdownTracing, isTracingInitialized, getTracer, withToolSpan } from './tracing.js';
 //# sourceMappingURL=index.d.ts.map

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

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

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": "20c45c2a9f24ce2bb1df9dee894d9182dfc71f42",
+  "tag": "v0.3.0-8-g20c45c2",
   "branch": "HEAD",
-  "version": "0.2.1"
+  "version": "0.3.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapbox/mcp-docs-server",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Mapbox MCP documentation server",
   "mcpName": "io.github.mapbox/mcp-docs-server",
   "main": "./dist/commonjs/index.js",
@@ -19,7 +19,6 @@
     "inspect:dev": "npx @modelcontextprotocol/inspector npx -y tsx src/index.ts",
     "lint": "eslint \"./src/**/*.{ts,tsx}\" \"./test/**/*.{ts,tsx}\" --no-error-on-unmatched-pattern",
     "lint:fix": "eslint \"./src/**/*.{ts,tsx}\" \"./test/**/*.{ts,tsx}\" --no-error-on-unmatched-pattern --fix",
-    "prepare": "node -e \"if(!process.env.CI&&process.env.HUSKY!=='0'){require('child_process').execSync('husky && node .husky/setup-hooks.js',{stdio:'inherit'})}\"",
     "spellcheck": "cspell \"*.md\" \"src/**/*.ts\" \"test/**/*.ts\"",
     "sync-manifest": "node scripts/sync-manifest-version.cjs",
     "test": "vitest"
@@ -47,13 +46,21 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.74.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.216.0",
+    "@opentelemetry/instrumentation": "^0.216.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-node": "^0.216.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.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 +72,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,