mcp-ts-template 1.1.6

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

@@ -0,0 +1,122 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js';
+// Import utils from the main barrel file (ErrorHandler, logger, requestContextService from ../../../utils/internal/*)
+import { ErrorHandler, logger, requestContextService } from '../../../utils/index.js';
+// Import logic, schema, and type from the dedicated logic file
+import { processEchoResource } from './echoResourceLogic.js'; // Removed querySchema import
+// Type inference for UnsubscribeRequest removed as it's not handled
+/**
+ * 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 const registerEchoResource = async (server) => {
+    const resourceName = "echo-resource"; // Internal identifier for the resource
+    // Create registration context using the service
+    const registrationContext = requestContextService.createRequestContext({
+        operation: 'RegisterEchoResource',
+        resourceName: resourceName,
+        module: 'EchoResourceRegistration'
+    });
+    logger.info(`Registering resource: ${resourceName}`, registrationContext);
+    // Use ErrorHandler to wrap the entire registration process for robustness
+    await ErrorHandler.tryCatch(async () => {
+        // Define the resource template structure (URI pattern and basic operations)
+        const template = new ResourceTemplate("echo://{message}", // URI template using RFC 6570 syntax
+        {
+            // --- List Operation ---
+            // Provides a list of example or discoverable resource URIs.
+            list: async () => ({
+                resources: [{
+                        uri: "echo://hello", // Example static URI
+                        name: "Default Echo Message",
+                        description: "A simple echo resource example using a default message."
+                    }]
+            }),
+            // --- Complete Operation ---
+            // (Optional) Provides suggestions or completions based on partial input.
+            // Not implemented for this simple resource.
+        });
+        logger.debug(`Resource template created for ${resourceName}`, registrationContext);
+        // Register the resource, its template, metadata, and handler with the server
+        // This implicitly handles 'resources/read' based on the template match.
+        server.resource(resourceName, // The unique name for this resource registration
+        template, // The ResourceTemplate defined above
+        // --- Resource Metadata ---
+        {
+            name: "Echo Message", // User-friendly name
+            description: "A simple echo resource that returns a message, optionally specified in the URI.",
+            mimeType: "application/json", // Default MIME type for responses
+            // --- Query Schema ---
+            // Removed querySchema as path variable is used via template
+            // --- Examples ---
+            // Provides illustrative examples for clients
+            examples: [
+                {
+                    name: "Basic echo",
+                    uri: "echo://hello",
+                    description: "Get a default welcome message."
+                },
+                {
+                    name: "Custom echo",
+                    uri: "echo://custom-message-here",
+                    description: "Get a response echoing 'custom-message-here'."
+                }
+            ],
+        }, 
+        // --- Resource Handler (for resources/read implicitly) ---
+        // The core logic executed when a request matches the resource template.
+        async (uri, params) => {
+            // Create handler context using the service
+            const handlerContext = requestContextService.createRequestContext({
+                parentContext: registrationContext, // Link to the registration context if needed
+                operation: 'HandleEchoResourceRequest',
+                resourceName: resourceName,
+                uri: uri.href,
+                params: params // Include relevant request details
+            });
+            logger.debug("Handling echo resource request", handlerContext);
+            // Wrap the handler logic in tryCatch for robust error handling
+            return await ErrorHandler.tryCatch(async () => {
+                // Delegate the core processing logic, passing the context
+                const responseData = processEchoResource(uri, params, handlerContext);
+                logger.debug("Echo resource processed successfully", handlerContext);
+                // Return the response in the standardized format expected by the MCP SDK
+                // Correctly omits `type: "text"` as per 2025-03-26 spec
+                return {
+                    contents: [{
+                            uri: uri.href, // Echo back the requested URI
+                            blob: Buffer.from(JSON.stringify(responseData)).toString('base64'), // Return Base64 encoded JSON object
+                            mimeType: "application/json" // Specify the content type
+                        }]
+                };
+            }, {
+                // Configuration for the error handler specific to this request
+                operation: 'processing echo resource handler',
+                context: handlerContext, // Pass handler-specific context
+                input: { uri: uri.href, params }, // Log input on error
+                // Provide a custom error mapping for more specific error reporting
+                errorMapper: (error) => new McpError(// Add type 'unknown' to error parameter
+                BaseErrorCode.INTERNAL_ERROR, // Map internal errors
+                `Error processing echo resource request for URI '${uri.href}': ${error instanceof Error ? error.message : 'Unknown error'}`, { ...handlerContext } // Include context in the McpError
+                )
+            });
+        }); // End of server.resource call
+        logger.info(`Resource registered successfully: ${resourceName}`, registrationContext);
+    }, {
+        // Configuration for the error handler wrapping the entire registration
+        operation: `registering resource ${resourceName}`,
+        context: registrationContext, // Context for registration-level errors
+        errorCode: BaseErrorCode.INTERNAL_ERROR, // Default error code for registration failure
+        // Custom error mapping for registration failures
+        errorMapper: (error) => new McpError(// Add type 'unknown' to error parameter
+        error instanceof McpError ? error.code : BaseErrorCode.INTERNAL_ERROR, `Failed to register resource '${resourceName}': ${error instanceof Error ? error.message : 'Unknown error'}`, { ...registrationContext } // Include context in the McpError
+        ),
+        critical: true // Mark registration failure as critical to halt startup
+    }); // End of ErrorHandler.tryCatch for registration
+};

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

@@ -0,0 +1,27 @@
+/**
+ * Main entry point for the MCP (Model Context Protocol) server.
+ * This file orchestrates the server's lifecycle:
+ * 1. Initializes the core McpServer instance with its identity and capabilities.
+ * 2. Registers available resources and tools, making them discoverable and usable by clients.
+ * 3. Selects and starts the appropriate communication transport (stdio or Streamable HTTP)
+ *    based on configuration.
+ * 4. Handles top-level error management during startup.
+ *
+ * MCP Specification References:
+ * - Lifecycle: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/lifecycle.mdx
+ * - Overview (Capabilities): https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/index.mdx
+ * - Transports: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Main application entry point. Initializes and starts the MCP server.
+ *
+ * MCP Spec Relevance:
+ * - Orchestrates the server startup sequence, culminating in a server ready to accept
+ *   connections and process MCP messages according to the chosen transport's rules.
+ * - Implements top-level error handling for critical startup failures, ensuring the
+ *   process exits appropriately if it cannot initialize correctly.
+ *
+ * @returns {Promise<void | McpServer>} Resolves upon successful startup (void for http, McpServer for stdio). Rejects on critical failure.
+ */
+export declare function initializeAndStartServer(): Promise<void | McpServer>;

