mcp-ts-template 1.5.0 → 1.5.1

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.12.1-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.12.3-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--03--26-lightgrey.svg)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/changelog.mdx)
-[![Version](https://img.shields.io/badge/Version-1.5.0-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.5.1-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)
@@ -59,9 +59,9 @@ _Note: [**toolkit-mcp-server**](https://github.com/cyanheads/toolkit-mcp-server)
 
 You can also **see my [GitHub profile](https://github.com/cyanheads/)** for additional MCP servers I've created, many of which are planned to be migrated to or built upon this template in the future.
 
-## 🏁 Quick Start
+## 📦 Installation
 
-Get the example server running in minutes:
+This project is a template, but can also directly be run as an MCP server. To get started, follow these steps:
 
 1.  **Clone the repository:**
 
@@ -77,31 +77,44 @@ Get the example server running in minutes:
     ```
 
 3.  **Build the project:**
-
     ```bash
     npm run build
-    # Or use 'npm run rebuild' for a clean install (deletes node_modules, logs, dist)
+    # Or use 'npm run rebuild' for a clean install
     ```
 
-4.  **Format the code (Optional but Recommended):**
+## 🚀 Usage
 
-    ```bash
-    npm run format
-    ```
+Once built, you can run the server. If you intend to publish your project as a package, you can test the `npx` command by linking it locally.
+
+### Using NPX
+To run the MCP server directly using `npx`, you can use the following command:
+
+```bash
+
+Now you can run it via `npx`:
+
+```bash
+# Run with default stdio transport
+npx mcp-ts-template
 
-5.  **Run the Example Server:**
+# Run with HTTP transport
+MCP_TRANSPORT_TYPE=http npx mcp-ts-template
+```
+
+### From Source (for Development)
 
-    - **Via Stdio (Default):** Many MCP host applications will run this automatically using `stdio`.
-      To run manually for testing:
-      ```bash
-      npm start
-      # or 'npm run start:stdio'
-      ```
-    - **Via Streamable HTTP:**
-      ```bash
-      npm run start:http
-      ```
-      This starts a **Streamable HTTP** server (default: `http://127.0.0.1:3010`) which uses Server-Sent Events for the server-to-client streaming component. The port, host, and allowed origins are configurable via environment variables (see [Configuration](#configuration)).
+You can also use the npm scripts to run the server directly from your cloned repository:
+
+-   **Via Stdio (Default):**
+    ```bash
+    npm start
+    # or 'npm run start:stdio'
+    ```
+-   **Via Streamable HTTP:**
+    ```bash
+    npm run start:http
+    ```
+This starts a **Streamable HTTP** server (default: `http://127.0.0.1:3010`) which uses Server-Sent Events for the server-to-client streaming component. The port, host, and allowed origins are configurable via environment variables (see [Configuration](#configuration)).
 
 ## ⚙️ Configuration
 
@@ -142,6 +155,28 @@ You **MUST** configure one of these modes for the security mechanism to function
 
 For detailed information on configuring the built-in **MCP client**, including how to set up connections to external MCP servers using `mcp-config.json`, please see the [Client Configuration Guide](src/mcp-client/client-config/README.md).
 
+#### Example: Adding to an MCP Client
+
+To add this server to an MCP client application (like [Claude Desktop](https://github.com/cyanheads/claude-desktop)), you would update the client's configuration file. This example assumes you have published your package or have used `npm link` to make it available locally.
+
+```json
+{
+  "mcpServers": {
+    "mcp-ts-template": {
+      "command": "npx",
+      "args": ["mcp-ts-template"],
+      "env": {
+        "MCP_LOG_LEVEL": "debug",
+        "MCP_TRANSPORT_TYPE": "http",
+        "MCP_HTTP_PORT": "3010"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
 ## 🏗️ Project Structure
 
 This project follows a standard TypeScript project layout. Here's an overview of the key directories and files:

package/dist/index.js

@@ -51,71 +51,47 @@ const shutdown = async (signal) => {
         triggerEvent: signal,
     });
     logger.info(`Received ${signal}. Initiating graceful shutdown...`, 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 if (mcpClosed && httpClosed) {
-            logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
-            process.exit(0);
-        }
-    };
+    const shutdownPromises = [];
     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();
-        });
-    }
-    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.", {
+        const serverToClose = mcpStdioServer;
+        shutdownPromises.push(new Promise((resolve) => {
+            logger.info("Closing main MCP server (STDIO)...", shutdownContext);
+            serverToClose
+                .close()
+                .then(() => {
+                logger.info("Main MCP server (STDIO) closed successfully.", shutdownContext);
+                resolve();
+            })
+                .catch((err) => {
+                logger.error("Error closing MCP server (STDIO).", {
                     ...shutdownContext,
                     error: err,
                 });
-                if (!closeError)
-                    closeError = err;
-            }
-            else {
-                logger.info("HTTP server closed successfully.", shutdownContext);
-            }
-            httpClosed = true;
-            checkAndExit();
-        });
-    }
-    else {
-        httpClosed = true; // No HTTP server to close
+                resolve(); // Resolve even on error to not block shutdown
+            });
+        }));
     }
-    // Initial check in case no servers needed closing
-    if (mcpClosed && httpClosed) {
-        checkAndExit();
+    if (actualHttpServer) {
+        const serverToClose = actualHttpServer;
+        shutdownPromises.push(new Promise((resolve) => {
+            logger.info("Closing HTTP server...", shutdownContext);
+            serverToClose.close((err) => {
+                if (err) {
+                    logger.error("Error closing HTTP server.", {
+                        ...shutdownContext,
+                        error: err,
+                    });
+                }
+                else {
+                    logger.info("HTTP server closed successfully.", shutdownContext);
+                }
+                resolve(); // Resolve regardless of error
+            });
+        }));
     }
+    await Promise.allSettled(shutdownPromises);
+    logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
+    process.exit(0);
 };
 /**
  * Initializes and starts the main MCP server application.

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

@@ -2,32 +2,14 @@
  * @fileoverview Defines the core logic, schemas, and types for the `echo` resource.
  * This module includes a Zod schema for query parameter validation, type definitions,
  * and the main processing function that constructs the resource response.
- * The echo resource is designed to return a message, typically extracted from the
- * request URI's path or query parameters, along with a timestamp.
  * @module src/mcp-server/resources/echoResource/echoResourceLogic
  */
 import { z } from "zod";
 import { type RequestContext } from "../../../utils/index.js";
 /**
  * Zod schema defining expected query parameters for the echo resource.
- *
- * This schema is intended for validating parameters passed via the URI's query string
- * (e.g., `echo://some_message?message=override_from_query&anotherParam=value`).
- * Path parameters, such as `{message}` in a template like `echo://{message}`,
- * are typically defined in the `ResourceTemplate` (see `registration.ts`) and
- * extracted by the MCP SDK from the URI path. The SDK merges these path
- * parameters into the `params` object passed to the handler.
- *
- * If a path parameter and a query parameter share the same name (e.g., 'message'),
- * the query parameter will take precedence over the path parameter. This schema
- * defines `message` as an optional query parameter.
  */
 export declare const EchoResourceQuerySchema: z.ZodObject<{
-    /**
-     * Optional message to be echoed back in the response.
-     * If the resource template also defines a 'message' path parameter,
-     * this query parameter will override the path parameter's value if both are present.
-     */
     message: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     message?: string | undefined;
@@ -36,44 +18,21 @@ export declare const EchoResourceQuerySchema: z.ZodObject<{
 }>;
 /**
  * TypeScript type inferred from the {@link EchoResourceQuerySchema}.
- * Represents the validated query parameters that might be passed to the echo resource.
  */
 export type EchoResourceParams = z.infer<typeof EchoResourceQuerySchema>;
 /**
  * Defines the structure of the JSON payload returned by the `processEchoResource` function.
- * This object is typically JSON-stringified by the resource handler before being sent
- * as the resource content.
- *
- * @property message - The message that is being echoed. This could be from a path parameter,
- *   a query parameter (which takes precedence), or a default value.
- * @property timestamp - An ISO 8601 timestamp indicating when the response was generated.
- * @property requestUri - The full URI of the original resource request.
  */
 export interface EchoResourceResponsePayload {
-    /** The message that is being echoed. */
     message: string;
-    /** An ISO 8601 timestamp indicating when the response was generated. */
     timestamp: string;
-    /** The full URI of the original resource request. */
     requestUri: string;
 }
 /**
  * Processes the core logic for an echo resource request.
- * It constructs a response payload containing a message (derived from path or query parameters),
- * the current timestamp, and the original request URI.
- *
- * The `params` argument is expected to contain validated query parameters. If the resource
- * template (e.g., `echo://{message}`) includes path parameters, the MCP SDK extracts
- * them and merges them into the `params` object. If a query parameter shares the same
- * name as a path parameter, the query parameter's value takes precedence. This function
- * assumes `params.message` will hold the definitive message.
- *
  * @param uri - The full URL object of the incoming resource request.
  * @param params - The validated query parameters for the request.
- *   This object also includes path parameters merged by the SDK, with query parameters
- *   taking precedence in case of name conflicts.
  * @param context - The request context, used for logging and tracing the operation.
  * @returns The data payload for the response.
- *   This payload is typically JSON-stringified by the calling handler.
  */
-export declare const processEchoResource: (uri: URL, params: EchoResourceParams, context: RequestContext) => EchoResourceResponsePayload;
+export declare function echoResourceLogic(uri: URL, params: EchoResourceParams, context: RequestContext): Promise<EchoResourceResponsePayload>;

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

@@ -2,32 +2,14 @@
  * @fileoverview Defines the core logic, schemas, and types for the `echo` resource.
  * This module includes a Zod schema for query parameter validation, type definitions,
  * and the main processing function that constructs the resource response.
- * The echo resource is designed to return a message, typically extracted from the
- * request URI's path or query parameters, along with a timestamp.
  * @module src/mcp-server/resources/echoResource/echoResourceLogic
  */
 import { z } from "zod";
 import { logger } from "../../../utils/index.js";
 /**
  * Zod schema defining expected query parameters for the echo resource.
- *
- * This schema is intended for validating parameters passed via the URI's query string
- * (e.g., `echo://some_message?message=override_from_query&anotherParam=value`).
- * Path parameters, such as `{message}` in a template like `echo://{message}`,
- * are typically defined in the `ResourceTemplate` (see `registration.ts`) and
- * extracted by the MCP SDK from the URI path. The SDK merges these path
- * parameters into the `params` object passed to the handler.
- *
- * If a path parameter and a query parameter share the same name (e.g., 'message'),
- * the query parameter will take precedence over the path parameter. This schema
- * defines `message` as an optional query parameter.
  */
 export const EchoResourceQuerySchema = z.object({
-    /**
-     * Optional message to be echoed back in the response.
-     * If the resource template also defines a 'message' path parameter,
-     * this query parameter will override the path parameter's value if both are present.
-     */
     message: z
         .string()
         .optional()
@@ -35,34 +17,20 @@ export const EchoResourceQuerySchema = z.object({
 });
 /**
  * Processes the core logic for an echo resource request.
- * It constructs a response payload containing a message (derived from path or query parameters),
- * the current timestamp, and the original request URI.
- *
- * The `params` argument is expected to contain validated query parameters. If the resource
- * template (e.g., `echo://{message}`) includes path parameters, the MCP SDK extracts
- * them and merges them into the `params` object. If a query parameter shares the same
- * name as a path parameter, the query parameter's value takes precedence. This function
- * assumes `params.message` will hold the definitive message.
- *
  * @param uri - The full URL object of the incoming resource request.
  * @param params - The validated query parameters for the request.
- *   This object also includes path parameters merged by the SDK, with query parameters
- *   taking precedence in case of name conflicts.
  * @param context - The request context, used for logging and tracing the operation.
  * @returns The data payload for the response.
- *   This payload is typically JSON-stringified by the calling handler.
  */
-export const processEchoResource = (uri, params, context) => {
-    // The `params.message` can originate from a query parameter (validated by `EchoResourceQuerySchema`)
-    // or a path parameter (e.g., from a template like `echo://{message_from_path}`).
-    // The MCP SDK merges these, with query parameters taking precedence over path parameters if names conflict.
-    // The fallback "Default message..." is a safeguard if no message is provided via path or query.
-    const messageToEcho = params.message || `Default echo from ${uri.pathname}`;
+export async function echoResourceLogic(uri, params, context) {
+    // The message can come from a query parameter or the path itself.
+    // 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("Processing echo resource logic.", {
         ...context,
         resourceUri: uri.href,
         extractedMessage: messageToEcho,
-        queryParamMessage: params.message,
     });
     const responsePayload = {
         message: messageToEcho,
@@ -73,10 +41,7 @@ export const processEchoResource = (uri, params, context) => {
         ...context,
         responsePayloadSummary: {
             messageLength: responsePayload.message.length,
-            uriEchoed: responsePayload.requestUri.length > 50
-                ? `${responsePayload.requestUri.substring(0, 47)}...`
-                : responsePayload.requestUri,
         },
     });
     return responsePayload;
-};
+}

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

@@ -1,30 +1,14 @@
 /**
  * @fileoverview Handles the registration of the `echo` resource with an MCP server instance.
- * This module defines the resource's template (URI structure), metadata (name, description, examples),
- * and the asynchronous handler function that processes `resources/read` requests matching the template.
- * It utilizes the MCP SDK's `server.resource()` method for registration and integrates
- * robust error handling using the project's `ErrorHandler` utility.
+ * This module defines the resource's template, metadata, and the asynchronous handler
+ * that processes `resources/read` requests.
  * @module src/mcp-server/resources/echoResource/registration
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * Registers the 'echo' resource and its handlers with the provided MCP server instance.
  *
- * This function defines:
- * 1.  The resource template (e.g., `echo://{message}`), which determines the URI structure.
- *     The `{message}` part is a path variable.
- * 2.  A `list` operation for the template to provide example/discoverable URIs.
- * 3.  Metadata for the resource, including its user-friendly name, description, MIME type,
- *     and example URIs.
- * 4.  The core asynchronous handler logic for `resources/read` requests that match the template.
- *     This handler processes the request and returns the resource content.
- *
- * Error handling is integrated throughout using `ErrorHandler.tryCatch` for robustness.
- *
  * @param server - The MCP server instance to register the resource with.
- * @returns A promise that resolves when the resource registration is complete. It does not return a value upon successful completion.
- * @throws {McpError} If the registration process fails critically, which might halt server startup.
- * @see {@link EchoResourceParams} for the type of parameters passed to the handler.
- * @see {@link processEchoResource} for the core resource logic.
+ * @returns A promise that resolves when the resource registration is complete.
  */
 export declare const registerEchoResource: (server: McpServer) => Promise<void>;

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

@@ -1,128 +1,54 @@
 /**
  * @fileoverview Handles the registration of the `echo` resource with an MCP server instance.
- * This module defines the resource's template (URI structure), metadata (name, description, examples),
- * and the asynchronous handler function that processes `resources/read` requests matching the template.
- * It utilizes the MCP SDK's `server.resource()` method for registration and integrates
- * robust error handling using the project's `ErrorHandler` utility.
+ * This module defines the resource's template, metadata, and the asynchronous handler
+ * that processes `resources/read` requests.
  * @module src/mcp-server/resources/echoResource/registration
  */
 import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
-import { processEchoResource, } from "./echoResourceLogic.js";
+import { echoResourceLogic, } from "./echoResourceLogic.js";
 /**
  * Registers the 'echo' resource and its handlers with the provided MCP server instance.
  *
- * This function defines:
- * 1.  The resource template (e.g., `echo://{message}`), which determines the URI structure.
- *     The `{message}` part is a path variable.
- * 2.  A `list` operation for the template to provide example/discoverable URIs.
- * 3.  Metadata for the resource, including its user-friendly name, description, MIME type,
- *     and example URIs.
- * 4.  The core asynchronous handler logic for `resources/read` requests that match the template.
- *     This handler processes the request and returns the resource content.
- *
- * Error handling is integrated throughout using `ErrorHandler.tryCatch` for robustness.
- *
  * @param server - The MCP server instance to register the resource with.
- * @returns A promise that resolves when the resource registration is complete. It does not return a value upon successful completion.
- * @throws {McpError} If the registration process fails critically, which might halt server startup.
- * @see {@link EchoResourceParams} for the type of parameters passed to the handler.
- * @see {@link processEchoResource} for the core resource logic.
+ * @returns A promise that resolves when the resource registration is complete.
  */
 export const registerEchoResource = async (server) => {
-    const resourceName = "echo-resource"; // Internal identifier for this resource registration.
+    const resourceName = "echo-resource";
     const registrationContext = requestContextService.createRequestContext({
         operation: "RegisterResource",
         resourceName: resourceName,
-        moduleName: "EchoResourceRegistration",
     });
-    logger.info(`Attempting to register resource: '${resourceName}'`, registrationContext);
+    logger.info(`Registering resource: '${resourceName}'`, registrationContext);
     await ErrorHandler.tryCatch(async () => {
-        // Define the resource template. This specifies the URI structure and supported operations.
-        // The URI `echo://{message}` uses RFC 6570 syntax, where `{message}` is a path variable.
         const template = new ResourceTemplate("echo://{message}", {
-            /**
-             * Asynchronous handler for the `resources/list` operation associated with this template.
-             * It provides a list of example or discoverable resource URIs that match this template.
-             * This allows clients to discover how to interact with the echo resource.
-             *
-             * @returns A promise resolving to an object containing an array of resource descriptors.
-             */
             list: async () => {
-                const listContext = requestContextService.createRequestContext({
-                    parentContext: registrationContext,
-                    operation: "ListEchoResourceExamples",
-                });
-                logger.debug("Executing list operation for echo resource template.", listContext);
-                // Return a static list of example URIs.
                 return {
                     resources: [
                         {
                             uri: "echo://hello",
                             name: "Default Echo Message",
-                            description: "A simple echo resource example using a default message.",
+                            description: "A simple echo resource example.",
                         },
-                        // Add more examples as needed
                     ],
-                    // nextCursor could be used here if the list were paginated.
                 };
             },
-            // The `complete` operation (for URI completion suggestions) is optional and not implemented here.
         });
-        logger.debug(`Resource template created for '${resourceName}': ${template.uriTemplate}`, registrationContext);
-        // Register the resource with the server.
-        // This involves providing the registration name, the template, metadata, and the handler for read operations.
         server.resource(resourceName, template, {
             name: "Echo Message Resource",
-            description: "A simple echo resource that returns a message, optionally specified in the URI path.",
+            description: "A simple echo resource that returns a message.",
             mimeType: "application/json",
-            examples: [
-                {
-                    name: "Basic echo",
-                    uri: "echo://hello",
-                    description: "Accesses the echo resource to echo the message 'hello'.",
-                },
-                {
-                    name: "Custom echo",
-                    uri: "echo://custom-message-here",
-                    description: "Accesses the echo resource to echo 'custom-message-here'.",
-                },
-            ],
-        }, 
-        /**
-         * Asynchronous handler for `resources/read` requests matching the `echo://{message}` template.
-         * This function is invoked by the MCP SDK when a client requests to read a resource
-         * whose URI matches the registered template.
-         *
-         * The SDK extracts path variables (like `{message}` from `echo://{message}`) from the URI.
-         * These path variables, along with any validated query parameters, are passed in the `params` object.
-         *
-         * @param uri - The full URL object of the resource being requested.
-         * @param params - An object containing parameters derived from the request.
-         *   For this resource, it's expected to include `message` extracted from the URI
-         *   path by the SDK. It conforms to {@link EchoResourceParams}.
-         * @returns A promise that resolves with the resource content, formatted as a `ReadResourceResult`.
-         *   This includes the URI, Base64 encoded content blob, and MIME type.
-         *   If an error is thrown from this handler, the SDK is responsible for catching it and
-         *   formatting an error response.
-         */
-        async (uri, params) => {
+            examples: [{ name: "Basic echo", uri: "echo://hello" }],
+        }, async (uri, params) => {
             const handlerContext = requestContextService.createRequestContext({
-                parentContext: registrationContext,
+                parentRequestId: registrationContext.requestId,
                 operation: "HandleResourceRead",
-                resourceName: resourceName,
                 resourceUri: uri.href,
-                inputParamsSummary: params.message
-                    ? { messageLength: params.message.length }
-                    : { noMessageParam: true },
+                inputParams: params,
             });
-            logger.debug(`Handling read request for resource '${resourceName}', URI: ${uri.href}`, handlerContext);
-            return await ErrorHandler.tryCatch(async () => {
-                const responseData = processEchoResource(uri, params, handlerContext);
-                logger.debug(`'${resourceName}' (URI: ${uri.href}) processed successfully. Preparing content.`, handlerContext);
-                // Construct the `ReadResourceResult` as expected by the MCP SDK.
-                // The content (blob) must be Base64 encoded.
+            try {
+                const responseData = await echoResourceLogic(uri, params, handlerContext);
                 return {
                     contents: [
                         {
@@ -132,37 +58,22 @@ export const registerEchoResource = async (server) => {
                         },
                     ],
                 };
-            }, {
-                operation: `ExecutingCoreLogicFor_${resourceName}_Read`,
-                context: handlerContext,
-                input: { uri: uri.href, params },
-                errorMapper: (error) => {
-                    const baseErrorCode = error instanceof McpError
-                        ? error.code
-                        : BaseErrorCode.INTERNAL_ERROR;
-                    const errorMessage = `Error processing read request for resource '${uri.href}': ${error instanceof Error ? error.message : "An unknown error occurred"}`;
-                    return new McpError(baseErrorCode, errorMessage, {
-                        ...handlerContext,
-                        originalErrorName: error instanceof Error ? error.name : typeof error,
-                    });
-                },
-            });
+            }
+            catch (error) {
+                const handledError = ErrorHandler.handleError(error, {
+                    operation: "echoResourceReadHandler",
+                    context: handlerContext,
+                    input: { uri: uri.href, params },
+                });
+                // Re-throw to be caught by the SDK's top-level error handler
+                throw handledError;
+            }
         });
-        logger.info(`Resource '${resourceName}' (template: '${template.uriTemplate}') registered successfully.`, registrationContext);
+        logger.info(`Resource '${resourceName}' registered successfully.`, registrationContext);
     }, {
         operation: `RegisteringResource_${resourceName}`,
         context: registrationContext,
         errorCode: BaseErrorCode.INITIALIZATION_FAILED,
-        errorMapper: (error) => {
-            const errorMessage = `Failed to register resource '${resourceName}': ${error instanceof Error ? error.message : "An unknown error occurred during registration."}`;
-            const code = error instanceof McpError
-                ? error.code
-                : BaseErrorCode.INITIALIZATION_FAILED;
-            return new McpError(code, errorMessage, {
-                ...registrationContext,
-                originalErrorName: error instanceof Error ? error.name : typeof error,
-            });
-        },
         critical: true,
     });
 };

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

@@ -17,13 +17,5 @@ import { ServerType } from "@hono/node-server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * Main application entry point. Initializes and starts the MCP server.
- * Orchestrates server startup, transport selection, and top-level error handling.
- *
- * MCP Spec Relevance:
- * - Manages server startup, leading to a server ready for MCP messages.
- * - Handles critical startup failures, ensuring appropriate process exit.
- *
- * @returns For 'stdio', resolves with `McpServer`. For 'http', resolves with `http.Server`.
- *   Rejects on critical failure, leading to process exit.
  */
 export declare function initializeAndStartServer(): Promise<void | McpServer | ServerType>;