mcp-ts-template 1.1.7 → 1.1.9

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.11.0-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.1.7-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.9-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)
@@ -90,17 +90,26 @@ Get the example server running in minutes:
 
 Configure the MCP server's behavior using these environment variables:
 
-| Variable              | Description                                                                                         | Default                                |
-| :-------------------- | :-------------------------------------------------------------------------------------------------- | :------------------------------------- |
-| `MCP_TRANSPORT_TYPE`  | Server transport: `stdio` or `http`.                                                                | `stdio`                                |
-| `MCP_HTTP_PORT`       | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                            | `3010`                                 |
-| `MCP_HTTP_HOST`       | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                    | `127.0.0.1`                            |
-| `MCP_ALLOWED_ORIGINS` | Comma-separated allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).                            | (none)                                 |
-| `MCP_SERVER_NAME`     | Optional server name (used in MCP initialization).                                                  | (from package.json)                    |
-| `MCP_SERVER_VERSION`  | Optional server version (used in MCP initialization).                                               | (from package.json)                    |
-| `MCP_LOG_LEVEL`       | Server logging level (`debug`, `info`, `warning`, `error`, etc.).                                   | `info`                                 |
-| `NODE_ENV`            | Runtime environment (`development`, `production`).                                                  | `development`                          |
-| `MCP_AUTH_SECRET_KEY` | **Required for HTTP transport.** Secret key (min 32 chars) for signing/verifying auth tokens (JWT). | (none - **MUST be set in production**) |
+| Variable                  | Description                                                                                         | Default                                    |
+| :------------------------ | :-------------------------------------------------------------------------------------------------- | :----------------------------------------- |
+| `MCP_TRANSPORT_TYPE`      | Server transport: `stdio` or `http`.                                                                | `stdio`                                    |
+| `MCP_HTTP_PORT`           | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                            | `3010`                                     |
+| `MCP_HTTP_HOST`           | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                    | `127.0.0.1`                                |
+| `MCP_ALLOWED_ORIGINS`     | Comma-separated allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).                            | (none)                                     |
+| `MCP_SERVER_NAME`         | Optional server name (used in MCP initialization).                                                  | (from package.json)                        |
+| `MCP_SERVER_VERSION`      | Optional server version (used in MCP initialization).                                               | (from package.json)                        |
+| `MCP_LOG_LEVEL`           | Server logging level (`debug`, `info`, `warning`, `error`, etc.).                                   | `info`                                     |
+| `NODE_ENV`                | Runtime environment (`development`, `production`).                                                  | `development`                              |
+| `MCP_AUTH_SECRET_KEY`     | **Required for HTTP transport.** Secret key (min 32 chars) for signing/verifying auth tokens (JWT). | (none - **MUST be set in production**)     |
+| `OPENROUTER_APP_URL`      | URL of the application (used by OpenRouter service for HTTP Referer).                               | `https://caseyjhand.com`                   |
+| `OPENROUTER_APP_NAME`     | Name of the application (used by OpenRouter service for X-Title header).                            | 'mcp-ts-template'                          |
+| `OPENROUTER_API_KEY`      | API key for OpenRouter.ai service. Optional, but service will be unconfigured without it.           | (none)                                     |
+| `LLM_DEFAULT_MODEL`       | Default model to use for LLM calls via OpenRouter.                                                  | `google/gemini-2.5-flash-preview:thinking` |
+| `LLM_DEFAULT_TEMPERATURE` | Default temperature for LLM calls (0-2). Optional.                                                  | (none)                                     |
+| `LLM_DEFAULT_TOP_P`       | Default top_p for LLM calls (0-1). Optional.                                                        | (none)                                     |
+| `LLM_DEFAULT_MAX_TOKENS`  | Default max_tokens for LLM calls. Optional.                                                         | (none)                                     |
+| `LLM_DEFAULT_TOP_K`       | Default top_k for LLM calls (non-negative integer). Optional.                                       | (none)                                     |
+| `LLM_DEFAULT_MIN_P`       | Default min_p for LLM calls (0-1). Optional.                                                        | (none)                                     |
 
 **Note on HTTP Port Retries:** If the `MCP_HTTP_PORT` is busy, the server automatically tries the next port (up to 15 times).
 
