@cyanheads/pubmed-mcp-server 1.2.4 → 1.3.1

package/dist/config/index.js

@@ -4,14 +4,6 @@
  * 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";
@@ -21,11 +13,6 @@ 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) {
@@ -35,7 +22,6 @@ const findProjectRoot = (startDir) => {
         }
         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;
@@ -43,21 +29,17 @@ const findProjectRoot = (startDir) => {
 };
 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" };
+const pkgPath = join(projectRoot, "package.json");
+let pkg = { name: "pubmed-mcp-server", version: "0.0.0" };
 try {
     pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 }
@@ -66,90 +48,57 @@ catch (error) {
         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. */
+    // Core Server Config
     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". */
+    NODE_ENV: z.string().default("development"),
+    // Logging
     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")),
-    /** Defines the logging output mode. "file" for logs in LOGS_DIR, "stdout" for console logging. */
-    LOG_OUTPUT_MODE: z.enum(["file", "stdout"]).default("file"),
-    /** Runtime environment (e.g., "development", "production"). Default: "development". */
-    NODE_ENV: z.string().default("development"),
-    /** MCP communication transport ("stdio" or "http"). Default: "stdio". */
+    // Transport
     MCP_TRANSPORT_TYPE: z.enum(["stdio", "http"]).default("stdio"),
-    /** HTTP server port (if MCP_TRANSPORT_TYPE is "http"). Default: 3010. */
+    MCP_SESSION_MODE: z.enum(["stateless", "stateful", "auto"]).default("auto"),
     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_HTTP_ENDPOINT_PATH: z.string().default("/mcp"),
+    MCP_HTTP_MAX_PORT_RETRIES: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .default(15),
+    MCP_HTTP_PORT_RETRY_DELAY_MS: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .default(50),
+    MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(1800000),
     MCP_ALLOWED_ORIGINS: z.string().optional(),
-    /** Optional. Secret key (min 32 chars) for auth tokens (HTTP transport). CRITICAL for production. */
+    // Authentication
+    MCP_AUTH_MODE: z.enum(["jwt", "oauth", "none"]).default("none"),
     MCP_AUTH_SECRET_KEY: z
         .string()
-        .min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long for security reasons.")
+        .min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long.")
         .optional(),
-    /** Authentication mode ('jwt' or 'oauth'). Default: 'jwt'. */
-    MCP_AUTH_MODE: z.enum(["jwt", "oauth"]).default("jwt"),
-    /** OAuth: The expected issuer of the JWT. */
     OAUTH_ISSUER_URL: z.string().url().optional(),
-    /** OAuth: The expected audience of the JWT. */
-    OAUTH_AUDIENCE: z.string().optional(),
-    /** OAuth: The URI of the JWKS endpoint. */
     OAUTH_JWKS_URI: z.string().url().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. */
+    OAUTH_AUDIENCE: z.string().optional(),
+    // Dev mode JWT
+    DEV_MCP_CLIENT_ID: z.string().optional(),
+    DEV_MCP_SCOPES: z.string().optional(),
+    // NCBI E-utilities
     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_ADMIN_EMAIL: z.string().email().optional(),
+    NCBI_REQUEST_DELAY_MS: z.coerce.number().int().positive().optional(),
     NCBI_MAX_RETRIES: z.coerce.number().int().nonnegative().default(3),
 })
     .superRefine((data, ctx) => {
-    // Rule 1: MCP_AUTH_SECRET_KEY is required for http transport in production with jwt auth
     if (data.NODE_ENV === "production" &&
         data.MCP_TRANSPORT_TYPE === "http" &&
         data.MCP_AUTH_MODE === "jwt" &&
@@ -157,30 +106,22 @@ const EnvSchema = z
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["MCP_AUTH_SECRET_KEY"],
-            message: "MCP_AUTH_SECRET_KEY is required for 'jwt' auth with 'http' transport in a 'production' environment.",
+            message: "MCP_AUTH_SECRET_KEY is required for 'jwt' auth in production with 'http' transport.",
         });
     }