package/dist/mcp-server/server.js

@@ -0,0 +1,176 @@
+/**
+ * Main entry point for the MCP (Model Context Protocol) server.
+ * This file orchestrates the server's lifecycle:
+ * 1. Initializes the core McpServer instance with its identity and capabilities.
+ * 2. Registers available resources and tools, making them discoverable and usable by clients.
+ * 3. Selects and starts the appropriate communication transport (stdio or Streamable HTTP)
+ *    based on configuration.
+ * 4. Handles top-level error management during startup.
+ *
+ * MCP Specification References:
+ * - Lifecycle: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/lifecycle.mdx
+ * - Overview (Capabilities): https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/index.mdx
+ * - Transports: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+// Import validated configuration and environment details.
+import { config, environment } from '../config/index.js';
+// Import core utilities: ErrorHandler, logger, requestContextService.
+import { ErrorHandler, logger, requestContextService } from '../utils/index.js';
+// Import registration functions for specific resources and tools.
+import { registerEchoResource } from './resources/echoResource/index.js';
+import { registerEchoTool } from './tools/echoTool/index.js';
+// Import transport setup functions.
+import { startHttpTransport } from './transports/httpTransport.js';
+import { connectStdioTransport } from './transports/stdioTransport.js';
+/**
+ * Creates and configures a new instance of the McpServer.
+ *
+ * This function is central to defining the server's identity and functionality
+ * as presented to connecting clients during the MCP initialization phase.
+ *
+ * MCP Spec Relevance:
+ * - Server Identity (`serverInfo`): The `name` and `version` provided here are part
+ *   of the `ServerInformation` object returned in the `InitializeResult` message,
+ *   allowing clients to identify the server they are connected to.
+ * - Capabilities Declaration: The `capabilities` object declares the features this
+ *   server supports, enabling clients to tailor their interactions.
+ *   - `logging: {}`: Indicates the server can receive `logging/setLevel` requests
+ *     and may send `notifications/message` log messages (handled by the logger utility).
+ *   - `resources: { listChanged: true }`: Signals that the server supports dynamic
+ *     resource lists and will send `notifications/resources/list_changed` if the
+ *     available resources change after initialization.
+ *   - `tools: { listChanged: true }`: Signals support for dynamic tool lists and
+ *     `notifications/tools/list_changed`.
+ * - Resource/Tool Registration: This function calls specific registration functions
+ *   (e.g., `registerEchoResource`) which use SDK methods (`server.resource`, `server.tool`)
+ *   to make capabilities available for discovery (`resources/list`, `tools/list`) and
+ *   invocation (`resources/read`, `tools/call`).
+ *
+ * Design Note: This factory function is used to create server instances. For the 'stdio'
+ * transport, it's called once. For the 'http' transport, it's passed to `startHttpTransport`
+ * and called *per session* to ensure session isolation.
+ *
+ * @returns {Promise<McpServer>} A promise resolving with the configured McpServer instance.
+ * @throws {Error} If any resource or tool registration fails.
+ */
+async function createMcpServerInstance() {
+    const context = { operation: 'createMcpServerInstance' };
+    logger.info('Initializing MCP server instance', context);
+    // Configure the request context service (used for correlating logs/errors).
+    requestContextService.configure({
+        appName: config.mcpServerName,
+        appVersion: config.mcpServerVersion,
+        environment,
+    });
+    // Instantiate the core McpServer using the SDK.
+    // Provide server identity (name, version) and declare supported capabilities.
+    logger.debug('Instantiating McpServer with capabilities', { ...context, serverInfo: { name: config.mcpServerName, version: config.mcpServerVersion }, capabilities: { logging: {}, resources: { listChanged: true }, tools: { listChanged: true } } });
+    const server = new McpServer({ name: config.mcpServerName, version: config.mcpServerVersion }, // ServerInformation part of InitializeResult
+    { capabilities: { logging: {}, resources: { listChanged: true }, tools: { listChanged: true } } } // Declared capabilities
+    );
+    try {
+        // Register all defined resources and tools. These calls populate the server's
+        // internal registry, making them available via MCP methods like 'tools/list'.
+        logger.debug('Registering resources and tools...', context);
+        await registerEchoResource(server); // Example resource registration
+        await registerEchoTool(server); // Example tool registration
+        // Add calls to register other resources/tools here.
+        logger.info('Resources and tools registered successfully', context);
+    }
+    catch (err) {
+        // Registration is critical; log and re-throw errors.
+        logger.error('Failed to register resources/tools', {
+            ...context,
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined, // Include stack for debugging
+        });
+        throw err; // Propagate error to prevent server starting with incomplete capabilities.
+    }
+    return server;
+}
+/**
+ * Selects, sets up, and starts the appropriate MCP transport layer based on configuration.
+ * This function acts as the bridge between the core server logic and the communication channel.
+ *
+ * MCP Spec Relevance:
+ * - Transport Selection: Reads `config.mcpTransportType` ('stdio' or 'http') to determine
+ *   which transport mechanism defined in the MCP specification to use.
+ * - Transport Connection: Calls dedicated functions (`connectStdioTransport` or `startHttpTransport`)
+ *   which handle the specifics of establishing communication according to the chosen
+ *   transport's rules (e.g., stdin/stdout handling for 'stdio', HTTP server setup and
+ *   endpoint handling for 'http').
+ * - Server Instance Lifecycle:
+ *   - For 'stdio', creates a single `McpServer` instance for the lifetime of the process.
+ *   - For 'http', passes the `createMcpServerInstance` factory function to `startHttpTransport`,
+ *     allowing the HTTP transport to create a new, isolated server instance for each client session,
+ *     aligning with the stateful session management described in the Streamable HTTP spec.
+ *
+ * @returns {Promise<McpServer | void>} Resolves with the McpServer instance for 'stdio', or void for 'http'.
+ * @throws {Error} If the configured transport type is unsupported or if transport setup fails.
+ */
+async function startTransport() {
+    // Determine the transport type from the validated configuration.
+    const transportType = config.mcpTransportType;
+    const context = { operation: 'startTransport', transport: transportType };
+    logger.info(`Starting transport: ${transportType}`, context);
+    // --- HTTP Transport Setup ---
+    if (transportType === 'http') {
+        logger.debug('Delegating to startHttpTransport...', context);
+        // For HTTP, the transport layer manages its own lifecycle and potentially multiple sessions.
+        // We pass the factory function to allow the HTTP transport to create server instances as needed (per session).
+        await startHttpTransport(createMcpServerInstance, context);
+        // The HTTP server runs indefinitely, listening for connections, so this function returns void.
+        return;
+    }
+    // --- Stdio Transport Setup ---
+    if (transportType === 'stdio') {
+        logger.debug('Creating single McpServer instance for stdio transport...', context);
+        // For stdio, there's typically one persistent connection managed by a parent process.
+        // Create a single McpServer instance for the entire process lifetime.
+        const server = await createMcpServerInstance();
+        logger.debug('Delegating to connectStdioTransport...', context);
+        // Connect the server instance to the stdio transport handler.
+        await connectStdioTransport(server, context);
+        // Return the server instance; the caller (main entry point) might hold onto it.
+        return server;
+    }
+    // --- Unsupported Transport ---
+    // This case should theoretically not be reached due to config validation, but acts as a safeguard.
+    logger.fatal(`Unsupported transport type configured: ${transportType}`, context);
+    throw new Error(`Unsupported transport type: ${transportType}. Must be 'stdio' or 'http'.`);
+}
+/**
+ * Main application entry point. Initializes and starts the MCP server.
+ *
+ * MCP Spec Relevance:
+ * - Orchestrates the server startup sequence, culminating in a server ready to accept
+ *   connections and process MCP messages according to the chosen transport's rules.
+ * - Implements top-level error handling for critical startup failures, ensuring the
+ *   process exits appropriately if it cannot initialize correctly.
+ *
+ * @returns {Promise<void | McpServer>} Resolves upon successful startup (void for http, McpServer for stdio). Rejects on critical failure.
+ */
+export async function initializeAndStartServer() {
+    const context = { operation: 'initializeAndStartServer' };
+    logger.info('MCP Server initialization sequence started.', context);
+    try {
+        // Initiate the transport setup based on configuration.
+        const result = await startTransport();
+        logger.info('MCP Server initialization sequence completed successfully.', context);
+        return result;
+    }
+    catch (err) {
+        // Catch any errors that occurred during server instance creation or transport setup.
+        logger.fatal('Critical error during MCP server initialization.', {
+            ...context,
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+        // Use the centralized error handler for consistent critical error reporting.
+        ErrorHandler.handleError(err, { ...context, critical: true });
+        // Exit the process with a non-zero code to indicate failure.
+        logger.info('Exiting process due to critical initialization error.', context);
+        process.exit(1);
+    }
+}

package/dist/mcp-server/tools/echoTool/echoToolLogic.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { type RequestContext } from "../../../utils/index.js";
+/**
+ * Defines the valid formatting modes for the echo tool operation.
+ * - `standard`: Echo the message as is.
+ * - `uppercase`: Convert the message to uppercase.
+ * - `lowercase`: Convert the message to lowercase.
+ */
+export declare const ECHO_MODES: readonly ["standard", "uppercase", "lowercase"];
+/**
+ * Zod schema defining the input parameters for the `echo_message` tool.
+ * Includes validation rules and descriptions for each parameter.
+ */
+export declare const EchoToolInputSchema: z.ZodObject<{
+    /** The message to be echoed back. Must be between 1 and 1000 characters. */
+    message: z.ZodString;
+    /** Specifies how the message should be formatted. Defaults to 'standard'. */
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["standard", "uppercase", "lowercase"]>>>;
+    /** The number of times the formatted message should be repeated. Defaults to 1, max 10. */
+    repeat: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    /** Whether to include an ISO 8601 timestamp in the response. Defaults to true. */
+    timestamp: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    repeat: number;
+    message: string;
+    timestamp: boolean;
+    mode: "standard" | "uppercase" | "lowercase";
+}, {
+    message: string;
+    repeat?: number | undefined;
+    timestamp?: boolean | undefined;
+    mode?: "standard" | "uppercase" | "lowercase" | undefined;
+}>;
+/**
+ * TypeScript type inferred from `EchoToolInputSchema`.
+ * Represents the validated input parameters for the echo tool.
+ * @typedef {z.infer<typeof EchoToolInputSchema>} EchoToolInput
+ */
+export type EchoToolInput = z.infer<typeof EchoToolInputSchema>;
+/**
+ * Defines the structure of the JSON payload returned by the `echo_message` tool handler.
+ * This object is JSON-stringified and placed within the `text` field of the
+ * `CallToolResult`'s `content` array.
+ */
+export interface EchoToolResponse {
+    /** The original message provided in the input. */
+    originalMessage: string;
+    /** The message after applying the specified formatting mode. */
+    formattedMessage: string;
+    /** The formatted message repeated the specified number of times, joined by spaces. */
+    repeatedMessage: string;
+    /** The formatting mode that was applied ('standard', 'uppercase', or 'lowercase'). */
+    mode: typeof ECHO_MODES[number];
+    /** The number of times the message was repeated. */
+    repeatCount: number;
+    /** Optional ISO 8601 timestamp indicating when the response was generated. Included if `timestamp` input was true. */
+    timestamp?: string;
+}
+/**
+ * Processes the core logic for the echo tool.
+ * Formats and repeats the message based on the provided parameters.
+ *
+ * @function processEchoMessage
+ * @param {EchoToolInput} params - The validated input parameters for the echo tool.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {EchoToolResponse} The processed response data, including original message, formatted/repeated message, and optional timestamp.
+ */
+export declare const processEchoMessage: (params: EchoToolInput, context: RequestContext) => EchoToolResponse;

package/dist/mcp-server/tools/echoTool/echoToolLogic.js

@@ -0,0 +1,73 @@
+import { z } from 'zod'; // Import z here
+// 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";
+// --- Schema and Type Definitions (Moved from types.ts) ---
+/**
+ * Defines the valid formatting modes for the echo tool operation.
+ * - `standard`: Echo the message as is.
+ * - `uppercase`: Convert the message to uppercase.
+ * - `lowercase`: Convert the message to lowercase.
+ */
+export const ECHO_MODES = ['standard', 'uppercase', 'lowercase'];
+/**
+ * Zod schema defining the input parameters for the `echo_message` tool.
+ * Includes validation rules and descriptions for each parameter.
+ */
+export const EchoToolInputSchema = z.object({
+    /** The message to be echoed back. Must be between 1 and 1000 characters. */
+    message: z.string().min(1, "Message cannot be empty").max(1000, "Message cannot exceed 1000 characters").describe('The message to echo back (1-1000 characters)'),
+    /** Specifies how the message should be formatted. Defaults to 'standard'. */
+    mode: z.enum(ECHO_MODES).optional().default('standard').describe('How to format the echoed message: standard (as-is), uppercase, or lowercase'),
+    /** The number of times the formatted message should be repeated. Defaults to 1, max 10. */
+    repeat: z.number().int().min(1).max(10).optional().default(1).describe('Number of times to repeat the message (1-10)'),
+    /** Whether to include an ISO 8601 timestamp in the response. Defaults to true. */
+    timestamp: z.boolean().optional().default(true).describe('Whether to include a timestamp in the response')
+}).describe('Defines the input arguments for the echo_message tool.');
+// --- Core Logic Function ---
+/**
+ * Processes the core logic for the echo tool.
+ * Formats and repeats the message based on the provided parameters.
+ *
+ * @function processEchoMessage
+ * @param {EchoToolInput} params - The validated input parameters for the echo tool.
+ * @param {RequestContext} context - The request context for logging and tracing.
+ * @returns {EchoToolResponse} The processed response data, including original message, formatted/repeated message, and optional timestamp.
+ */
+export const processEchoMessage = (params, context // Add context parameter
+) => {
+    // Use the passed context for logging
+    logger.debug("Processing echo message logic", { ...context, inputMessage: params.message, mode: params.mode });
+    // Process the message according to the requested mode
+    let formattedMessage = params.message;
+    switch (params.mode) {
+        case 'uppercase':
+            formattedMessage = params.message.toUpperCase();
+            break;
+        case 'lowercase':
+            formattedMessage = params.message.toLowerCase();
+            break;
+        // 'standard' mode keeps the message as-is
+    }
+    // Repeat the message the specified number of times, ensuring it's within bounds
+    // Default repeat value is handled by the Zod schema
+    const safeRepeatCount = Math.min(params.repeat, 10);
+    const repeatedMessage = Array(safeRepeatCount)
+        .fill(formattedMessage)
+        .join(' ');
+    // Prepare the response data using the imported EchoToolResponse type
+    const response = {
+        originalMessage: params.message,
+        formattedMessage,
+        repeatedMessage,
+        // Default mode value is handled by the Zod schema
+        mode: params.mode,
+        repeatCount: safeRepeatCount
+    };
+    // Add timestamp if requested (default is true based on schema)
+    if (params.timestamp !== false) {
+        response.timestamp = new Date().toISOString();
+    }
+    // Use the passed context for logging the result
+    logger.debug("Echo message processed successfully", { ...context, response });
+    return response;
+};

package/dist/mcp-server/tools/echoTool/index.d.ts

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

package/dist/mcp-server/tools/echoTool/index.js

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

package/dist/mcp-server/tools/echoTool/registration.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the 'echo_message' tool and its handler with the provided MCP server instance.
+ * Defines the tool's input schema, description, and the core request handling logic.
+ * Error handling is integrated using ErrorHandler. (Asynchronous)
+ *
+ * @function registerEchoTool
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ * @returns {Promise<void>} A promise that resolves when the tool registration is complete.
+ * @throws {McpError} Throws an McpError if the registration process fails critically.
+ */
+export declare const registerEchoTool: (server: McpServer) => Promise<void>;

package/dist/mcp-server/tools/echoTool/registration.js

@@ -0,0 +1,86 @@
+// Import schema and types from the logic file
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+// Import utils from the main barrel file (ErrorHandler, logger, requestContextService from ../../../utils/internal/*)
+import { ErrorHandler, logger, requestContextService } from "../../../utils/index.js";
+import { EchoToolInputSchema } from './echoToolLogic.js'; // Schema needed for shape extraction
+// Import the core logic function
+import { processEchoMessage } from './echoToolLogic.js';
+/**
+ * Registers the 'echo_message' tool and its handler with the provided MCP server instance.
+ * Defines the tool's input schema, description, and the core request handling logic.
+ * Error handling is integrated using ErrorHandler. (Asynchronous)
+ *
+ * @function registerEchoTool
+ * @param {McpServer} server - The MCP server instance to register the tool with.
+ * @returns {Promise<void>} A promise that resolves when the tool registration is complete.
+ * @throws {McpError} Throws an McpError if the registration process fails critically.
+ */
+export const registerEchoTool = async (server) => {
+    const toolName = "echo_message"; // The unique identifier for the tool
+    const toolDescription = "Echoes a message back with optional formatting and repetition."; // Tool description
+    // Create registration context using the service
+    const registrationContext = requestContextService.createRequestContext({
+        operation: 'RegisterEchoTool',
+        toolName: toolName,
+        module: 'EchoToolRegistration'
+    });
+    logger.info(`Registering tool: ${toolName}`, registrationContext);
+    // Use ErrorHandler to wrap the entire registration process
+    await ErrorHandler.tryCatch(async () => {
+        // Register the tool using the 4-argument server.tool() overload (SDK v1.10.2+)
+        server.tool(toolName, toolDescription, // Argument 2: Tool Description
+        // --- Tool Input Schema (Raw Shape) ---
+        // Pass the raw shape of the Zod schema. The SDK uses this for validation.
+        EchoToolInputSchema.shape, // Argument 3: Schema Shape
+        // --- Tool Handler ---
+        // The core logic executed when the tool is called.
+        // Params are automatically validated against the provided schema shape by the SDK.
+        async (params) => {
+            // Create handler context using the service
+            const handlerContext = requestContextService.createRequestContext({
+                parentContext: registrationContext, // Link to registration context
+                operation: 'HandleEchoToolRequest',
+                toolName: toolName,
+                params: params // Include relevant request details
+            });
+            logger.debug("Handling echo tool request", handlerContext);
+            // Wrap the handler logic in tryCatch for robust error handling
+            return await ErrorHandler.tryCatch(async () => {
+                // Delegate the core processing logic, passing the context
+                const response = processEchoMessage(params, handlerContext);
+                logger.debug("Echo tool processed successfully", handlerContext);
+                // Return the response in the standard MCP tool result format
+                // as required by the SDK's server.tool method signature.
+                return {
+                    content: [{
+                            type: "text", // Content type is text
+                            // The actual content is a JSON string representing the EchoToolResponse
+                            text: JSON.stringify(response, null, 2)
+                        }],
+                    isError: false // Explicitly set isError to false for successful execution
+                };
+            }, {
+                // Configuration for the error handler specific to this tool call
+                operation: 'processing echo message handler',
+                context: handlerContext, // Pass handler-specific context
+                input: params, // Log input parameters on error
+                // Provide a custom error mapping for more specific error reporting
+                errorMapper: (error) => new McpError(// Add type 'unknown' to error parameter
+                // Use VALIDATION_ERROR if the error likely stems from processing invalid (though schema-valid) input
+                error instanceof McpError ? error.code : BaseErrorCode.INTERNAL_ERROR, `Error processing echo message tool: ${error instanceof Error ? error.message : 'Unknown error'}`, { ...handlerContext } // Include context in the McpError
+                )
+            });
+        }); // End of server.tool call
+        logger.info(`Tool registered successfully: ${toolName}`, registrationContext);
+    }, {
+        // Configuration for the error handler wrapping the entire registration
+        operation: `registering tool ${toolName}`,
+        context: registrationContext, // Context for registration-level errors
+        errorCode: BaseErrorCode.INTERNAL_ERROR, // Default error code for registration failure
+        // Custom error mapping for registration failures
+        errorMapper: (error) => new McpError(// Add type 'unknown' to error parameter
+        error instanceof McpError ? error.code : BaseErrorCode.INTERNAL_ERROR, `Failed to register tool '${toolName}': ${error instanceof Error ? error.message : 'Unknown error'}`, { ...registrationContext } // Include context in the McpError
+        ),
+        critical: true // Mark registration failure as critical to halt startup
+    }); // End of ErrorHandler.tryCatch for registration
+};

package/dist/mcp-server/transports/authentication/authMiddleware.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MCP Authentication Middleware: Bearer Token Validation (JWT).
+ *
+ * This middleware validates JSON Web Tokens (JWT) passed via the 'Authorization' header
+ * using the 'Bearer' scheme (e.g., "Authorization: Bearer <your_token>").
+ * It verifies the token's signature and expiration using the secret key defined
+ * in the configuration (MCP_AUTH_SECRET_KEY).
+ *
+ * If the token is valid, the decoded payload is attached to `req.auth` for potential
+ * use in downstream authorization logic (e.g., checking scopes or permissions).
+ * If the token is missing, invalid, or expired, it sends an HTTP 401 Unauthorized response.
+ *
+ * --- Scope and Relation to MCP Authorization Spec (2025-03-26) ---
+ * - This middleware handles the *validation* of an already obtained Bearer token,
+ *   as required by Section 2.6 of the MCP Auth Spec.
+ * - It does *NOT* implement the full OAuth 2.1 authorization flows (e.g., Authorization
+ *   Code Grant with PKCE), token endpoints (/token), authorization endpoints (/authorize),
+ *   metadata discovery (/.well-known/oauth-authorization-server), or dynamic client
+ *   registration (/register) described in the specification. It assumes the client
+ *   obtained the JWT through an external process compliant with the spec or another
+ *   agreed-upon mechanism.
+ * - It correctly returns HTTP 401 errors for invalid/missing tokens as per Section 2.8.
+ *
+ * --- Implementation Details & Requirements ---
+ * - Requires the 'jsonwebtoken' package (`npm install jsonwebtoken @types/jsonwebtoken`).
+ * - The `MCP_AUTH_SECRET_KEY` environment variable MUST be set to a strong, secret value
+ *   in production. The middleware includes a startup check for this.
+ * - In non-production environments, if the secret key is missing, authentication checks
+ *   are bypassed for development convenience (a warning is logged). THIS IS INSECURE FOR PRODUCTION.
+ * - The structure of the JWT payload (e.g., containing user ID, scopes) depends on the
+ *   token issuer and is not dictated by this middleware itself, but the payload is made
+ *   available on `req.auth`.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ */
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+declare global {
+    namespace Express {
+        interface Request {
+            /** Decoded JWT payload if authentication is successful, or a development mode indicator. */
+            auth?: jwt.JwtPayload | string | {
+                devMode: boolean;
+                warning: string;
+            };
+        }
+    }
+}
+/**
+ * Express middleware function for verifying JWT Bearer token authentication.
+ * Checks the `Authorization` header, verifies the token, and attaches the payload to `req.auth`.
+ *
+ * @param {Request} req - Express request object.
+ * @param {Response} res - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
+ */
+export declare function mcpAuthMiddleware(req: Request, res: Response, next: NextFunction): void;