mcp-ts-template 1.2.7 → 1.3.2

package/README.md

@@ -1,9 +1,9 @@
 # MCP TypeScript Template 🚀
 
 [![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.5-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-1.12.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.2.7-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.3.2-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)
@@ -97,39 +97,39 @@ 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.).                                   | `debug`                                    |
-| `LOGS_DIR`                | Directory for log files.                                                                            | `logs/` (in project root)                  |
-| `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).                               | `http://localhost:3000`                    |
-| `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-05-20`    |
-| `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)                                     |
+| 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.).                                   | `debug`                                 |
+| `LOGS_DIR`                | Directory for log files.                                                                            | `logs/` (in project root)               |
+| `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).                               | `http://localhost:3000`                 |
+| `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-05-20` |
+| `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).
 
 **Security Note for HTTP Transport:** When using `MCP_TRANSPORT_TYPE=http`, authentication is **mandatory** as per the MCP specification. This template includes JWT-based authentication middleware (`src/mcp-server/transports/authentication/authMiddleware.ts`). You **MUST** set a strong, unique `MCP_AUTH_SECRET_KEY` in your production environment for this security mechanism to function correctly. Failure to do so will result in bypassed authentication checks in development and fatal errors in production.
 
-### Client Configuration (`mcp-config.json`)
+### Client Configuration (`src/mcp-client/client-config/mcp-config.json`)
 
-Configure the connections for the built-in **MCP client** using `src/mcp-client/mcp-config.json`. If this file is missing, it falls back to `src/mcp-client/mcp-config.json.example`.
+Configure the connections for the built-in **MCP client** using `src/mcp-client/client-config/mcp-config.json`. If this file is missing, it falls back to `src/mcp-client/client-config/mcp-config.json.example`.
 
 This file defines external MCP servers the client can connect to. The client implementation adheres to the **MCP 2025-03-26 specification**.
 
-**Example `mcp-config.json` (see `mcp-config.json.example` for the full version):**
+**Example `mcp-config.json` (see `src/mcp-client/client-config/mcp-config.json.example` for the full version):**
 
 ```json
 {
@@ -156,7 +156,7 @@ This file defines external MCP servers the client can connect to. The client imp
 - **`env`**: Optional environment variables to set for the server process (`stdio`).
 - **`transportType`**: `stdio` (default) or `http`.
 
-See `src/mcp-client/configLoader.ts` for the Zod validation schema and `src/mcp-client/mcp-config.json.example` for a complete example.
+See `src/mcp-client/client-config/configLoader.ts` for the Zod validation schema and `src/mcp-client/client-config/mcp-config.json.example` for a complete example.
 
 ## 🏗️ Project Structure
 
@@ -164,10 +164,18 @@ The `src/` directory is organized for clarity:
 
 - `config/`: Loads environment variables and package info.
 - `mcp-client/`: Logic for the client connecting to _external_ MCP servers (updated to MCP 2025-03-26 spec).
-  - `client.ts`: Core connection management, initialization, capability declaration.
-  - `configLoader.ts`: Loads and validates `mcp-config.json`.
-  - `transport.ts`: Creates `stdio` or `http` client transports based on config.
-  - `mcp-config.json.example`: Example client config. Copy to `mcp-config.json`.
+  - `client-config/`: Handles loading and validation of `mcp-config.json`.
+    - `configLoader.ts`: Loads and validates server configurations.
+    - `mcp-config.json.example`: Example configuration file.
+  - `core/`: Core client logic including connection management and caching.
+    - `clientManager.ts`: Manages client instances and their lifecycle.
+    - `clientConnectionLogic.ts`: Handles the details of connecting and initializing with servers.
+    - `clientCache.ts`: Caches active client connections.
+  - `transports/`: Manages different communication transports (Stdio, HTTP).
+    - `transportFactory.ts`: Creates appropriate transport instances.
+    - `stdioClientTransport.ts`: Implements Stdio transport.
+    - `httpClientTransport.ts`: Implements HTTP transport.
+  - `index.ts`: Barrel file exporting key client functionalities.
 - `mcp-server/`: Logic for the MCP server _provided by this template_.
   - `server.ts`: Initializes the server, registers tools/resources.
   - `resources/`: Example resource implementations (e.g., EchoResource).
@@ -218,38 +226,38 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
 
 ## Detailed Features Table
 
-| Category                 | Feature                         | Description                                                                                                  | Location(s)                                                   |
-| :----------------------- | :------------------------------ | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
-| **Core Components**      | MCP Server                      | Core server logic, tool/resource registration, transport handling. Includes Echo Tool & Resource examples.   | `src/mcp-server/`                                             |
-|                          | MCP Client                      | Logic for connecting to external MCP servers (updated to **MCP 2025-03-26 spec**).                           | `src/mcp-client/`                                             |
-|                          | Configuration                   | Environment-aware settings with Zod validation.                                                              | `src/config/`, `src/mcp-client/configLoader.ts`               |
-|                          | HTTP Transport                  | Express-based server with SSE, session management, CORS, port retries.                                       | `src/mcp-server/transports/httpTransport.ts`                  |
-|                          | Stdio Transport                 | Handles MCP communication over standard input/output.                                                        | `src/mcp-server/transports/stdioTransport.ts`                 |
-| **Utilities (Core)**     | Logger                          | Structured, context-aware logging (files with rotation & MCP notifications).                                 | `src/utils/internal/logger.ts`                                |
-|                          | ErrorHandler                    | Centralized error processing, classification, and logging.                                                   | `src/utils/internal/errorHandler.ts`                          |
-|                          | RequestContext                  | Request/operation tracking and correlation.                                                                  | `src/utils/internal/requestContext.ts`                        |
-| **Utilities (Metrics)**  | TokenCounter                    | Estimates token counts using `tiktoken`.                                                                     | `src/utils/metrics/tokenCounter.ts`                           |
-| **Utilities (Parsing)**  | DateParser                      | Parses natural language date strings using `chrono-node`.                                                    | `src/utils/parsing/dateParser.ts`                             |
-|                          | JsonParser                      | Parses potentially partial JSON, handles `<think>` blocks.                                                   | `src/utils/parsing/jsonParser.ts`                             |
-| **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/llm-providers/openRouter/openRouterProvider.ts` |
-|                          | LLM Provider Factory            | Centralized factory for creating LLM client instances (e.g., OpenRouter, Gemini (partial integration in LLMFactory but not usable yet)).                            | `src/services/llm-providers/llmFactory.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`                          |
-|                          | Consistent Formatting           | Standardized error responses with additional context.                                                        | `src/utils/internal/errorHandler.ts`                          |
-|                          | Safe Try/Catch Patterns         | Centralized error processing helpers (`ErrorHandler.tryCatch`).                                              | `src/utils/internal/errorHandler.ts`                          |
-|                          | Client/Transport Error Handling | Specific handlers for MCP client and transport error handling.                                               | `src/mcp-client/client.ts`, `transport.ts`                    |
-| **Security**             | Input Validation                | Using `validator` and `zod` for various data type checks.                                                    | `src/utils/security/sanitization.ts`, etc.                    |
-|                          | Input Sanitization              | Using `sanitize-html` to prevent injection attacks.                                                          | `src/utils/security/sanitization.ts`                          |
-|                          | Sensitive Data Redaction        | Automatic redaction in logs.                                                                                 | `src/utils/security/sanitization.ts`                          |
-|                          | Configuration Fallback          | Safely falls back to `mcp-config.json.example` if primary client config is missing.                          | `src/mcp-client/configLoader.ts`                              |
-| **Scripts**              | Clean Script                    | Removes `dist` and `logs` directories (or custom targets).                                                   | `scripts/clean.ts`                                            |
-|                          | Make Executable Script          | Sets executable permissions (`chmod +x`) on specified files (Unix-like only).                                | `scripts/make-executable.ts`                                  |
-|                          | Tree Script                     | Generates a directory structure tree, respecting `.gitignore`.                                               | `scripts/tree.ts`                                             |
-|                          | Fetch OpenAPI Spec Script       | Fetches an OpenAPI spec (YAML/JSON) from a URL with fallbacks, saves locally.                                | `scripts/fetch-openapi-spec.ts`                               |
+| Category                 | Feature                         | Description                                                                                                                              | Location(s)                                                               |
+| :----------------------- | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
+| **Core Components**      | MCP Server                      | Core server logic, tool/resource registration, transport handling. Includes Echo Tool & Resource examples.                               | `src/mcp-server/`                                                         |
+|                          | MCP Client                      | Logic for connecting to external MCP servers (updated to **MCP 2025-03-26 spec**). Refactored for modularity.                            | `src/mcp-client/` (see subdirs: `core/`, `client-config/`, `transports/`) |
+|                          | Configuration                   | Environment-aware settings with Zod validation.                                                                                          | `src/config/`, `src/mcp-client/client-config/configLoader.ts`             |
+|                          | HTTP Transport                  | Express-based server with SSE, session management, CORS, port retries.                                                                   | `src/mcp-server/transports/httpTransport.ts`                              |
+|                          | Stdio Transport                 | Handles MCP communication over standard input/output.                                                                                    | `src/mcp-server/transports/stdioTransport.ts`                             |
+| **Utilities (Core)**     | Logger                          | Structured, context-aware logging (files with rotation & MCP notifications).                                                             | `src/utils/internal/logger.ts`                                            |
+|                          | ErrorHandler                    | Centralized error processing, classification, and logging.                                                                               | `src/utils/internal/errorHandler.ts`                                      |
+|                          | RequestContext                  | Request/operation tracking and correlation.                                                                                              | `src/utils/internal/requestContext.ts`                                    |
+| **Utilities (Metrics)**  | TokenCounter                    | Estimates token counts using `tiktoken`.                                                                                                 | `src/utils/metrics/tokenCounter.ts`                                       |
+| **Utilities (Parsing)**  | DateParser                      | Parses natural language date strings using `chrono-node`.                                                                                | `src/utils/parsing/dateParser.ts`                                         |
+|                          | JsonParser                      | Parses potentially partial JSON, handles `<think>` blocks.                                                                               | `src/utils/parsing/jsonParser.ts`                                         |
+| **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/llm-providers/openRouter/openRouterProvider.ts`             |
+|                          | LLM Provider Factory            | Centralized factory for creating LLM client instances (e.g., OpenRouter, Gemini (partial integration in LLMFactory but not usable yet)). | `src/services/llm-providers/llmFactory.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`                                      |
+|                          | Consistent Formatting           | Standardized error responses with additional context.                                                                                    | `src/utils/internal/errorHandler.ts`                                      |
+|                          | Safe Try/Catch Patterns         | Centralized error processing helpers (`ErrorHandler.tryCatch`).                                                                          | `src/utils/internal/errorHandler.ts`                                      |
+|                          | Client/Transport Error Handling | Specific handlers for MCP client and transport error handling.                                                                           | `src/mcp-client/core/`, `src/mcp-client/transports/`                      |
+| **Security**             | Input Validation                | Using `validator` and `zod` for various data type checks.                                                                                | `src/utils/security/sanitization.ts`, etc.                                |
+|                          | Input Sanitization              | Using `sanitize-html` to prevent injection attacks.                                                                                      | `src/utils/security/sanitization.ts`                                      |
+|                          | Sensitive Data Redaction        | Automatic redaction in logs.                                                                                                             | `src/utils/security/sanitization.ts`                                      |
+|                          | Configuration Fallback          | Safely falls back to `mcp-config.json.example` if primary client config is missing.                                                      | `src/mcp-client/client-config/configLoader.ts`                            |
+| **Scripts**              | Clean Script                    | Removes `dist` and `logs` directories (or custom targets).                                                                               | `scripts/clean.ts`                                                        |
+|                          | Make Executable Script          | Sets executable permissions (`chmod +x`) on specified files (Unix-like only).                                                            | `scripts/make-executable.ts`                                              |
+|                          | Tree Script                     | Generates a directory structure tree, respecting `.gitignore`.                                                                           | `scripts/tree.ts`                                                         |
+|                          | Fetch OpenAPI Spec Script       | Fetches an OpenAPI spec (YAML/JSON) from a URL with fallbacks, saves locally.                                                            | `scripts/fetch-openapi-spec.ts`                                           |
 
 ---
 

package/dist/config/index.js

@@ -29,7 +29,7 @@ dotenv.config();
 const findProjectRoot = (startDir) => {
     let currentDir = startDir;
     while (true) {
-        const packageJsonPath = join(currentDir, 'package.json');
+        const packageJsonPath = join(currentDir, "package.json");
         if (existsSync(packageJsonPath)) {
             return currentDir;
         }
@@ -165,9 +165,12 @@ const env = parsedEnv.success ? parsedEnv.data : EnvSchema.parse({});
  * @returns The validated, absolute path to the directory, or null if invalid.
  */
 const ensureDirectory = (dirPath, rootDir, dirName) => {
-    const resolvedDirPath = path.isAbsolute(dirPath) ? dirPath : path.resolve(rootDir, dirPath);
+    const resolvedDirPath = path.isAbsolute(dirPath)
+        ? dirPath
+        : path.resolve(rootDir, dirPath);
     // Ensure the resolved path is within the project root boundary
-    if (!resolvedDirPath.startsWith(rootDir + path.sep) && resolvedDirPath !== rootDir) {
+    if (!resolvedDirPath.startsWith(rootDir + path.sep) &&
+        resolvedDirPath !== rootDir) {
         if (process.stdout.isTTY) {
             console.error(`Error: ${dirName} path "${dirPath}" resolves to "${resolvedDirPath}", which is outside the project boundary "${rootDir}".`);
         }

package/dist/index.js

@@ -22,16 +22,21 @@
  * @module src/index
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import http from "http"; // Import http module
 import { config, environment } from "./config/index.js";
 import { initializeAndStartServer } from "./mcp-server/server.js";
 import { requestContextService } from "./utils/index.js";
 import { logger } from "./utils/internal/logger.js";
 /**
  * Holds the main MCP server instance, primarily for STDIO transport.
- * For HTTP transport, server instances are typically managed per session.
  * @private
  */
-let server;
+let mcpStdioServer;
+/**
+ * Holds the Node.js HTTP server instance if HTTP transport is used.
+ * @private
+ */
+let actualHttpServer;
 /**
  * Gracefully shuts down the main MCP server and associated resources.
  * Called on process termination signals or critical unhandled errors.
@@ -46,25 +51,63 @@ const shutdown = async (signal) => {
         triggerEvent: signal,
     });
     logger.info(`Received ${signal}. Initiating graceful shutdown...`, shutdownContext);
-    try {
-        if (server) {
-            logger.info("Attempting to close main MCP server...", shutdownContext);
-            await server.close();
-            logger.info("Main MCP server closed successfully.", shutdownContext);
+    let mcpClosed = false;
+    let httpClosed = false;
+    let closeError = null;
+    const checkAndExit = () => {
+        if (closeError) {
+            logger.error("Critical error encountered during shutdown process.", {
+                ...shutdownContext,
+                errorMessage: closeError.message,
+                errorStack: closeError.stack,
+            });
+            process.exit(1);
         }
-        else {
-            logger.notice("No global server instance found to close during shutdown (this may be normal for HTTP transport).", shutdownContext);
+        else if (mcpClosed && httpClosed) {
+            logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
+            process.exit(0);
         }
-        logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
-        process.exit(0);
+    };
+    if (mcpStdioServer) {
+        logger.info("Attempting to close main MCP server (STDIO)...", shutdownContext);
+        mcpStdioServer.close()
+            .then(() => {
+            logger.info("Main MCP server (STDIO) closed successfully.", shutdownContext);
+            mcpClosed = true;
+            checkAndExit();
+        })
+            .catch((err) => {
+            logger.error("Error closing MCP server (STDIO).", { ...shutdownContext, error: err });
+            mcpClosed = true; // Consider it closed even on error to allow exit
+            if (!closeError)
+                closeError = err;
+            checkAndExit();
+        });
     }
-    catch (error) {
-        logger.error("Critical error encountered during shutdown process.", {
-            ...shutdownContext,
-            errorMessage: error instanceof Error ? error.message : String(error),
-            errorStack: error instanceof Error ? error.stack : undefined,
+    else {
+        mcpClosed = true; // No STDIO McpServer to close
+    }
+    if (actualHttpServer) {
+        logger.info("Attempting to close HTTP server...", shutdownContext);
+        actualHttpServer.close((err) => {
+            if (err) {
+                logger.error("Error closing HTTP server.", { ...shutdownContext, error: err });
+                if (!closeError)
+                    closeError = err;
+            }
+            else {
+                logger.info("HTTP server closed successfully.", shutdownContext);
+            }
+            httpClosed = true;
+            checkAndExit();
         });
-        process.exit(1);
+    }
+    else {
+        httpClosed = true; // No HTTP server to close
+    }
+    // Initial check in case no servers needed closing
+    if (mcpClosed && httpClosed) {
+        checkAndExit();
     }
 };
 /**
@@ -122,14 +165,18 @@ const start = async () => {
     logger.info(`Starting ${config.mcpServerName} (Version: ${config.mcpServerVersion}, Transport: ${transportType}, Env: ${environment})...`, startupContext);
     try {
         logger.debug("Calling initializeAndStartServer to set up MCP transport...", startupContext);
-        const potentialServerInstance = await initializeAndStartServer();
-        if (transportType === "stdio" &&
-            potentialServerInstance instanceof McpServer) {
-            server = potentialServerInstance;
+        const serverInstance = await initializeAndStartServer();
+        if (transportType === "stdio" && serverInstance instanceof McpServer) {
+            mcpStdioServer = serverInstance;
             logger.info("STDIO McpServer instance stored globally for shutdown.", startupContext);
         }
+        else if (transportType === "http" && serverInstance instanceof http.Server) {
+            actualHttpServer = serverInstance;
+            logger.info("HTTP transport initialized, http.Server instance stored globally for shutdown.", startupContext);
+        }
         else if (transportType === "http") {
-            logger.info("HTTP transport initialized. Server lifecycle managed by HTTP listener and session handlers.", startupContext);
+            // This case should ideally not be reached if initializeAndStartServer correctly returns http.Server
+            logger.warning("HTTP transport initialized, but no http.Server instance was returned to index.ts. Shutdown might be incomplete.", startupContext);
         }
         logger.info(`${config.mcpServerName} is now running and ready to accept connections via ${transportType} transport.`, {
             ...startupContext,

package/dist/mcp-client/{configLoader.d.ts → client-config/configLoader.d.ts}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { RequestContext } from "../utils/index.js";
+import { RequestContext } from "../../utils/index.js";
 /**
  * Zod schema for a single MCP server's configuration entry.
  * Defines the command, arguments, environment variables, and transport type for an MCP server.
@@ -10,16 +10,22 @@ export declare const McpServerConfigEntrySchema: z.ZodObject<{
     args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     transportType: z.ZodDefault<z.ZodEnum<["stdio", "http"]>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    autoApprove: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     transportType: "stdio" | "http";
     command: string;
     args: string[];
+    disabled?: boolean | undefined;
     env?: Record<string, string> | undefined;
+    autoApprove?: boolean | undefined;
 }, {
     command: string;
+    disabled?: boolean | undefined;
     transportType?: "stdio" | "http" | undefined;
     args?: string[] | undefined;
     env?: Record<string, string> | undefined;
+    autoApprove?: boolean | undefined;
 }>;
 /**
  * Represents the configuration for a single MCP server.
@@ -36,30 +42,40 @@ export declare const McpClientConfigFileSchema: z.ZodObject<{
         args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         transportType: z.ZodDefault<z.ZodEnum<["stdio", "http"]>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+        autoApprove: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         transportType: "stdio" | "http";
         command: string;
         args: string[];
+        disabled?: boolean | undefined;
         env?: Record<string, string> | undefined;
+        autoApprove?: boolean | undefined;
     }, {
         command: string;
+        disabled?: boolean | undefined;
         transportType?: "stdio" | "http" | undefined;
         args?: string[] | undefined;
         env?: Record<string, string> | undefined;
+        autoApprove?: boolean | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     mcpServers: Record<string, {
         transportType: "stdio" | "http";
         command: string;
         args: string[];
+        disabled?: boolean | undefined;
         env?: Record<string, string> | undefined;
+        autoApprove?: boolean | undefined;
     }>;
 }, {
     mcpServers: Record<string, {
         command: string;
+        disabled?: boolean | undefined;
         transportType?: "stdio" | "http" | undefined;
         args?: string[] | undefined;
         env?: Record<string, string> | undefined;
+        autoApprove?: boolean | undefined;
     }>;
 }>;
 /**
@@ -68,13 +84,12 @@ export declare const McpClientConfigFileSchema: z.ZodObject<{
  */
 export type McpClientConfigFile = z.infer<typeof McpClientConfigFileSchema>;
 /**
- * Loads, validates, and caches the MCP client configuration from `mcp-config.json`
- * or `mcp-config.json.example`.
+ * Loads, validates, and caches the MCP client configuration from `mcp-config.json`.
  * The configuration is validated against {@link McpClientConfigFileSchema}.
  *
  * @param parentContext - Optional parent request context for logging and tracing.
  * @returns The loaded and validated MCP server configurations object.
- * @throws {McpError} If neither config file can be read, or if parsing or validation fails.
+ * @throws {McpError} If the config file cannot be read, or if parsing or validation fails.
  */
 export declare function loadMcpClientConfig(parentContext?: RequestContext | null): McpClientConfigFile;
 /**

package/dist/mcp-client/{configLoader.js → client-config/configLoader.js}

@@ -1,16 +1,16 @@
 /**
- * @fileoverview Loads and validates MCP client configuration from JSON files.
+ * @fileoverview Loads and validates MCP client configuration from a JSON file.
  * This module defines Zod schemas for the configuration structure, provides functions
- * to load configuration from `mcp-config.json` (with a fallback to `mcp-config.json.example`),
- * and retrieves specific server configurations.
- * @module src/mcp-client/configLoader
+ * to load configuration from `mcp-config.json`, and retrieves specific server
+ * configurations.
+ * @module src/mcp-client/client-config/configLoader
  */
 import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
-import { BaseErrorCode, McpError } from "../types-global/errors.js";
-import { logger, requestContextService, } from "../utils/index.js";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService, } from "../../utils/index.js";
 // --- Zod Schemas for Configuration Validation ---
 /**
  * Zod schema for environment variables passed to an MCP server process.
@@ -37,8 +37,14 @@ export const McpServerConfigEntrySchema = z.object({
         .enum(["stdio", "http"])
         .default("stdio")
         .describe("Communication transport type ('stdio' or 'http')."),
-    // disabled: z.boolean().optional().describe("If true, this server configuration is ignored."),
-    // autoApprove: z.boolean().optional().describe("If true, skip user approval prompts for this server (use with caution)."),
+    disabled: z
+        .boolean()
+        .optional()
+        .describe("If true, this server configuration is ignored."),
+    autoApprove: z
+        .boolean()
+        .optional()
+        .describe("If true, skip user approval prompts for this server (use with caution)."),
 });
 /**
  * Zod schema for the root structure of the `mcp-config.json` file.
@@ -51,18 +57,18 @@ export const McpClientConfigFileSchema = z.object({
 });
 // --- Configuration Loading Logic ---
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const primaryConfigPath = join(__dirname, "mcp-config.json");
-const exampleConfigPath = join(__dirname, "mcp-config.json.example");
+// Path when running from dist: __dirname is .../dist/mcp-client/client-config
+// We want to reach: .../src/mcp-client/client-config/mcp-config.json
+const primaryConfigPath = join(__dirname, "../../../src/mcp-client/client-config/mcp-config.json");
 let loadedConfig = null;
 let loadedConfigPath = null;
 /**
- * Loads, validates, and caches the MCP client configuration from `mcp-config.json`
- * or `mcp-config.json.example`.
+ * Loads, validates, and caches the MCP client configuration from `mcp-config.json`.
  * The configuration is validated against {@link McpClientConfigFileSchema}.
  *
  * @param parentContext - Optional parent request context for logging and tracing.
  * @returns The loaded and validated MCP server configurations object.
- * @throws {McpError} If neither config file can be read, or if parsing or validation fails.
+ * @throws {McpError} If the config file cannot be read, or if parsing or validation fails.
  */
 export function loadMcpClientConfig(parentContext) {
     const context = requestContextService.createRequestContext({
@@ -73,60 +79,30 @@ export function loadMcpClientConfig(parentContext) {
         logger.debug(`Returning cached MCP client config from: ${loadedConfigPath}`, context);
         return loadedConfig;
     }
-    let fileContent = null;
-    let configPathToLog = "";
-    if (existsSync(primaryConfigPath)) {
-        logger.info(`Attempting to load primary MCP config: ${primaryConfigPath}`, context);
-        try {
-            fileContent = readFileSync(primaryConfigPath, "utf-8");
-            configPathToLog = primaryConfigPath;
-            logger.info(`Successfully read primary config file.`, {
-                ...context,
-                filePath: configPathToLog,
-            });
-        }
-        catch (readError) {
-            logger.warning(`Failed to read primary config file at ${primaryConfigPath}, attempting fallback.`, {
-                ...context,
-                filePath: primaryConfigPath,
-                error: readError instanceof Error ? readError.message : String(readError),
-            });
-        }
-    }
-    else {
-        logger.info(`Primary config file not found at ${primaryConfigPath}, attempting fallback.`, {
+    let fileContent;
+    const configPathToLog = primaryConfigPath; // Only attempt to load the primary config
+    if (!existsSync(primaryConfigPath)) {
+        logger.error(`MCP client config file not found at ${primaryConfigPath}.`, {
             ...context,
             filePath: primaryConfigPath,
         });
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `MCP client config file not found: ${primaryConfigPath} does not exist.`, context);
     }
-    if (!fileContent) {
-        if (existsSync(exampleConfigPath)) {
-            logger.info(`Attempting to load example MCP config: ${exampleConfigPath}`, context);
-            try {
-                fileContent = readFileSync(exampleConfigPath, "utf-8");
-                configPathToLog = exampleConfigPath;
-                logger.info(`Successfully read example config file.`, {
-                    ...context,
-                    filePath: configPathToLog,
-                });
-            }
-            catch (readError) {
-                logger.error(`Failed to read example config file as well.`, {
-                    ...context,
-                    filePath: exampleConfigPath,
-                    error: readError instanceof Error ? readError.message : String(readError),
-                });
-                throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Failed to read MCP client config: Neither ${primaryConfigPath} nor ${exampleConfigPath} could be read.`, { originalError: readError });
-            }
-        }
-        else {
-            logger.error(`Neither primary nor example config file found.`, {
-                ...context,
-                primaryPath: primaryConfigPath,
-                examplePath: exampleConfigPath,
-            });
-            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `MCP client config file not found: Looked for ${primaryConfigPath} and ${exampleConfigPath}.`);
-        }
+    logger.info(`Attempting to load MCP config from: ${primaryConfigPath}`, context);
+    try {
+        fileContent = readFileSync(primaryConfigPath, "utf-8");
+        logger.info(`Successfully read config file: ${primaryConfigPath}`, {
+            ...context,
+            filePath: configPathToLog,
+        });
+    }
+    catch (readError) {
+        logger.error(`Failed to read MCP client config file: ${primaryConfigPath}`, {
+            ...context,
+            filePath: primaryConfigPath,
+            error: readError instanceof Error ? readError.message : String(readError),
+        });
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Failed to read MCP client config file ${primaryConfigPath}: ${readError instanceof Error ? readError.message : String(readError)}`, { originalError: readError, ...context });
     }
     try {
         const parsedJson = JSON.parse(fileContent);
@@ -140,6 +116,7 @@ export function loadMcpClientConfig(parentContext) {
             const errorMessages = validationResult.error.errors
                 .map((e) => `${e.path.join(".")}: ${e.message}`)
                 .join("; ");
+            // The comment about ErrorHandlerOption was here, removing it.
             throw new Error(`Validation failed: ${errorMessages}`);
         }
         loadedConfig = validationResult.data;
@@ -158,7 +135,7 @@ export function loadMcpClientConfig(parentContext) {
             error: errorMessage,
             stack: error instanceof Error ? error.stack : undefined,
         });
-        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Failed to load/validate MCP client config from ${configPathToLog}: ${errorMessage}`, { originalError: error });
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Failed to load/validate MCP client config from ${configPathToLog}: ${errorMessage}`, { originalError: error, ...context });
     }
 }
 /**
@@ -181,8 +158,9 @@ export function getMcpServerConfig(serverName, parentContext) {
     const serverConfig = config.mcpServers[serverName];
     if (!serverConfig) {
         logger.error(`Configuration for MCP server "${serverName}" not found in ${configPath}.`, context);
-        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Configuration for MCP server "${serverName}" not found in ${configPath}.`);
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Configuration for MCP server "${serverName}" not found in ${configPath}.`, context);
     }
     logger.debug(`Retrieved configuration for server "${serverName}" from ${configPath}`, context);
-    return { ...serverConfig }; // Return a copy
+    // Return a deep copy to prevent accidental modification of the cached config
+    return JSON.parse(JSON.stringify(serverConfig));
 }