@cyanheads/pubmed-mcp-server 1.0.12

package/dist/config/index.js

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview Loads, validates, and exports application configuration.
+ * This module centralizes configuration management, sourcing values from
+ * environment variables and `package.json`. It uses Zod for schema validation
+ * to ensure type safety and correctness of configuration parameters.
+ *
+ * Key responsibilities:
+ * - Load environment variables from a `.env` file.
+ * - Read `package.json` for default server name and version.
+ * - Define a Zod schema for all expected environment variables.
+ * - Validate environment variables against the schema.
+ * - Construct and export a comprehensive `config` object.
+ * - Export individual configuration values like `logLevel` and `environment` for convenience.
+ *
+ * @module src/config/index
+ */
+import dotenv from "dotenv";
+import { existsSync, mkdirSync, readFileSync, statSync } from "fs";
+import path, { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+dotenv.config();
+// --- Determine Project Root ---
+/**
+ * Finds the project root directory by searching upwards for package.json.
+ * @param startDir The directory to start searching from.
+ * @returns The absolute path to the project root, or throws an error if not found.
+ */
+const findProjectRoot = (startDir) => {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            // Reached the root of the filesystem without finding package.json
+            throw new Error(`Could not find project root (package.json) starting from ${startDir}`);
+        }
+        currentDir = parentDir;
+    }
+};
+let projectRoot;
+try {
+    // For ESM, __dirname is not available directly.
+    // import.meta.url gives the URL of the current module.
+    const currentModuleDir = dirname(fileURLToPath(import.meta.url));
+    projectRoot = findProjectRoot(currentModuleDir);
+}
+catch (error) {
+    console.error(`FATAL: Error determining project root: ${error.message}`);
+    // Fallback to process.cwd() if project root cannot be determined.
+    // This might happen in unusual execution environments.
+    projectRoot = process.cwd();
+    console.warn(`Warning: Using process.cwd() (${projectRoot}) as fallback project root.`);
+}
+// --- End Determine Project Root ---
+const pkgPath = join(projectRoot, "package.json"); // Use determined projectRoot
+let pkg = { name: "mcp-ts-template", version: "0.0.0" };
+try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+}
+catch (error) {
+    if (process.stdout.isTTY) {
+        console.error("Warning: Could not read package.json for default config values. Using hardcoded defaults.", error);
+    }
+}
+/**
+ * Zod schema for validating environment variables.
+ * Provides type safety, validation, defaults, and clear error messages.
+ * @private
+ */
+const EnvSchema = z.object({
+    /** Optional. The desired name for the MCP server. Defaults to `package.json` name. */
+    MCP_SERVER_NAME: z.string().optional(),
+    /** Optional. The version of the MCP server. Defaults to `package.json` version. */
+    MCP_SERVER_VERSION: z.string().optional(),
+    /** Minimum logging level. See `McpLogLevel` in logger utility. Default: "debug". */
+    MCP_LOG_LEVEL: z.string().default("debug"),
+    /** Directory for log files. Defaults to "logs" in project root. */
+    LOGS_DIR: z.string().default(path.join(projectRoot, "logs")),
+    /** Runtime environment (e.g., "development", "production"). Default: "development". */
+    NODE_ENV: z.string().default("development"),
+    /** MCP communication transport ("stdio" or "http"). Default: "stdio". */
+    MCP_TRANSPORT_TYPE: z.enum(["stdio", "http"]).default("stdio"),
+    /** HTTP server port (if MCP_TRANSPORT_TYPE is "http"). Default: 3010. */
+    MCP_HTTP_PORT: z.coerce.number().int().positive().default(3010),
+    /** HTTP server host (if MCP_TRANSPORT_TYPE is "http"). Default: "127.0.0.1". */
+    MCP_HTTP_HOST: z.string().default("127.0.0.1"),
+    /** Optional. Comma-separated allowed origins for CORS (HTTP transport). */
+    MCP_ALLOWED_ORIGINS: z.string().optional(),
+    /** Optional. Secret key (min 32 chars) for auth tokens (HTTP transport). CRITICAL for production. */
+    MCP_AUTH_SECRET_KEY: z
+        .string()
+        .min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long for security reasons.")
+        .optional(),
+    /** Optional. Application URL for OpenRouter integration. */
+    OPENROUTER_APP_URL: z
+        .string()
+        .url("OPENROUTER_APP_URL must be a valid URL (e.g., http://localhost:3000)")
+        .optional(),
+    /** Optional. Application name for OpenRouter. Defaults to MCP_SERVER_NAME or package name. */
+    OPENROUTER_APP_NAME: z.string().optional(),
+    /** Optional. API key for OpenRouter services. */
+    OPENROUTER_API_KEY: z.string().optional(),
+    /** Default LLM model. Default: "google/gemini-2.5-flash-preview:thinking". */
+    LLM_DEFAULT_MODEL: z
+        .string()
+        .default("google/gemini-2.5-flash-preview-05-20"),
+    /** Optional. Default LLM temperature (0.0-2.0). */
+    LLM_DEFAULT_TEMPERATURE: z.coerce.number().min(0).max(2).optional(),
+    /** Optional. Default LLM top_p (0.0-1.0). */
+    LLM_DEFAULT_TOP_P: z.coerce.number().min(0).max(1).optional(),
+    /** Optional. Default LLM max tokens (positive integer). */
+    LLM_DEFAULT_MAX_TOKENS: z.coerce.number().int().positive().optional(),
+    /** Optional. Default LLM top_k (non-negative integer). */
+    LLM_DEFAULT_TOP_K: z.coerce.number().int().nonnegative().optional(),
+    /** Optional. Default LLM min_p (0.0-1.0). */
+    LLM_DEFAULT_MIN_P: z.coerce.number().min(0).max(1).optional(),
+    /** Optional. API key for Google Gemini services. */
+    GEMINI_API_KEY: z.string().optional(),
+    /** Optional. OAuth provider authorization endpoint URL. */
+    OAUTH_PROXY_AUTHORIZATION_URL: z
+        .string()
+        .url("OAUTH_PROXY_AUTHORIZATION_URL must be a valid URL.")
+        .optional(),
+    /** Optional. OAuth provider token endpoint URL. */
+    OAUTH_PROXY_TOKEN_URL: z
+        .string()
+        .url("OAUTH_PROXY_TOKEN_URL must be a valid URL.")
+        .optional(),
+    /** Optional. OAuth provider revocation endpoint URL. */
+    OAUTH_PROXY_REVOCATION_URL: z
+        .string()
+        .url("OAUTH_PROXY_REVOCATION_URL must be a valid URL.")
+        .optional(),
+    /** Optional. OAuth provider issuer URL. */
+    OAUTH_PROXY_ISSUER_URL: z
+        .string()
+        .url("OAUTH_PROXY_ISSUER_URL must be a valid URL.")
+        .optional(),
+    /** Optional. OAuth service documentation URL. */
+    OAUTH_PROXY_SERVICE_DOCUMENTATION_URL: z
+        .string()
+        .url("OAUTH_PROXY_SERVICE_DOCUMENTATION_URL must be a valid URL.")
+        .optional(),
+    /** Optional. Comma-separated default OAuth client redirect URIs. */
+    OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS: z.string().optional(),
+    // NCBI E-utilities Configuration
+    /** NCBI API Key. Optional, but highly recommended for higher rate limits. */
+    NCBI_API_KEY: z.string().optional(),
+    /** Tool identifier sent to NCBI. Defaults to MCP_SERVER_NAME/MCP_SERVER_VERSION. */
+    NCBI_TOOL_IDENTIFIER: z.string().optional(),
+    /** Administrator's email for NCBI contact. Optional, but recommended if using an API key. */
+    NCBI_ADMIN_EMAIL: z
+        .string()
+        .email("NCBI_ADMIN_EMAIL must be a valid email address.")
+        .optional(),
+    /** Milliseconds to wait between NCBI requests. Default: 100 (for API key), 334 (without API key). */
+    NCBI_REQUEST_DELAY_MS: z.coerce.number().int().positive().optional(), // Default will be set conditionally
+    /** Maximum number of retries for failed NCBI requests. Default: 3. */
+    NCBI_MAX_RETRIES: z.coerce.number().int().nonnegative().default(3),
+});
+const parsedEnv = EnvSchema.safeParse(process.env);
+if (!parsedEnv.success) {
+    if (process.stdout.isTTY) {
+        console.error("❌ Invalid environment variables found:", parsedEnv.error.flatten().fieldErrors);
+    }
+    // Consider throwing an error in production for critical misconfigurations.
+}
+const env = parsedEnv.success ? parsedEnv.data : EnvSchema.parse({});
+// --- Directory Ensurance Function ---
+/**
+ * Ensures a directory exists and is within the project root.
+ * @param dirPath The desired path for the directory (can be relative or absolute).
+ * @param rootDir The root directory of the project to contain the directory.
+ * @param dirName The name of the directory type for logging (e.g., "logs").
+ * @returns The validated, absolute path to the directory, or null if invalid.
+ */
+const ensureDirectory = (dirPath, rootDir, dirName) => {
+    const resolvedDirPath = path.isAbsolute(dirPath)
+        ? dirPath
+        : path.resolve(rootDir, dirPath);
+    // Ensure the resolved path is within the project root boundary
+    if (!resolvedDirPath.startsWith(rootDir + path.sep) &&
+        resolvedDirPath !== rootDir) {
+        if (process.stdout.isTTY) {
+            console.error(`Error: ${dirName} path "${dirPath}" resolves to "${resolvedDirPath}", which is outside the project boundary "${rootDir}".`);
+        }
+        return null;
+    }
+    if (!existsSync(resolvedDirPath)) {
+        try {
+            mkdirSync(resolvedDirPath, { recursive: true });
+            if (process.stdout.isTTY) {
+                console.log(`Created ${dirName} directory: ${resolvedDirPath}`);
+            }
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            if (process.stdout.isTTY) {
+                console.error(`Error creating ${dirName} directory at ${resolvedDirPath}: ${errorMessage}`);
+            }
+            return null;
+        }
+    }
+    else {
+        try {
+            const stats = statSync(resolvedDirPath);
+            if (!stats.isDirectory()) {
+                if (process.stdout.isTTY) {
+                    console.error(`Error: ${dirName} path ${resolvedDirPath} exists but is not a directory.`);
+                }
+                return null;
+            }
+        }
+        catch (statError) {
+            if (process.stdout.isTTY) {
+                console.error(`Error accessing ${dirName} path ${resolvedDirPath}: ${statError.message}`);
+            }
+            return null;
+        }
+    }
+    return resolvedDirPath;
+};
+// --- End Directory Ensurance Function ---
+// --- Logs Directory Handling ---
+const validatedLogsPath = ensureDirectory(env.LOGS_DIR, projectRoot, "logs");
+if (!validatedLogsPath) {
+    if (process.stdout.isTTY) {
+        console.error("FATAL: Logs directory configuration is invalid or could not be created. Please check permissions and path. Exiting.");
+    }
+    process.exit(1); // Exit if logs directory is not usable
+}
+// --- End Logs Directory Handling ---
+/**
+ * Main application configuration object.
+ * Aggregates settings from validated environment variables and `package.json`.
+ */
+export const config = {
+    /** MCP server name. Env `MCP_SERVER_NAME` > `package.json` name > "mcp-ts-template". */
+    mcpServerName: env.MCP_SERVER_NAME || pkg.name,
+    /** MCP server version. Env `MCP_SERVER_VERSION` > `package.json` version > "0.0.0". */
+    mcpServerVersion: env.MCP_SERVER_VERSION || pkg.version,
+    /** Logging level. From `MCP_LOG_LEVEL` env var. Default: "debug". */
+    logLevel: env.MCP_LOG_LEVEL,
+    /** Absolute path to the logs directory. From `LOGS_DIR` env var. */
+    logsPath: validatedLogsPath,
+    /** Runtime environment. From `NODE_ENV` env var. Default: "development". */
+    environment: env.NODE_ENV,
+    /** MCP transport type ('stdio' or 'http'). From `MCP_TRANSPORT_TYPE` env var. Default: "stdio". */
+    mcpTransportType: env.MCP_TRANSPORT_TYPE,
+    /** HTTP server port (if http transport). From `MCP_HTTP_PORT` env var. Default: 3010. */
+    mcpHttpPort: env.MCP_HTTP_PORT,
+    /** HTTP server host (if http transport). From `MCP_HTTP_HOST` env var. Default: "127.0.0.1". */
+    mcpHttpHost: env.MCP_HTTP_HOST,
+    /** Array of allowed CORS origins (http transport). From `MCP_ALLOWED_ORIGINS` (comma-separated). */
+    mcpAllowedOrigins: env.MCP_ALLOWED_ORIGINS?.split(",")
+        .map((origin) => origin.trim())
+        .filter(Boolean),
+    /** Auth secret key (JWTs, http transport). From `MCP_AUTH_SECRET_KEY`. CRITICAL. */
+    mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
+    /** OpenRouter App URL. From `OPENROUTER_APP_URL`. Default: "http://localhost:3000". */
+    openrouterAppUrl: env.OPENROUTER_APP_URL || "http://localhost:3000",
+    /** OpenRouter App Name. From `OPENROUTER_APP_NAME`. Defaults to `mcpServerName`. */
+    openrouterAppName: env.OPENROUTER_APP_NAME || pkg.name || "MCP TS App",
+    /** OpenRouter API Key. From `OPENROUTER_API_KEY`. */
+    openrouterApiKey: env.OPENROUTER_API_KEY,
+    /** Default LLM model. From `LLM_DEFAULT_MODEL`. */
+    llmDefaultModel: env.LLM_DEFAULT_MODEL,
+    /** Default LLM temperature. From `LLM_DEFAULT_TEMPERATURE`. */
+    llmDefaultTemperature: env.LLM_DEFAULT_TEMPERATURE,
+    /** Default LLM top_p. From `LLM_DEFAULT_TOP_P`. */
+    llmDefaultTopP: env.LLM_DEFAULT_TOP_P,
+    /** Default LLM max tokens. From `LLM_DEFAULT_MAX_TOKENS`. */
+    llmDefaultMaxTokens: env.LLM_DEFAULT_MAX_TOKENS,
+    /** Default LLM top_k. From `LLM_DEFAULT_TOP_K`. */
+    llmDefaultTopK: env.LLM_DEFAULT_TOP_K,
+    /** Default LLM min_p. From `LLM_DEFAULT_MIN_P`. */
+    llmDefaultMinP: env.LLM_DEFAULT_MIN_P,
+    /** Gemini API Key. From `GEMINI_API_KEY`. */
+    geminiApiKey: env.GEMINI_API_KEY,
+    // NCBI Configuration
+    /** NCBI API Key. From `NCBI_API_KEY`. */
+    ncbiApiKey: env.NCBI_API_KEY,
+    /** NCBI Tool Identifier. From `NCBI_TOOL_IDENTIFIER`. Defaults to server name/version. */
+    ncbiToolIdentifier: env.NCBI_TOOL_IDENTIFIER ||
+        `${env.MCP_SERVER_NAME || pkg.name}/${env.MCP_SERVER_VERSION || pkg.version}`,
+    /** NCBI Admin Email. From `NCBI_ADMIN_EMAIL`. */
+    ncbiAdminEmail: env.NCBI_ADMIN_EMAIL,
+    /** NCBI Request Delay in MS. From `NCBI_REQUEST_DELAY_MS`. Dynamically set based on API key presence. */
+    ncbiRequestDelayMs: env.NCBI_REQUEST_DELAY_MS ?? (env.NCBI_API_KEY ? 100 : 334),
+    /** NCBI Max Retries. From `NCBI_MAX_RETRIES`. */
+    ncbiMaxRetries: env.NCBI_MAX_RETRIES,
+    /** OAuth Proxy configurations. Undefined if no related env vars are set. */
+    oauthProxy: env.OAUTH_PROXY_AUTHORIZATION_URL ||
+        env.OAUTH_PROXY_TOKEN_URL ||
+        env.OAUTH_PROXY_REVOCATION_URL ||
+        env.OAUTH_PROXY_ISSUER_URL ||
+        env.OAUTH_PROXY_SERVICE_DOCUMENTATION_URL ||
+        env.OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS
+        ? {
+            authorizationUrl: env.OAUTH_PROXY_AUTHORIZATION_URL,
+            tokenUrl: env.OAUTH_PROXY_TOKEN_URL,
+            revocationUrl: env.OAUTH_PROXY_REVOCATION_URL,
+            issuerUrl: env.OAUTH_PROXY_ISSUER_URL,
+            serviceDocumentationUrl: env.OAUTH_PROXY_SERVICE_DOCUMENTATION_URL,
+            defaultClientRedirectUris: env.OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS?.split(",")
+                .map((uri) => uri.trim())
+                .filter(Boolean),
+        }
+        : undefined,
+};
+/**
+ * Configured logging level for the application.
+ * Exported for convenience.
+ */
+export const logLevel = config.logLevel;
+/**
+ * Configured runtime environment ("development", "production", etc.).
+ * Exported for convenience.
+ */
+export const environment = config.environment;

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Main entry point for the MCP TypeScript Template application.
+ * This script initializes the configuration, sets up the logger, starts the
+ * MCP server (either via STDIO or HTTP transport), and handles graceful
+ * shutdown on process signals or unhandled errors.
+ *
+ * The script uses an Immediately Invoked Function Expression (IIFE) with async/await
+ * to manage the asynchronous nature of server startup and shutdown.
+ *
+ * Key operations:
+ * 1. Import necessary modules and utilities.
+ * 2. Define a `shutdown` function for graceful server termination.
+ * 3. Define a `start` function to:
+ *    - Initialize the logger with the configured log level.
+ *    - Create a startup request context for logging and correlation.
+ *    - Initialize and start the MCP server transport (stdio or http).
+ *    - Set up global error handlers (uncaughtException, unhandledRejection)
+ *      and signal handlers (SIGTERM, SIGINT) to trigger graceful shutdown.
+ * 4. Execute the `start` function within an async IIFE.
+ *
+ * @module src/index
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Main entry point for the MCP TypeScript Template application.
+ * This script initializes the configuration, sets up the logger, starts the
+ * MCP server (either via STDIO or HTTP transport), and handles graceful
+ * shutdown on process signals or unhandled errors.
+ *
+ * The script uses an Immediately Invoked Function Expression (IIFE) with async/await
+ * to manage the asynchronous nature of server startup and shutdown.
+ *
+ * Key operations:
+ * 1. Import necessary modules and utilities.
+ * 2. Define a `shutdown` function for graceful server termination.
+ * 3. Define a `start` function to:
+ *    - Initialize the logger with the configured log level.
+ *    - Create a startup request context for logging and correlation.
+ *    - Initialize and start the MCP server transport (stdio or http).
+ *    - Set up global error handlers (uncaughtException, unhandledRejection)
+ *      and signal handlers (SIGTERM, SIGINT) to trigger graceful shutdown.
+ * 4. Execute the `start` function within an async IIFE.
+ *
+ * @module src/index
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { config, environment } from "./config/index.js";
+import { initializeAndStartServer } from "./mcp-server/server.js";
+import { requestContextService } from "./utils/index.js";
+import { logger } from "./utils/internal/logger.js";
+/**
+ * Holds the main MCP server instance, primarily for STDIO transport.
+ * For HTTP transport, server instances are typically managed per session.
+ * @private
+ */
+let server;
+/**
+ * Gracefully shuts down the main MCP server and associated resources.
+ * Called on process termination signals or critical unhandled errors.
+ *
+ * @param signal - The signal or event name that triggered the shutdown.
+ * @returns A promise that resolves when shutdown is complete or an error occurs.
+ * @private
+ */
+const shutdown = async (signal) => {
+    const shutdownContext = requestContextService.createRequestContext({
+        operation: "ServerShutdown",
+        triggerEvent: signal,
+    });
+    logger.info(`Received ${signal}. Initiating graceful shutdown...`, shutdownContext);
+    try {
+        if (server) {
+            logger.info("Attempting to close main MCP server...", shutdownContext);
+            await server.close();
+            logger.info("Main MCP server closed successfully.", shutdownContext);
+        }
+        else {
+            logger.notice("No global server instance found to close during shutdown (this may be normal for HTTP transport).", shutdownContext);
+        }
+        logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
+        process.exit(0);
+    }
+    catch (error) {
+        logger.error("Critical error encountered during shutdown process.", {
+            ...shutdownContext,
+            errorMessage: error instanceof Error ? error.message : String(error),
+            errorStack: error instanceof Error ? error.stack : undefined,
+        });
+        process.exit(1);
+    }
+};
+/**
+ * Initializes and starts the main MCP server application.
+ * Orchestrates logger setup, server initialization, transport startup,
+ * and global error/signal handling.
+ *
+ * @returns A promise that resolves when the server has started and handlers are registered,
+ *   or rejects if a critical startup error occurs.
+ * @private
+ */
+const start = async () => {
+    const validMcpLogLevels = [
+        "debug",
+        "info",
+        "notice",
+        "warning",
+        "error",
+        "crit",
+        "alert",
+        "emerg",
+    ];
+    const initialLogLevelConfig = config.logLevel;
+    let validatedMcpLogLevel = "info";
+    if (validMcpLogLevels.includes(initialLogLevelConfig)) {
+        validatedMcpLogLevel = initialLogLevelConfig;
+    }
+    else {
+        if (process.stdout.isTTY) {
+            console.warn(`[Startup Warning] Invalid MCP_LOG_LEVEL "${initialLogLevelConfig}" found in configuration. ` +
+                `Defaulting to log level "info". Valid levels are: ${validMcpLogLevels.join(", ")}.`);
+        }
+    }
+    await logger.initialize(validatedMcpLogLevel);
+    logger.info(`Logger has been initialized by start(). Effective MCP logging level set to: ${validatedMcpLogLevel}.`);
+    // Configure RequestContextService once globally
+    requestContextService.configure({
+        appName: config.mcpServerName,
+        appVersion: config.mcpServerVersion,
+        environment,
+    });
+    logger.debug("RequestContextService configured with app name, version, and environment.");
+    const transportType = config.mcpTransportType;
+    const startupContext = requestContextService.createRequestContext({
+        operation: `ServerStartupSequence_${transportType}`,
+        applicationName: config.mcpServerName,
+        applicationVersion: config.mcpServerVersion,
+        nodeEnvironment: environment,
+    });
+    logger.debug("Application configuration loaded successfully.", {
+        ...startupContext,
+        configSummary: {
+            serverName: config.mcpServerName,
+            serverVersion: config.mcpServerVersion,
+            transport: config.mcpTransportType,
+            logLevel: config.logLevel,
+            env: config.environment,
+            httpPort: config.mcpTransportType === "http" ? config.mcpHttpPort : undefined,
+            httpHost: config.mcpTransportType === "http" ? config.mcpHttpHost : undefined,
+        },
+    });
+    logger.info(`Starting ${config.mcpServerName} (Version: ${config.mcpServerVersion}, Transport: ${transportType}, Env: ${environment})...`, startupContext);
+    try {
+        logger.debug("Calling initializeAndStartServer to set up MCP transport...", startupContext);
+        const potentialServerInstance = await initializeAndStartServer();
+        if (transportType === "stdio" &&
+            potentialServerInstance instanceof McpServer) {
+            server = potentialServerInstance;
+            logger.info("STDIO McpServer instance stored globally for shutdown.", startupContext);
+        }
+        else if (transportType === "http") {
+            logger.info("HTTP transport initialized. Server lifecycle managed by HTTP listener and session handlers.", startupContext);
+        }
+        logger.info(`${config.mcpServerName} is now running and ready to accept connections via ${transportType} transport.`, {
+            ...startupContext,
+            serverStartTime: new Date().toISOString(),
+        });
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+        process.on("SIGINT", () => shutdown("SIGINT"));
+        process.on("uncaughtException", async (error) => {
+            const errorContext = {
+                ...startupContext,
+                triggerEvent: "uncaughtException",
+                errorMessage: error.message,
+                errorStack: error.stack,
+            };
+            logger.error("FATAL: Uncaught exception detected. This indicates a bug or unexpected state. Initiating shutdown...", errorContext);
+            await shutdown("uncaughtException");
+        });
+        process.on("unhandledRejection", async (reason, promise) => {
+            const rejectionContext = {
+                ...startupContext,
+                triggerEvent: "unhandledRejection",
+                rejectionReason: reason instanceof Error ? reason.message : String(reason),
+                rejectionStack: reason instanceof Error ? reason.stack : undefined,
+            };
+            logger.error("FATAL: Unhandled promise rejection detected. This indicates a bug or missing error handling in async code. Initiating shutdown...", rejectionContext);
+            await shutdown("unhandledRejection");
+        });
+    }
+    catch (error) {
+        logger.error("CRITICAL ERROR DURING STARTUP: The application could not start. Exiting.", {
+            ...startupContext,
+            finalErrorContext: "ApplicationStartupFailure",
+            errorMessage: error instanceof Error ? error.message : String(error),
+            errorStack: error instanceof Error ? error.stack : undefined,
+        });
+        process.exit(1);
+    }
+};
+// Async IIFE to allow top-level await for the start function.
+(async () => {
+    try {
+        await start();
+    }
+    catch (error) {
+        // This catch is a final fallback. `start()` should handle its errors and exit.
+        if (process.stdout.isTTY) {
+            console.error("[GLOBAL CATCH] An unexpected error occurred outside of the main start function's error handling:", error);
+        }
+        process.exit(1);
+    }
+})();

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

@@ -0,0 +1,79 @@
+/**
+ * @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;
+}, {
+    message?: string | undefined;
+}>;
+/**
+ * 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;