@cyanheads/pubmed-mcp-server 1.1.1 → 1.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.12.1-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-1.0.16-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.1.4-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/pubmed-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/pubmed-mcp-server?style=social)](https://github.com/cyanheads/pubmed-mcp-server)
@@ -17,13 +17,13 @@ Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-t
 
 This server equips your AI with specialized tools to interact with PubMed:
 
-| Tool Name                                                                               | Description                                                                                                                                                                                                                                    | Key Features                                                                                                                                                                                                                                                                                                                                                                                         |
-| :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`search_pubmed_articles`](./src/mcp-server/tools/searchPubMedArticles/)                | Searches PubMed for articles based on your query. (See [Example](./examples/search_pubmed_articles_example.md))                                                                                                                                | - Filter by max results, sort order, date range, publication types.<br/>- Uses NCBI ESearch for PMIDs.<br/>- Optionally fetches brief summaries (title, authors, source, dates) via ESummary.                                                                                                                                                                                                        |
-| [`fetch_pubmed_content`](./src/mcp-server/tools/fetchPubMedContent/)                    | Retrieves detailed information for PubMed articles. Can use a list of PMIDs or ESearch history (queryKey/webEnv) with pagination. (See [Example](./examples/fetch_pubmed_content_example.md))                                                  | - Flexible `detailLevel`: `abstract_plus` (parsed details, optional MeSH/grant), `full_xml` (JSON representation of the PubMedArticle XML structure), `medline_text` (MEDLINE format), `citation_data` (minimal for citations).<br/>- Supports direct PMID list or `queryKey`/`webEnv` from ESearch history.<br/>- Supports `retstart`/`retmax` for pagination with history.<br/>- Uses NCBI EFetch. |
-| [`get_pubmed_article_connections`](./src/mcp-server/tools/getPubMedArticleConnections/) | Finds related articles (cited by, similar, references) or formats citations for a PMID. (See [Ex.1](./examples/get_pubmed_article_connections_1.md), [Ex.2](./examples/get_pubmed_article_connections_2.md))                                   | - Uses NCBI ELink for relationships.<br/>- Uses NCBI EFetch for citation data (RIS, BibTeX, APA, MLA).<br/>- Filter by max related results.                                                                                                                                                                                                                                                          |
-| [`pubmed_research_agent`](./src/mcp-server/tools/pubmedResearchAgent/)                  | Generates a standardized JSON research plan outline from component details. (See [Example](./examples/pubmed_research_agent_example.md))                                                                                                       | - Accepts granular inputs for all research phases.<br/>- Optionally embeds instructive prompts for agent execution.<br/>- Structures rough ideas into a formal, machine-readable plan for further processing.                                                                                                                                                                                        |
-| [`generate_pubmed_chart`](./src/mcp-server/tools/generatePubMedChart/)                  | Generates a chart image (PNG) from given input data. (See [Bar](./examples/generate_pubmed_chart_example_bar.svg), [Line](./examples/generate_pubmed_chart_example_line.svg), [Scatter](./examples/generate_pubmed_chart_example_scatter.svg)) | - Supports 'bar', 'line', and 'scatter' chart types.<br/>- Takes data values and field specifications for axes and encoding.<br/>- Constructs a Vega-Lite specification internally and renders it as a PNG.                                                                                                                                                                                          |
+| Tool Name                                                                               | Description                                                                                                                                                                                                  | Key Features                                                                                                                                                                                                                                                                                                                                                                                         |
+| :-------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`search_pubmed_articles`](./src/mcp-server/tools/searchPubMedArticles/)                | Searches PubMed for articles based on your query. (See [Example](./examples/search_pubmed_articles_example.md))                                                                                              | - Filter by max results, sort order, date range, publication types.<br/>- Uses NCBI ESearch for PMIDs.<br/>- Optionally fetches brief summaries (title, authors, source, dates) via ESummary.                                                                                                                                                                                                        |
+| [`fetch_pubmed_content`](./src/mcp-server/tools/fetchPubMedContent/)                    | Retrieves detailed information for PubMed articles. Can use a list of PMIDs or ESearch history (queryKey/webEnv) with pagination. (See [Example](./examples/fetch_pubmed_content_example.md))                | - Flexible `detailLevel`: `abstract_plus` (parsed details, optional MeSH/grant), `full_xml` (JSON representation of the PubMedArticle XML structure), `medline_text` (MEDLINE format), `citation_data` (minimal for citations).<br/>- Supports direct PMID list or `queryKey`/`webEnv` from ESearch history.<br/>- Supports `retstart`/`retmax` for pagination with history.<br/>- Uses NCBI EFetch. |
+| [`get_pubmed_article_connections`](./src/mcp-server/tools/getPubMedArticleConnections/) | Finds related articles (cited by, similar, references) or formats citations for a PMID. (See [Ex.1](./examples/get_pubmed_article_connections_1.md), [Ex.2](./examples/get_pubmed_article_connections_2.md)) | - Uses NCBI ELink for relationships.<br/>- Uses NCBI EFetch for citation data (RIS, BibTeX, APA, MLA).<br/>- Filter by max related results.                                                                                                                                                                                                                                                          |
+| [`pubmed_research_agent`](./src/mcp-server/tools/pubmedResearchAgent/)                  | Generates a standardized JSON research plan outline from component details. (See [Example](./examples/pubmed_research_agent_example.md))                                                                     | - Accepts granular inputs for all research phases.<br/>- Optionally embeds instructive prompts for agent execution.<br/>- Structures rough ideas into a formal, machine-readable plan for further processing.                                                                                                                                                                                        |
+| [`generate_pubmed_chart`](./src/mcp-server/tools/generatePubMedChart/)                  | Generates a chart image (PNG) from given input data. (See [Examples](./examples/))                                                                                                                           | - Supports 'bar', 'line', and 'scatter' chart types.<br/>- Takes data values and field specifications for axes and encoding.<br/>- Constructs a Vega-Lite specification internally and renders it as a PNG using a canvas renderer.                                                                                                                                                                  |
 
 ---
 