@@ -211,6 +220,7 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
 | **Utilities (Security)** | IdGenerator                     | Generates unique IDs (prefixed or UUIDs).                                                                    | `src/utils/security/idGenerator.ts`              |
 |                          | RateLimiter                     | Request throttling based on keys.                                                                            | `src/utils/security/rateLimiter.ts`              |
 |                          | Sanitization                    | Input validation/cleaning (HTML, paths, URLs, numbers, JSON) & log redaction (`validator`, `sanitize-html`). | `src/utils/security/sanitization.ts`             |
+| **Services**             | OpenRouter Provider             | Service for interacting with OpenRouter API via OpenAI SDK compatibility.                                    | `src/services/openRouterProvider.ts`             |
 | **Type Safety**          | Global Types                    | Shared TypeScript definitions for consistent interfaces (Errors, MCP types).                                 | `src/types-global/`                              |
 |                          | Zod Schemas                     | Used for robust validation of configuration files and tool/resource inputs.                                  | Throughout (`config`, `mcp-client`, tools, etc.) |
 | **Error Handling**       | Pattern-Based Classification    | Automatically categorize errors based on message patterns.                                                   | `src/utils/internal/errorHandler.ts`             |

package/dist/config/index.d.ts

@@ -58,6 +58,15 @@ export declare const config: {
      * Default: undefined (Auth middleware should throw error if not set in production)
      */
     mcpAuthSecretKey: string | undefined;
+    openrouterAppUrl: string;
+    openrouterAppName: string;
+    openrouterApiKey: string | undefined;
+    llmDefaultModel: string;
+    llmDefaultTemperature: number | undefined;
+    llmDefaultTopP: number | undefined;
+    llmDefaultMaxTokens: number | undefined;
+    llmDefaultTopK: number | undefined;
+    llmDefaultMinP: number | undefined;
 };
 /**
  * The configured logging level for the application.

package/dist/config/index.js

@@ -32,6 +32,16 @@ const EnvSchema = z.object({
     MCP_HTTP_HOST: z.string().default('127.0.0.1'),
     MCP_ALLOWED_ORIGINS: z.string().optional(), // Comma-separated string
     MCP_AUTH_SECRET_KEY: z.string().min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long for security").optional(), // Secret for signing/verifying tokens
+    // OpenRouter and LLM specific configurations
+    OPENROUTER_APP_URL: z.string().url("OPENROUTER_APP_URL must be a valid URL").optional(),
+    OPENROUTER_APP_NAME: z.string().optional(),
+    OPENROUTER_API_KEY: z.string().optional(),
+    LLM_DEFAULT_MODEL: z.string().default('google/gemini-2.5-flash-preview:thinking'),
+    LLM_DEFAULT_TEMPERATURE: z.coerce.number().min(0).max(2).optional(),
+    LLM_DEFAULT_TOP_P: z.coerce.number().min(0).max(1).optional(),
+    LLM_DEFAULT_MAX_TOKENS: z.coerce.number().int().positive().optional(),
+    LLM_DEFAULT_TOP_K: z.coerce.number().int().nonnegative().optional(), // top_k can be 0
+    LLM_DEFAULT_MIN_P: z.coerce.number().min(0).max(1).optional(),
 });
 // Parse and validate environment variables
 const parsedEnv = EnvSchema.safeParse(process.env);
@@ -105,6 +115,16 @@ export const config = {
      * Default: undefined (Auth middleware should throw error if not set in production)
      */
     mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
+    // OpenRouter and LLM specific properties
+    openrouterAppUrl: env.OPENROUTER_APP_URL || 'http://localhost:3000', // Default if not set
+    openrouterAppName: env.OPENROUTER_APP_NAME || pkg.name || 'MCP TS App', // Default if not set
+    openrouterApiKey: env.OPENROUTER_API_KEY, // No default, service handles if missing
+    llmDefaultModel: env.LLM_DEFAULT_MODEL,
+    llmDefaultTemperature: env.LLM_DEFAULT_TEMPERATURE,
+    llmDefaultTopP: env.LLM_DEFAULT_TOP_P,
+    llmDefaultMaxTokens: env.LLM_DEFAULT_MAX_TOKENS,
+    llmDefaultTopK: env.LLM_DEFAULT_TOP_K,
+    llmDefaultMinP: env.LLM_DEFAULT_MIN_P,
     // Note: mcpClient configuration is loaded separately via src/mcp-client/configLoader.ts
     // Note: Logger-specific configurations (LOG_FILE_PATH, LOG_MAX_FILES, etc.)
     //       are typically handled directly within the logger utility (src/utils/internal/logger.ts)