-    // Rule 2: Core OAuth variables are required when MCP_AUTH_MODE is 'oauth'
     if (data.MCP_AUTH_MODE === "oauth") {
         if (!data.OAUTH_ISSUER_URL) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["OAUTH_ISSUER_URL"],
-                message: "OAUTH_ISSUER_URL is required when MCP_AUTH_MODE is 'oauth'.",
+                message: "OAUTH_ISSUER_URL is required for 'oauth' mode.",
             });
         }
         if (!data.OAUTH_AUDIENCE) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["OAUTH_AUDIENCE"],
-                message: "OAUTH_AUDIENCE is required when MCP_AUTH_MODE is 'oauth'.",
-            });
-        }
-        if (!data.OAUTH_JWKS_URI) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ["OAUTH_JWKS_URI"],
-                message: "OAUTH_JWKS_URI is required when MCP_AUTH_MODE is 'oauth'.",
+                message: "OAUTH_AUDIENCE is required for 'oauth' mode.",
             });
         }
     }
@@ -188,153 +129,69 @@ const EnvSchema = z
 const parsedEnv = EnvSchema.safeParse(process.env);
 if (!parsedEnv.success) {
     if (process.stdout.isTTY) {
-        console.error("❌ Invalid environment variables found:", parsedEnv.error.flatten().fieldErrors);
+        console.error("❌ Invalid environment variables:", 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 (!resolvedDirPath.startsWith(rootDir)) {
         if (process.stdout.isTTY) {
-            console.error(`Error: ${dirName} path "${dirPath}" resolves to "${resolvedDirPath}", which is outside the project boundary "${rootDir}".`);
+            console.error(`Error: ${dirName} path "${dirPath}" is outside the project boundary "${rootDir}".`);
         }
         return null;
     }
-    if (!existsSync(resolvedDirPath)) {
-        try {
+    try {
+        if (!existsSync(resolvedDirPath)) {
             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.`);
-                }
+        else {
+            if (!statSync(resolvedDirPath).isDirectory()) {
+                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;
     }
-    return resolvedDirPath;
-};
-// --- End Directory Ensurance Function ---
-// --- Logs Directory Handling ---
-let validatedLogsPath = null;
-if (env.LOG_OUTPUT_MODE === "file") {
-    validatedLogsPath = ensureDirectory(env.LOGS_DIR, projectRoot, "logs");
-    if (!validatedLogsPath) {
-        if (process.stdout.isTTY) {
-            console.error("FATAL: Log mode is 'file' but logs directory is invalid or could not be created. Please check LOGS_DIR, permissions, and path. Exiting.");
-        }
-        process.exit(1); // Exit if file logging is configured but directory is not usable
+    catch (error) {
+        console.error(`Error ensuring ${dirName} directory at ${resolvedDirPath}: ${error.message}`);
+        return null;
     }
-}
-// --- End Logs Directory Handling ---
-/**
- * Main application configuration object.
- * Aggregates settings from validated environment variables and `package.json`.
- */
+};
+const validatedLogsPath = ensureDirectory(env.LOGS_DIR, projectRoot, "logs");
 export const config = {
-    /** MCP server name. Env `MCP_SERVER_NAME` > `package.json` name > "mcp-ts-template". */
+    pkg,
     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,
-    /** Defines the logging output mode ('file' or 'stdout'). From `LOG_OUTPUT_MODE`. */
-    logOutputMode: env.LOG_OUTPUT_MODE,
-    /** Absolute path to the logs directory (if logOutputMode is 'file'). From `LOGS_DIR`. */
     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. */
+    mcpSessionMode: env.MCP_SESSION_MODE,
     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). */
+    mcpHttpEndpointPath: env.MCP_HTTP_ENDPOINT_PATH,
+    mcpHttpMaxPortRetries: env.MCP_HTTP_MAX_PORT_RETRIES,
+    mcpHttpPortRetryDelayMs: env.MCP_HTTP_PORT_RETRY_DELAY_MS,
+    mcpStatefulSessionStaleTimeoutMs: env.MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS,
     mcpAllowedOrigins: env.MCP_ALLOWED_ORIGINS?.split(",")
-        .map((origin) => origin.trim())
+        .map((o) => o.trim())
         .filter(Boolean),
-    /** Auth secret key (JWTs, http transport). From `MCP_AUTH_SECRET_KEY`. CRITICAL. */
-    mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
-    /** Auth mode ('jwt' or 'oauth'). From `MCP_AUTH_MODE`. */
     mcpAuthMode: env.MCP_AUTH_MODE,
-    /** OAuth Issuer URL. From `OAUTH_ISSUER_URL`. */
+    mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
     oauthIssuerUrl: env.OAUTH_ISSUER_URL,
-    /** OAuth Audience. From `OAUTH_AUDIENCE`. */
-    oauthAudience: env.OAUTH_AUDIENCE,
-    /** OAuth JWKS URI. From `OAUTH_JWKS_URI`. */
     oauthJwksUri: env.OAUTH_JWKS_URI,
-    // NCBI Configuration
-    /** NCBI API Key. From `NCBI_API_KEY`. */
+    oauthAudience: env.OAUTH_AUDIENCE,
+    devMcpClientId: env.DEV_MCP_CLIENT_ID,
+    devMcpScopes: env.DEV_MCP_SCOPES?.split(",").map((s) => s.trim()),
     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.js

@@ -51,70 +51,40 @@ const shutdown = async (signal) => {
         triggerEvent: signal,
     });
     logger.info(`Received ${signal}. Initiating graceful shutdown...`, shutdownContext);
-    let mcpClosed = false;
-    let httpClosed = false;
-    let closeError = null;
-    const checkAndExit = () => {
-        if (closeError) {
-            logger.error("Critical error encountered during shutdown process.", {
-                ...shutdownContext,
-                errorMessage: closeError.message,
-                errorStack: closeError.stack,
-            });
-            process.exit(1);
-        }
-        else if (mcpClosed && httpClosed) {
-            logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
-            process.exit(0);
+    try {
+        let closePromise = Promise.resolve();
+        const transportType = config.mcpTransportType;
+        if (transportType === "stdio" && mcpStdioServer) {
+            logger.info("Attempting to close main MCP server (STDIO)...", shutdownContext);
+            closePromise = mcpStdioServer.close();
         }
-    };
-    if (mcpStdioServer) {
-        logger.info("Attempting to close main MCP server (STDIO)...", shutdownContext);
-        mcpStdioServer
-            .close()
-            .then(() => {
-            logger.info("Main MCP server (STDIO) closed successfully.", shutdownContext);
-            mcpClosed = true;
-            checkAndExit();
-        })
-            .catch((err) => {
-            logger.error("Error closing MCP server (STDIO).", {
-                ...shutdownContext,
-                error: err,
+        else if (transportType === "http" && actualHttpServer) {
+            logger.info("Attempting to close HTTP server...", shutdownContext);
+            closePromise = new Promise((resolve, reject) => {
+                actualHttpServer.close((err) => {
+                    if (err) {
+                        logger.error("Error closing HTTP server.", {
+                            ...shutdownContext,
+                            error: err.message,
+                        });
+                        return reject(err);
+                    }
+                    logger.info("HTTP server closed successfully.", shutdownContext);
+                    resolve();
+                });
             });
-            mcpClosed = true; // Consider it closed even on error to allow exit
-            if (!closeError)
-                closeError = err;
-            checkAndExit();
-        });
-    }
-    else {
-        mcpClosed = true; // No STDIO McpServer to close
+        }
+        await closePromise;
+        logger.info("Graceful shutdown completed successfully. Exiting.", shutdownContext);
+        process.exit(0);
     }
-    if (actualHttpServer) {
-        logger.info("Attempting to close HTTP server...", shutdownContext);
-        actualHttpServer.close((err) => {
-            if (err) {
-                logger.error("Error closing HTTP server.", {
-                    ...shutdownContext,
-                    error: err,
-                });
-                if (!closeError)
-                    closeError = err;
-            }
-            else {
-                logger.info("HTTP server closed successfully.", shutdownContext);
-            }
-            httpClosed = true;
-            checkAndExit();
+    catch (error) {
+        logger.error("Critical error during shutdown process.", {
+            ...shutdownContext,
+            errorMessage: error instanceof Error ? error.message : String(error),
+            errorStack: error instanceof Error ? error.stack : undefined,
         });
-    }
-    else {
-        httpClosed = true; // No HTTP server to close
-    }
-    // Initial check in case no servers needed closing
-    if (mcpClosed && httpClosed) {
-        checkAndExit();
+        process.exit(1);
     }
 };
 /**

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

@@ -7,16 +7,11 @@
  *    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
  * @module src/mcp-server/server
  */
 import { ServerType } from "@hono/node-server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * Main application entry point. Initializes and starts the MCP server.
- * Orchestrates server startup, transport selection, and top-level error handling.
  */
 export declare function initializeAndStartServer(): Promise<void | McpServer | ServerType>;

package/dist/mcp-server/server.js

@@ -7,10 +7,6 @@
  *    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
  * @module src/mcp-server/server
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -22,19 +18,11 @@ import { registerGeneratePubMedChartTool } from "./tools/generatePubMedChart/ind
 import { registerGetPubMedArticleConnectionsTool } from "./tools/getPubMedArticleConnections/index.js";
 import { registerPubMedResearchAgentTool } from "./tools/pubmedResearchAgent/index.js";
 import { registerSearchPubMedArticlesTool } from "./tools/searchPubMedArticles/index.js";
-import { startHttpTransport } from "./transports/httpTransport.js";
-import { connectStdioTransport } from "./transports/stdioTransport.js";
+import { startHttpTransport } from "./transports/http/index.js";
+import { startStdioTransport } from "./transports/stdio/index.js";
 /**
  * Creates and configures a new instance of the `McpServer`.
  *
- * This function defines the server's identity and capabilities as presented
- * to clients during MCP initialization.
- *
- * MCP Spec Relevance:
- * - Server Identity (`serverInfo`): `name` and `version` are part of `ServerInformation`.
- * - Capabilities Declaration: Declares supported features (logging, dynamic resources/tools).
- * - Resource/Tool Registration: Makes capabilities discoverable and invocable.
- *
  * @returns A promise resolving with the configured `McpServer` instance.
  * @throws {McpError} If any resource or tool registration fails.
  * @private
@@ -44,21 +32,16 @@ async function createMcpServerInstance() {
         operation: "createMcpServerInstance",
     });
     logger.info("Initializing MCP server instance", context);
-    requestContextService.configure({
-        appName: config.mcpServerName,
-        appVersion: config.mcpServerVersion,
-        environment,
-    });
     const server = new McpServer({ name: config.mcpServerName, version: config.mcpServerVersion }, {
         capabilities: {
-            logging: {}, // Server can receive logging/setLevel and send notifications/message
-            resources: { listChanged: true }, // Server supports dynamic resource lists
-            tools: { listChanged: true }, // Server supports dynamic tool lists
+            logging: {},
+            resources: { listChanged: true },
+            tools: { listChanged: true },
         },
     });
     await ErrorHandler.tryCatch(async () => {
         logger.debug("Registering resources and tools...", context);
-        // IMPORTANT: Keep tool registrations in alphabetical order. Do not remove this comment.
+        // IMPORTANT: Keep tool registrations in alphabetical order.
         await registerFetchPubMedContentTool(server);
         await registerGeneratePubMedChartTool(server);
         await registerGetPubMedArticleConnectionsTool(server);
@@ -66,7 +49,7 @@ async function createMcpServerInstance() {
         await registerSearchPubMedArticlesTool(server);
         logger.info("Resources and tools registered successfully", context);
     }, {
-        operation: "registerAllTools",
+        operation: "registerAllCapabilities",
         context,
         errorCode: BaseErrorCode.INITIALIZATION_FAILED,
         critical: true,
@@ -76,11 +59,6 @@ async function createMcpServerInstance() {
 /**
  * Selects, sets up, and starts the appropriate MCP transport layer based on configuration.
  *
- * MCP Spec Relevance:
- * - Transport Selection: Uses `config.mcpTransportType` ('stdio' or 'http').
- * - Transport Connection: Calls dedicated functions for chosen transport.
- * - Server Instance Lifecycle: Single instance for 'stdio', per-session for 'http'.
- *
  * @returns Resolves with `McpServer` for 'stdio', `http.Server` for 'http', or `void`.
  * @throws {Error} If transport type is unsupported or setup fails.
  * @private
@@ -92,25 +70,31 @@ async function startTransport() {
         transport: transportType,
     });
     logger.info(`Starting transport: ${transportType}`, context);
+    const serverFactory = createMcpServerInstance;
     if (transportType === "http") {
-        return startHttpTransport(createMcpServerInstance, context);
+        const { server } = await startHttpTransport(serverFactory, context);
+        return server;
     }
     if (transportType === "stdio") {
-        const server = await createMcpServerInstance();
-        await connectStdioTransport(server, context);
+        const server = await serverFactory();
+        await startStdioTransport(server, context);
         return server;
     }
     throw new Error(`Unsupported transport type: ${transportType}. Must be 'stdio' or 'http'.`);
 }
 /**
  * Main application entry point. Initializes and starts the MCP server.
- * Orchestrates server startup, transport selection, and top-level error handling.
  */
 export async function initializeAndStartServer() {
     const context = requestContextService.createRequestContext({
         operation: "initializeAndStartServer",
     });
     logger.info("MCP Server initialization sequence started.", context);
+    requestContextService.configure({
+        appName: config.mcpServerName,
+        appVersion: config.mcpServerVersion,
+        environment,
+    });
     try {
         const result = await startTransport();
         logger.info("MCP Server initialization sequence completed successfully.", context);
@@ -121,7 +105,7 @@ export async function initializeAndStartServer() {
             operation: "initializeAndStartServer",
             context: context,
             critical: true,
-            rethrow: false, // Ensure we don't rethrow, so we can exit gracefully.
+            rethrow: false,
         });
         logger.info("Exiting process due to critical initialization error.", context);
         process.exit(1);

package/dist/mcp-server/tools/fetchPubMedContent/logic.js

@@ -6,10 +6,10 @@
  * @module src/mcp-server/tools/fetchPubMedContent/logic
  */
 import { z } from "zod";
-import { getNcbiService } from "../../../services/NCBI/ncbiService.js";
+import { getNcbiService } from "../../../services/NCBI/core/ncbiService.js";
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
-import { ensureArray, extractAbstractText, extractArticleDates, extractAuthors, extractDoi, extractGrants, extractJournalInfo, extractKeywords, extractMeshTerms, extractPmid, extractPublicationTypes, getText, } from "../../../utils/parsing/ncbi-parsing/index.js";
+import { ensureArray, extractAbstractText, extractArticleDates, extractAuthors, extractDoi, extractGrants, extractJournalInfo, extractKeywords, extractMeshTerms, extractPmid, extractPublicationTypes, getText, } from "../../../services/NCBI/parsing/index.js";
 export const FetchPubMedContentInputSchema = z
     .object({
     pmids: z