@@ -56,14 +56,15 @@ Built on the robust `mcp-ts-template`, this server provides a standardized, secu
 
 Leverages the robust utilities provided by the `mcp-ts-template`:
 
-- **Logging**: Structured, configurable logging (file rotation, console, MCP notifications) with sensitive data redaction.
+- **Logging**: Structured, configurable logging (file rotation, stdout JSON, MCP notifications) with sensitive data redaction.
 - **Error Handling**: Centralized error processing, standardized error types (`McpError`), and automatic logging.
 - **Configuration**: Environment variable loading (`dotenv`) with comprehensive validation.
 - **Input Validation/Sanitization**: Uses `zod` for schema validation and custom sanitization logic.
-- **Request Context**: Tracking and correlation of operations via unique request IDs.
+- **Request Context**: Tracking and correlation of operations via unique request IDs using `AsyncLocalStorage`.
 - **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
-- **HTTP Transport Option**: Built-in Express server with SSE, session management, CORS support, and JWT authentication.
-- **Rate Limiting**: Built-in request queuing and delay management for NCBI API compliance.
+- **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management with garbage collection, CORS, and IP-based rate limiting.
+- **Authentication**: Robust authentication layer supporting JWT and OAuth 2.1, with fine-grained scope enforcement.
+- **Deployment**: Multi-stage `Dockerfile` for creating small, secure production images with native dependency support.
 
 ### PubMed Integration
 