package/dist/services/openRouterProvider.d.ts

@@ -0,0 +1,43 @@
+import { ChatCompletion, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from 'openai/resources/chat/completions';
+import { Stream } from 'openai/streaming';
+import { OperationContext, RequestContext } from '../utils/internal/requestContext.js';
+type OpenRouterChatParams = (ChatCompletionCreateParamsNonStreaming | ChatCompletionCreateParamsStreaming) & {
+    top_k?: number;
+    min_p?: number;
+    transforms?: string[];
+    models?: string[];
+    route?: 'fallback';
+    provider?: Record<string, any>;
+};
+/**
+ * Service class for interacting with the OpenRouter API using the OpenAI SDK compatibility.
+ */
+declare class OpenRouterProvider {
+    private client?;
+    readonly status: 'unconfigured' | 'initializing' | 'ready' | 'error';
+    private initializationError;
+    constructor(apiKey: string | undefined, context?: OperationContext);
+    private checkReady;
+    /**
+     * Creates a chat completion using the OpenRouter API. Can return a stream or a single response.
+     * @param params - The parameters for the chat completion request, potentially including OpenRouter-specific fields and stream option.
+     * @param context - The request context for logging and error handling.
+     * @returns A promise that resolves with the chat completion response or an async iterable stream.
+     * @throws {McpError} If the service is not ready, the API call fails, or returns an error.
+     */
+    chatCompletion(params: OpenRouterChatParams, // Use the defined type here
+    context: RequestContext): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+    /**
+     * Lists available models from OpenRouter.
+     * Note: The standard OpenAI SDK doesn't have a direct equivalent for listing models
+     * from a custom base URL like OpenRouter's `/models` endpoint.
+     * This method uses fetch directly.
+     * @param context - The request context for logging.
+     * @returns A promise that resolves with the list of models.
+     * @throws {McpError} If the service is not ready or the API call fails.
+     */
+    listModels(context: RequestContext): Promise<any>;
+}
+declare const openRouterProviderInstance: OpenRouterProvider;
+export { openRouterProviderInstance as openRouterProvider };
+export type { OpenRouterProvider };

package/dist/services/openRouterProvider.js

@@ -0,0 +1,269 @@
+import OpenAI from 'openai';
+import { config } from '../config/index.js';
+import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { ErrorHandler } from '../utils/internal/errorHandler.js';
+import { logger } from '../utils/internal/logger.js';
+import { sanitization } from '../utils/security/sanitization.js';
+import { rateLimiter } from '../utils/security/rateLimiter.js';
+// Use the updated config properties
+const YOUR_SITE_URL = config.openrouterAppUrl;
+const YOUR_SITE_NAME = config.openrouterAppName;
+/**
+ * Service class for interacting with the OpenRouter API using the OpenAI SDK compatibility.
+ */
+class OpenRouterProvider {
+    constructor(apiKey, context) {
+        this.initializationError = null;
+        const opContext = context || { operation: 'OpenRouterProvider.constructor' };
+        this.status = 'initializing'; // Start in initializing state
+        if (!apiKey) {
+            this.status = 'unconfigured';
+            logger.warning('OPENROUTER_API_KEY is not set. OpenRouter service is not configured.', { ...opContext, service: 'OpenRouterProvider' });
+            return; // Stop initialization
+        }
+        try {
+            this.client = new OpenAI({
+                baseURL: 'https://openrouter.ai/api/v1',
+                apiKey: apiKey,
+                defaultHeaders: {
+                    'HTTP-Referer': YOUR_SITE_URL, // Use config value
+                    'X-Title': YOUR_SITE_NAME, // Use config value
+                },
+            });
+            this.status = 'ready';
+            logger.info('OpenRouter Service Initialized and Ready', { ...opContext, service: 'OpenRouterProvider' });
+        }
+        catch (error) {
+            this.status = 'error';
+            this.initializationError = error instanceof Error ? error : new Error(String(error));
+            logger.error('Failed to initialize OpenRouter client', { ...opContext, service: 'OpenRouterProvider', error: this.initializationError.message });
+            // Don't throw here, let status indicate failure
+        }
+    }
+    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, cause: this.initializationError });
+        }
+        if (!this.client) {
+            // This should theoretically not happen if status is 'ready', but belts and suspenders
+            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 a stream or a single response.
+     * @param params - The parameters for the chat completion request, potentially including OpenRouter-specific fields and stream option.
+     * @param context - The request context for logging and error handling.
+     * @returns A promise that resolves with the chat completion response or an async iterable stream.
+     * @throws {McpError} If the service is not ready, the API call fails, or returns an error.
+     */
+    async chatCompletion(params, // Use the defined type here
+    context) {
+        const operation = 'OpenRouterProvider.chatCompletion';
+        this.checkReady(operation, context); // Check if service is ready
+        // Determine if streaming is requested
+        const isStreaming = params.stream === true;
+        // Explicitly pick known standard OpenAI params and apply defaults
+        // Use the appropriate type based on streaming
+        const standardParams = {
+            model: params.model || config.llmDefaultModel,
+            messages: params.messages,
+            // Only include standard params if they exist in the input or have a default from config
+            ...(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 } : {}),
+            // Only include penalties if explicitly provided in params, ignore config defaults for these
+            ...(params.presence_penalty !== undefined ? { presence_penalty: params.presence_penalty } : {}),
+            ...(params.max_tokens !== undefined || config.llmDefaultMaxTokens !== undefined ? { max_tokens: params.max_tokens ?? config.llmDefaultMaxTokens } : {}),
+            ...(params.stream !== undefined && { stream: params.stream }), // Keep stream param if provided
+            ...(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 }),
+            // Only include penalties if explicitly provided in params, ignore config defaults for these
+            ...(params.frequency_penalty !== undefined ? { frequency_penalty: params.frequency_penalty } : {}),
+            ...(params.logit_bias !== undefined && { logit_bias: params.logit_bias }),
+            // Add other standard OpenAI params here if needed, checking params object first
+        };
+        // Collect remaining/non-standard params for extra_body
+        const extraBody = {};
+        const standardKeys = new Set(Object.keys(standardParams)); // Use Set for faster lookups
+        standardKeys.add('messages'); // Ensure messages isn't added to extraBody
+        for (const key in params) {
+            // Ensure the key is actually a property of params before checking standardKeys
+            if (Object.prototype.hasOwnProperty.call(params, key) && !standardKeys.has(key)) {
+                extraBody[key] = params[key];
+            }
+        }
+        // Apply defaults for known non-standard params if they weren't provided in input `params`
+        // Check if the key exists in extraBody before applying default from config
+        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;
+        }
+        // Note: If params explicitly included top_k: null or min_p: null, the loop above would have added them.
+        // This logic correctly applies defaults only if the key is entirely absent.
+        // Combine for logging
+        const allEffectiveParams = { ...standardParams, ...extraBody };
+        const sanitizedParams = sanitization.sanitizeForLogging(allEffectiveParams);
+        logger.info(`[${operation}] Request received`, { ...context, params: sanitizedParams, streaming: isStreaming });
+        // --- BEGIN SPEED PRIORITIZATION ---
+        // Ensure provider routing prioritizes throughput for faster responses.
+        // If a provider preference is already set, merge 'sort' if not present.
+        // If no provider preference exists, create it.
+        if (extraBody.provider && typeof extraBody.provider === 'object') {
+            if (!extraBody.provider.sort) {
+                extraBody.provider.sort = 'throughput';
+                logger.debug(`[${operation}] Merged 'sort: throughput' into existing provider preferences.`, context);
+            }
+            else {
+                logger.debug(`[${operation}] Provider 'sort' preference already exists, respecting provided value: ${extraBody.provider.sort}`, context);
+            }
+        }
+        else if (extraBody.provider === undefined) {
+            // Only add if 'provider' is completely undefined, not if it's null or another type
+            extraBody.provider = { sort: 'throughput' };
+            logger.debug(`[${operation}] Added 'provider: { sort: 'throughput' }' preferences.`, context);
+        }
+        // --- END SPEED PRIORITIZATION ---
+        // Apply rate limiting before making the API call
+        const rateLimitKey = context.requestId || 'openrouter_default_key';
+        try {
+            rateLimiter.check(rateLimitKey, context);
+            logger.debug(`[${operation}] Rate limit check passed`, { ...context, key: rateLimitKey });
+        }
+        catch (error) {
+            // If rate limit check fails, log and re-throw the McpError (RATE_LIMITED)
+            logger.warning(`[${operation}] Rate limit exceeded`, { ...context, key: rateLimitKey, error: error instanceof Error ? error.message : String(error) });
+            throw error; // Re-throw the McpError from rateLimiter.check()
+        }
+        // Use tryCatch for error handling, but return type depends on streaming
+        return await ErrorHandler.tryCatch(async () => {
+            // Ensure client is defined (checkReady should guarantee this, but TS needs reassurance)
+            if (!this.client)
+                throw new Error("Client missing despite ready status");
+            // Prepare the final parameters for the API call
+            // Cast to the correct type based on streaming flag
+            const apiParams = { ...standardParams };
+            if (Object.keys(extraBody).length > 0) {
+                // Pass non-standard params via extra_body
+                apiParams.extra_body = extraBody;
+            }
+            try {
+                if (isStreaming) {
+                    // Call with streaming true
+                    const stream = await this.client.chat.completions.create(apiParams // Cast to streaming type
+                    );
+                    logger.info(`[${operation}] Streaming request successful`, { ...context, model: apiParams.model });
+                    return stream;
+                }
+                else {
+                    // Call with streaming false (or default)
+                    const completion = await this.client.chat.completions.create(apiParams // Cast to non-streaming type
+                    );
+                    logger.info(`[${operation}] Non-streaming request successful`, { ...context, model: apiParams.model });
+                    // Consider sanitizing completion if logging full response
+                    // logger.debug(`[${operation}] Response data`, { ...context, response: completion });
+                    return completion;
+                }
+            }
+            catch (error) {
+                // Catch specific OpenAI/API errors if possible, otherwise treat as generic error
+                logger.error(`[${operation}] API call failed`, { ...context, error: error.message, status: error.status });
+                // Map API errors to McpError types using correct codes and constructor signature (code, message, details?)
+                const errorDetails = { providerStatus: error.status, providerMessage: error.message, cause: error?.cause };
+                if (error.status === 401) {
+                    throw new McpError(BaseErrorCode.UNAUTHORIZED, `OpenRouter authentication failed`, errorDetails);
+                }
+                else if (error.status === 429) {
+                    throw new McpError(BaseErrorCode.RATE_LIMITED, `OpenRouter rate limit exceeded`, errorDetails);
+                }
+                else if (error.status === 402) {
+                    // Using FORBIDDEN as the closest match for payment required
+                    throw new McpError(BaseErrorCode.FORBIDDEN, `OpenRouter insufficient credits or payment required`, errorDetails);
+                }
+                // Throw a generic internal error for other API statuses
+                throw new McpError(BaseErrorCode.INTERNAL_ERROR, `OpenRouter API error (${error.status})`, errorDetails);
+            }
+        }, {
+            operation,
+            context,
+            input: sanitizedParams, // Log sanitized input
+            errorCode: BaseErrorCode.INTERNAL_ERROR, // Default error code if unexpected error occurs
+        });
+    }
+    // Removed getNextAction and its private helper methods:
+    // - buildSystemPrompt
+    // - formatToolsForPrompt
+    // - formatConversationHistory
+    // - parseAndValidateAction
+    /**
+     * Lists available models from OpenRouter.
+     * Note: The standard OpenAI SDK doesn't have a direct equivalent for listing models
+     * from a custom base URL like OpenRouter's `/models` endpoint.
+     * This method uses fetch directly.
+     * @param context - The request context for logging.
+     * @returns A promise that resolves with the list of models.
+     * @throws {McpError} If the service is not ready or the API call fails.
+     */
+    async listModels(context) {
+        const operation = 'OpenRouterProvider.listModels';
+        this.checkReady(operation, context); // Check if service is ready
+        logger.info(`[${operation}] Request received`, context);
+        return await ErrorHandler.tryCatch(async () => {
+            // No need to check this.client here, checkReady handles it
+            try {
+                const response = await fetch('https://openrouter.ai/api/v1/models', {
+                    method: 'GET',
+                    headers: {
+                        // No API key needed for listing models as per OpenRouter docs
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    const errorDetails = { status: response.status, body: errorBody };
+                    logger.error(`[${operation}] Failed to list models`, { ...context, ...errorDetails });
+                    // Context is not passed to McpError constructor directly.
+                    throw new McpError(BaseErrorCode.INTERNAL_ERROR, `OpenRouter list models failed (${response.status})`, errorDetails);
+                }
+                const models = await response.json();
+                logger.info(`[${operation}] Successfully listed models`, context);
+                // logger.debug(`[${operation}] Models data`, { ...context, count: models?.data?.length });
+                return models;
+            }
+            catch (error) {
+                logger.error(`[${operation}] Error listing models`, { ...context, error: error.message });
+                if (error instanceof McpError) {
+                    throw error; // Re-throw McpErrors directly
+                }
+                // Use SERVICE_UNAVAILABLE for network/fetch errors
+                // Context is not passed to McpError constructor directly.
+                throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, `Network error listing OpenRouter models: ${error.message}`, { cause: error });
+            }
+        }, {
+            operation,
+            context,
+            errorCode: BaseErrorCode.INTERNAL_ERROR, // Default error code if unexpected error occurs
+        });
+    }
+}
+// Initialize and export the service instance.
+// It reads the API key from the config/environment variables.
+// The instance will always exist, but its status indicates if it's usable.
+const openRouterProviderInstance = new OpenRouterProvider(config.openrouterApiKey);
+// Export the guaranteed instance. Consumers should check its status or handle errors from its methods.
+export { openRouterProviderInstance as openRouterProvider };

