mcp-ts-template 1.1.6

package/dist/mcp-client/configLoader.js

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+// Import utils from the main barrel file (logger, RequestContext, requestContextService from ../utils/internal/*)
+import { logger, requestContextService, } from "../utils/index.js";
+// Import local McpError and BaseErrorCode
+import { BaseErrorCode, McpError } from "../types-global/errors.js";
+// --- Zod Schemas for Configuration Validation ---
+// Ensures the configuration structure adheres to expected formats.
+// Schema for environment variables passed to the server process (optional).
+// Allows defining specific environment variables for each server.
+const EnvSchema = z
+    .record(z.string())
+    .optional()
+    .describe("Optional key-value pairs for environment variables specific to the server process.");
+// Schema for a single MCP server configuration entry within the main config file.
+const McpServerConfigEntrySchema = z.object({
+    // The command or script used to launch the MCP server process (e.g., 'node', '/path/to/server.py').
+    // For HTTP transport, this field typically holds the base URL of the server.
+    command: z
+        .string()
+        .min(1, "Server command or HTTP base URL cannot be empty"),
+    // Arguments to pass to the server command (only applicable for stdio transport).
+    args: z.array(z.string()).default([]),
+    // Optional environment variables specific to this server process (merged with client's env).
+    env: EnvSchema,
+    // Specifies the communication method (stdio or http). Defaults to 'stdio'.
+    transportType: z.enum(["stdio", "http"]).default("stdio"),
+    // Optional fields for future use:
+    // 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)."),
+});
+// Schema for the root structure of the mcp-config.json file.
+// Expects a top-level key 'mcpServers' containing a map of server names to their configurations.
+const McpClientConfigFileSchema = z.object({
+    mcpServers: z.record(McpServerConfigEntrySchema),
+});
+// --- Configuration Loading Logic ---
+// Determine the directory of the current module to locate config files reliably.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Define paths for the primary configuration file and the example fallback.
+const primaryConfigPath = join(__dirname, "mcp-config.json");
+const exampleConfigPath = join(__dirname, "mcp-config.json.example");
+// Cache for the loaded configuration to avoid redundant file I/O and parsing.
+let loadedConfig = null;
+// Track which configuration file was successfully loaded (primary or example).
+let loadedConfigPath = null;
+/**
+ * Loads, validates, and caches the MCP client configuration.
+ * It first attempts to load from `mcp-config.json`. If that file doesn't exist
+ * or fails to read, it falls back to loading `mcp-config.json.example`.
+ * The loaded content is then parsed as JSON and validated against the Zod schema.
+ *
+ * @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, parsed, or validated successfully.
+ */
+export function loadMcpClientConfig(parentContext) {
+    const context = requestContextService.createRequestContext({
+        ...(parentContext ?? {}),
+        operation: "loadMcpClientConfig",
+    });
+    // --- Return Cached Config (if available) ---
+    if (loadedConfig && loadedConfigPath) {
+        logger.debug(`Returning cached MCP client config from: ${loadedConfigPath}`, context);
+        return loadedConfig;
+    }
+    let fileContent = null;
+    let configPathToLog = ""; // Store the path of the file being processed for logging
+    // --- 1. Attempt to Load Primary Config File ---
+    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),
+            });
+            // Error reading primary file, proceed to fallback.
+        }
+    }
+    else {
+        logger.info(`Primary config file not found at ${primaryConfigPath}, attempting fallback.`, {
+            ...context,
+            filePath: primaryConfigPath,
+        });
+        // Primary file doesn't exist, proceed to fallback.
+    }
+    // --- 2. Attempt to Load Example Config File (if primary failed) ---
+    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) {
+                // If reading the example file also fails, it's a critical error.
+                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 {
+            // If neither file exists, it's a critical error.
+            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}.`);
+        }
+    }
+    // --- 3. Parse and Validate JSON Content ---
+    try {
+        // Parse the raw file content into a JavaScript object.
+        const parsedJson = JSON.parse(fileContent);
+        // Validate the parsed object against the defined Zod schema.
+        const validationResult = McpClientConfigFileSchema.safeParse(parsedJson);
+        if (!validationResult.success) {
+            // Validation failed; log the specific Zod errors.
+            logger.error("MCP client configuration validation failed.", {
+                ...context,
+                filePath: configPathToLog,
+                errors: validationResult.error.errors, // Detailed Zod error info
+            });
+            // Format Zod errors into a user-friendly message.
+            const errorMessages = validationResult.error.errors
+                .map((e) => `${e.path.join(".")}: ${e.message}`)
+                .join("; ");
+            throw new Error(`Validation failed: ${errorMessages}`); // Throw standard Error to be caught below
+        }
+        // --- Validation Successful ---
+        // Cache the validated configuration and the path it was loaded from.
+        loadedConfig = validationResult.data;
+        loadedConfigPath = configPathToLog;
+        logger.info(`MCP client configuration loaded and validated successfully from: ${loadedConfigPath}`, {
+            ...context,
+            serversFound: Object.keys(loadedConfig.mcpServers).length,
+        });
+        // Return the validated configuration.
+        return loadedConfig;
+    }
+    catch (error) {
+        // Catch errors from JSON.parse or the Zod validation failure.
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error("Failed to parse or validate MCP client configuration", {
+            ...context,
+            filePath: configPathToLog,
+            error: errorMessage,
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        // Throw a specific McpError indicating a configuration problem.
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Failed to load/validate MCP client config from ${configPathToLog}: ${errorMessage}`, { originalError: error });
+    }
+}
+/**
+ * Retrieves the configuration entry for a specific MCP server by its name.
+ * Ensures the main configuration is loaded (using the cached version if available)
+ * before attempting to access the specific server's details.
+ *
+ * @param serverName - The name identifier of the server (key in the 'mcpServers' map).
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A copy of the configuration entry for the specified server.
+ * @throws McpError if the configuration hasn't been loaded or the server name is not found within the loaded config.
+ */
+export function getMcpServerConfig(serverName, parentContext) {
+    const context = requestContextService.createRequestContext({
+        ...(parentContext ?? {}),
+        operation: "getMcpServerConfig",
+        targetServer: serverName,
+    });
+    // Ensure the main config is loaded (uses cache or loads/validates).
+    const config = loadMcpClientConfig(context);
+    // Get the path from where the config was loaded for logging clarity.
+    const configPath = loadedConfigPath || "unknown";
+    // Attempt to retrieve the specific server's configuration.
+    const serverConfig = config.mcpServers[serverName];
+    if (!serverConfig) {
+        // If the server name doesn't exist as a key in the config.
+        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}.`);
+    }
+    logger.debug(`Retrieved configuration for server "${serverName}" from ${configPath}`, context);
+    // Return a shallow copy to prevent accidental modification of the cached configuration object.
+    return { ...serverConfig };
+}

package/dist/mcp-client/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Barrel file for the MCP Client module (`src/mcp-client`).
+ * This file re-exports the primary functions and types related to creating,
+ * configuring, connecting, and managing MCP client instances based on the
+ * MCP 2025-03-26 specification and the high-level TypeScript SDK.
+ */
+export { connectMcpClient, disconnectAllMcpClients, disconnectMcpClient, type ConnectedMcpClient, } from "./client.js";
+export { getMcpServerConfig, loadMcpClientConfig, type McpServerConfigEntry, // Export the type for a single server's config
+type McpClientConfigFile, } from "./configLoader.js";
+export { createStdioClientTransport, getClientTransport } from "./transport.js";

package/dist/mcp-client/index.js

@@ -0,0 +1,14 @@
+/**
+ * Barrel file for the MCP Client module (`src/mcp-client`).
+ * This file re-exports the primary functions and types related to creating,
+ * configuring, connecting, and managing MCP client instances based on the
+ * MCP 2025-03-26 specification and the high-level TypeScript SDK.
+ */
+// Export core client connection management functions and the connected client type alias.
+export { connectMcpClient, disconnectAllMcpClients, disconnectMcpClient, } from "./client.js";
+// Export configuration loading functions and related types.
+// These handle reading and validating server connection details from `mcp-config.json`.
+export { getMcpServerConfig, loadMcpClientConfig, } from "./configLoader.js";
+// Export transport creation functions.
+// `getClientTransport` acts as a factory based on the server's configured `transportType`.
+export { createStdioClientTransport, getClientTransport } from "./transport.js";

package/dist/mcp-client/transport.d.ts

@@ -0,0 +1,34 @@
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { RequestContext } from "../utils/index.js";
+/**
+ * Configuration options specifically required for creating a StdioClientTransport.
+ * This includes the command to execute, arguments, and optional environment variables.
+ */
+interface StdioTransportConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Creates and configures a StdioClientTransport instance for launching and communicating
+ * with an MCP server process via standard input/output.
+ *
+ * @param transportConfig - Configuration containing the command, args, and env for the server process.
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A configured StdioClientTransport instance ready to be connected.
+ * @throws McpError if the provided configuration is invalid or if the transport fails to initialize.
+ */
+export declare function createStdioClientTransport(transportConfig: StdioTransportConfig, parentContext?: RequestContext | null): StdioClientTransport;
+/**
+ * Retrieves the server configuration and creates the appropriate client transport
+ * (Stdio or HTTP) based on the `transportType` specified in the configuration.
+ * This acts as a factory function for obtaining the correct transport instance.
+ *
+ * @param serverName - The name of the MCP server (key in mcp-config.json).
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A configured transport instance (either StdioClientTransport or StreamableHTTPClientTransport).
+ * @throws McpError if configuration is missing, invalid, specifies an unsupported transport type, or if transport creation fails.
+ */
+export declare function getClientTransport(serverName: string, parentContext?: RequestContext | null): StdioClientTransport | StreamableHTTPClientTransport;
+export {};

package/dist/mcp-client/transport.js

@@ -0,0 +1,183 @@
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; // Corrected Import HTTP transport name
+// Import utils from the main barrel file (logger, RequestContext, requestContextService from ../utils/internal/*)
+import { BaseErrorCode, McpError } from "../types-global/errors.js";
+import { logger, requestContextService, } from "../utils/index.js";
+import { getMcpServerConfig } from "./configLoader.js";
+/**
+ * Creates and configures a StdioClientTransport instance for launching and communicating
+ * with an MCP server process via standard input/output.
+ *
+ * @param transportConfig - Configuration containing the command, args, and env for the server process.
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A configured StdioClientTransport instance ready to be connected.
+ * @throws McpError if the provided configuration is invalid or if the transport fails to initialize.
+ */
+export function createStdioClientTransport(transportConfig, parentContext) {
+    const baseContext = parentContext ? { ...parentContext } : {};
+    const context = requestContextService.createRequestContext({
+        ...baseContext,
+        operation: "createStdioClientTransport",
+        transportType: "stdio",
+        command: transportConfig.command,
+    });
+    logger.debug("Creating StdioClientTransport", context);
+    // --- Input Validation ---
+    if (!transportConfig.command || typeof transportConfig.command !== "string") {
+        logger.error("Invalid command provided for StdioClientTransport", context);
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "Invalid command for StdioClientTransport", context);
+    }
+    if (!Array.isArray(transportConfig.args)) {
+        logger.error("Invalid args provided for StdioClientTransport (must be an array)", context);
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "Invalid args for StdioClientTransport (must be an array)", context);
+    }
+    try {
+        // --- Environment Merging ---
+        // Combine the client's current environment with server-specific variables from the config.
+        // Server-specific variables take precedence.
+        // Filter out undefined values from process.env to avoid potential issues.
+        const filteredProcessEnv = {};
+        for (const key in process.env) {
+            if (Object.prototype.hasOwnProperty.call(process.env, key) &&
+                process.env[key] !== undefined) {
+                filteredProcessEnv[key] = process.env[key];
+            }
+        }
+        const mergedEnv = {
+            ...filteredProcessEnv, // Start with client's environment
+            ...(transportConfig.env || {}), // Override/add server-specific env vars
+        };
+        logger.debug("Creating StdioClientTransport with merged environment", {
+            ...context,
+            envKeys: Object.keys(mergedEnv).length, // Log count for brevity
+        });
+        // --- Instantiate Transport ---
+        // Create the transport instance, passing the command, args, and merged environment.
+        const transport = new StdioClientTransport({
+            command: transportConfig.command,
+            args: transportConfig.args,
+            env: mergedEnv,
+        });
+        logger.info("StdioClientTransport created successfully", context);
+        return transport;
+    }
+    catch (error) {
+        // Catch errors during transport instantiation (e.g., invalid command path).
+        logger.error("Failed to create StdioClientTransport", {
+            ...context,
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        // Re-throw as a specific McpError for consistent error handling.
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, // Could potentially be CONFIGURATION_ERROR if command is invalid
+        `Failed to create StdioClientTransport: ${error instanceof Error ? error.message : String(error)}`, { originalError: error, ...context });
+    }
+}
+/**
+ * Retrieves the server configuration and creates the appropriate client transport
+ * (Stdio or HTTP) based on the `transportType` specified in the configuration.
+ * This acts as a factory function for obtaining the correct transport instance.
+ *
+ * @param serverName - The name of the MCP server (key in mcp-config.json).
+ * @param parentContext - Optional parent request context for logging.
+ * @returns A configured transport instance (either StdioClientTransport or StreamableHTTPClientTransport).
+ * @throws McpError if configuration is missing, invalid, specifies an unsupported transport type, or if transport creation fails.
+ */
+export function getClientTransport(serverName, parentContext) {
+    const baseContext = parentContext ? { ...parentContext } : {};
+    const context = requestContextService.createRequestContext({
+        ...baseContext,
+        operation: "getClientTransport",
+        targetServer: serverName,
+    });
+    logger.info(`Getting transport for server: ${serverName}`, context);
+    try {
+        // --- 1. Load Server Configuration ---
+        // Retrieve the validated configuration for the specified server.
+        const serverConfig = getMcpServerConfig(serverName, context);
+        // --- 2. Determine and Create Transport ---
+        const transportType = serverConfig.transportType; // Already defaulted to 'stdio' by config loader if missing
+        logger.info(`Selected transport type "${transportType}" for server: ${serverName}`, { ...context, transportType });
+        if (transportType === "stdio") {
+            // --- Create Stdio Transport ---
+            logger.info(`Creating stdio transport for server: ${serverName}`, {
+                ...context,
+                command: serverConfig.command,
+                args: serverConfig.args,
+                envProvided: !!serverConfig.env,
+            });
+            // Delegate to the dedicated stdio creation function.
+            return createStdioClientTransport({
+                command: serverConfig.command,
+                args: serverConfig.args,
+                env: serverConfig.env, // Pass validated env config
+            }, context);
+        }
+        else if (transportType === "http") {
+            // --- Create HTTP Transport ---
+            // For HTTP, the 'command' field in the config is interpreted as the base URL.
+            const baseUrl = serverConfig.command;
+            // Validate that the command field looks like a URL for HTTP transport.
+            if (!baseUrl ||
+                typeof baseUrl !== "string" ||
+                !baseUrl.startsWith("http")) {
+                const httpConfigError = `Invalid configuration for HTTP transport server "${serverName}": The 'command' field must be a valid base URL (e.g., "http://localhost:3001"). Found: "${baseUrl}"`;
+                logger.error(httpConfigError, context);
+                throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, httpConfigError, context);
+            }
+            logger.info(`Creating HTTP transport for server: ${serverName} with base URL: ${baseUrl}`, context);
+            try {
+                // Instantiate the StreamableHTTPClientTransport using the base URL.
+                // The SDK handles constructing the full /mcp endpoint path.
+                // IMPORTANT: Authentication headers (e.g., Authorization: Bearer <token>)
+                // need to be added here or via client options if required by the server,
+                // following the MCP Authentication Specification.
+                const transportOptions = {
+                // Example: Adding authentication headers if needed
+                // headers: {
+                //   'Authorization': `Bearer ${getAuthTokenForServer(serverName)}`
+                // }
+                };
+                const transport = new StreamableHTTPClientTransport(new URL(baseUrl), transportOptions // Pass options if needed
+                );
+                logger.info(`StreamableHTTPClientTransport created successfully for ${serverName}`, context);
+                return transport;
+            }
+            catch (error) {
+                // Catch errors during HTTP transport instantiation (e.g., invalid URL format).
+                logger.error(`Failed to create StreamableHttpClientTransport for ${serverName}`, {
+                    ...context,
+                    baseUrl: baseUrl,
+                    error: error instanceof Error ? error.message : String(error),
+                    stack: error instanceof Error ? error.stack : undefined,
+                });
+                throw new McpError(BaseErrorCode.INTERNAL_ERROR, // Or CONFIGURATION_ERROR if URL is invalid
+                `Failed to create HTTP transport for ${serverName}: ${error instanceof Error ? error.message : String(error)}`, { originalError: error, ...context });
+            }
+        }
+        else {
+            // --- Unsupported Transport Type ---
+            // This path should ideally not be reachable due to Zod validation in the config loader.
+            const unsupportedErrorMessage = `Unsupported transportType "${serverConfig.transportType}" configured for server "${serverName}".`;
+            logger.error(unsupportedErrorMessage, context);
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, unsupportedErrorMessage, context);
+        }
+    }
+    catch (error) {
+        // Catch errors from config loading or transport creation steps.
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to get or create transport for server "${serverName}"`, {
+            ...context,
+            error: errorMessage,
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        // Ensure a consistent McpError is thrown.
+        if (error instanceof McpError) {
+            throw error;
+        }
+        else {
+            // Assume configuration error if not already an McpError
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, `Failed to initialize transport for ${serverName}: ${errorMessage}`, { originalError: error });
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { type RequestContext } from '../../../utils/index.js';
+/**
+ * Zod schema defining the expected *query* parameters for the echo resource.
+ * Note: Path parameters (like '{message}' in 'echo://{message}') are defined
+ * in the ResourceTemplate and are typically extracted directly from the URI path,
+ * not validated by this schema. This schema focuses on optional or additional
+ * parameters passed via the query string (e.g., ?param=value).
+ * Used for validation and type inference of query parameters.
+ */
+export declare const querySchema: z.ZodObject<{
+    /** Optional message to be echoed back in the response. */
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message?: string | undefined;
+}, {
+    message?: string | undefined;
+}>;
+/**
+ * TypeScript type inferred from the `querySchema`. Represents the validated query parameters.
+ * @typedef {z.infer<typeof querySchema>} EchoParams
+ */
+export type EchoParams = z.infer<typeof querySchema>;
+/**
+ * Processes the core logic for the echo resource request.
+ * Takes the request URI and validated parameters, then constructs the response data.
+ *
+ * @function processEchoResource
+ * @param {URL} uri - The full URI of the incoming resource request.
+ * @param {EchoParams} params - The validated query parameters for the request.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {EchoResourceResponse} The data payload for the response (will be JSON-stringified by the handler).
+ */
+export declare const processEchoResource: (uri: URL, params: EchoParams, context: RequestContext) => {
+    message: string;
+    timestamp: string;
+    requestUri: string;
+};

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+// Import utils from the main barrel file (logger from ../../../utils/internal/logger.js, RequestContext from ../../../utils/internal/requestContext.js)
+import { logger } from '../../../utils/index.js';
+/**
+ * Zod schema defining the expected *query* parameters for the echo resource.
+ * Note: Path parameters (like '{message}' in 'echo://{message}') are defined
+ * in the ResourceTemplate and are typically extracted directly from the URI path,
+ * not validated by this schema. This schema focuses on optional or additional
+ * parameters passed via the query string (e.g., ?param=value).
+ * Used for validation and type inference of query parameters.
+ */
+export const querySchema = z.object({
+    /** Optional message to be echoed back in the response. */
+    message: z.string().optional()
+        .describe('Message to echo back in the response')
+});
+/**
+ * Processes the core logic for the echo resource request.
+ * Takes the request URI and validated parameters, then constructs the response data.
+ *
+ * @function processEchoResource
+ * @param {URL} uri - The full URI of the incoming resource request.
+ * @param {EchoParams} params - The validated query parameters for the request.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {EchoResourceResponse} The data payload for the response (will be JSON-stringified by the handler).
+ */
+export const processEchoResource = (uri, params, context // Add context parameter
+) => {
+    // The 'message' parameter is guaranteed by the ResourceTemplate match "echo://{message}"
+    // Use the value directly from the params object populated by the SDK.
+    const message = params.message || 'Default message if somehow empty'; // Added fallback just in case, though template should ensure it exists.
+    // Use the passed context for logging
+    logger.debug("Processing echo resource logic", { ...context, message });
+    // Prepare response data including timestamp and original URI
+    return {
+        message,
+        timestamp: new Date().toISOString(),
+        requestUri: uri.href
+    };
+};

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

@@ -0,0 +1,5 @@
+/**
+ * Barrel file for the echo resource.
+ * Exports the registration function.
+ */
+export { registerEchoResource } from './registration.js';

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

@@ -0,0 +1,5 @@
+/**
+ * Barrel file for the echo resource.
+ * Exports the registration function.
+ */
+export { registerEchoResource } from './registration.js';

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

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'echo' resource and its handlers with the provided MCP server instance.
+ * This includes defining the resource template, metadata, query schema, examples,
+ * and the core request handling logic. Error handling is integrated using ErrorHandler.
+ *
+ * @function registerEchoResource
+ * @param {McpServer} server - The MCP server instance to register the resource with.
+ * @returns {Promise<void>} A promise that resolves when the resource registration is complete.
+ * @throws {McpError} Throws an McpError if the registration process fails critically.
+ */
+export declare const registerEchoResource: (server: McpServer) => Promise<void>;