mcp-ts-template 1.5.1 → 1.5.3

package/README.md

@@ -3,7 +3,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.12.3-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.5.1-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.5.3-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/mcp-ts-template/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/mcp-ts-template?style=social)](https://github.com/cyanheads/mcp-ts-template)

package/dist/mcp-client/core/clientManager.d.ts

@@ -15,8 +15,7 @@
  */
 import { McpError } from "../../types-global/errors.js";
 import { RequestContext } from "../../utils/index.js";
-import { // Import the new function
-type ConnectedMcpClient as CachedConnectedMcpClient } from "./clientCache.js";
+import { type ConnectedMcpClient as CachedConnectedMcpClient } from "./clientCache.js";
 /**
  * Represents a successfully connected and initialized MCP Client instance.
  * This type alias is re-exported for external use.
@@ -25,16 +24,6 @@ export type ConnectedMcpClient = CachedConnectedMcpClient;
 /**
  * Creates, connects, or returns an existing/pending MCP client instance for a specified server.
  *
- * This function orchestrates the client connection lifecycle:
- * 1.  **Cache Check**: Uses `clientCache.getCachedClient` to check for an active connection.
- * 2.  **Pending Connection Check**: Uses `clientCache.getPendingConnection` to check for an in-flight connection attempt.
- * 3.  **New Connection**: If no cached or pending connection exists:
- *     a.  A new connection promise is initiated by calling `establishNewMcpConnection`.
- *     b.  This promise is stored using `clientCache.setPendingConnection`.
- *     c.  Upon successful connection, the client is cached using `clientCache.setCachedClient`.
- *     d.  The pending promise is removed using `clientCache.removePendingConnection`.
- * 4.  **Error Handling**: The entire process is wrapped in `ErrorHandler.tryCatch` for robust error management.
- *
  * @param serverName - The unique name of the MCP server to connect to.
  * @param parentContext - Optional parent `RequestContext` for logging and tracing.
  * @returns A promise that resolves to the connected and initialized `ConnectedMcpClient` instance.
@@ -43,7 +32,6 @@ export type ConnectedMcpClient = CachedConnectedMcpClient;
 export declare function connectMcpClient(serverName: string, parentContext?: RequestContext | null): Promise<ConnectedMcpClient>;
 /**
  * Disconnects a specific MCP client, closes its transport with a timeout, and removes it from the cache.
- * Idempotent: multiple calls for an already disconnected client will not cause errors.
  *
  * @param serverName - The name of the server whose client connection should be terminated.
  * @param parentContext - Optional parent `RequestContext` for logging.
@@ -53,7 +41,6 @@ export declare function connectMcpClient(serverName: string, parentContext?: Req
 export declare function disconnectMcpClient(serverName: string, parentContext?: RequestContext | null, error?: Error | McpError): Promise<void>;
 /**
  * Disconnects all currently active MCP client connections.
- * Typically used during application shutdown.
  *
  * @param parentContext - Optional parent `RequestContext` for logging.
  * @returns A promise that resolves when all disconnection attempts are processed.

package/dist/mcp-client/core/clientManager.js

@@ -15,23 +15,12 @@
  */
 import { BaseErrorCode } from "../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../utils/index.js";
-import { getCachedClient, getPendingConnection, removeClientFromCache, removePendingConnection, setCachedClient, setPendingConnection, clearAllClientCache, getAllCachedServerNames, // Import the new function
- } from "./clientCache.js";
+import { clearAllClientCache, getAllCachedServerNames, getCachedClient, getPendingConnection, removeClientFromCache, removePendingConnection, setCachedClient, setPendingConnection, } from "./clientCache.js";
 import { establishNewMcpConnection } from "./clientConnectionLogic.js";
 const SHUTDOWN_TIMEOUT_MS = 5000; // 5 seconds for client.close() timeout
 /**
  * Creates, connects, or returns an existing/pending MCP client instance for a specified server.
  *
- * This function orchestrates the client connection lifecycle:
- * 1.  **Cache Check**: Uses `clientCache.getCachedClient` to check for an active connection.
- * 2.  **Pending Connection Check**: Uses `clientCache.getPendingConnection` to check for an in-flight connection attempt.
- * 3.  **New Connection**: If no cached or pending connection exists:
- *     a.  A new connection promise is initiated by calling `establishNewMcpConnection`.
- *     b.  This promise is stored using `clientCache.setPendingConnection`.
- *     c.  Upon successful connection, the client is cached using `clientCache.setCachedClient`.
- *     d.  The pending promise is removed using `clientCache.removePendingConnection`.
- * 4.  **Error Handling**: The entire process is wrapped in `ErrorHandler.tryCatch` for robust error management.
- *
  * @param serverName - The unique name of the MCP server to connect to.
  * @param parentContext - Optional parent `RequestContext` for logging and tracing.
  * @returns A promise that resolves to the connected and initialized `ConnectedMcpClient` instance.
@@ -55,7 +44,6 @@ export async function connectMcpClient(serverName, parentContext) {
     }
     logger.info(`No active or pending connection for ${serverName}. Initiating new connection.`, operationContext);
     const connectionPromise = ErrorHandler.tryCatch(async () => {
-        // Pass the local disconnectMcpClient function to break the circular dependency
         const client = await establishNewMcpConnection(serverName, operationContext, disconnectMcpClient);
         setCachedClient(serverName, client);
         return client;
@@ -71,7 +59,6 @@ export async function connectMcpClient(serverName, parentContext) {
 }
 /**
  * Disconnects a specific MCP client, closes its transport with a timeout, and removes it from the cache.
- * Idempotent: multiple calls for an already disconnected client will not cause errors.
  *
  * @param serverName - The name of the server whose client connection should be terminated.
  * @param parentContext - Optional parent `RequestContext` for logging.
@@ -85,37 +72,32 @@ export async function disconnectMcpClient(serverName, parentContext, error) {
         targetServer: serverName,
         triggerReason: error
             ? `Error: ${error.message}`
-            : "Explicit disconnect call or transport close event",
+            : "Explicit disconnect call",
     });
     const client = getCachedClient(serverName);
     if (!client) {
         if (!error) {
-            logger.warning(`Client for server ${serverName} not found in cache or already disconnected. No action taken.`, context);
+            logger.warning(`Client for ${serverName} not found in cache or already disconnected.`, context);
         }
         removeClientFromCache(serverName, "Not found during disconnect");
         return;
     }
     logger.info(`Disconnecting client for server: ${serverName}...`, context);
-    try {
+    await ErrorHandler.tryCatch(async () => {
         const closePromise = client.close();
         const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout: client.close() for ${serverName} exceeded ${SHUTDOWN_TIMEOUT_MS}ms`)), SHUTDOWN_TIMEOUT_MS));
         await Promise.race([closePromise, timeoutPromise]);
         logger.info(`Client for ${serverName} and its transport closed successfully.`, context);
-    }
-    catch (closeError) {
-        logger.error(`Error during client.close() for server ${serverName} (or timeout)`, {
-            ...context,
-            error: closeError instanceof Error ? closeError.message : String(closeError),
-            stack: closeError instanceof Error ? closeError.stack : undefined,
-        });
-    }
-    finally {
+    }, {
+        operation: `disconnectMcpClient.close (server: ${serverName})`,
+        context,
+        errorCode: BaseErrorCode.SHUTDOWN_ERROR,
+    }).finally(() => {
         removeClientFromCache(serverName, "After close attempt");
-    }
+    });
 }
 /**
  * Disconnects all currently active MCP client connections.
- * Typically used during application shutdown.
  *
  * @param parentContext - Optional parent `RequestContext` for logging.
  * @returns A promise that resolves when all disconnection attempts are processed.
@@ -129,32 +111,13 @@ export async function disconnectAllMcpClients(parentContext) {
     const serverNamesToDisconnect = getAllCachedServerNames();
     if (serverNamesToDisconnect.length === 0) {
         logger.info("No active MCP clients to disconnect.", context);
-        // Still call clearAllClientCache in case pending connections exist or for consistency
         clearAllClientCache();
-        logger.info("Finished processing all client disconnections (no active clients found, cache cleared).", context);
         return;
     }
     logger.debug(`Found ${serverNamesToDisconnect.length} active clients to disconnect: ${serverNamesToDisconnect.join(", ")}`, context);
     const disconnectionPromises = serverNamesToDisconnect.map((serverName) => disconnectMcpClient(serverName, context));
-    const results = await Promise.allSettled(disconnectionPromises);
-    logger.info("All MCP client disconnection attempts completed. Reviewing results...", context);
-    results.forEach((result, index) => {
-        const serverName = serverNamesToDisconnect[index];
-        if (result.status === "rejected") {
-            logger.error(`Failed to cleanly disconnect client for server: ${serverName}`, {
-                ...context,
-                targetServer: serverName,
-                error: result.reason instanceof Error
-                    ? result.reason.message
-                    : String(result.reason),
-                stack: result.reason instanceof Error ? result.reason.stack : undefined,
-            });
-        }
-        else {
-            logger.debug(`Successfully processed disconnection for server: ${serverName}.`, { ...context, targetServer: serverName });
-        }
-    });
-    // Ensure all caches are cleared regardless of individual disconnections.
+    await Promise.allSettled(disconnectionPromises);
+    logger.info("All MCP client disconnection attempts have been processed.", context);
     clearAllClientCache();
-    logger.info("Finished processing all client disconnections and cleared caches.", context);
+    logger.info("All client caches have been cleared.", context);
 }

package/dist/mcp-client/transports/transportFactory.js

@@ -16,66 +16,48 @@ import { createHttpClientTransport } from "./httpClientTransport.js";
  *                    transport type is specified, or if transport creation fails.
  */
 export function getClientTransport(serverName, parentContext) {
-    const baseContext = parentContext ? { ...parentContext } : {};
     const context = requestContextService.createRequestContext({
-        ...baseContext,
+        ...(parentContext ?? {}),
         operation: "getClientTransport",
         targetServer: serverName,
     });
     logger.info(`Getting transport for server: ${serverName}`, context);
     try {
         const serverConfig = getMcpServerConfig(serverName, context);
-        const transportType = serverConfig.transportType;
+        const { transportType, command, args, env } = serverConfig;
         logger.info(`Selected transport type "${transportType}" for server: ${serverName}`, { ...context, transportType });
-        if (transportType === "stdio") {
-            logger.info(`Creating stdio transport for server: ${serverName}`, {
-                ...context,
-                command: serverConfig.command,
-                args: serverConfig.args,
-                envProvided: !!serverConfig.env,
-            });
-            return createStdioClientTransport({
-                command: serverConfig.command,
-                args: serverConfig.args,
-                env: serverConfig.env,
-            }, context);
-        }
-        else if (transportType === "http") {
-            const baseUrl = serverConfig.command; // In HTTP config, 'command' holds the baseUrl
-            // Validate baseUrl for HTTP transport
-            if (!baseUrl ||
-                typeof baseUrl !== "string" ||
-                !baseUrl.startsWith("http")) {
-                const httpConfigError = `Invalid configuration for HTTP transport server "${serverName}": The 'command' field (used as baseUrl for HTTP) must be a valid URL string starting with http(s). Found: "${baseUrl}"`;
-                logger.error(httpConfigError, context);
-                throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, httpConfigError, context);
+        switch (transportType) {
+            case "stdio":
+                logger.info(`Creating stdio transport for server: ${serverName}`, {
+                    ...context,
+                    command,
+                    args,
+                    envProvided: !!env,
+                });
+                return createStdioClientTransport({ command, args, env }, context);
+            case "http": {
+                const baseUrl = command;
+                if (!baseUrl ||
+                    typeof baseUrl !== "string" ||
+                    !baseUrl.startsWith("http")) {
+                    throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Invalid 'command' for HTTP transport (must be a valid URL): "${baseUrl}"`, context);
+                }
+                logger.info(`Creating HTTP transport for server: ${serverName} with base URL: ${baseUrl}`, context);
+                return createHttpClientTransport({ baseUrl }, context);
             }
-            logger.info(`Creating HTTP transport for server: ${serverName} with base URL: ${baseUrl}`, context);
-            return createHttpClientTransport({
-                baseUrl: baseUrl,
-            }, context);
-        }
-        else {
-            const unsupportedErrorMessage = `Unsupported transportType "${serverConfig.transportType}" configured for server "${serverName}".`;
-            logger.error(unsupportedErrorMessage, context);
-            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, unsupportedErrorMessage, context);
+            default:
+                throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Unsupported transportType "${transportType}" for server "${serverName}".`, context);
         }
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
         logger.error(`Failed to get or create transport for server "${serverName}"`, {
             ...context,
-            error: errorMessage,
+            error: error instanceof Error ? error.message : String(error),
             stack: error instanceof Error ? error.stack : undefined,
         });
         if (error instanceof McpError) {
-            throw error; // Re-throw McpError instances directly as they should have context.
-        }
-        else {
-            // For unexpected errors not already McpError, wrap them.
-            // These are likely programming errors or unexpected system issues.
-            throw new McpError(BaseErrorCode.INTERNAL_ERROR, // Use INTERNAL_ERROR for unexpected issues
-            `Unexpected error while getting transport for ${serverName}: ${errorMessage}`, { originalError: error, ...context });
+            throw error;
         }
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Unexpected error while getting transport for ${serverName}: ${error instanceof Error ? error.message : String(error)}`, { originalError: error, ...context });
     }
 }

package/dist/mcp-server/tools/imageTest/logic.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Core logic for the fetch_image_test tool. Fetches a random cat image.
+ * @module src/mcp-server/tools/imageTest/logic
+ */
 import { z } from "zod";
 import { RequestContext } from "../../../utils/index.js";
 export declare const FetchImageTestInputSchema: z.ZodObject<{

package/dist/mcp-server/tools/imageTest/logic.js

@@ -2,10 +2,9 @@
  * @fileoverview Core logic for the fetch_image_test tool. Fetches a random cat image.
  * @module src/mcp-server/tools/imageTest/logic
  */
-import fetch from "node-fetch";
 import { z } from "zod";
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
+import { fetchWithTimeout, logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
 export const FetchImageTestInputSchema = z.object({
     trigger: z
         .boolean()
@@ -21,7 +20,7 @@ export async function fetchImageTestLogic(input, parentRequestContext) {
         input: sanitizeInputForLogging(input),
     });
     logger.info(`Executing 'fetch_image_test'. Trigger: ${input.trigger}`, operationContext);
-    const response = await fetch(CAT_API_URL);
+    const response = await fetchWithTimeout(CAT_API_URL, 5000, operationContext);
     if (!response.ok) {
         throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, `Failed to fetch cat image from ${CAT_API_URL}. Status: ${response.status}`, {
             ...operationContext,

package/dist/services/llm-providers/openRouterProvider.d.ts

@@ -12,17 +12,6 @@ export interface OpenRouterClientOptions {
 }
 /**
  * Defines the parameters for an OpenRouter chat completion request.
- * This type extends standard OpenAI chat completion parameters and includes
- * OpenRouter-specific fields.
- *
- * @property top_k - OpenRouter specific: Sample from the k most likely next tokens.
- * @property min_p - OpenRouter specific: Minimum probability for a token to be considered.
- * @property transforms - OpenRouter specific: Apply transformations to the request or response.
- * @property models - OpenRouter specific: A list of models to use, often for fallback or routing.
- * @property route - OpenRouter specific: Specifies routing strategy, e.g., 'fallback'.
- * @property provider - OpenRouter specific: Provider-specific parameters or routing preferences.
- * @property stream - If true, the response will be a stream of `ChatCompletionChunk` objects.
- *   If false or undefined, a single `ChatCompletion` object is returned.
  */
 export type OpenRouterChatParams = (ChatCompletionCreateParamsNonStreaming | ChatCompletionCreateParamsStreaming) & {
     top_k?: number;
@@ -34,74 +23,18 @@ export type OpenRouterChatParams = (ChatCompletionCreateParamsNonStreaming | Cha
 };
 /**
  * Service class for interacting with the OpenRouter API.
- * Uses the OpenAI SDK for chat completions, configured for OpenRouter.
- * Handles API key management, default headers, model-specific parameter adjustments,
- * and provides methods for chat completions and listing models.
+ * Acts as a "handler" that manages state, configuration, and error handling,
+ * wrapping calls to the internal core logic functions.
  */
 declare class OpenRouterProvider {
-    /**
-     * The OpenAI SDK client instance configured for OpenRouter.
-     * @private
-     */
     private client?;
-    /**
-     * Current status of the OpenRouter service.
-     * - `unconfigured`: API key is missing.
-     * - `initializing`: Constructor is running.
-     * - `ready`: Client initialized successfully and service is usable.
-     * - `error`: An error occurred during initialization.
-     */
     status: "unconfigured" | "initializing" | "ready" | "error";
-    /**
-     * Stores any error that occurred during client initialization.
-     * @private
-     */
     private initializationError;
-    /**
-     * Constructs an `OpenRouterProvider` instance.
-     * Initializes the OpenAI client for OpenRouter if an API key is provided.
-     * Sets default headers required by OpenRouter.
-     * @param options - Optional configuration for the OpenRouter client.
-     * @param parentOpContext - Optional parent operation context for linked logging.
-     */
     constructor(options?: OpenRouterClientOptions, parentOpContext?: OperationContext);
-    /**
-     * Checks if the service is ready to make API calls.
-     * @param operation - The name of the operation attempting to use the service.
-     * @param context - The request context for logging.
-     * @throws {McpError} If the service is not ready.
-     * @private
-     */
     private checkReady;
-    /**
-     * Creates a chat completion using the OpenRouter API.
-     * Can return either a single response or a stream of chunks.
-     * Applies rate limiting and handles model-specific parameter adjustments.
-     *
-     * @param params - Parameters for the chat completion request.
-     * @param context - Request context for logging, error handling, and rate limiting.
-     * @returns A promise resolving with either a `ChatCompletion` or a `Stream<ChatCompletionChunk>`.
-     * @throws {McpError} If service not ready, rate limit exceeded, or API call fails.
-     */
     chatCompletion(params: OpenRouterChatParams, context: RequestContext): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
-    /**
-     * Lists available models from the OpenRouter API.
-     * Makes a direct `fetch` call to the `/models` endpoint.
-     *
-     * @param context - Request context for logging and error handling.
-     * @returns A promise resolving with the JSON response from the OpenRouter API.
-     * @throws {McpError} If the service is not ready, or if the API call fails.
-     */
     listModels(context: RequestContext): Promise<any>;
 }
-/**
- * Singleton instance of the `OpenRouterProvider`.
- * Initialized with the OpenRouter API key from application configuration.
- */
 declare const openRouterProviderInstance: OpenRouterProvider;
 export { openRouterProviderInstance as openRouterProvider };
-/**
- * Exporting the type of the OpenRouterProvider class for use in dependency injection
- * or for type hinting elsewhere in the application.
- */
 export type { OpenRouterProvider };

package/dist/services/llm-providers/openRouterProvider.js

@@ -1,8 +1,8 @@
 /**
  * @fileoverview Provides a service class (`OpenRouterProvider`) for interacting with the
- * OpenRouter API, using the OpenAI SDK for chat completions. It handles API key
- * configuration, default parameters, rate limiting, model-specific parameter adjustments,
- * and error handling.
+ * OpenRouter API. This file implements the "handler" pattern internally, where the
+ * OpenRouterProvider class manages state and error handling, while private logic functions
+ * execute the core API interactions and throw structured errors.
  * @module src/services/llm-providers/openRouterProvider
  */
 import OpenAI from "openai";
@@ -13,316 +13,225 @@ import { logger } from "../../utils/internal/logger.js";
 import { requestContextService, } from "../../utils/internal/requestContext.js";
 import { rateLimiter } from "../../utils/security/rateLimiter.js";
 import { sanitization } from "../../utils/security/sanitization.js";
+// #region Internal Logic Functions (Throwing Errors)
+/**
+ * Prepares parameters for the OpenRouter API call, separating standard
+ * and extra parameters and applying defaults.
+ * @internal
+ */
+function _prepareApiParameters(params, context) {
+    const operation = "openRouterLogic.prepareApiParameters";
+    const effectiveModelId = params.model || config.llmDefaultModel;
+    const standardParams = {
+        model: effectiveModelId,
+        messages: params.messages,
+        ...(params.temperature !== undefined ||
+            config.llmDefaultTemperature !== undefined
+            ? { temperature: params.temperature ?? config.llmDefaultTemperature }
+            : {}),
+        ...(params.top_p !== undefined || config.llmDefaultTopP !== undefined
+            ? { top_p: params.top_p ?? config.llmDefaultTopP }
+            : {}),
+        ...(params.presence_penalty !== undefined
+            ? { presence_penalty: params.presence_penalty }
+            : {}),
+        ...(params.stream !== undefined && { stream: params.stream }),
+        ...(params.tools !== undefined && { tools: params.tools }),
+        ...(params.tool_choice !== undefined && {
+            tool_choice: params.tool_choice,
+        }),
+        ...(params.response_format !== undefined && {
+            response_format: params.response_format,
+        }),
+        ...(params.stop !== undefined && { stop: params.stop }),
+        ...(params.seed !== undefined && { seed: params.seed }),
+        ...(params.frequency_penalty !== undefined
+            ? { frequency_penalty: params.frequency_penalty }
+            : {}),
+        ...(params.logit_bias !== undefined && { logit_bias: params.logit_bias }),
+    };
+    const extraBody = {};
+    const standardKeys = new Set(Object.keys(standardParams));
+    standardKeys.add("messages");
+    for (const key in params) {
+        if (Object.prototype.hasOwnProperty.call(params, key) &&
+            !standardKeys.has(key) &&
+            key !== "max_tokens") {
+            extraBody[key] = params[key];
+        }
+    }
+    if (extraBody.top_k === undefined && config.llmDefaultTopK !== undefined) {
+        extraBody.top_k = config.llmDefaultTopK;
+    }
+    if (extraBody.min_p === undefined && config.llmDefaultMinP !== undefined) {
+        extraBody.min_p = config.llmDefaultMinP;
+    }
+    if (extraBody.provider && typeof extraBody.provider === "object") {
+        if (!extraBody.provider.sort)
+            extraBody.provider.sort = "throughput";
+    }
+    else if (extraBody.provider === undefined) {
+        extraBody.provider = { sort: "throughput" };
+    }
+    const modelsRequiringMaxCompletionTokens = ["openai/o1", "openai/gpt-4.1"];
+    const needsMaxCompletionTokens = modelsRequiringMaxCompletionTokens.some((modelPrefix) => effectiveModelId.startsWith(modelPrefix));
+    const effectiveMaxTokensValue = params.max_tokens ?? config.llmDefaultMaxTokens;
+    if (effectiveMaxTokensValue !== undefined) {
+        if (needsMaxCompletionTokens) {
+            extraBody.max_completion_tokens = effectiveMaxTokensValue;
+            logger.info(`[${operation}] Using 'max_completion_tokens: ${effectiveMaxTokensValue}' for model ${effectiveModelId}.`, context);
+        }
+        else {
+            standardParams.max_tokens = effectiveMaxTokensValue;
+            logger.info(`[${operation}] Using 'max_tokens: ${effectiveMaxTokensValue}' for model ${effectiveModelId}.`, context);
+        }
+    }
+    return { standardParams, extraBody };
+}
+/**
+ * Core logic for making a chat completion request. Throws McpError on failure.
+ * @internal
+ */
+async function _openRouterChatCompletionLogic(client, params, context) {
+    const operation = "openRouterLogic.chatCompletion";
+    const isStreaming = params.stream === true;
+    const { standardParams, extraBody } = _prepareApiParameters(params, context);
+    const apiParams = { ...standardParams };
+    if (Object.keys(extraBody).length > 0) {
+        apiParams.extra_body = extraBody;
+    }
+    try {
+        if (isStreaming) {
+            return await client.chat.completions.create(apiParams);
+        }
+        return await client.chat.completions.create(apiParams);
+    }
+    catch (error) {
+        logger.error(`[${operation}] API call failed`, {
+            ...context,
+            error: error.message,
+            status: error.status,
+        });
+        const errorDetails = {
+            providerStatus: error.status,
+            providerMessage: error.message,
+            cause: error?.cause,
+        };
+        if (error.status === 401) {
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, `OpenRouter authentication failed: ${error.message}`, errorDetails);
+        }
+        else if (error.status === 429) {
+            throw new McpError(BaseErrorCode.RATE_LIMITED, `OpenRouter rate limit exceeded: ${error.message}`, errorDetails);
+        }
+        else if (error.status === 402) {
+            throw new McpError(BaseErrorCode.FORBIDDEN, `OpenRouter insufficient credits or payment required: ${error.message}`, errorDetails);
+        }
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `OpenRouter API error (${error.status || "unknown status"}): ${error.message}`, errorDetails);
+    }
+}
+/**
+ * Core logic for fetching the list of available models. Throws McpError on failure.
+ * @internal
+ */
+async function _listModelsLogic(context) {
+    const operation = "openRouterLogic.listModels";
+    try {
+        const response = await fetch("https://openrouter.ai/api/v1/models", {
+            method: "GET",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new McpError(BaseErrorCode.INTERNAL_ERROR, `OpenRouter list models API request failed with status ${response.status}.`, { providerStatus: response.status, providerMessage: errorBody });
+        }
+        return await response.json();
+    }
+    catch (error) {
+        logger.error(`[${operation}] Error listing models`, {
+            ...context,
+            error: error.message,
+        });
+        if (error instanceof McpError)
+            throw error;
+        throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, `Network or unexpected error listing OpenRouter models: ${error.message}`, { cause: error });
+    }
+}
+// #endregion
 /**
  * Service class for interacting with the OpenRouter API.
- * Uses the OpenAI SDK for chat completions, configured for OpenRouter.
- * Handles API key management, default headers, model-specific parameter adjustments,
- * and provides methods for chat completions and listing models.
+ * Acts as a "handler" that manages state, configuration, and error handling,
+ * wrapping calls to the internal core logic functions.
  */
 class OpenRouterProvider {
-    /**
-     * Constructs an `OpenRouterProvider` instance.
-     * Initializes the OpenAI client for OpenRouter if an API key is provided.
-     * Sets default headers required by OpenRouter.
-     * @param options - Optional configuration for the OpenRouter client.
-     * @param parentOpContext - Optional parent operation context for linked logging.
-     */
     constructor(options, parentOpContext) {
-        /**
-         * Stores any error that occurred during client initialization.
-         * @private
-         */
         this.initializationError = null;
-        const operationName = parentOpContext?.operation
-            ? `${parentOpContext.operation}.OpenRouterProvider.constructor`
-            : "OpenRouterProvider.constructor";
         const opContext = requestContextService.createRequestContext({
-            operation: operationName,
+            operation: "OpenRouterProvider.constructor",
             parentRequestId: parentOpContext?.requestId,
         });
         this.status = "initializing";
         const apiKey = options?.apiKey || config.openrouterApiKey;
-        const baseURL = options?.baseURL || "https://openrouter.ai/api/v1";
-        const siteUrl = options?.siteUrl || config.openrouterAppUrl;
-        const siteName = options?.siteName || config.openrouterAppName;
         if (!apiKey) {
             this.status = "unconfigured";
-            this.initializationError = new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OpenRouter API key is not configured.", { operation: operationName });
-            logger.error(`[${operationName}] OpenRouter API key not provided in options or global config. Service is unconfigured.`, { ...opContext, service: "OpenRouterProvider" });
+            this.initializationError = new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OpenRouter API key is not configured.");
+            logger.error(this.initializationError.message, opContext);
             return;
         }
         try {
             this.client = new OpenAI({
-                baseURL,
+                baseURL: options?.baseURL || "https://openrouter.ai/api/v1",
                 apiKey,
                 defaultHeaders: {
-                    "HTTP-Referer": siteUrl,
-                    "X-Title": siteName,
+                    "HTTP-Referer": options?.siteUrl || config.openrouterAppUrl,
+                    "X-Title": options?.siteName || config.openrouterAppName,
                 },
             });
             this.status = "ready";
-            logger.info("OpenRouter Service Initialized and Ready", {
-                ...opContext,
-                service: "OpenRouterProvider",
-            });
+            logger.info("OpenRouter Service Initialized and Ready", opContext);
         }
         catch (error) {
             this.status = "error";
-            this.initializationError =
-                error instanceof Error
-                    ? error
-                    : new McpError(BaseErrorCode.INITIALIZATION_FAILED, String(error));
+            this.initializationError = error;
             logger.error("Failed to initialize OpenRouter client", {
                 ...opContext,
-                service: "OpenRouterProvider",
-                error: this.initializationError.message,
+                error: error.message,
             });
         }
     }
-    /**
-     * Checks if the service is ready to make API calls.
-     * @param operation - The name of the operation attempting to use the service.
-     * @param context - The request context for logging.
-     * @throws {McpError} If the service is not ready.
-     * @private
-     */
     checkReady(operation, context) {
-        if (this.status !== "ready") {
-            let errorCode = BaseErrorCode.SERVICE_UNAVAILABLE;
-            let message = `OpenRouter service is not available (status: ${this.status}).`;
-            if (this.status === "unconfigured") {
-                errorCode = BaseErrorCode.CONFIGURATION_ERROR;
-                message = "OpenRouter service is not configured (missing API key).";
-            }
-            else if (this.status === "error") {
-                errorCode = BaseErrorCode.INITIALIZATION_FAILED;
-                message = `OpenRouter service failed to initialize: ${this.initializationError?.message || "Unknown error"}`;
-            }
-            logger.error(`[${operation}] Attempted to use OpenRouter service when not ready.`, { ...context, status: this.status });
-            throw new McpError(errorCode, message, {
-                operation,
-                status: this.status,
+        if (this.status !== "ready" || !this.client) {
+            const message = `OpenRouter service is not available (status: ${this.status}).`;
+            logger.error(`[${operation}] ${message}`, { ...context, status: this.status });
+            throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, message, {
                 cause: this.initializationError,
             });
         }
-        if (!this.client) {
-            // This should ideally not happen if status is 'ready', but as a safeguard:
-            logger.error(`[${operation}] Service status is ready, but client is missing.`, { ...context });
-            throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Internal inconsistency: OpenRouter client is missing despite ready status.", { operation });
-        }
     }
-    /**
-     * Creates a chat completion using the OpenRouter API.
-     * Can return either a single response or a stream of chunks.
-     * Applies rate limiting and handles model-specific parameter adjustments.
-     *
-     * @param params - Parameters for the chat completion request.
-     * @param context - Request context for logging, error handling, and rate limiting.
-     * @returns A promise resolving with either a `ChatCompletion` or a `Stream<ChatCompletionChunk>`.
-     * @throws {McpError} If service not ready, rate limit exceeded, or API call fails.
-     */
     async chatCompletion(params, context) {
         const operation = "OpenRouterProvider.chatCompletion";
-        this.checkReady(operation, context);
-        const isStreaming = params.stream === true;
-        const effectiveModelId = params.model || config.llmDefaultModel;
-        const standardParams = {
-            model: effectiveModelId,
-            messages: params.messages,
-            ...(params.temperature !== undefined ||
-                config.llmDefaultTemperature !== undefined
-                ? { temperature: params.temperature ?? config.llmDefaultTemperature }
-                : {}),
-            ...(params.top_p !== undefined || config.llmDefaultTopP !== undefined
-                ? { top_p: params.top_p ?? config.llmDefaultTopP }
-                : {}),
-            ...(params.presence_penalty !== undefined
-                ? { presence_penalty: params.presence_penalty }
-                : {}),
-            ...(params.stream !== undefined && { stream: params.stream }),
-            ...(params.tools !== undefined && { tools: params.tools }),
-            ...(params.tool_choice !== undefined && {
-                tool_choice: params.tool_choice,
-            }),
-            ...(params.response_format !== undefined && {
-                response_format: params.response_format,
-            }),
-            ...(params.stop !== undefined && { stop: params.stop }),
-            ...(params.seed !== undefined && { seed: params.seed }),
-            ...(params.frequency_penalty !== undefined
-                ? { frequency_penalty: params.frequency_penalty }
-                : {}),
-            ...(params.logit_bias !== undefined && { logit_bias: params.logit_bias }),
-        };
-        const extraBody = {};
-        const standardKeys = new Set(Object.keys(standardParams));
-        standardKeys.add("messages");
-        for (const key in params) {
-            if (Object.prototype.hasOwnProperty.call(params, key) &&
-                !standardKeys.has(key) &&
-                key !== "max_tokens") {
-                extraBody[key] = params[key];
-            }
-        }
-        if (extraBody.top_k === undefined && config.llmDefaultTopK !== undefined) {
-            extraBody.top_k = config.llmDefaultTopK;
-        }
-        if (extraBody.min_p === undefined && config.llmDefaultMinP !== undefined) {
-            extraBody.min_p = config.llmDefaultMinP;
-        }
-        if (extraBody.provider && typeof extraBody.provider === "object") {
-            if (!extraBody.provider.sort)
-                extraBody.provider.sort = "throughput";
-        }
-        else if (extraBody.provider === undefined) {
-            extraBody.provider = { sort: "throughput" };
-        }
-        const modelsRequiringMaxCompletionTokens = ["openai/o1", "openai/gpt-4.1"];
-        const needsMaxCompletionTokens = modelsRequiringMaxCompletionTokens.some((modelPrefix) => effectiveModelId.startsWith(modelPrefix));
-        const effectiveMaxTokensValue = params.max_tokens ?? config.llmDefaultMaxTokens;
-        if (effectiveMaxTokensValue !== undefined) {
-            if (needsMaxCompletionTokens) {
-                extraBody.max_completion_tokens = effectiveMaxTokensValue;
-                logger.info(`[${operation}] Using 'max_completion_tokens: ${effectiveMaxTokensValue}' for model ${effectiveModelId} (sent via extra_body).`, context);
-            }
-            else {
-                standardParams.max_tokens = effectiveMaxTokensValue;
-                logger.info(`[${operation}] Using 'max_tokens: ${effectiveMaxTokensValue}' for model ${effectiveModelId}.`, context);
-            }
-        }
-        const allEffectiveParams = { ...standardParams, ...extraBody };
-        const sanitizedParams = sanitization.sanitizeForLogging(allEffectiveParams);
-        logger.info(`[${operation}] Request received`, {
-            ...context,
-            params: sanitizedParams,
-            streaming: isStreaming,
-        });
-        const rateLimitKey = context.requestId || "openrouter_default_key";
-        try {
+        const sanitizedParams = sanitization.sanitizeForLogging(params);
+        return await ErrorHandler.tryCatch(async () => {
+            this.checkReady(operation, context);
+            const rateLimitKey = context.requestId || "openrouter_default_key";
             rateLimiter.check(rateLimitKey, context);
-            logger.debug(`[${operation}] Rate limit check passed`, {
-                ...context,
-                key: rateLimitKey,
-            });
-        }
-        catch (error) {
-            logger.warning(`[${operation}] Rate limit exceeded`, {
+            const result = await _openRouterChatCompletionLogic(this.client, params, context);
+            logger.info(`[${operation}] Request successful`, {
                 ...context,
-                key: rateLimitKey,
-                error: error instanceof Error ? error.message : String(error),
+                model: params.model,
+                streaming: params.stream,
             });
-            throw error;
-        }
-        return await ErrorHandler.tryCatch(async () => {
-            if (!this.client)
-                throw new Error("Client missing despite ready status");
-            const apiParams = { ...standardParams };
-            if (Object.keys(extraBody).length > 0) {
-                apiParams.extra_body = extraBody;
-            }
-            try {
-                if (isStreaming) {
-                    const stream = await this.client.chat.completions.create(apiParams);
-                    logger.info(`[${operation}] Streaming request successful`, {
-                        ...context,
-                        model: apiParams.model,
-                    });
-                    return stream;
-                }
-                else {
-                    const completion = await this.client.chat.completions.create(apiParams);
-                    logger.info(`[${operation}] Non-streaming request successful`, {
-                        ...context,
-                        model: apiParams.model,
-                    });
-                    return completion;
-                }
-            }
-            catch (error) {
-                logger.error(`[${operation}] API call failed`, {
-                    ...context,
-                    error: error.message,
-                    status: error.status,
-                });
-                const errorDetails = {
-                    providerStatus: error.status,
-                    providerMessage: error.message,
-                    cause: error?.cause,
-                };
-                if (error.status === 401) {
-                    throw new McpError(BaseErrorCode.UNAUTHORIZED, `OpenRouter authentication failed: ${error.message}`, errorDetails);
-                }
-                else if (error.status === 429) {
-                    throw new McpError(BaseErrorCode.RATE_LIMITED, `OpenRouter rate limit exceeded: ${error.message}`, errorDetails);
-                }
-                else if (error.status === 402) {
-                    throw new McpError(BaseErrorCode.FORBIDDEN, `OpenRouter insufficient credits or payment required: ${error.message}`, errorDetails);
-                }
-                throw new McpError(BaseErrorCode.INTERNAL_ERROR, `OpenRouter API error (${error.status || "unknown status"}): ${error.message}`, errorDetails);
-            }
-        }, {
-            operation,
-            context,
-            input: sanitizedParams,
-            errorCode: BaseErrorCode.INTERNAL_ERROR,
-        });
+            return result;
+        }, { operation, context, input: sanitizedParams });
     }
-    /**
-     * Lists available models from the OpenRouter API.
-     * Makes a direct `fetch` call to the `/models` endpoint.
-     *
-     * @param context - Request context for logging and error handling.
-     * @returns A promise resolving with the JSON response from the OpenRouter API.
-     * @throws {McpError} If the service is not ready, or if the API call fails.
-     */
     async listModels(context) {
         const operation = "OpenRouterProvider.listModels";
-        this.checkReady(operation, context);
-        logger.info(`[${operation}] Request received`, context);
         return await ErrorHandler.tryCatch(async () => {
-            try {
-                const response = await fetch("https://openrouter.ai/api/v1/models", {
-                    method: "GET",
-                    headers: {
-                        "Content-Type": "application/json",
-                    },
-                });
-                if (!response.ok) {
-                    const errorBody = await response.text();
-                    const errorDetails = {
-                        providerStatus: response.status,
-                        providerMessage: errorBody,
-                    };
-                    logger.error(`[${operation}] Failed to list models`, {
-                        ...context,
-                        ...errorDetails,
-                    });
-                    throw new McpError(BaseErrorCode.INTERNAL_ERROR, `OpenRouter list models API request failed with status ${response.status}.`, errorDetails);
-                }
-                const models = await response.json();
-                logger.info(`[${operation}] Successfully listed models`, context);
-                return models;
-            }
-            catch (error) {
-                logger.error(`[${operation}] Error listing models`, {
-                    ...context,
-                    error: error.message,
-                });
-                if (error instanceof McpError) {
-                    throw error;
-                }
-                throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, `Network or unexpected error listing OpenRouter models: ${error.message}`, { cause: error });
-            }
-        }, {
-            operation,
-            context,
-            errorCode: BaseErrorCode.INTERNAL_ERROR,
-        });
+            this.checkReady(operation, context);
+            const models = await _listModelsLogic(context);
+            logger.info(`[${operation}] Successfully listed models`, context);
+            return models;
+        }, { operation, context });
     }
 }
-/**
- * Singleton instance of the `OpenRouterProvider`.
- * Initialized with the OpenRouter API key from application configuration.
- */
-const openRouterProviderInstance = new OpenRouterProvider(undefined);
+const openRouterProviderInstance = new OpenRouterProvider();
 export { openRouterProviderInstance as openRouterProvider };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.5.1",
-  "description": "TypeScript template for building Model Context Protocol (MCP) Servers & Clients. Features extensive utilities (logger, requestContext, etc.), STDIO & Streamable HTTP (with authMiddleware), examples, and type safety. Ideal starting point for creating production-ready MCP Servers & Clients.",
+  "version": "1.5.3",
+  "description": "Production-ready TypeScript template for building robust Model Context Protocol (MCP) Servers & Clients. Features extensive utilities, service integrations (OpenRouter, DuckDB), advanced authentication (OAuth 2.1, JWT), and both STDIO & Hono-based HTTP transports.",
   "main": "dist/index.js",
   "files": [
     "dist"
@@ -35,14 +35,14 @@
     "db:duckdb-example": "MCP_LOG_LEVEL=debug tsc && node dist/storage/duckdbExample.js"
   },
   "dependencies": {
-    "@duckdb/node-api": "^1.3.0-alpha.21",
+    "@duckdb/node-api": "^1.3.1-alpha.22",
     "@hono/node-server": "^1.14.4",
     "@modelcontextprotocol/sdk": "^1.12.3",
     "@supabase/supabase-js": "^2.50.0",
-    "@types/jsonwebtoken": "^9.0.9",
-    "@types/node": "^24.0.1",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.0.3",
     "@types/sanitize-html": "^2.16.0",
-    "@types/validator": "13.15.1",
+    "@types/validator": "13.15.2",
     "chrono-node": "^2.8.0",
     "dotenv": "^16.5.0",
     "hono": "^4.7.11",
@@ -50,7 +50,7 @@
     "jose": "^6.0.11",
     "jsonwebtoken": "^9.0.2",
     "node-fetch": "^3.3.2",
-    "openai": "^5.3.0",
+    "openai": "^5.5.0",
     "partial-json": "^0.1.7",
     "sanitize-html": "^2.17.0",
     "tiktoken": "^1.0.21",
@@ -59,21 +59,28 @@
     "validator": "13.15.15",
     "winston": "^3.17.0",
     "winston-transport": "^4.9.0",
-    "zod": "^3.25.64"
+    "zod": "^3.25.67"
   },
   "keywords": [
     "typescript",
     "template",
-    "MCP",
+    "mcp",
     "model-context-protocol",
-    "LLM",
-    "AI-integration",
+    "architecture",
+    "error-handling",
+    "llm",
+    "ai-integration",
     "mcp-server",
     "mcp-client",
-    "mcp-template",
+    "hono",
     "stdio",
-    "streamable-http",
-    "authentication"
+    "http",
+    "authentication",
+    "oauth",
+    "jwt",
+    "openrouter",
+    "duckdb",
+    "zod"
   ],
   "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/mcp-ts-template#readme)",
   "license": "Apache-2.0",