package/dist/types-global/errors.d.ts

@@ -27,7 +27,9 @@ export declare enum BaseErrorCode {
     /** An error occurred, but the specific cause is unknown or cannot be categorized. */
     UNKNOWN_ERROR = "UNKNOWN_ERROR",
     /** An error occurred during the loading or validation of configuration data. */
-    CONFIGURATION_ERROR = "CONFIGURATION_ERROR"
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    /** An error occurred during the initialization phase of a service or module. */
+    INITIALIZATION_FAILED = "INITIALIZATION_FAILED"
 }
 /**
  * Custom error class for MCP-specific errors.

package/dist/types-global/errors.js

@@ -29,6 +29,8 @@ export var BaseErrorCode;
     BaseErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
     /** An error occurred during the loading or validation of configuration data. */
     BaseErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
+    /** An error occurred during the initialization phase of a service or module. */
+    BaseErrorCode["INITIALIZATION_FAILED"] = "INITIALIZATION_FAILED";
 })(BaseErrorCode || (BaseErrorCode = {}));
 /**
  * Custom error class for MCP-specific errors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ts-template",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "TypeScript template for building Model Context Protocol (MCP) servers & clients. Features production-ready utilities, stdio/HTTP transports (with JWT auth), examples, and type safety. Ideal starting point for creating MCP-based applications.",
   "main": "dist/index.js",
   "files": [
@@ -30,9 +30,9 @@
     "inspector": "mcp-inspector --config mcp.json --server mcp-ts-template"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@modelcontextprotocol/sdk": "^1.11.2",
     "@types/jsonwebtoken": "^9.0.9",
-    "@types/node": "^22.15.15",
+    "@types/node": "^22.15.17",
     "@types/sanitize-html": "^2.16.0",
     "@types/validator": "13.15.0",
     "chrono-node": "^2.8.0",
@@ -40,7 +40,7 @@
     "express": "^5.1.0",
     "ignore": "^7.0.4",
     "jsonwebtoken": "^9.0.2",
-    "openai": "^4.97.0",
+    "openai": "^4.98.0",
     "partial-json": "^0.1.7",
     "sanitize-html": "^2.16.0",
     "tiktoken": "^1.0.21",