@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/internal/runtime.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Runtime capability detection for multi-environment support.
+ * Detects presence of Node features, Web/Workers APIs, and common globals.
+ * @module src/utils/internal/runtime
+ */
+// Best-effort static detection without throwing in restricted envs
+const safeHas = (key) => {
+    try {
+        // @ts-expect-error index access on globalThis
+        return typeof globalThis[key] !== 'undefined';
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Safely checks if process.versions.node exists and is a string.
+ * Uses try-catch to handle environments where property access might be restricted.
+ */
+const hasNodeVersion = () => {
+    try {
+        return (typeof process !== 'undefined' &&
+            typeof process.versions === 'object' &&
+            process.versions !== null &&
+            typeof process.versions.node === 'string');
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Safely checks if globalThis.performance.now is a function.
+ * Uses try-catch to handle environments where property access might be restricted.
+ */
+const hasPerformanceNowFunction = () => {
+    try {
+        const perf = globalThis.performance;
+        return typeof perf === 'object' && perf !== null && typeof perf.now === 'function';
+    }
+    catch {
+        return false;
+    }
+};
+const isNode = hasNodeVersion();
+const isBun = isNode && typeof process?.versions?.bun === 'string';
+const hasProcess = typeof process !== 'undefined';
+const hasBuffer = typeof Buffer !== 'undefined';
+const hasTextEncoder = safeHas('TextEncoder');
+const hasPerformanceNow = hasPerformanceNowFunction();
+/**
+ * Safely checks if WorkerGlobalScope exists.
+ * Cloudflare Workers and other worker environments expose this.
+ */
+const hasWorkerGlobalScope = () => {
+    try {
+        return 'WorkerGlobalScope' in globalThis;
+    }
+    catch {
+        return false;
+    }
+};
+// Cloudflare Workers expose "Web Worker"-like environment (self, caches, fetch, etc.)
+const isWorkerLike = !isNode && hasWorkerGlobalScope();
+const isBrowserLike = !isNode && !isWorkerLike && safeHas('window');
+/**
+ * Singleton snapshot of runtime capabilities for the current environment.
+ * Computed once at module load; safe to read at any time without async.
+ *
+ * @example
+ * ```typescript
+ * import { runtimeCaps } from './runtime.js';
+ *
+ * if (runtimeCaps.hasBuffer) {
+ *   // Node.js / Bun path — use Buffer for encoding
+ * } else {
+ *   // Worker / browser path — use Web APIs
+ * }
+ * ```
+ */
+export const runtimeCaps = {
+    isNode,
+    isBun,
+    isWorkerLike,
+    isBrowserLike,
+    hasProcess,
+    hasBuffer,
+    hasTextEncoder,
+    hasPerformanceNow,
+};
+//# sourceMappingURL=runtime.js.map

package/dist/utils/internal/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/utils/internal/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8BH,mEAAmE;AACnE,MAAM,OAAO,GAAG,CAAC,GAAW,EAAW,EAAE;IACvC,IAAI,CAAC;QACH,8CAA8C;QAC9C,OAAO,OAAO,UAAU,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,cAAc,GAAG,GAAY,EAAE;IACnC,IAAI,CAAC;QACH,OAAO,CACL,OAAO,OAAO,KAAK,WAAW;YAC9B,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;YACpC,OAAO,CAAC,QAAQ,KAAK,IAAI;YACzB,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAC1C,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,yBAAyB,GAAG,GAAY,EAAE;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAI,UAAkD,CAAC,WAAW,CAAC;QAC7E,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,UAAU,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;AAChC,MAAM,KAAK,GAAG,MAAM,IAAI,OAAO,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,QAAQ,CAAC;AACnE,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC;AAChD,MAAM,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAC9C,MAAM,iBAAiB,GAAG,yBAAyB,EAAE,CAAC;AAEtD;;;GAGG;AACH,MAAM,oBAAoB,GAAG,GAAY,EAAE;IACzC,IAAI,CAAC;QACH,OAAO,mBAAmB,IAAI,UAAU,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,sFAAsF;AACtF,MAAM,YAAY,GAAG,CAAC,MAAM,IAAI,oBAAoB,EAAE,CAAC;AACvD,MAAM,aAAa,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAwB;IAC9C,MAAM;IACN,KAAK;IACL,YAAY;IACZ,aAAa;IACb,UAAU;IACV,SAAS;IACT,cAAc;IACd,iBAAiB;CAClB,CAAC"}

package/dist/utils/internal/startupBanner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Utility for displaying startup banners in TTY environments.
+ * Provides a centralized way to show user-facing messages during server initialization
+ * while preventing output pollution in non-interactive environments (CI, pipes, STDIO transport).
+ * @module src/utils/internal/startupBanner
+ */
+/**
+ * Displays a startup banner message to the console only if running in a TTY environment.
+ * This prevents polluting STDIO transport, piped output, or CI/CD logs.
+ *
+ * In STDIO mode, the banner is written to stderr to avoid polluting stdout, which is
+ * reserved for MCP JSON-RPC protocol messages.
+ *
+ * @param message - The banner message to display
+ * @param transportType - The transport type ('stdio' or 'http'). If 'stdio', uses stderr.
+ * @example
+ * ```typescript
+ * logStartupBanner('🚀 MCP Server running at: http://localhost:3010', 'http');
+ * logStartupBanner('🚀 MCP Server running in STDIO mode', 'stdio');
+ * ```
+ */
+export declare function logStartupBanner(message: string, transportType?: 'stdio' | 'http'): void;
+//# sourceMappingURL=startupBanner.d.ts.map

package/dist/utils/internal/startupBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startupBanner.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/startupBanner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUxF"}

package/dist/utils/internal/startupBanner.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Utility for displaying startup banners in TTY environments.
+ * Provides a centralized way to show user-facing messages during server initialization
+ * while preventing output pollution in non-interactive environments (CI, pipes, STDIO transport).
+ * @module src/utils/internal/startupBanner
+ */
+/**
+ * Displays a startup banner message to the console only if running in a TTY environment.
+ * This prevents polluting STDIO transport, piped output, or CI/CD logs.
+ *
+ * In STDIO mode, the banner is written to stderr to avoid polluting stdout, which is
+ * reserved for MCP JSON-RPC protocol messages.
+ *
+ * @param message - The banner message to display
+ * @param transportType - The transport type ('stdio' or 'http'). If 'stdio', uses stderr.
+ * @example
+ * ```typescript
+ * logStartupBanner('🚀 MCP Server running at: http://localhost:3010', 'http');
+ * logStartupBanner('🚀 MCP Server running in STDIO mode', 'stdio');
+ * ```
+ */
+export function logStartupBanner(message, transportType) {
+    // Guard against environments where process.stdout may not exist (e.g. Cloudflare Workers)
+    if (typeof process === 'undefined' || !process.stdout?.isTTY)
+        return;
+    // In STDIO mode, use stderr to avoid polluting stdout (which is reserved for MCP JSON-RPC)
+    if (transportType === 'stdio') {
+        console.error(message);
+    }
+    else {
+        console.log(message);
+    }
+}
+//# sourceMappingURL=startupBanner.js.map

package/dist/utils/internal/startupBanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startupBanner.js","sourceRoot":"","sources":["../../../src/utils/internal/startupBanner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,aAAgC;IAChF,0FAA0F;IAC1F,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK;QAAE,OAAO;IAErE,2FAA2F;IAC3F,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/utils/metrics/tokenCounter.d.ts

@@ -0,0 +1,97 @@
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Minimal chat message shape used for token counting, intentionally provider-agnostic.
+ * Covers the common subset of OpenAI-style chat message fields without depending on
+ * any specific SDK types.
+ */
+export type ChatMessage = {
+    /** The message author role (e.g. `'user'`, `'assistant'`, `'tool'`, `'system'`). */
+    role: string;
+    /**
+     * Message body. Either a plain string, a multi-part content array (e.g. for vision
+     * or tool-result messages), or `null` when the assistant emits tool calls with no
+     * accompanying text.
+     */
+    content: string | Array<{
+        type: string;
+        text?: string;
+        [k: string]: unknown;
+    }> | null;
+    /** Optional display name; when present, adds `tokensPerName` overhead per model heuristics. */
+    name?: string;
+    /**
+     * Tool calls emitted by an `assistant` message. Only `function`-type calls are counted;
+     * the function name and serialized arguments each contribute to the token total.
+     */
+    tool_calls?: Array<{
+        id?: string;
+        type?: string;
+        function?: {
+            name?: string;
+            arguments?: string;
+        };
+    }> | null;
+    /** Tool result correlation ID present on `tool` role messages. Counted as plain text. */
+    tool_call_id?: string | null;
+};
+/**
+ * Heuristic parameters that control how tokens are estimated for a specific model.
+ * Add entries to the internal `HEURISTICS` map to calibrate per-model behavior.
+ */
+export interface ModelHeuristics {
+    /** Average number of characters per token. ~4 for English prose on most GPT-family models. */
+    charsPerToken: number;
+    /**
+     * Fixed token overhead added once per call to {@link countChatTokens} to account for the
+     * assistant reply primer (`<|im_start|>assistant`).
+     */
+    replyPrimer: number;
+    /** Fixed token overhead added per message (e.g. role delimiters). Typically 3 for gpt-4o. */
+    tokensPerMessage: number;
+    /** Extra tokens added when a message includes a `name` field. Typically 1 for gpt-4o. */
+    tokensPerName: number;
+}
+/**
+ * Estimates the number of tokens in a plain-text string using model-specific character-per-token
+ * heuristics. Whitespace is normalized before counting. No external dependencies are required.
+ *
+ * @param text - The input string to estimate. Empty or whitespace-only strings return `0`.
+ * @param context - Optional request context forwarded to the error handler for correlated logging.
+ * @param model - Model identifier used to look up heuristics (e.g. `'gpt-4o'`). Falls back to
+ *   `'gpt-4o'` when omitted or unrecognized.
+ * @returns Estimated token count, rounded up to the nearest integer.
+ * @throws {McpError} With `InternalError` code if the heuristic calculation fails unexpectedly.
+ * @example
+ * const tokens = await countTokens('Hello, world!');
+ * // Returns approximately 4 (13 chars / 4 charsPerToken, rounded up)
+ */
+export declare function countTokens(text: string, context?: RequestContext, model?: string): Promise<number>;
+/**
+ * Estimates the total number of tokens for an array of chat messages using the same
+ * heuristics as OpenAI's token-counting cookbook for gpt-4o-family models.
+ *
+ * Per-message overhead (`tokensPerMessage`) and an assistant reply primer (`replyPrimer`)
+ * are added on top of the raw content estimates. Counting logic:
+ * - String `content`: normalized character count divided by `charsPerToken`.
+ * - Array `content`: only `type: 'text'` parts are counted; other part types emit a warning
+ *   and are skipped.
+ * - `name` field: adds `tokensPerName` plus the name's character-count estimate.
+ * - `tool_calls` (assistant role): function name and serialized arguments are counted.
+ * - `tool_call_id` (tool role): counted as plain text.
+ *
+ * @param messages - Ordered array of chat messages to estimate. May be empty (returns
+ *   `replyPrimer` tokens).
+ * @param context - Optional request context forwarded to the error handler for correlated logging.
+ * @param model - Model identifier used to look up heuristics (e.g. `'gpt-4o-mini'`). Falls back
+ *   to `'gpt-4o'` when omitted or unrecognized.
+ * @returns Estimated total token count across all messages, including per-message overhead and
+ *   the reply primer.
+ * @throws {McpError} With `InternalError` code if the heuristic calculation fails unexpectedly.
+ * @example
+ * const tokens = await countChatTokens([
+ *   { role: 'user', content: 'What is 2 + 2?' },
+ *   { role: 'assistant', content: 'It is 4.' },
+ * ]);
+ */
+export declare function countChatTokens(messages: ReadonlyArray<ChatMessage>, context?: RequestContext, model?: string): Promise<number>;
+//# sourceMappingURL=tokenCounter.d.ts.map

package/dist/utils/metrics/tokenCounter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenCounter.d.ts","sourceRoot":"","sources":["../../../src/utils/metrics/tokenCounter.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACtF,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAClD,CAAC,GAAG,IAAI,CAAC;IACV,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,gBAAgB,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,aAAa,EAAE,MAAM,CAAC;CACvB;AA2CD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,EACxB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,EACpC,OAAO,CAAC,EAAE,cAAc,EACxB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAgEjB"}

package/dist/utils/metrics/tokenCounter.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Lightweight, dependency-free token counters with model-configurable heuristics.
+ * This avoids native/WASM dependencies (e.g., tiktoken) while providing a stable extension point
+ * to adjust per-model tokenization and overhead later.
+ * @module src/utils/metrics/tokenCounter
+ */
+import { JsonRpcErrorCode } from '../../types-global/errors.js';
+import { ErrorHandler } from '../../utils/internal/error-handler/errorHandler.js';
+import { logger } from '../../utils/internal/logger.js';
+const DEFAULT_MODEL = 'gpt-4o';
+// Known heuristics; tweak as you calibrate
+const HEURISTICS = {
+    'gpt-4o': {
+        charsPerToken: 4,
+        tokensPerMessage: 3,
+        tokensPerName: 1,
+        replyPrimer: 3,
+    },
+    'gpt-4o-mini': {
+        charsPerToken: 4,
+        tokensPerMessage: 3,
+        tokensPerName: 1,
+        replyPrimer: 3,
+    },
+    default: {
+        charsPerToken: 4,
+        tokensPerMessage: 3,
+        tokensPerName: 1,
+        replyPrimer: 3,
+    },
+};
+function getModelHeuristics(model) {
+    const key = (model ?? DEFAULT_MODEL).toLowerCase();
+    const found = HEURISTICS[key];
+    return (found ?? HEURISTICS.default);
+}
+function nonEmptyString(s) {
+    return typeof s === 'string' && s.length > 0;
+}
+function approxTokenCount(text, charsPerToken) {
+    if (!text)
+        return 0;
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return 0;
+    return Math.ceil(normalized.length / Math.max(1, charsPerToken));
+}
+/**
+ * Estimates the number of tokens in a plain-text string using model-specific character-per-token
+ * heuristics. Whitespace is normalized before counting. No external dependencies are required.
+ *
+ * @param text - The input string to estimate. Empty or whitespace-only strings return `0`.
+ * @param context - Optional request context forwarded to the error handler for correlated logging.
+ * @param model - Model identifier used to look up heuristics (e.g. `'gpt-4o'`). Falls back to
+ *   `'gpt-4o'` when omitted or unrecognized.
+ * @returns Estimated token count, rounded up to the nearest integer.
+ * @throws {McpError} With `InternalError` code if the heuristic calculation fails unexpectedly.
+ * @example
+ * const tokens = await countTokens('Hello, world!');
+ * // Returns approximately 4 (13 chars / 4 charsPerToken, rounded up)
+ */
+export async function countTokens(text, context, model) {
+    return await ErrorHandler.tryCatch(() => {
+        const h = getModelHeuristics(model);
+        return approxTokenCount(text ?? '', h.charsPerToken);
+    }, {
+        operation: 'countTokens',
+        ...(context && { context }),
+        input: {
+            textSample: nonEmptyString(text)
+                ? text.length > 53
+                    ? `${text.slice(0, 50)}...`
+                    : text
+                : '',
+        },
+        errorCode: JsonRpcErrorCode.InternalError,
+    });
+}
+/**
+ * Estimates the total number of tokens for an array of chat messages using the same
+ * heuristics as OpenAI's token-counting cookbook for gpt-4o-family models.
+ *
+ * Per-message overhead (`tokensPerMessage`) and an assistant reply primer (`replyPrimer`)
+ * are added on top of the raw content estimates. Counting logic:
+ * - String `content`: normalized character count divided by `charsPerToken`.
+ * - Array `content`: only `type: 'text'` parts are counted; other part types emit a warning
+ *   and are skipped.
+ * - `name` field: adds `tokensPerName` plus the name's character-count estimate.
+ * - `tool_calls` (assistant role): function name and serialized arguments are counted.
+ * - `tool_call_id` (tool role): counted as plain text.
+ *
+ * @param messages - Ordered array of chat messages to estimate. May be empty (returns
+ *   `replyPrimer` tokens).
+ * @param context - Optional request context forwarded to the error handler for correlated logging.
+ * @param model - Model identifier used to look up heuristics (e.g. `'gpt-4o-mini'`). Falls back
+ *   to `'gpt-4o'` when omitted or unrecognized.
+ * @returns Estimated total token count across all messages, including per-message overhead and
+ *   the reply primer.
+ * @throws {McpError} With `InternalError` code if the heuristic calculation fails unexpectedly.
+ * @example
+ * const tokens = await countChatTokens([
+ *   { role: 'user', content: 'What is 2 + 2?' },
+ *   { role: 'assistant', content: 'It is 4.' },
+ * ]);
+ */
+export async function countChatTokens(messages, context, model) {
+    return await ErrorHandler.tryCatch(() => {
+        const h = getModelHeuristics(model);
+        let tokens = 0;
+        for (const message of messages) {
+            tokens += h.tokensPerMessage;
+            // role contribution (very small; approximate as 1)
+            tokens += 1;
+            // content
+            if (typeof message.content === 'string') {
+                tokens += approxTokenCount(message.content, h.charsPerToken);
+            }
+            else if (Array.isArray(message.content)) {
+                for (const part of message.content) {
+                    if (part && part.type === 'text' && nonEmptyString(part.text)) {
+                        tokens += approxTokenCount(part.text, h.charsPerToken);
+                    }
+                    else if (part) {
+                        logger.warning(`Non-text content part found (type: ${String(part.type)}), token count contribution ignored.`, context);
+                    }
+                }
+            }
+            // optional name
+            if (message.name) {
+                tokens += h.tokensPerName;
+                tokens += approxTokenCount(message.name, h.charsPerToken);
+            }
+            // assistant tool calls
+            if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
+                for (const toolCall of message.tool_calls) {
+                    if (toolCall?.type === 'function') {
+                        if (toolCall.function?.name) {
+                            tokens += approxTokenCount(toolCall.function.name, h.charsPerToken);
+                        }
+                        if (toolCall.function?.arguments) {
+                            tokens += approxTokenCount(toolCall.function.arguments, h.charsPerToken);
+                        }
+                    }
+                }
+            }
+            // tool message id
+            if (message.role === 'tool' && message.tool_call_id) {
+                tokens += approxTokenCount(message.tool_call_id, h.charsPerToken);
+            }
+        }
+        tokens += h.replyPrimer;
+        return tokens;
+    }, {
+        operation: 'countChatTokens',
+        ...(context && { context }),
+        input: { messageCount: messages.length },
+        errorCode: JsonRpcErrorCode.InternalError,
+    });
+}
+// Intentionally no generic helpers; the return above asserts to satisfy
+// TypeScript with noUncheckedIndexedAccess while remaining safe at runtime.
+//# sourceMappingURL=tokenCounter.js.map

package/dist/utils/metrics/tokenCounter.js.map

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

package/dist/utils/network/fetchWithTimeout.d.ts

@@ -0,0 +1,91 @@
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Options for the `fetchWithTimeout` utility.
+ *
+ * Extends the standard `RequestInit` type, omitting `signal` (which is managed
+ * internally via `AbortController`) and adding SSRF protection and caller-supplied
+ * cancellation options.
+ */
+export interface FetchWithTimeoutOptions extends Omit<RequestInit, 'signal'> {
+    /**
+     * When `true`, rejects requests to private/reserved IP ranges and localhost.
+     *
+     * Use this when fetching user-controlled URLs to prevent SSRF attacks against
+     * internal services (e.g., cloud metadata endpoints, internal APIs). Covered
+     * ranges include RFC 1918, loopback (127.x, ::1), link-local (169.254.x),
+     * CGNAT (100.64–127.x), and known internal hostnames (e.g., `metadata.google.internal`).
+     *
+     * On Node.js, DNS is also resolved and all A/AAAA records are validated against
+     * private ranges before the request is sent. On Workers, only string-based
+     * hostname/IP checks apply (no DNS API available).
+     *
+     * When enabled, redirects are followed manually (up to {@link MAX_SSRF_REDIRECTS}
+     * hops) with SSRF validation applied to each redirect target.
+     *
+     * Default: `false` (no restriction).
+     */
+    rejectPrivateIPs?: boolean;
+    /**
+     * An optional external `AbortSignal` (e.g., `ctx.signal` from the request context)
+     * to combine with the internal timeout signal. If this signal aborts before the
+     * timeout fires, the fetch is cancelled immediately and a `McpError` with code
+     * `InternalError` is thrown.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Fetches a resource with a configurable timeout and optional SSRF protection.
+ *
+ * Internally manages an `AbortController` that fires after `timeoutMs`. An optional
+ * external `signal` (e.g., `ctx.signal`) can be passed via `options` to support
+ * early cancellation by the caller. The two signals are composed — whichever fires
+ * first wins.
+ *
+ * When `options.rejectPrivateIPs` is `true`, the target URL is validated before the
+ * request is sent, and all redirects are followed manually with per-hop SSRF checks
+ * (up to 5 hops). This mode forces `redirect: 'manual'` on the underlying fetch.
+ *
+ * Non-2xx responses are treated as errors: the response body is read, logged, and
+ * wrapped in a `McpError` with code `ServiceUnavailable`.
+ *
+ * @param url - The URL to fetch (string or `URL` instance).
+ * @param timeoutMs - Maximum duration in milliseconds before the request is aborted.
+ * @param context - Request context used for structured logging (requestId, operation, etc.).
+ * @param options - Optional fetch configuration extending `RequestInit`.
+ *   - `rejectPrivateIPs`: Block requests to private/internal IP space (SSRF protection).
+ *   - `signal`: External `AbortSignal` to cancel the request independently of the timeout.
+ *   - All other standard `RequestInit` fields (method, headers, body, etc.) are forwarded.
+ * @returns A promise resolving to the `Response` object on HTTP 2xx.
+ * @throws {McpError} `ValidationError` if the URL targets a private/reserved address
+ *   and `rejectPrivateIPs` is enabled.
+ * @throws {McpError} `Timeout` if the request exceeds `timeoutMs`.
+ * @throws {McpError} `InternalError` if the request is cancelled via the external signal.
+ * @throws {McpError} `ServiceUnavailable` if the server returns a non-2xx status or a
+ *   network-level error occurs.
+ * @example
+ * ```ts
+ * // Basic GET with a 5-second timeout
+ * const response = await fetchWithTimeout(
+ *   'https://api.example.com/data',
+ *   5000,
+ *   ctx,
+ * );
+ * const data = await response.json();
+ *
+ * // POST with SSRF protection and caller-cancellable signal
+ * const response = await fetchWithTimeout(
+ *   userProvidedUrl,
+ *   10_000,
+ *   ctx,
+ *   {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify(payload),
+ *     rejectPrivateIPs: true,
+ *     signal: ctx.signal,
+ *   },
+ * );
+ * ```
+ */
+export declare function fetchWithTimeout(url: string | URL, timeoutMs: number, context: RequestContext, options?: FetchWithTimeoutOptions): Promise<Response>;
+//# sourceMappingURL=fetchWithTimeout.d.ts.map

package/dist/utils/network/fetchWithTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchWithTimeout.d.ts","sourceRoot":"","sources":["../../../src/utils/network/fetchWithTimeout.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IAC1E;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA+ID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,QAAQ,CAAC,CA4JnB"}