@cyanheads/pubmed-mcp-server 1.1.2 → 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.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. */
@@ -146,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) {

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,
+    });
 }

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

@@ -2,6 +2,11 @@ import * as vega from "vega";
 import * as vegaLite from "vega-lite";
 import { z } from "zod";
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+// IMPORTANT DEPLOYMENT NOTE:
+// This tool uses the 'canvas' package to render PNG images on the server.
+// The 'canvas' package has native system dependencies (e.g., cairo, pango, libjpeg).
+// Ensure these are installed on the deployment environment.
+// See: https://www.npmjs.com/package/canvas#compiling
 import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
 export const GeneratePubMedChartInputSchema = z.object({
     chartType: z
@@ -73,8 +78,6 @@ export const GeneratePubMedChartInputSchema = z.object({
         .enum(["quantitative", "ordinal"])
         .optional()
         .describe("Optional. Specifies the data type of the `sizeField`. Options: 'quantitative', 'ordinal'. Defaults to 'quantitative' if `sizeField` is provided and this is omitted."),
-    // shapeField: z.string().optional().describe("Optional field for encoding point shape in scatter plots."), // Future enhancement
-    // shapeFieldType: z.enum(["nominal", "ordinal"]).optional().describe("Type of the shape field."), // Future enhancement
 });
 export async function generatePubMedChartLogic(input, parentRequestContext) {
     const operationContext = requestContextService.createRequestContext({
@@ -84,9 +87,7 @@ export async function generatePubMedChartLogic(input, parentRequestContext) {
     });
     logger.info(`Executing 'generate_pubmed_chart'. Chart type: ${input.chartType}, Output format: ${input.outputFormat}`, operationContext);
     if (input.outputFormat !== "png") {
-        // Changed from svg to png
-        const unsupportedFormatError = new McpError(BaseErrorCode.VALIDATION_ERROR, `Unsupported output format: ${input.outputFormat}. Currently, only 'png' is supported.`, // Changed message
-        { requestedFormat: input.outputFormat });
+        const unsupportedFormatError = new McpError(BaseErrorCode.VALIDATION_ERROR, `Unsupported output format: ${input.outputFormat}. Currently, only 'png' is supported.`, { requestedFormat: input.outputFormat });
         logger.warning(unsupportedFormatError.message, operationContext);
         return {
             content: [
@@ -105,15 +106,14 @@ export async function generatePubMedChartLogic(input, parentRequestContext) {
         };
     }
     try {
-        let vegaLiteSpec = {
+        const vegaLiteSpec = {
             $schema: "https://vega.github.io/schema/vega-lite/v5.json",
             title: input.title,
             width: input.width,
             height: input.height,
             data: { values: input.dataValues },
-            encoding: {}, // To be populated by chart type specific logic
+            encoding: {},
         };
-        // Default field types if not provided
         const yEncType = input.yFieldType || "quantitative";
         const colorEncType = input.colorFieldType || "nominal";
         const seriesEncType = input.seriesFieldType || "nominal";
@@ -158,14 +158,12 @@ export async function generatePubMedChartLogic(input, parentRequestContext) {
                     },
                 };
                 if (input.seriesField) {
-                    // For line charts, seriesField is typically used for color
                     vegaLiteSpec.encoding.color = {
                         field: input.seriesField,
                         type: seriesEncType,
                     };
                 }
                 else if (input.colorField) {
-                    // Allow direct colorField as well
                     vegaLiteSpec.encoding.color = {
                         field: input.colorField,
                         type: colorEncType,
@@ -174,7 +172,7 @@ export async function generatePubMedChartLogic(input, parentRequestContext) {
                 break;
             case "scatter":
                 xEncType = input.xFieldType || "quantitative";
-                vegaLiteSpec.mark = "point"; // "circle" is also an option
+                vegaLiteSpec.mark = "point";
                 vegaLiteSpec.encoding = {
                     x: {
                         field: input.xField,
@@ -199,28 +197,28 @@ export async function generatePubMedChartLogic(input, parentRequestContext) {
                         type: sizeEncType,
                     };
                 }
-                // Add shape encoding here if shapeField is implemented
                 break;
-            // No default case needed as chartType is an enum and Zod validates it.
         }
         const compiledVegaSpec = vegaLite.compile(vegaLiteSpec).spec;
         const view = new vega.View(vega.parse(compiledVegaSpec), {
-            renderer: "canvas", // Explicitly set renderer to 'canvas'
+            renderer: "canvas",
         });
-        // const svgString = await view.toSVG(); // Old SVG method
-        // New PNG method
-        // Initialize the view to ensure canvas is ready
-        await view.runAsync(); // Initialize and run the view
-        const canvas = await view.toCanvas(); // Render to canvas
-        // Cast to 'any' to access toBuffer, assuming it's a Node Canvas instance at runtime
-        const imageBuffer = await canvas.toBuffer("image/png"); // Get PNG buffer from canvas
+        await view.runAsync();
+        const canvas = await view.toCanvas();
+        const imageBuffer = await canvas.toBuffer("image/png");
         const base64Data = imageBuffer.toString("base64");
+        logger.notice("Successfully generated chart.", {
+            ...operationContext,
+            chartType: input.chartType,
+            outputFormat: input.outputFormat,
+            dataPoints: input.dataValues.length,
+        });
         return {
             content: [
                 {
                     type: "image",
                     data: base64Data,
-                    mimeType: "image/png", // Changed MIME type to image/png
+                    mimeType: "image/png",
                 },
             ],
             isError: false,

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

@@ -4,4 +4,4 @@
  * @module src/mcp-server/tools/generatePubMedChart/registration
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerGeneratePubMedChartTool(server: McpServer): void;
+export declare function registerGeneratePubMedChartTool(server: McpServer): Promise<void>;

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

@@ -1,10 +1,10 @@
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { GeneratePubMedChartInputSchema, generatePubMedChartLogic, } from "./logic.js";
-export function registerGeneratePubMedChartTool(server) {
+export async function registerGeneratePubMedChartTool(server) {
     const operation = "registerGeneratePubMedChartTool";
     const regContext = requestContextService.createRequestContext({ operation });
-    try {
+    await ErrorHandler.tryCatch(() => {
         server.tool("generate_pubmed_chart", "Generates a customizable chart (PNG) from structured data. " +
             "Supports 'bar', 'line', and 'scatter' plots. " +
             "Requires data values and field mappings for axes. " +
@@ -17,20 +17,11 @@ export function registerGeneratePubMedChartTool(server) {
             });
             return generatePubMedChartLogic(validatedInput, handlerRequestContext);
         });
-        logger.notice(`Tool 'generate_pubmed_chart' registered with updated schema (added scatter).`, regContext);
-    }
-    catch (error) {
-        const mcpError = error instanceof McpError
-            ? error
-            : new McpError(BaseErrorCode.INITIALIZATION_FAILED, `Failed to register 'generate_pubmed_chart': ${error instanceof Error ? error.message : String(error)}`, {
-                originalErrorName: error instanceof Error ? error.name : "UnknownError",
-                details: "Error during server.tool() call for generate_pubmed_chart.",
-            });
-        ErrorHandler.handleError(mcpError, {
-            operation,
-            context: regContext,
-            errorCode: BaseErrorCode.INITIALIZATION_FAILED,
-            critical: true,
-        });
-    }
+        logger.notice("Tool 'generate_pubmed_chart' registered.", regContext);
+    }, {
+        operation,
+        context: regContext,
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED,
+        critical: true,
+    });
 }

package/dist/mcp-server/tools/getPubMedArticleConnections/logic/citationFormatter.js

@@ -199,8 +199,8 @@ function formatAsAPA(article, context) {
     }
     const year = journalInfo?.publicationDate?.year || "n.d.";
     const apaTitle = titleText.charAt(0).toUpperCase() + titleText.slice(1); // APA typically sentence case for article titles.
-    const journal = journalInfo?.title ? `<em>${journalInfo.title}</em>` : "N/A";
-    const volume = journalInfo?.volume ? `<em>${journalInfo.volume}</em>` : "";
+    const journal = journalInfo?.title || "N/A";
+    const volume = journalInfo?.volume || "";
     const issue = journalInfo?.issue ? `(${journalInfo.issue})` : "";
     const pages = journalInfo?.pages || "";
     const doiLink = doi ? ` https://doi.org/${doi}` : "";
@@ -253,7 +253,7 @@ function formatAsMLA(article, context) {
         }
     }
     const title = titleText ? `"${titleText}."` : "N/A.";
-    const journal = journalInfo?.title ? `<em>${journalInfo.title}</em>` : "N/A";
+    const journal = journalInfo?.title || "N/A";
     let publicationDateString = journalInfo?.publicationDate?.year || "";
     if (journalInfo?.publicationDate?.month && journalInfo.publicationDate.year) {
         const month = journalInfo.publicationDate.month.substring(0, 3) + "."; // Abbreviate month

package/dist/mcp-server/tools/getPubMedArticleConnections/logic/index.js

@@ -15,7 +15,7 @@ import { handleELinkRelationships } from "./elinkHandler.js";
  */
 export async function handleGetPubMedArticleConnections(input, context) {
     const toolLogicContext = requestContextService.createRequestContext({
-        parentRequestId: context.requestId, // Link to parent context
+        parentRequestId: context.requestId,
         operation: "handleGetPubMedArticleConnections",
         toolName: "get_pubmed_article_connections",
         input: sanitizeInputForLogging(input),
@@ -27,8 +27,8 @@ export async function handleGetPubMedArticleConnections(input, context) {
         relatedArticles: [],
         citations: {},
         retrievedCount: 0,
-        eUtilityUrl: undefined, // Initialize
-        message: undefined, // Initialize
+        eUtilityUrl: undefined,
+        message: undefined,
     };
     try {
         switch (input.relationshipType) {
@@ -41,10 +41,8 @@ export async function handleGetPubMedArticleConnections(input, context) {
                 await handleCitationFormats(input, outputData, toolLogicContext);
                 break;
             default:
-                // This case should ideally be caught by Zod schema validation beforehand
                 throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unsupported relationshipType: ${input.relationshipType}`, { receivedType: input.relationshipType });
         }
-        // Ensure message is set if no specific error but also no results from handlers
         if (outputData.retrievedCount === 0 &&
             !outputData.message &&
             (input.relationshipType !== "citation_formats" ||
@@ -58,7 +56,6 @@ export async function handleGetPubMedArticleConnections(input, context) {
             error instanceof McpError
                 ? error.message
                 : "An unexpected error occurred while processing the request.";
-        // Ensure critical details from McpError are passed through if available
         const errorDetails = error instanceof McpError
             ? error.details
             : { originalError: error.message };
@@ -75,6 +72,12 @@ export async function handleGetPubMedArticleConnections(input, context) {
         ];
         return { content, isError: true };
     }
+    logger.notice("Successfully executed get_pubmed_article_connections tool.", {
+        ...toolLogicContext,
+        relationshipType: input.relationshipType,
+        retrievedCount: outputData.retrievedCount,
+        citationsGenerated: Object.keys(outputData.citations).length,
+    });
     const responseContent = [
         { type: "text", text: JSON.stringify(outputData) },
     ];

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

@@ -31,6 +31,5 @@ export type GetPubMedArticleConnectionsInput = z.infer<typeof GetPubMedArticleCo
 /**
  * Registers the 'get_pubmed_article_connections' tool with the given MCP server instance.
  * @param {McpServer} server - The MCP server instance.
- * @param {RequestContext} registrationContext - The context for this registration operation.
  */
-export declare function registerGetPubMedArticleConnectionsTool(server: McpServer): void;
+export declare function registerGetPubMedArticleConnectionsTool(server: McpServer): Promise<void>;

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

@@ -4,8 +4,8 @@
  * @module src/mcp-server/tools/getPubMedArticleConnections/registration
  */
 import { z } from "zod";
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js"; // Import McpError
-import { ErrorHandler, requestContextService, } from "../../../utils/index.js"; // Import requestContextService
+import { BaseErrorCode } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { handleGetPubMedArticleConnections } from "./logic.js";
 /**
  * Zod schema for the input parameters of the 'get_pubmed_article_connections' tool.
@@ -23,7 +23,7 @@ export const GetPubMedArticleConnectionsInputSchema = z.object({
         "citation_formats",
     ])
         .default("pubmed_similar_articles")
-        .describe("Specifies the type of connection or action: \n- 'pubmed_similar_articles': Finds articles similar to the source PMID (uses ELink `cmd=neighbor`). \n- 'pubmed_citedin': Finds articles in PubMed that cite the source PMID (uses ELink `linkname=pubmed_pubmed_citedin`). \n- 'pubmed_references': Finds articles in PubMed referenced by the source PMID (uses ELink `linkname=pubmed_pubmed_refs`). \n- 'citation_formats': Retrieves data for the source PMID and formats it into specified citation styles (uses EFetch)."),
+        .describe("Specifies the type of connection or action: \n- 'pubmed_similar_articles': Finds articles similar to the source PMID (uses ELink `cmd=neighbor`). \n- 'pubmed_citedin': Finds articles in PubMed that cite the source PMID (uses ELink `linkname=pubmed_pubmed_citedin`). \n- 'pubmed_references': Finds articles in PubMed referenced by the source PMID (uses ELink `linkname=pubmed_pubmed_refs`). \n- 'citation_formats': Retrieves data for the source PMID and formats it into specified citation styles (RIS, BibTeX, APA, MLA via NCBI EFetch and server-side formatting)."),
     maxRelatedResults: z
         .number()
         .int()
@@ -41,36 +41,26 @@ export const GetPubMedArticleConnectionsInputSchema = z.object({
 /**
  * Registers the 'get_pubmed_article_connections' tool with the given MCP server instance.
  * @param {McpServer} server - The MCP server instance.
- * @param {RequestContext} registrationContext - The context for this registration operation.
  */
-export function registerGetPubMedArticleConnectionsTool(server) {
+export async function registerGetPubMedArticleConnectionsTool(server) {
     const operation = "registerGetPubMedArticleConnectionsTool";
     const registrationContext = requestContextService.createRequestContext({
         operation,
     });
-    try {
-        server.tool("get_pubmed_article_connections", "Finds articles related to a source PubMed ID (PMID) or retrieves formatted citations for it. Supports finding similar articles, articles that cite the source, articles referenced by the source (via NCBI ELink), or fetching data to generate citations in various styles (RIS, BibTeX, APA, MLA via NCBI EFetch and server-side formatting). Returns a JSON object detailing the connections or formatted citations.", GetPubMedArticleConnectionsInputSchema.shape, // Pass .shape
-        async (validatedInput, toolContext) => {
-            // Create a new rich context for the logic handler
+    await ErrorHandler.tryCatch(() => {
+        server.tool("get_pubmed_article_connections", "Finds articles related to a source PubMed ID (PMID) or retrieves formatted citations for it. Supports finding similar articles, articles that cite the source, articles referenced by the source (via NCBI ELink), or fetching data to generate citations in various styles (RIS, BibTeX, APA, MLA via NCBI EFetch and server-side formatting). Returns a JSON object detailing the connections or formatted citations.", GetPubMedArticleConnectionsInputSchema.shape, async (validatedInput, toolContext) => {
             const richLogicContext = requestContextService.createRequestContext({
-                parentRequestId: registrationContext.requestId, // Link to registration context
+                parentRequestId: registrationContext.requestId,
                 operation: "getPubMedArticleConnectionsToolHandler",
-                mcpToolContext: toolContext, // Include MCP-provided context
+                mcpToolContext: toolContext,
             });
-            return await handleGetPubMedArticleConnections(validatedInput, richLogicContext);
+            return handleGetPubMedArticleConnections(validatedInput, richLogicContext);
         });
-        // Consistent with other tools, explicit success logging here might be omitted,
-        // relying on ErrorHandler for issues or higher-level logging.
-    }
-    catch (error) {
-        ErrorHandler.handleError(new McpError(// Create an McpError for consistent handling
-        BaseErrorCode.INITIALIZATION_FAILED, "Failed to register 'get_pubmed_article_connections' tool.", {
-            originalError: error instanceof Error ? error.message : String(error),
-        }), {
-            operation,
-            context: registrationContext, // Use the context of the registration operation
-            errorCode: BaseErrorCode.INITIALIZATION_FAILED,
-            critical: true, // Registration failure is critical
-        });
-    }
+        logger.notice("Tool 'get_pubmed_article_connections' registered.", registrationContext);
+    }, {
+        operation,
+        context: registrationContext,
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED,
+        critical: true,
+    });
 }

package/dist/mcp-server/tools/pubmedResearchAgent/logic.d.ts

@@ -6,7 +6,6 @@
  */
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { RequestContext } from "../../../utils/index.js";
-import { // Re-export for registration
-PubMedResearchAgentInput, PubMedResearchAgentInputSchema } from "./logic/index.js";
+import { PubMedResearchAgentInput, PubMedResearchAgentInputSchema } from "./logic/index.js";
 export { PubMedResearchAgentInput, PubMedResearchAgentInputSchema };
 export declare function pubmedResearchAgentLogic(input: PubMedResearchAgentInput, parentRequestContext: RequestContext): Promise<CallToolResult>;

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

@@ -6,9 +6,7 @@
  */
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
-import { generateFullResearchPlanOutline, PubMedResearchAgentInputSchema, // Re-export for registration
- } from "./logic/index.js";
-// Re-export schema and input type for easy access by registration.ts
+import { generateFullResearchPlanOutline, PubMedResearchAgentInputSchema, } from "./logic/index.js";
 export { PubMedResearchAgentInputSchema };
 export async function pubmedResearchAgentLogic(input, parentRequestContext) {
     const operationContext = requestContextService.createRequestContext({
@@ -19,6 +17,10 @@ export async function pubmedResearchAgentLogic(input, parentRequestContext) {
     logger.info(`Executing 'pubmed_research_agent' to generate research plan outline. Keywords: ${input.research_keywords.join(", ")}`, operationContext);
     try {
         const researchPlanOutline = generateFullResearchPlanOutline(input, operationContext);
+        logger.notice("Successfully generated research plan outline.", {
+            ...operationContext,
+            projectTitle: input.project_title_suggestion,
+        });
         return {
             content: [
                 { type: "text", text: JSON.stringify(researchPlanOutline, null, 2) },
@@ -30,11 +32,10 @@ export async function pubmedResearchAgentLogic(input, parentRequestContext) {
         logger.error("Execution failed for 'pubmed_research_agent'", error, operationContext);
         const mcpError = error instanceof McpError
             ? error
-            : new McpError(BaseErrorCode.INTERNAL_ERROR, // Using a generic internal error
-            `'pubmed_research_agent' tool failed during plan outline generation: ${error.message || "Internal server error."}`, {
+            : new McpError(BaseErrorCode.INTERNAL_ERROR, `'pubmed_research_agent' tool failed during plan outline generation: ${error.message || "Internal server error."}`, {
                 originalErrorName: error.name,
                 requestId: operationContext.requestId,
-                inputKeywords: input.research_keywords, // Adding some input context to error
+                inputKeywords: input.research_keywords,
             });
         return {
             content: [

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

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

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

@@ -2,17 +2,17 @@
  * @fileoverview Registration for the pubmed_research_agent tool.
  * @module pubmedResearchAgent/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { PubMedResearchAgentInputSchema, pubmedResearchAgentLogic, } from "./logic.js";
 /**
  * Registers the pubmed_research_agent tool with the MCP server.
  * @param server - The McpServer instance.
  */
-export function registerPubMedResearchAgentTool(server) {
+export async function registerPubMedResearchAgentTool(server) {
     const operation = "registerPubMedResearchAgentTool";
     const context = requestContextService.createRequestContext({ operation });
-    try {
+    await ErrorHandler.tryCatch(() => {
         server.tool("pubmed_research_agent", "Generates a standardized JSON research plan outline from component details you provide. It accepts granular inputs for all research phases (conception, data collection, analysis, dissemination, cross-cutting concerns). If `include_detailed_prompts_for_agent` is true, the output plan will embed instructive prompts and detailed guidance notes to aid the research agent. The tool's primary function is to organize and structure your rough ideas into a formal, machine-readable plan. This plan is intended for further processing; as the research agent, you should then utilize your full suite of tools (e.g., file manipulation, `get_pubmed_article_connections` for literature/data search via PMID) to execute the outlined research, tailored to the user's request.", PubMedResearchAgentInputSchema.shape, async (validatedInput, mcpProvidedContext) => {
             const handlerRequestContext = requestContextService.createRequestContext({
                 parentRequestId: context.requestId,
@@ -22,15 +22,10 @@ export function registerPubMedResearchAgentTool(server) {
             return pubmedResearchAgentLogic(validatedInput, handlerRequestContext);
         });
         logger.notice(`Tool 'pubmed_research_agent' registered.`, context);
-    }
-    catch (error) {
-        ErrorHandler.handleError(new McpError(BaseErrorCode.INITIALIZATION_FAILED, "Failed to register pubmed_research_agent tool", {
-            originalError: error instanceof Error ? error.message : String(error),
-        }), {
-            operation,
-            context,
-            errorCode: BaseErrorCode.INITIALIZATION_FAILED,
-            critical: true,
-        });
-    }
+    }, {
+        operation,
+        context,
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED,
+        critical: true,
+    });
 }

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

@@ -140,10 +140,9 @@ export async function searchPubMedArticlesLogic(input, parentRequestContext) {
             if (esResult.WebEnv && esResult.QueryKey) {
                 eSummaryParams.WebEnv = esResult.WebEnv;
                 eSummaryParams.query_key = esResult.QueryKey;
-                eSummaryParams.retmax = currentFetchBriefSummaries; // Use history with retmax
+                eSummaryParams.retmax = currentFetchBriefSummaries;
             }
             else {
-                // Fallback to using explicit IDs if history is not available (should not happen if usehistory='y' was successful)
                 const pmidsForSummary = pmids
                     .slice(0, currentFetchBriefSummaries)
                     .join(",");
@@ -185,13 +184,19 @@ export async function searchPubMedArticlesLogic(input, parentRequestContext) {
             effectiveESearchTerm: effectiveQuery,
             totalFound,
             retrievedPmidCount,
-            pmids, // These are the PMIDs from ESearch, limited by input.maxResults
-            briefSummaries, // These should now be limited by currentFetchBriefSummaries
+            pmids,
+            briefSummaries,
             eSearchUrl,
             eSummaryUrl: currentFetchBriefSummaries > 0 && pmids.length > 0
                 ? eSummaryUrl
                 : undefined,
         };
+        logger.notice("Successfully executed searchPubMedArticles tool.", {
+            ...toolLogicContext,
+            totalFound,
+            retrievedPmidCount,
+            summariesFetched: briefSummaries.length,
+        });
         return {
             content: [{ type: "text", text: JSON.stringify(resultPayload) }],
             isError: false,

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

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

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

@@ -2,37 +2,30 @@
  * @fileoverview Registration for the searchPubMedArticles MCP tool.
  * @module src/mcp-server/tools/searchPubMedArticles/registration
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js"; // Import McpError
-import { ErrorHandler, requestContextService } from "../../../utils/index.js";
+import { BaseErrorCode } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { SearchPubMedArticlesInputSchema, searchPubMedArticlesLogic, } from "./logic.js";
 /**
  * Registers the searchPubMedArticles tool with the MCP server.
  * @param server - The McpServer instance.
  */
-export function registerSearchPubMedArticlesTool(server) {
+export async function registerSearchPubMedArticlesTool(server) {
     const operation = "registerSearchPubMedArticlesTool";
     const context = requestContextService.createRequestContext({ operation });
-    try {
-        server.tool("search_pubmed_articles", "Searches PubMed for articles using a query term and optional filters (max results, sort, date range, publication types). Uses NCBI ESearch to find PMIDs and ESummary (optional) for brief summaries. Returns a JSON object with search parameters, ESearch term, result counts, PMIDs, optional summaries (PMID, title, authors, source, dates), and E-utility URLs.", SearchPubMedArticlesInputSchema.shape, // Pass the .shape for ZodRawShape
-        async (input, toolContext) => {
-            // Explicitly type input
+    await ErrorHandler.tryCatch(() => {
+        server.tool("search_pubmed_articles", "Searches PubMed for articles using a query term and optional filters (max results, sort, date range, publication types). Uses NCBI ESearch to find PMIDs and ESummary (optional) for brief summaries. Returns a JSON object with search parameters, ESearch term, result counts, PMIDs, optional summaries (PMID, title, authors, source, dates), and E-utility URLs.", SearchPubMedArticlesInputSchema.shape, async (input, toolContext) => {
             const richContext = requestContextService.createRequestContext({
                 parentRequestId: context.requestId,
                 operation: "searchPubMedArticlesToolHandler",
-                mcpToolContext: toolContext, // Include MCP-provided context if any
+                mcpToolContext: toolContext,
             });
             return searchPubMedArticlesLogic(input, richContext);
         });
-    }
-    catch (error) {
-        ErrorHandler.handleError(new McpError(// Create an McpError for consistent handling
-        BaseErrorCode.INITIALIZATION_FAILED, "Failed to register searchPubMedArticles tool", {
-            originalError: error instanceof Error ? error.message : String(error),
-        }), {
-            operation,
-            context,
-            errorCode: BaseErrorCode.INITIALIZATION_FAILED, // errorCode is still useful for categorization
-            critical: true,
-        });
-    }
+        logger.notice("Tool 'search_pubmed_articles' registered.", context);
+    }, {
+        operation,
+        context,
+        errorCode: BaseErrorCode.INITIALIZATION_FAILED,
+        critical: true,
+    });
 }

package/dist/mcp-server/transports/httpTransport.js

@@ -54,6 +54,11 @@ const MAX_PORT_RETRIES = 15;
  * Stores active `StreamableHTTPServerTransport` instances from the SDK, keyed by their session ID.
  * This is essential for routing subsequent HTTP requests (GET, DELETE, non-initialize POST)
  * to the correct stateful session transport instance.
+ *
+ * @scalability Note: This is an in-memory store. For horizontal scaling across
+ * multiple processes or machines, this state would need to be moved to a shared,
+ * distributed store like Redis or a database.
+ *
  * @type {Record<string, StreamableHTTPServerTransport>}
  * @private
  */
@@ -61,6 +66,10 @@ const httpTransports = {};
 /**
  * Stores the last activity timestamp for each session, keyed by session ID.
  * Used for garbage collecting stale/abandoned sessions.
+ *
+ * @scalability Note: This is an in-memory store. Like `httpTransports`, this
+ * would need to be moved to a distributed store for multi-instance deployments.
+ *
  * @type {Record<string, number>}
  * @private
  */

package/dist/utils/security/rateLimiter.d.ts

@@ -28,6 +28,10 @@ export interface RateLimitEntry {
 /**
  * A generic rate limiter class using an in-memory store.
  * Controls frequency of operations based on unique keys.
+ *
+ * @scalability Note: This is an in-memory store. For horizontal scaling across
+ * multiple processes or machines, this state would need to be moved to a shared,
+ * distributed store like Redis or a database.
  */
 export declare class RateLimiter {
     private config;

package/dist/utils/security/rateLimiter.js

@@ -9,6 +9,10 @@ import { logger, requestContextService } from "../index.js";
 /**
  * A generic rate limiter class using an in-memory store.
  * Controls frequency of operations based on unique keys.
+ *
+ * @scalability Note: This is an in-memory store. For horizontal scaling across
+ * multiple processes or machines, this state would need to be moved to a shared,
+ * distributed store like Redis or a database.
  */
 export class RateLimiter {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/pubmed-mcp-server",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "A Model Context Protocol (MCP) server enabling AI agents to intelligently search, retrieve, and analyze biomedical literature from PubMed via NCBI E-utilities. Built on the mcp-ts-template for robust, production-ready performance.",
   "main": "dist/index.js",
   "files": [