mcp-ts-template 1.9.2 → 1.9.3

package/README.md

@@ -7,8 +7,8 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue?style=flat-square)](https://www.typescriptlang.org/)
 [![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.17.4-green?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--06--18-lightgrey?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.9.1-blue?style=flat-square)](./CHANGELOG.md)
-[![Coverage](https://img.shields.io/badge/Coverage-46.52%25-brightgreen?style=flat-square)](./vitest.config.ts)
+[![Version](https://img.shields.io/badge/Version-1.9.3-blue?style=flat-square)](./CHANGELOG.md)
+[![Coverage](https://img.shields.io/badge/Coverage-63.51%25-brightgreen?style=flat-square)](./vitest.config.ts)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green?style=flat-square)](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)
@@ -26,7 +26,7 @@ Building a robust server for AI agents is more than just writing code. It requir
 - **Best Practices by Default**: Enforces a clean, modular architecture that's easy to maintain and extend.
 - **AI-Ready**: Designed with LLM agents in mind, including detailed schemas and rich LLM developer-friendly resources (e.g. .clinerules).
 
-> **Note on src/mcp-client & src/agent:** The MCP client & Agent components have been enhanced and moved to the (Coming Soon)[**atlas-mcp-agent**](https://github.com/cyanheads/atlas-mcp-agent) repository. This template now focuses exclusively on providing a best-in-class server implementation and framework.
+> **Note on src/mcp-client & src/agent:** The MCP client & Agent components have been enhanced and moved to the [**atlas-mcp-agent**](https://github.com/cyanheads/atlas-mcp-agent) repository. This template now focuses exclusively on providing a best-in-class server implementation and framework.
 
 ## ✨ Key Features
 
@@ -34,14 +34,14 @@ Building a robust server for AI agents is more than just writing code. It requir
 | :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
 | **🔌 MCP Server**           | A functional server with example tools and resources. Supports `stdio` and a **Streamable HTTP** transport built with [**Hono**](https://hono.dev/). | `src/mcp-server/`, `src/mcp-server/transports/`                      |
 | **🔭 Observability**        | Built-in **OpenTelemetry** for distributed tracing and metrics. Auto-instrumentation for core modules and custom tracing for all tool executions.    | `src/utils/telemetry/`                                               |
-| **🚀 Production Utilities** | High-performance logging (Pino), Error Handling, ID Generation, Rate Limiting, Async Request Context, Input Sanitization.                            | `src/utils/`                                                         |
+| **🚀 Production Utilities** | Logging, Error Handling, ID Generation, Rate Limiting, Request Context tracking, Input Sanitization.                                                 | `src/utils/`                                                         |
 | **🔒 Type Safety/Security** | Strong type checking via TypeScript & Zod validation. Built-in security utilities (sanitization, auth middleware for HTTP).                          | Throughout, `src/utils/security/`, `src/mcp-server/transports/auth/` |
-| **⚙️ Error Handling**       | Consistent error categorization (`JsonRpcErrorCode`), detailed logging, centralized handling (`ErrorHandler`).                                       | `src/utils/internal/errorHandler.ts`, `src/types-global/`            |
-| **📚 Documentation**        | Comprehensive `README.md`, structured JSDoc comments, API references, and a detailed [Migration Guide](./docs/migrations/v1.9.0.md).                 | `README.md`, Codebase, `tsdoc.json`, `docs/`                         |
+| **⚙️ Error Handling**       | Consistent error categorization (`JsonRpcErrorCode`), detailed logging, centralized handling (`ErrorHandler`).                                          | `src/utils/internal/errorHandler.ts`, `src/types-global/`            |
+| **📚 Documentation**        | Comprehensive `README.md`, structured JSDoc comments, API references.                                                                                | `README.md`, Codebase, `tsdoc.json`, `docs/api-references/`          |
 | **🕵️ Interaction Logging**  | Captures raw requests and responses for all external LLM provider interactions to a dedicated `interactions.log` file for full traceability.         | `src/utils/internal/logger.ts`                                       |
 | **🤖 Agent Ready**          | Includes a [.clinerules](./.clinerules/clinerules.md) developer cheatsheet tailored for LLM coding agents.                                           | `.clinerules/`                                                       |
 | **🛠️ Utility Scripts**      | Scripts for cleaning builds, setting executable permissions, generating directory trees, and fetching OpenAPI specs.                                 | `scripts/`                                                           |
-| **🧩 Services**             | Reusable modules for LLM (OpenRouter) and data storage (DuckDB) integration, with examples.                                                          | `src/services/`, `src/storage/duckdbExample.ts`                      |
+| **🧩 Services**             | Reusable modules for LLM (OpenRouter) integration.                                                          | `src/services/`                      |
 | **🧪 Integration Testing**  | Integrated with Vitest for fast and reliable integration testing. Includes example tests for core logic and a coverage reporter.                     | `vitest.config.ts`, `tests/`                                         |
 | **⏱️ Performance Metrics**  | Built-in utility to automatically measure and log the execution time and payload size of every tool call.                                            | `src/utils/internal/performance.ts`                                  |
 
@@ -49,12 +49,12 @@ Building a robust server for AI agents is more than just writing code. It requir
 
 This template is built on a set of architectural principles to ensure modularity, testability, and operational clarity.
 
-- **Core Server (`src/mcp-server/server.ts`)**: The central point where tools and resources are registered using the standard `McpServer` from the SDK.
+- **Core Server (`src/mcp-server/server.ts`)**: The central point where tools and resources are registered. It uses a `ManagedMcpServer` wrapper to provide enhanced introspection capabilities. It acts the same way as the native McpServer, but with additional features like introspection and enhanced error handling.
 - **Transports (`src/mcp-server/transports/`)**: The transport layer connects the core server to the outside world. It supports both `stdio` for direct process communication and a streamable **Hono**-based `http` server.
 - **"Logic Throws, Handler Catches"**: This is the immutable cornerstone of our error-handling strategy.
   - **Core Logic (`logic.ts`)**: This layer is responsible for pure, self-contained business logic. It **throws** a structured `McpError` on any failure.
-  - **Handlers (`registration.ts`)**: This layer interfaces with the server, invokes the core logic, and **catches** any errors using centralized utilities (`createToolHandler`). It is the exclusive location where errors are processed and formatted into a final response.
-- **Structured, Traceable Operations**: Every operation is traced from initiation to completion via a `RequestContext` that is implicitly available throughout the entire asynchronous call stack using Node.js's `AsyncLocalStorage`.
+  - **Handlers (`registration.ts`)**: This layer interfaces with the server, invokes the core logic, and **catches** any errors. It is the exclusive location where errors are processed and formatted into a final response.
+- **Structured, Traceable Operations**: Every operation is traced from initiation to completion via a `RequestContext` that is passed through the entire call stack, ensuring comprehensive and structured logging.
 
 ## Quick Start
 
@@ -79,11 +79,11 @@ npm run build
 
 - **Via Stdio (Default):**
   ```bash
-  npm run start:stdio
+  npm run start:server
   ```
 - **Via Streamable HTTP:**
   ```bash
-  npm run start:http
+  npm run start:server:http
   ```
 
 ### 4. Running Tests
@@ -127,7 +127,7 @@ Configure the server using these environment variables (or a `.env` file):
 
 - **`src/mcp-server/`**: Contains the core MCP server, tools, resources, and transport handlers.
 - **`src/config/`**: Handles loading and validation of environment variables.
-- **`src/services/`**: Reusable modules for integrating with external services (DuckDB, OpenRouter).
+- **`src/services/`**: Reusable modules for integrating with external services (OpenRouter).
 - **`src/types-global/`**: Defines shared TypeScript interfaces and type definitions.
 - **`src/utils/`**: Core utilities (logging, error handling, security, etc.).
 - **`src/index.ts`**: The main entry point that initializes and starts the server.
@@ -150,13 +150,13 @@ This is the cornerstone of the architecture:
 
 1.  **`logic.ts`**: This file contains the pure business logic.
     - It defines the Zod schemas for input and output, which serve as the single source of truth for the tool's data contract.
-    - The core logic function is pure: it takes validated parameters and either returns a result or **throws** a structured `McpError`. It retrieves the request context via `getRequestContext()`.
+    - The core logic function is pure: it takes validated parameters and a request context, and either returns a result or **throws** a structured `McpError`.
     - It **never** contains `try...catch` blocks for formatting a final response.
 
 2.  **`registration.ts`**: This file is the "handler" that connects the logic to the MCP server.
     - It imports the schemas and logic function from `logic.ts`.
-    - It calls `server.registerTool()`, providing the tool's metadata and the runtime handler created by the `createToolHandler` utility.
-    - The centralized handler **always** wraps the call to the logic function in a `try...catch` block. This is the **only** place where errors are caught, processed by the `ErrorHandler`, and formatted into a standardized error response.
+    - It calls `server.registerTool()`, providing the tool's metadata and the runtime handler.
+    - The runtime handler **always** wraps the call to the logic function in a `try...catch` block. This is the **only** place where errors are caught, processed by the `ErrorHandler`, and formatted into a standardized error response.
 
 This pattern ensures that core logic remains decoupled, pure, and easily testable, while the registration layer handles all transport-level concerns, side effects, and response formatting.
 

package/dist/index.js

@@ -9,12 +9,12 @@
 // IMPORTANT: This line MUST be the first import to ensure OpenTelemetry is
 // initialized before any other modules are loaded.
 import { shutdownOpenTelemetry } from "./utils/telemetry/instrumentation.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import http from "http";
 import { config, environment } from "./config/index.js";
 import { initializeAndStartServer } from "./mcp-server/server.js";
 import { requestContextService } from "./utils/index.js";
-import { logFatal, logOperationError, logOperationStart, logOperationSuccess, } from "./utils/internal/logging-helpers.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import http from "http";
+import { logger } from "./utils/internal/logger.js";
 let mcpStdioServer;
 let actualHttpServer;
 const shutdown = async (signal) => {
@@ -22,38 +22,61 @@ const shutdown = async (signal) => {
         operation: "ServerShutdown",
         triggerEvent: signal,
     });
-    logOperationStart(shutdownContext, `Received ${signal}. Initiating graceful shutdown...`);
+    logger.info(`Received ${signal}. Initiating graceful shutdown...`, shutdownContext);
     try {
+        // Shutdown OpenTelemetry first to ensure buffered telemetry is sent
         await shutdownOpenTelemetry();
         let closePromise = Promise.resolve();
         const transportType = config.mcpTransportType;
         if (transportType === "stdio" && mcpStdioServer) {
-            logOperationStart(shutdownContext, "Attempting to close main MCP server (STDIO)...");
+            logger.info("Attempting to close main MCP server (STDIO)...", shutdownContext);
             closePromise = mcpStdioServer.close();
         }
         else if (transportType === "http" && actualHttpServer) {
-            logOperationStart(shutdownContext, "Attempting to close HTTP server...");
+            logger.info("Attempting to close HTTP server...", shutdownContext);
             closePromise = new Promise((resolve, reject) => {
                 actualHttpServer.close((err) => {
                     if (err) {
-                        logOperationError(shutdownContext, "Error closing HTTP server.", err);
+                        logger.error("Error closing HTTP server.", err, shutdownContext);
                         return reject(err);
                     }
-                    logOperationSuccess(shutdownContext, "HTTP server closed successfully.");
+                    logger.info("HTTP server closed successfully.", shutdownContext);
                     resolve();
                 });
             });
         }
         await closePromise;
-        logOperationSuccess(shutdownContext, "Graceful shutdown completed successfully. Exiting.");
+        logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
         process.exit(0);
     }
     catch (error) {
-        logOperationError(shutdownContext, "Critical error during shutdown process.", error);
+        logger.error("Critical error during shutdown process.", error, shutdownContext);
         process.exit(1);
     }
 };
 const start = async () => {
+    const validMcpLogLevels = [
+        "debug",
+        "info",
+        "notice",
+        "warning",
+        "error",
+        "crit",
+        "alert",
+        "emerg",
+    ];
+    const initialLogLevelConfig = config.logLevel;
+    let validatedMcpLogLevel = "info";
+    if (validMcpLogLevels.includes(initialLogLevelConfig)) {
+        validatedMcpLogLevel = initialLogLevelConfig;
+    }
+    else {
+        if (process.stdout.isTTY) {
+            console.warn(`[Startup Warning] Invalid MCP_LOG_LEVEL "${initialLogLevelConfig}". Defaulting to "info".`);
+        }
+    }
+    await logger.initialize(validatedMcpLogLevel);
+    logger.info(`Logger initialized. Effective MCP logging level: ${validatedMcpLogLevel}.`, requestContextService.createRequestContext({ operation: "LoggerInit" }));
     const transportType = config.mcpTransportType;
     const startupContext = requestContextService.createRequestContext({
         operation: `ServerStartupSequence_${transportType}`,
@@ -61,7 +84,7 @@ const start = async () => {
         applicationVersion: config.mcpServerVersion,
         nodeEnvironment: environment,
     });
-    logOperationStart(startupContext, `Starting ${config.mcpServerName} (Version: ${config.mcpServerVersion}, Transport: ${transportType}, Env: ${environment})...`);
+    logger.info(`Starting ${config.mcpServerName} (Version: ${config.mcpServerVersion}, Transport: ${transportType}, Env: ${environment})...`, startupContext);
     try {
         const serverInstance = await initializeAndStartServer();
         if (transportType === "stdio" && serverInstance instanceof McpServer) {
@@ -71,28 +94,20 @@ const start = async () => {
             serverInstance instanceof http.Server) {
             actualHttpServer = serverInstance;
         }
-        logOperationSuccess(startupContext, `${config.mcpServerName} is now running and ready.`);
+        logger.info(`${config.mcpServerName} is now running and ready.`, startupContext);
         process.on("SIGTERM", () => shutdown("SIGTERM"));
         process.on("SIGINT", () => shutdown("SIGINT"));
-        // The logger already has a global uncaughtException handler for logging.
-        // This handler is for initiating a graceful shutdown.
         process.on("uncaughtException", (error) => {
-            const context = requestContextService.createRequestContext({
-                operation: "uncaughtException",
-            });
-            logFatal(context, "FATAL: Uncaught exception triggered shutdown.", error);
+            logger.fatal("FATAL: Uncaught exception detected.", error, startupContext);
             shutdown("uncaughtException");
         });
         process.on("unhandledRejection", (reason) => {
-            const context = requestContextService.createRequestContext({
-                operation: "unhandledRejection",
-            });
-            logFatal(context, "FATAL: Unhandled promise rejection triggered shutdown.", reason);
+            logger.fatal("FATAL: Unhandled promise rejection detected.", reason, startupContext);
             shutdown("unhandledRejection");
         });
     }
     catch (error) {
-        logFatal(startupContext, "CRITICAL ERROR DURING STARTUP.", error);
+        logger.fatal("CRITICAL ERROR DURING STARTUP.", error, startupContext);
         await shutdownOpenTelemetry(); // Attempt to flush any startup-related traces
         process.exit(1);
     }
@@ -102,10 +117,9 @@ const start = async () => {
         await start();
     }
     catch (error) {
-        const context = requestContextService.createRequestContext({
-            operation: "globalCatch",
-        });
-        logFatal(context, "[GLOBAL CATCH] A fatal, unhandled error occurred.", error);
+        if (process.stdout.isTTY) {
+            console.error("[GLOBAL CATCH] A fatal, unhandled error occurred:", error);
+        }
         process.exit(1);
     }
 })();

package/dist/index.js.map

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

package/dist/mcp-server/core/managedMcpServer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Defines a wrapper around the McpServer class to provide
+ * extended functionality, such as metadata introspection, without needing
+ * to access private properties of the underlying SDK class.
+ * @module src/mcp-server/core/managedMcpServer
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type RegisterToolParameters = Parameters<McpServer["registerTool"]>;
+type ToolSpec = RegisterToolParameters[1];
+type ToolImplementation = RegisterToolParameters[2];
+type RegisteredToolReturn = ReturnType<McpServer["registerTool"]>;
+type ServerIdentity = ConstructorParameters<typeof McpServer>[0];
+type McpServerOptions = NonNullable<ConstructorParameters<typeof McpServer>[1]>;
+/**
+ * A wrapper around the McpServer that captures registration metadata
+ * to make it available for status endpoints and other diagnostics.
+ * It acts as a full pass-through for all McpServer functionality.
+ */
+export declare class ManagedMcpServer extends McpServer {
+    private readonly storedTools;
+    readonly serverIdentity: ServerIdentity;
+    readonly serverOptions?: McpServerOptions;
+    constructor(identity: ServerIdentity, options?: McpServerOptions);
+    registerTool(name: string, spec: ToolSpec, implementation: ToolImplementation): RegisteredToolReturn;
+    /**
+     * Retrieves the metadata for all registered tools.
+     */
+    getTools(): {
+        name: string;
+        description?: string;
+        inputSchema: unknown;
+        outputSchema?: unknown;
+    }[];
+    /**
+     * Gets the server's name from its identity.
+     */
+    get name(): string;
+    /**
+     * Gets the server's version from its identity.
+     */
+    get version(): string;
+    /**
+     * Gets the server's capabilities from its options.
+     */
+    get capabilities(): McpServerOptions["capabilities"] | undefined;
+}
+export {};
+//# sourceMappingURL=managedMcpServer.d.ts.map

package/dist/mcp-server/core/managedMcpServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedMcpServer.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/core/managedMcpServer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,KAAK,sBAAsB,GAAG,UAAU,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;AACpE,KAAK,QAAQ,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAC1C,KAAK,kBAAkB,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;AACpD,KAAK,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;AAElE,KAAK,cAAc,GAAG,qBAAqB,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,KAAK,gBAAgB,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAOhF;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,SAAgB,cAAc,EAAE,cAAc,CAAC;IAC/C,SAAgB,aAAa,CAAC,EAAE,gBAAgB,CAAC;gBAErC,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAMvD,YAAY,CACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,EACd,cAAc,EAAE,kBAAkB,GACjC,oBAAoB;IAKvB;;OAEG;IACI,QAAQ,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,OAAO,CAAC;QACrB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,EAAE;IASH;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,gBAAgB,CAAC,cAAc,CAAC,GAAG,SAAS,CAQtE;CACF"}

package/dist/mcp-server/core/managedMcpServer.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Defines a wrapper around the McpServer class to provide
+ * extended functionality, such as metadata introspection, without needing
+ * to access private properties of the underlying SDK class.
+ * @module src/mcp-server/core/managedMcpServer
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * A wrapper around the McpServer that captures registration metadata
+ * to make it available for status endpoints and other diagnostics.
+ * It acts as a full pass-through for all McpServer functionality.
+ */
+export class ManagedMcpServer extends McpServer {
+    storedTools = [];
+    serverIdentity;
+    serverOptions;
+    constructor(identity, options) {
+        super(identity, options);
+        this.serverIdentity = identity;
+        this.serverOptions = options;
+    }
+    registerTool(name, spec, implementation) {
+        this.storedTools.push({ name, spec });
+        return super.registerTool(name, spec, implementation);
+    }
+    /**
+     * Retrieves the metadata for all registered tools.
+     */
+    getTools() {
+        return this.storedTools.map((t) => ({
+            name: t.name,
+            description: t.spec.description,
+            inputSchema: t.spec.inputSchema,
+            outputSchema: t.spec.outputSchema,
+        }));
+    }
+    /**
+     * Gets the server's name from its identity.
+     */
+    get name() {
+        return this.serverIdentity.name;
+    }
+    /**
+     * Gets the server's version from its identity.
+     */
+    get version() {
+        return this.serverIdentity.version;
+    }
+    /**
+     * Gets the server's capabilities from its options.
+     */
+    get capabilities() {
+        // The type inference for McpServerOptions is imperfect, so we cast to a
+        // known shape as a pragmatic solution, knowing the property exists at runtime.
+        return this.serverOptions?.capabilities;
+    }
+}
+//# sourceMappingURL=managedMcpServer.js.map

package/dist/mcp-server/core/managedMcpServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedMcpServer.js","sourceRoot":"","sources":["../../../src/mcp-server/core/managedMcpServer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkBpE;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC5B,WAAW,GAAiB,EAAE,CAAC;IAEhC,cAAc,CAAiB;IAC/B,aAAa,CAAoB;IAEjD,YAAY,QAAwB,EAAE,OAA0B;QAC9D,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;IAC/B,CAAC;IAEQ,YAAY,CACnB,IAAY,EACZ,IAAc,EACd,cAAkC;QAElC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,OAAO,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACI,QAAQ;QAMb,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAClC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW;YAC/B,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW;YAC/B,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY;SAClC,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACH,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAW,YAAY;QACrB,wEAAwE;QACxE,+EAA+E;QAC/E,OACE,IAAI,CAAC,aAGN,EAAE,YAAY,CAAC;IAClB,CAAC;CACF"}

package/dist/mcp-server/resources/echoResource/logic.d.ts

@@ -1,7 +1,8 @@
 /**
  * @fileoverview Defines the core logic, schemas, and types for the `echo` resource.
  * @module src/mcp-server/resources/echoResource/logic
- **/
+ * @see {@link src/mcp-server/resources/echoResource/registration.ts} for the handler and registration logic.
+ */
 import { z } from "zod";
 import { type RequestContext } from "../../../utils/index.js";
 /**

package/dist/mcp-server/resources/echoResource/logic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logic.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/logic.ts"],"names":[],"mappings":"AAAA;;;IAGI;AAEJ,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;EAOlC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,2BAA2B,CAAC,CAiCtC"}
+{"version":3,"file":"logic.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/logic.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;EAOlC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,2BAA2B,CAAC,CA2BtC"}

package/dist/mcp-server/resources/echoResource/logic.js

@@ -1,7 +1,8 @@
 /**
  * @fileoverview Defines the core logic, schemas, and types for the `echo` resource.
  * @module src/mcp-server/resources/echoResource/logic
- **/
+ * @see {@link src/mcp-server/resources/echoResource/registration.ts} for the handler and registration logic.
+ */
 import { z } from "zod";
 import { logger } from "../../../utils/index.js";
 /**
@@ -25,22 +26,22 @@ export async function echoResourceLogic(uri, params, context) {
     // For a URI like `echo://my-message?param=1`, `hostname` is `my-message`.
     const messageFromPath = uri.hostname || uri.pathname.replace(/^\/+/g, "");
     const messageToEcho = params.message || messageFromPath || "Default echo message";
-    logger.debug({
+    logger.debug("Processing echo resource logic.", {
         ...context,
         resourceUri: uri.href,
         extractedMessage: messageToEcho,
-    }, "Processing echo resource logic.");
+    });
     const responsePayload = {
         message: messageToEcho,
         timestamp: new Date().toISOString(),
         requestUri: uri.href,
     };
-    logger.debug({
+    logger.debug("Echo resource processed successfully.", {
         ...context,
         responsePayloadSummary: {
             messageLength: responsePayload.message.length,
         },
-    }, "Echo resource processed successfully.");
+    });
     return responsePayload;
 }
 //# sourceMappingURL=logic.js.map

package/dist/mcp-server/resources/echoResource/logic.js.map

@@ -1 +1 @@
-{"version":3,"file":"logic.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/logic.ts"],"names":[],"mappings":"AAAA;;;IAGI;AAEJ,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAuB,MAAM,kBAAkB,CAAC;AAE/D;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iHAAiH,CAClH;CACJ,CAAC,CAAC;AAgBH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAQ,EACR,MAA0B,EAC1B,OAAuB;IAEvB,kEAAkE;IAClE,0EAA0E;IAC1E,MAAM,eAAe,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1E,MAAM,aAAa,GACjB,MAAM,CAAC,OAAO,IAAI,eAAe,IAAI,sBAAsB,CAAC;IAE9D,MAAM,CAAC,KAAK,CACV;QACE,GAAG,OAAO;QACV,WAAW,EAAE,GAAG,CAAC,IAAI;QACrB,gBAAgB,EAAE,aAAa;KAChC,EACD,iCAAiC,CAClC,CAAC;IAEF,MAAM,eAAe,GAAgC;QACnD,OAAO,EAAE,aAAa;QACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,UAAU,EAAE,GAAG,CAAC,IAAI;KACrB,CAAC;IAEF,MAAM,CAAC,KAAK,CACV;QACE,GAAG,OAAO;QACV,sBAAsB,EAAE;YACtB,aAAa,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM;SAC9C;KACF,EACD,uCAAuC,CACxC,CAAC;IAEF,OAAO,eAAe,CAAC;AACzB,CAAC"}
+{"version":3,"file":"logic.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/logic.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAuB,MAAM,yBAAyB,CAAC;AAEtE;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,iHAAiH,CAClH;CACJ,CAAC,CAAC;AAgBH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAQ,EACR,MAA0B,EAC1B,OAAuB;IAEvB,kEAAkE;IAClE,0EAA0E;IAC1E,MAAM,eAAe,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1E,MAAM,aAAa,GACjB,MAAM,CAAC,OAAO,IAAI,eAAe,IAAI,sBAAsB,CAAC;IAE9D,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;QAC9C,GAAG,OAAO;QACV,WAAW,EAAE,GAAG,CAAC,IAAI;QACrB,gBAAgB,EAAE,aAAa;KAChC,CAAC,CAAC;IAEH,MAAM,eAAe,GAAgC;QACnD,OAAO,EAAE,aAAa;QACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,UAAU,EAAE,GAAG,CAAC,IAAI;KACrB,CAAC;IAEF,MAAM,CAAC,KAAK,CAAC,uCAAuC,EAAE;QACpD,GAAG,OAAO;QACV,sBAAsB,EAAE;YACtB,aAAa,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM;SAC9C;KACF,CAAC,CAAC;IAEH,OAAO,eAAe,CAAC;AACzB,CAAC"}

package/dist/mcp-server/resources/echoResource/registration.d.ts

@@ -1,7 +1,13 @@
 /**
  * @fileoverview Handles the registration of the `echo` resource with an MCP server instance.
  * @module src/mcp-server/resources/echoResource/registration.ts
- **/
+ * @see {@link src/mcp-server/resources/echoResource/logic.ts} for the core business logic and schemas.
+ */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'echo' resource and its handlers with the provided MCP server instance.
+ *
+ * @param server - The MCP server instance to register the resource with.
+ */
 export declare const registerEchoResource: (server: McpServer) => Promise<void>;
 //# sourceMappingURL=registration.d.ts.map

package/dist/mcp-server/resources/echoResource/registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/registration.ts"],"names":[],"mappings":"AAAA;;;IAGI;AAEJ,OAAO,EACL,SAAS,EAEV,MAAM,yCAAyC,CAAC;AA+BjD,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,KAChB,OAAO,CAAC,IAAI,CAsDd,CAAC"}
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/registration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,SAAS,EAEV,MAAM,yCAAyC,CAAC;AAcjD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,KAChB,OAAO,CAAC,IAAI,CAgGd,CAAC"}

package/dist/mcp-server/resources/echoResource/registration.js

@@ -1,51 +1,80 @@
 /**
  * @fileoverview Handles the registration of the `echo` resource with an MCP server instance.
  * @module src/mcp-server/resources/echoResource/registration.ts
- **/
+ * @see {@link src/mcp-server/resources/echoResource/logic.ts} for the core business logic and schemas.
+ */
 import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { JsonRpcErrorCode } from "../../../types-global/errors.js";
-import { ErrorHandler, requestContextService, } from "../../../utils/index.js";
-import { logOperationStart, logOperationSuccess, } from "../../../utils/internal/logging-helpers.js";
-import { createResourceHandler, } from "../../resources/utils/resource-utils.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { echoResourceLogic } from "./logic.js";
-const RESOURCE_NAME = "echo-resource";
-const responseFormatter = (result, uri) => ({
-    contents: [
-        {
-            uri: uri.href,
-            mimeType: "application/json",
-            text: JSON.stringify(result),
-        },
-    ],
-});
+/**
+ * Registers the 'echo' resource and its handlers with the provided MCP server instance.
+ *
+ * @param server - The MCP server instance to register the resource with.
+ */
 export const registerEchoResource = async (server) => {
+    const resourceName = "echo-resource";
     const registrationContext = requestContextService.createRequestContext({
         operation: "RegisterResource",
-        resourceName: RESOURCE_NAME,
+        additionalContext: { resourceName },
     });
-    logOperationStart(registrationContext, `Registering resource: '${RESOURCE_NAME}'`);
-    const errorHandler = new ErrorHandler();
-    await errorHandler.tryCatch(async () => {
+    logger.info(`Registering resource: '${resourceName}'`, registrationContext);
+    await ErrorHandler.tryCatch(async () => {
         const template = new ResourceTemplate("echo://{message}", {
-            list: async () => ({
-                resources: [
-                    {
-                        uri: "echo://hello",
-                        name: "Default Echo Message",
-                        description: "A simple echo resource example.",
-                    },
-                ],
-            }),
+            list: async () => {
+                return {
+                    resources: [
+                        {
+                            uri: "echo://hello",
+                            name: "Default Echo Message",
+                            description: "A simple echo resource example.",
+                        },
+                    ],
+                };
+            },
         });
-        server.resource(RESOURCE_NAME, template, {
+        server.resource(resourceName, template, {
             name: "Echo Message Resource",
             description: "A simple echo resource that returns a message.",
             mimeType: "application/json",
             examples: [{ name: "Basic echo", uri: "echo://hello" }],
-        }, createResourceHandler(RESOURCE_NAME, echoResourceLogic, responseFormatter));
-        logOperationSuccess(registrationContext, `Resource '${RESOURCE_NAME}' registered successfully.`);
+        }, async (uri, params, callContext) => {
+            const sessionId = typeof callContext?.sessionId === "string"
+                ? callContext.sessionId
+                : undefined;
+            const handlerContext = requestContextService.createRequestContext({
+                parentContext: callContext,
+                operation: "HandleResourceRead",
+                additionalContext: {
+                    resourceUri: uri.href,
+                    sessionId,
+                    inputParams: params,
+                },
+            });
+            try {
+                const responseData = await echoResourceLogic(uri, params, handlerContext);
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            blob: Buffer.from(JSON.stringify(responseData)).toString("base64"),
+                            mimeType: "application/json",
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                // Re-throw to be caught by the SDK's top-level error handler
+                throw ErrorHandler.handleError(error, {
+                    operation: "echoResourceReadHandler",
+                    context: handlerContext,
+                    input: { uri: uri.href, params },
+                });
+            }
+        });
+        logger.info(`Resource '${resourceName}' registered successfully.`, registrationContext);
     }, {
-        operation: `RegisteringResource_${RESOURCE_NAME}`,
+        operation: `RegisteringResource_${resourceName}`,
         context: registrationContext,
         errorCode: JsonRpcErrorCode.InitializationFailed,
         critical: true,

package/dist/mcp-server/resources/echoResource/registration.js.map

@@ -1 +1 @@
-{"version":3,"file":"registration.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/registration.ts"],"names":[],"mappings":"AAAA;;;IAGI;AAEJ,OAAO,EAEL,gBAAgB,GACjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,YAAY,EAEZ,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,qBAAqB,GAEtB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAA+B,MAAM,YAAY,CAAC;AAE5E,MAAM,aAAa,GAAG,eAAe,CAAC;AAEtC,MAAM,iBAAiB,GAEnB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACpB,QAAQ,EAAE;QACR;YACE,GAAG,EAAE,GAAG,CAAC,IAAI;YACb,QAAQ,EAAE,kBAAkB;YAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B;KACF;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,MAAiB,EACF,EAAE;IACjB,MAAM,mBAAmB,GACvB,qBAAqB,CAAC,oBAAoB,CAAC;QACzC,SAAS,EAAE,kBAAkB;QAC7B,YAAY,EAAE,aAAa;KAC5B,CAAC,CAAC;IAEL,iBAAiB,CACf,mBAAmB,EACnB,0BAA0B,aAAa,GAAG,CAC3C,CAAC;IACF,MAAM,YAAY,GAAG,IAAI,YAAY,EAAE,CAAC;IACxC,MAAM,YAAY,CAAC,QAAQ,CACzB,KAAK,IAAI,EAAE;QACT,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,kBAAkB,EAAE;YACxD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;gBACjB,SAAS,EAAE;oBACT;wBACE,GAAG,EAAE,cAAc;wBACnB,IAAI,EAAE,sBAAsB;wBAC5B,WAAW,EAAE,iCAAiC;qBAC/C;iBACF;aACF,CAAC;SACH,CAAC,CAAC;QAEH,MAAM,CAAC,QAAQ,CACb,aAAa,EACb,QAAQ,EACR;YACE,IAAI,EAAE,uBAAuB;YAC7B,WAAW,EAAE,gDAAgD;YAC7D,QAAQ,EAAE,kBAAkB;YAC5B,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC;SACxD,EACD,qBAAqB,CACnB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,CAClB,CACF,CAAC;QAEF,mBAAmB,CACjB,mBAAmB,EACnB,aAAa,aAAa,4BAA4B,CACvD,CAAC;IACJ,CAAC,EACD;QACE,SAAS,EAAE,uBAAuB,aAAa,EAAE;QACjD,OAAO,EAAE,mBAAmB;QAC5B,SAAS,EAAE,gBAAgB,CAAC,oBAAoB;QAChD,QAAQ,EAAE,IAAI;KACf,CACF,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/echoResource/registration.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/server.d.ts

@@ -13,10 +13,10 @@
  * - Transports: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx
  * @module src/mcp-server/server
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import http from "http";
+import { ManagedMcpServer } from "./core/managedMcpServer.js";
 /**
  * Main application entry point. Initializes and starts the MCP server.
  */
-export declare function initializeAndStartServer(): Promise<McpServer | http.Server>;
+export declare function initializeAndStartServer(): Promise<ManagedMcpServer | http.Server>;
 //# sourceMappingURL=server.d.ts.map

package/dist/mcp-server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,IAAI,MAAM,MAAM,CAAC;AA4FxB;;GAEG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CACvD,SAAS,GAAG,IAAI,CAAC,MAAM,CACxB,CAuBA"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AA+F9D;;GAEG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CACvD,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAC/B,CA6BA"}