@@ -82,6 +83,7 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 
 - [Node.js (>=18.0.0)](https://nodejs.org/)
 - [npm](https://www.npmjs.com/) (comes with Node.js)
+- [Docker](https://www.docker.com/) (optional, for containerized deployment)
 - **NCBI API Key** (recommended for higher rate limits) - [Get one here](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)
 
 ### Install via npm (recommended)
@@ -124,10 +126,12 @@ Configure the server using environment variables. These environmental variables
 | `MCP_HTTP_HOST`        | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                         | `127.0.0.1`                    |
 | `MCP_ALLOWED_ORIGINS`  | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).         | (none)                         |
 | `MCP_LOG_LEVEL`        | Logging level (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). | `debug`                        |
-| `MCP_AUTH_SECRET_KEY`  | **Required for HTTP transport.** Minimum 32-character secret key for JWT authentication. | (none)                         |
+| `LOG_OUTPUT_MODE`      | Logging output mode: `file` or `stdout`.                                                 | `file`                         |
+| `MCP_AUTH_MODE`        | Authentication mode for HTTP: `jwt` or `oauth`.                                          | `jwt`                          |
+| `MCP_AUTH_SECRET_KEY`  | **Required for `jwt` auth.** Minimum 32-character secret key for JWT authentication.     | (none)                         |
 | `NCBI_API_KEY`         | **Recommended.** Your NCBI API Key for higher rate limits and reliable access.           | (none)                         |
 | `NCBI_TOOL_IDENTIFIER` | Tool identifier for NCBI E-utility requests.                                             | `@cyanheads/pubmed-mcp-server` |
-| `LOGS_DIR`             | Directory for log file storage.                                                          | `logs/`                        |
+| `LOGS_DIR`             | Directory for log file storage (if `LOG_OUTPUT_MODE=file`).                              | `logs/`                        |
 
 ### MCP Client Settings
 
@@ -166,8 +170,7 @@ src/
 │   ├── resources/        # MCP Resource implementations
 │   └── tools/            # MCP Tool implementations (subdirs per tool)
 ├── services/             # External service integrations
-│   ├── NCBI/            # NCBI E-utilities API client and parsing
-│   └── llm-providers/   # LLM provider integrations (optional)
+│   └── NCBI/             # NCBI E-utilities API client and parsing
 ├── types-global/         # Shared TypeScript type definitions
 └── utils/                # Common utility functions (logger, error handler, etc.)
 ```

package/dist/config/index.d.ts

@@ -25,8 +25,10 @@ export declare const config: {
     mcpServerVersion: string;
     /** Logging level. From `MCP_LOG_LEVEL` env var. Default: "debug". */
     logLevel: string;
-    /** Absolute path to the logs directory. From `LOGS_DIR` env var. */
-    logsPath: string;
+    /** Defines the logging output mode ('file' or 'stdout'). From `LOG_OUTPUT_MODE`. */
+    logOutputMode: "file" | "stdout";
+    /** Absolute path to the logs directory (if logOutputMode is 'file'). From `LOGS_DIR`. */
+    logsPath: string | null;
     /** Runtime environment. From `NODE_ENV` env var. Default: "development". */
     environment: string;
     /** MCP transport type ('stdio' or 'http'). From `MCP_TRANSPORT_TYPE` env var. Default: "stdio". */

package/dist/config/index.js

@@ -71,7 +71,8 @@ catch (error) {
  * Provides type safety, validation, defaults, and clear error messages.
  * @private
  */
-const EnvSchema = z.object({
+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. */
@@ -80,6 +81,8 @@ const EnvSchema = z.object({
     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". */
@@ -144,6 +147,43 @@ const EnvSchema = z.object({
     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),
+})
+    .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" &&
+        !data.MCP_AUTH_SECRET_KEY) {
+        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.",
+        });
+    }
+    // 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'.",
+            });
+        }
+        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'.",
+            });
+        }
+    }
 });
 const parsedEnv = EnvSchema.safeParse(process.env);
 if (!parsedEnv.success) {
@@ -209,12 +249,15 @@ const ensureDirectory = (dirPath, rootDir, dirName) => {
 };
 // --- 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.");
+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
     }
-    process.exit(1); // Exit if logs directory is not usable
 }
 // --- End Logs Directory Handling ---
 /**
@@ -228,7 +271,9 @@ export const config = {
     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. */
+    /** 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,

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

@@ -97,14 +97,12 @@ export const FetchPubMedContentInputSchema = z
         });
     }
 });
-function parsePubMedArticleSet(xmlData, // Changed from { PubmedArticleSet?: XmlPubmedArticleSet } | any
-input, parentContext) {
+function parsePubMedArticleSet(xmlData, input, parentContext) {
     const articles = [];
     const operationContext = requestContextService.createRequestContext({
         parentRequestId: parentContext.requestId,
         operation: "parsePubMedArticleSet",
     });
-    // Type guard for xmlData
     if (!xmlData ||
         typeof xmlData !== "object" ||
         !("PubmedArticleSet" in xmlData)) {
@@ -115,30 +113,17 @@ input, parentContext) {
         });
         return articles;
     }
-    const typedXmlData = xmlData; // Cast after check
+    const typedXmlData = xmlData;
     const articleSet = typedXmlData.PubmedArticleSet;
     if (!articleSet || !articleSet.PubmedArticle) {
-        logger.warning("PubmedArticleSet or PubmedArticle array not found in EFetch XML response.", requestContextService.createRequestContext({
+        logger.warning("PubmedArticleSet or PubmedArticle array not found in EFetch XML response.", {
             ...operationContext,
             xmlDataPreview: sanitizeInputForLogging(JSON.stringify(typedXmlData).substring(0, 200)),
-        }));
+        });
         return articles;
     }
     const pubmedArticlesXml = ensureArray(articleSet.PubmedArticle);
-    logger.debug("Result of ensureArray(articleSet.PubmedArticle):", {
-        ...operationContext,
-        pubmedArticlesXmlPreview: sanitizeInputForLogging(JSON.stringify(pubmedArticlesXml).substring(0, 500)),
-        isPubmedArticlesXmlArray: Array.isArray(pubmedArticlesXml),
-        pubmedArticlesXmlLength: Array.isArray(pubmedArticlesXml)
-            ? pubmedArticlesXml.length
-            : undefined,
-    });
-    if (Array.isArray(pubmedArticlesXml) && pubmedArticlesXml.length > 0) {
-        logger.debug("First item of pubmedArticlesXml:", {
-            ...operationContext,
-            firstItemPreview: sanitizeInputForLogging(JSON.stringify(pubmedArticlesXml[0]).substring(0, 500)),
-        });
-    }
+    const totalArticlesInXml = pubmedArticlesXml.length;
     for (const articleXml of pubmedArticlesXml) {
         if (!articleXml || typeof articleXml !== "object") {
             logger.warning("Skipping invalid articleXml item in pubmedArticlesXml array", {
@@ -156,13 +141,13 @@ input, parentContext) {
             continue;
         }
         const pmid = extractPmid(medlineCitation);
-        logger.debug("Extracted PMID from MedlineCitation:", {
-            ...operationContext,
-            extractedPmid: pmid,
-            medlineCitationPreview: sanitizeInputForLogging(JSON.stringify(medlineCitation).substring(0, 200)),
-        });
-        if (!pmid)
+        if (!pmid) {
+            logger.warning("Could not extract PMID from MedlineCitation, skipping.", {
+                ...operationContext,
+                medlineCitationPreview: sanitizeInputForLogging(JSON.stringify(medlineCitation).substring(0, 200)),
+            });
             continue;
+        }
         const articleNode = medlineCitation.Article;
         const parsedArticle = {
             pmid: pmid,
@@ -201,82 +186,24 @@ input, parentContext) {
         }
         articles.push(parsedArticle);
     }
+    logger.debug(`Successfully parsed ${articles.length} of ${totalArticlesInXml} articles from XML.`, {
+        ...operationContext,
+        parsedCount: articles.length,
+        totalInXml: totalArticlesInXml,
+    });
     return articles;
 }
 export async function fetchPubMedContentLogic(input, parentRequestContext) {
-    // Manual validation for conditions superRefine should catch,
-    // as SDK might call handler even with refinement issues.
-    if (input.queryKey && !input.webEnv) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: {
-                            code: BaseErrorCode.VALIDATION_ERROR,
-                            message: "webEnv is required if queryKey is provided.",
-                        },
-                    }),
-                },
-            ],
-            isError: true,
-        };
-    }
-    if (!input.queryKey && input.webEnv) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: {
-                            code: BaseErrorCode.VALIDATION_ERROR,
-                            message: "queryKey is required if webEnv is provided.",
-                        },
-                    }),
-                },
-            ],
-            isError: true,
-        };
-    }
-    if (input.pmids &&
-        input.pmids.length > 0 &&
-        (input.queryKey || input.webEnv)) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: {
-                            code: BaseErrorCode.VALIDATION_ERROR,
-                            message: "Cannot use pmids and queryKey/webEnv simultaneously. Please choose one method.",
-                        },
-                    }),
-                },
-            ],
-            isError: true,
-        };
-    }
-    if ((input.retstart !== undefined || input.retmax !== undefined) &&
-        !(input.queryKey && input.webEnv)) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: {
-                            code: BaseErrorCode.VALIDATION_ERROR,
-                            message: "retstart/retmax can only be used with queryKey and webEnv.",
-                        },
-                    }),
-                },
-            ],
-            isError: true,
-        };
-    }
-    // SuperRefine also checks: if ((!data.pmids || data.pmids.length === 0) && !(data.queryKey && data.webEnv))
-    // This should ideally be caught before handler, but as a safeguard:
-    if ((!input.pmids || input.pmids.length === 0) &&
-        !(input.queryKey && input.webEnv)) {
+    const toolLogicContext = requestContextService.createRequestContext({
+        parentRequestId: parentRequestContext.requestId,
+        operation: "fetchPubMedContentLogic",
+        input: sanitizeInputForLogging(input),
+    });
+    // Manual validation safeguard
+    const validationResult = FetchPubMedContentInputSchema.safeParse(input);
+    if (!validationResult.success) {
+        const errorMessage = validationResult.error.errors[0]?.message || "Invalid input";
+        logger.warning(`Input validation failed pre-check: ${errorMessage}`, toolLogicContext);
         return {
             content: [
                 {
@@ -284,7 +211,8 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
                     text: JSON.stringify({
                         error: {
                             code: BaseErrorCode.VALIDATION_ERROR,
-                            message: "Either pmids (non-empty array) or both queryKey and webEnv must be provided.",
+                            message: errorMessage,
+                            details: validationResult.error.flatten(),
                         },
                     }),
                 },
@@ -293,18 +221,13 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
         };
     }
     const ncbiService = getNcbiService();
-    const toolLogicContext = requestContextService.createRequestContext({
-        parentRequestId: parentRequestContext.requestId,
-        operation: "fetchPubMedContentLogic",
-        input: sanitizeInputForLogging(input),
-    });
     logger.info("Executing fetch_pubmed_content tool", toolLogicContext);
     const eFetchParams = { db: "pubmed" };
     let usingHistory = false;
     if (input.queryKey && input.webEnv) {
         usingHistory = true;
         eFetchParams.query_key = input.queryKey;
-        eFetchParams.WebEnv = input.webEnv; // NCBI uses WebEnv with capital E
+        eFetchParams.WebEnv = input.webEnv;
         if (input.retstart !== undefined) {
             eFetchParams.retstart = String(input.retstart);
         }
@@ -315,10 +238,8 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
     else if (input.pmids && input.pmids.length > 0) {
         eFetchParams.id = input.pmids.join(",");
     }
-    // The superRefine ensures that either pmids or (queryKey & webEnv) is provided.
-    let serviceRetmode = "xml"; // Renamed to avoid conflict with local retmode variable if any
+    let serviceRetmode = "xml";
     let rettype;
-    // responseContentType is determined by input.outputFormat at the end
     switch (input.detailLevel) {
         case "full_xml":
             serviceRetmode = "xml";
@@ -329,7 +250,7 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
             break;
         case "abstract_plus":
         case "citation_data":
-            serviceRetmode = "xml"; // Parsed by server, so fetch XML
+            serviceRetmode = "xml";
             break;
     }
     eFetchParams.retmode = serviceRetmode;
@@ -340,11 +261,11 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
         const eFetchBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi";
         const eFetchQueryString = new URLSearchParams(eFetchParams).toString();
         eFetchUrl = `${eFetchBase}?${eFetchQueryString}`;
-        // Determine if raw XML should be fetched
         const shouldReturnRawXml = input.detailLevel === "full_xml" && input.outputFormat === "raw_text";
         const eFetchResponseData = await ncbiService.eFetch(eFetchParams, toolLogicContext, { retmode: serviceRetmode, rettype, returnRawXml: shouldReturnRawXml });
         let finalOutputText;
-        let structuredResponseData; // Used for building the JSON response
+        let structuredResponseData;
+        let articlesCount = 0;
         if (input.detailLevel === "medline_text") {
             const medlineText = String(eFetchResponseData);
             const foundPmidsInMedline = new Set();
@@ -353,6 +274,7 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
             while ((match = pmidRegex.exec(medlineText)) !== null) {
                 foundPmidsInMedline.add(match[1]);
             }
+            articlesCount = foundPmidsInMedline.size;
             let notFoundPmids = [];
             if (input.pmids && input.pmids.length > 0) {
                 notFoundPmids = input.pmids.filter((pmid) => !foundPmidsInMedline.has(pmid));
@@ -375,48 +297,30 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
                         : "GET",
                 },
             };
-            if (input.outputFormat === "raw_text") {
-                finalOutputText = String(eFetchResponseData);
-            }
-            else {
-                finalOutputText = JSON.stringify(structuredResponseData);
-            }
+            finalOutputText =
+                input.outputFormat === "raw_text"
+                    ? medlineText
+                    : JSON.stringify(structuredResponseData);
         }
         else if (input.detailLevel === "full_xml") {
             if (input.outputFormat === "raw_text") {
-                // eFetchResponseData is already the raw XML string due to returnRawXml: true
                 finalOutputText = String(eFetchResponseData);
-                // Optionally, wrap it in a minimal JSON structure if that's preferred for raw_text output consistency
-                // For now, returning the direct XML string as per user expectation for "raw_text"
+                articlesCount = (finalOutputText.match(/<PubmedArticle>/g) || []).length;
             }
             else {
-                // outputFormat is 'json', so eFetchResponseData is the parsed XML object
                 const articlesXml = ensureArray(eFetchResponseData?.PubmedArticleSet?.PubmedArticle || []);
+                articlesCount = articlesXml.length;
                 const articlesPayload = [];
                 const foundPmidsInXml = new Set();
                 for (const articleXml of articlesXml) {
-                    let pmid = "unknown_pmid";
-                    if (articleXml?.MedlineCitation) {
-                        const extracted = extractPmid(articleXml.MedlineCitation);
-                        if (extracted) {
-                            pmid = extracted;
-                        }
-                    }
-                    if (pmid !== "unknown_pmid") {
+                    const pmid = extractPmid(articleXml.MedlineCitation) || "unknown_pmid";
+                    if (pmid !== "unknown_pmid")
                         foundPmidsInXml.add(pmid);
-                    }
-                    articlesPayload.push({
-                        pmid: pmid,
-                        fullXmlContent: articleXml,
-                    });
-                }
-                let notFoundPmids = [];
-                if (input.pmids && input.pmids.length > 0) {
-                    notFoundPmids = input.pmids.filter((pmid) => !foundPmidsInXml.has(pmid));
-                }
-                else if (usingHistory) {
-                    notFoundPmids = "N/A (used history query)";
+                    articlesPayload.push({ pmid, fullXmlContent: articleXml });
                 }
+                const notFoundPmids = input.pmids && input.pmids.length > 0
+                    ? input.pmids.filter((pmid) => !foundPmidsInXml.has(pmid))
+                    : "N/A (used history query)";
                 structuredResponseData = {
                     requestedPmids: input.pmids || "N/A (used history query)",
                     articles: articlesPayload,
@@ -432,17 +336,13 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
             }
         }
         else {
-            // abstract_plus or citation_data (outputFormat is always 'json' effectively)
-            // eFetchResponseData is the parsed XML object
+            // abstract_plus or citation_data
             const parsedArticles = parsePubMedArticleSet(eFetchResponseData, input, toolLogicContext);
+            articlesCount = parsedArticles.length;
             const foundPmids = new Set(parsedArticles.map((p) => p.pmid));
-            let notFoundPmids = [];
-            if (input.pmids && input.pmids.length > 0) {
-                notFoundPmids = input.pmids.filter((pmid) => !foundPmids.has(pmid));
-            }
-            else if (usingHistory) {
-                notFoundPmids = "N/A (used history query)";
-            }
+            const notFoundPmids = input.pmids && input.pmids.length > 0
+                ? input.pmids.filter((pmid) => !foundPmids.has(pmid))
+                : "N/A (used history query)";
             structuredResponseData = {
                 requestedPmids: input.pmids || "N/A (used history query)",
                 articles: parsedArticles,
@@ -471,21 +371,20 @@ export async function fetchPubMedContentLogic(input, parentRequestContext) {
                         year: article.journalInfo?.publicationDate?.year,
                     },
                     doi: article.doi,
-                    // Conditionally include meshTerms if the input flag was set (it defaults to true)
                     ...(input.includeMeshTerms && { meshTerms: article.meshTerms }),
                 }));
             }
-            // For abstract_plus and citation_data, outputFormat 'raw_text' doesn't make sense,
-            // as the data is inherently structured. So, always output JSON.
             finalOutputText = JSON.stringify(structuredResponseData);
         }
+        logger.notice("Successfully executed fetch_pubmed_content tool.", {
+            ...toolLogicContext,
+            detailLevel: input.detailLevel,
+            outputFormat: input.outputFormat,
+            articlesReturned: articlesCount,
+            usingHistory,
+        });
         return {
-            content: [
-                {
-                    type: "text",
-                    text: finalOutputText,
-                },
-            ],
+            content: [{ type: "text", text: finalOutputText }],
             isError: false,
         };
     }

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

@@ -7,4 +7,4 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * Registers the fetch_pubmed_content tool with the MCP server.
  * @param server - The McpServer instance.
  */
-export declare function registerFetchPubMedContentTool(server: McpServer): void;
+export declare function registerFetchPubMedContentTool(server: McpServer): Promise<void>;

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

@@ -2,17 +2,17 @@
  * @fileoverview Registration for the fetch_pubmed_content MCP tool.
  * @module src/mcp-server/tools/fetchPubMedContent/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { ErrorHandler, requestContextService } from "../../../utils/index.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { FetchPubMedContentInputSchema, fetchPubMedContentLogic, } from "./logic.js";
 /**
  * Registers the fetch_pubmed_content tool with the MCP server.
  * @param server - The McpServer instance.
  */
-export function registerFetchPubMedContentTool(server) {
+export async function registerFetchPubMedContentTool(server) {
     const operation = "registerFetchPubMedContentTool";
     const context = requestContextService.createRequestContext({ operation });
-    try {
+    await ErrorHandler.tryCatch(() => {
         server.tool("fetch_pubmed_content", "Fetches detailed information from PubMed using NCBI EFetch. Can be used with a direct list of PMIDs or with queryKey/webEnv from an ESearch history entry. Supports pagination (retstart, retmax) when using history. Available 'detailLevel' options: 'abstract_plus' (parsed title, abstract, authors, journal, keywords, DOI, optional MeSH/grant info), 'full_xml' (JSON representation of the PubMedArticle XML structure), 'medline_text' (MEDLINE format), or 'citation_data' (minimal data for citations). Returns a JSON object containing results, any PMIDs not found (if applicable), and EFetch details.", FetchPubMedContentInputSchema._def.schema.shape, // Access .shape from the ZodObject before superRefine
         async (input, toolContext) => {
             // Added 'any' type for toolContext
@@ -23,15 +23,11 @@ export function registerFetchPubMedContentTool(server) {
             });
             return fetchPubMedContentLogic(input, richContext);
         });
-    }
-    catch (error) {
-        ErrorHandler.handleError(new McpError(BaseErrorCode.INITIALIZATION_FAILED, "Failed to register fetch_pubmed_content tool", {
-            originalError: error instanceof Error ? error.message : String(error),
-        }), {
-            operation,
-            context,
-            errorCode: BaseErrorCode.INITIALIZATION_FAILED,
-            critical: true,
-        });
-    }
+        logger.notice("Tool 'fetch_pubmed_content' registered.", context);
+    }, {
+        operation,
+        context,
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED,
+        critical: true,
+    });
 }