@cyanheads/pubmed-mcp-server 1.0.12

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

@@ -0,0 +1,229 @@
+/**
+ * @fileoverview Logic for the searchPubMedArticles MCP tool.
+ * Handles constructing ESearch and ESummary queries, interacting with
+ * the NcbiService, and formatting the results.
+ * @module src/mcp-server/tools/searchPubMedArticles/logic
+ */
+import { z } from "zod";
+import { ncbiService } from "../../../services/NCBI/ncbiService.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
+import { extractBriefSummaries } from "../../../utils/parsing/ncbi-parsing/index.js";
+import { sanitization } from "../../../utils/security/sanitization.js";
+export const SearchPubMedArticlesInputSchema = z.object({
+    queryTerm: z
+        .string()
+        .min(3, "Query term must be at least 3 characters")
+        .describe("The primary keyword or phrase to search for in PubMed. Must be at least 3 characters long."),
+    maxResults: z
+        .number()
+        .int()
+        .positive()
+        .max(1000, "Max results per query. ESearch's retmax is used.")
+        .optional()
+        .default(20)
+        .describe("Maximum number of articles to retrieve. Corresponds to ESearch's 'retmax' parameter. Default is 20, max is 1000."),
+    sortBy: z
+        .enum(["relevance", "pub_date", "author", "journal_name"])
+        .optional()
+        .default("relevance")
+        .describe("Sorting criteria for results. Options: 'relevance' (default), 'pub_date', 'author', 'journal_name'. Note: Other sorting (e.g., last_author, title) may require client-side implementation or be future server enhancements."),
+    dateRange: z
+        .object({
+        minDate: z
+            .string()
+            .regex(/^\d{4}(\/\d{2}(\/\d{2})?)?$/, "Date must be YYYY, YYYY/MM, or YYYY/MM/DD")
+            .optional()
+            .describe("The start date for the search range (YYYY, YYYY/MM, or YYYY/MM/DD)."),
+        maxDate: z
+            .string()
+            .regex(/^\d{4}(\/\d{2}(\/\d{2})?)?$/, "Date must be YYYY, YYYY/MM, or YYYY/MM/DD")
+            .optional()
+            .describe("The end date for the search range (YYYY, YYYY/MM, or YYYY/MM/DD)."),
+        dateType: z
+            .enum(["pdat", "mdat", "edat"])
+            .optional()
+            .default("pdat")
+            .describe("The type of date to filter by: 'pdat' (Publication Date), 'mdat' (Modification Date), 'edat' (Entrez Date). Default is 'pdat'."),
+    })
+        .optional()
+        .describe("Defines an optional date range for the search, including min/max dates and the type of date field to use."),
+    filterByPublicationTypes: z
+        .array(z.string())
+        .optional()
+        .describe('An array of publication types to filter by (e.g., ["Review", "Clinical Trial"]). The server maps these to the appropriate Entrez query syntax (e.g., "Review"[Publication Type]).'),
+    fetchBriefSummaries: z
+        .number()
+        .int()
+        .min(0)
+        .max(50)
+        .optional()
+        .default(0)
+        .describe("Number of top PMIDs for which to fetch brief summaries using ESummary v2.0. Set to 0 to disable. Maximum is 50 for this tool. Default is 0."),
+});
+/**
+ * Logic for the searchPubMedArticles tool.
+ * Constructs and executes ESearch and optionally ESummary queries via NcbiService,
+ * then formats the results into a CallToolResult.
+ * @param input - Validated input arguments for the tool.
+ * @param parentRequestContext - The parent request context for logging and correlation.
+ * @returns A promise resolving to a CallToolResult.
+ */
+export async function searchPubMedArticlesLogic(input, parentRequestContext) {
+    const toolLogicContext = requestContextService.createRequestContext({
+        parentRequestId: parentRequestContext.requestId,
+        operation: "searchPubMedArticlesLogic",
+        input: sanitizeInputForLogging(input),
+    });
+    logger.info("Executing searchPubMedArticles tool", toolLogicContext);
+    let effectiveQuery = sanitization.sanitizeString(input.queryTerm, {
+        context: "text",
+    });
+    if (input.dateRange) {
+        const { minDate, maxDate, dateType } = input.dateRange;
+        if (minDate && maxDate) {
+            effectiveQuery += ` AND (${minDate}[${dateType}] : ${maxDate}[${dateType}])`;
+        }
+        else if (minDate) {
+            effectiveQuery += ` AND ${minDate}[${dateType}]`;
+        }
+        else if (maxDate) {
+            effectiveQuery += ` AND ${maxDate}[${dateType}]`;
+        }
+    }
+    if (input.filterByPublicationTypes &&
+        input.filterByPublicationTypes.length > 0) {
+        const ptQuery = input.filterByPublicationTypes
+            .map((pt) => `"${sanitization.sanitizeString(pt, { context: "text" })}"[Publication Type]`)
+            .join(" OR ");
+        effectiveQuery += ` AND (${ptQuery})`;
+    }
+    const currentFetchBriefSummaries = input.fetchBriefSummaries ?? 0;
+    const eSearchParams = {
+        db: "pubmed",
+        term: effectiveQuery,
+        retmax: input.maxResults,
+        sort: input.sortBy,
+        usehistory: currentFetchBriefSummaries > 0 ? "y" : "n",
+    };
+    let eSearchUrl = "";
+    let eSummaryUrl = "";
+    try {
+        const eSearchResponse = await ncbiService.eSearch(eSearchParams, toolLogicContext);
+        const eSearchBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi";
+        const eSearchQueryStringParams = {};
+        for (const key in eSearchParams) {
+            if (eSearchParams[key] !== undefined) {
+                eSearchQueryStringParams[key] = String(eSearchParams[key]);
+            }
+        }
+        const eSearchQueryString = new URLSearchParams(eSearchQueryStringParams).toString();
+        eSearchUrl = `${eSearchBase}?${eSearchQueryString}`;
+        if (!eSearchResponse || !eSearchResponse.eSearchResult) {
+            throw new McpError(BaseErrorCode.NCBI_PARSING_ERROR, "Invalid or empty ESearch response from NCBI.", {
+                responsePreview: sanitizeInputForLogging(JSON.stringify(eSearchResponse).substring(0, 200)),
+                requestId: toolLogicContext.requestId,
+            });
+        }
+        const esResult = eSearchResponse.eSearchResult;
+        const pmids = esResult.IdList?.Id || [];
+        const totalFound = parseInt(esResult.Count || "0", 10);
+        const retrievedPmidCount = pmids.length;
+        let briefSummaries = [];
+        if (currentFetchBriefSummaries > 0 && pmids.length > 0) {
+            const eSummaryParams = {
+                db: "pubmed",
+                version: "2.0",
+                retmode: "xml",
+            };
+            if (esResult.WebEnv && esResult.QueryKey) {
+                eSummaryParams.WebEnv = esResult.WebEnv;
+                eSummaryParams.query_key = esResult.QueryKey;
+                eSummaryParams.retmax = currentFetchBriefSummaries; // Use history with retmax
+            }
+            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(",");
+                eSummaryParams.id = pmidsForSummary;
+            }
+            const eSummaryBase = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi";
+            const eSummaryQueryStringParams = {};
+            for (const key in eSummaryParams) {
+                if (eSummaryParams[key] !== undefined) {
+                    eSummaryQueryStringParams[key] = String(eSummaryParams[key]);
+                }
+            }
+            const eSummaryQueryString = new URLSearchParams(eSummaryQueryStringParams).toString();
+            eSummaryUrl = `${eSummaryBase}?${eSummaryQueryString}`;
+            const eSummaryResponseXml = await ncbiService.eSummary(eSummaryParams, toolLogicContext);
+            logger.debug("Raw ESummary Response (XML parsed by ncbiService):", {
+                ...toolLogicContext,
+                eSummaryResponse: sanitizeInputForLogging(eSummaryResponseXml),
+            });
+            if (eSummaryResponseXml && eSummaryResponseXml.eSummaryResult) {
+                briefSummaries = await extractBriefSummaries(eSummaryResponseXml.eSummaryResult, toolLogicContext);
+            }
+            else if (eSummaryResponseXml && eSummaryResponseXml.ERROR) {
+                logger.warning("ESummary returned a top-level error", {
+                    ...toolLogicContext,
+                    errorDetails: eSummaryResponseXml.ERROR,
+                });
+            }
+        }
+        const resultPayload = {
+            searchParameters: {
+                queryTerm: input.queryTerm,
+                maxResults: input.maxResults,
+                sortBy: input.sortBy,
+                dateRange: input.dateRange,
+                filterByPublicationTypes: input.filterByPublicationTypes,
+                fetchBriefSummaries: currentFetchBriefSummaries,
+            },
+            effectiveESearchTerm: effectiveQuery,
+            totalFound,
+            retrievedPmidCount,
+            pmids, // These are the PMIDs from ESearch, limited by input.maxResults
+            briefSummaries, // These should now be limited by currentFetchBriefSummaries
+            eSearchUrl,
+            eSummaryUrl: currentFetchBriefSummaries > 0 && pmids.length > 0
+                ? eSummaryUrl
+                : undefined,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(resultPayload) }],
+            isError: false,
+        };
+    }
+    catch (error) {
+        logger.error("Error in searchPubMedArticlesLogic", error, toolLogicContext);
+        const mcpError = error instanceof McpError
+            ? error
+            : new McpError(BaseErrorCode.INTERNAL_ERROR, "Failed to search PubMed articles due to an unexpected error.", {
+                originalErrorName: error.name,
+                originalErrorMessage: error.message,
+                requestId: toolLogicContext.requestId,
+            });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: {
+                            code: mcpError.code,
+                            message: mcpError.message,
+                            details: mcpError.details,
+                        },
+                        searchParameters: sanitizeInputForLogging(input),
+                        eSearchUrl,
+                        eSummaryUrl: (input.fetchBriefSummaries ?? 0) > 0 && eSummaryUrl
+                            ? eSummaryUrl
+                            : undefined,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Registration for the searchPubMedArticles MCP tool.
+ * @module src/mcp-server/tools/searchPubMedArticles/registration
+ */
+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;

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

@@ -0,0 +1,38 @@
+/**
+ * @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 { SearchPubMedArticlesInputSchema, searchPubMedArticlesLogic, } from "./logic.js";
+/**
+ * Registers the searchPubMedArticles tool with the MCP server.
+ * @param server - The McpServer instance.
+ */
+export 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
+            const richContext = requestContextService.createRequestContext({
+                parentRequestId: context.requestId,
+                operation: "searchPubMedArticlesToolHandler",
+                mcpToolContext: toolContext, // Include MCP-provided context if any
+            });
+            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,
+        });
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview MCP Authentication Middleware for Bearer Token Validation (JWT).
+ *
+ * This middleware validates JSON Web Tokens (JWT) passed via the 'Authorization' header
+ * using the 'Bearer' scheme (e.g., "Authorization: Bearer <your_token>").
+ * It verifies the token's signature and expiration using the secret key defined
+ * in the configuration (`config.mcpAuthSecretKey`).
+ *
+ * If the token is valid, an object conforming to the MCP SDK's `AuthInfo` type
+ * (expected to contain `token`, `clientId`, and `scopes`) is attached to `req.auth`.
+ * If the token is missing, invalid, or expired, it sends an HTTP 401 Unauthorized response.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ * @module src/mcp-server/transports/authentication/authMiddleware
+ */
+import { NextFunction, Request, Response } from "express";
+import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+declare global {
+    namespace Express {
+        interface Request {
+            /** Authentication information derived from the JWT, conforming to MCP SDK's AuthInfo. */
+            auth?: AuthInfo;
+        }
+    }
+}
+/**
+ * Express middleware for verifying JWT Bearer token authentication.
+ */
+export declare function mcpAuthMiddleware(req: Request, res: Response, next: NextFunction): void;

package/dist/mcp-server/transports/authentication/authMiddleware.js

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview MCP Authentication Middleware for Bearer Token Validation (JWT).
+ *
+ * This middleware validates JSON Web Tokens (JWT) passed via the 'Authorization' header
+ * using the 'Bearer' scheme (e.g., "Authorization: Bearer <your_token>").
+ * It verifies the token's signature and expiration using the secret key defined
+ * in the configuration (`config.mcpAuthSecretKey`).
+ *
+ * If the token is valid, an object conforming to the MCP SDK's `AuthInfo` type
+ * (expected to contain `token`, `clientId`, and `scopes`) is attached to `req.auth`.
+ * If the token is missing, invalid, or expired, it sends an HTTP 401 Unauthorized response.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ * @module src/mcp-server/transports/authentication/authMiddleware
+ */
+import jwt from "jsonwebtoken";
+import { config, environment } from "../../../config/index.js";
+import { logger, requestContextService } from "../../../utils/index.js";
+// Startup Validation: Validate secret key presence on module load.
+if (environment === "production" && !config.mcpAuthSecretKey) {
+    logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment. Authentication cannot proceed securely.");
+    throw new Error("MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.");
+}
+else if (!config.mcpAuthSecretKey) {
+    logger.warning("MCP_AUTH_SECRET_KEY is not set. Authentication middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
+}
+/**
+ * Express middleware for verifying JWT Bearer token authentication.
+ */
+export function mcpAuthMiddleware(req, res, next) {
+    const context = requestContextService.createRequestContext({
+        operation: "mcpAuthMiddleware",
+        method: req.method,
+        path: req.path,
+    });
+    logger.debug("Running MCP Authentication Middleware (Bearer Token Validation)...", context);
+    // Development Mode Bypass
+    if (!config.mcpAuthSecretKey) {
+        if (environment !== "production") {
+            logger.warning("Bypassing JWT authentication: MCP_AUTH_SECRET_KEY is not set (DEVELOPMENT ONLY).", context);
+            // Populate req.auth strictly according to SDK's AuthInfo
+            req.auth = {
+                token: "dev-mode-placeholder-token",
+                clientId: "dev-client-id",
+                scopes: ["dev-scope"],
+            };
+            // Log dev mode details separately, not attaching to req.auth if not part of AuthInfo
+            logger.debug("Dev mode auth object created.", {
+                ...context,
+                authDetails: req.auth,
+            });
+            return next();
+        }
+        else {
+            logger.error("FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.", context);
+            res.status(500).json({
+                error: "Server configuration error: Authentication key missing.",
+            });
+            return;
+        }
+    }
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        logger.warning("Authentication failed: Missing or malformed Authorization header (Bearer scheme required).", context);
+        res.status(401).json({
+            error: "Unauthorized: Missing or invalid authentication token format.",
+        });
+        return;
+    }
+    const tokenParts = authHeader.split(" ");
+    if (tokenParts.length !== 2 || tokenParts[0] !== "Bearer" || !tokenParts[1]) {
+        logger.warning("Authentication failed: Malformed Bearer token.", context);
+        res
+            .status(401)
+            .json({ error: "Unauthorized: Malformed authentication token." });
+        return;
+    }
+    const rawToken = tokenParts[1];
+    try {
+        const decoded = jwt.verify(rawToken, config.mcpAuthSecretKey);
+        if (typeof decoded === "string") {
+            logger.warning("Authentication failed: JWT decoded to a string, expected an object payload.", context);
+            res
+                .status(401)
+                .json({ error: "Unauthorized: Invalid token payload format." });
+            return;
+        }
+        // Extract and validate fields for SDK's AuthInfo
+        const clientIdFromToken = typeof decoded.cid === "string"
+            ? decoded.cid
+            : typeof decoded.client_id === "string"
+                ? decoded.client_id
+                : undefined;
+        if (!clientIdFromToken) {
+            logger.warning("Authentication failed: JWT 'cid' or 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            res.status(401).json({
+                error: "Unauthorized: Invalid token, missing client identifier.",
+            });
+            return;
+        }
+        let scopesFromToken;
+        if (Array.isArray(decoded.scp) &&
+            decoded.scp.every((s) => typeof s === "string")) {
+            scopesFromToken = decoded.scp;
+        }
+        else if (typeof decoded.scope === "string" &&
+            decoded.scope.trim() !== "") {
+            scopesFromToken = decoded.scope.split(" ").filter((s) => s);
+            if (scopesFromToken.length === 0 && decoded.scope.trim() !== "") {
+                // handles case " " -> [""]
+                scopesFromToken = [decoded.scope.trim()];
+            }
+            else if (scopesFromToken.length === 0 && decoded.scope.trim() === "") {
+                // If scope is an empty string, treat as no scopes rather than erroring, or use a default.
+                // Depending on strictness, could also error here. For now, allow empty array if scope was empty string.
+                logger.debug("JWT 'scope' claim was an empty string, resulting in empty scopes array.", context);
+            }
+        }
+        else {
+            // If scopes are strictly mandatory and not found or invalid format
+            logger.warning("Authentication failed: JWT 'scp' or 'scope' claim is missing, not an array of strings, or not a valid space-separated string. Assigning default empty array of scopes.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
+            // Default to empty array if scopes are not found or are in an invalid format.
+            // IMPORTANT: Downstream authorization logic MUST be aware of this default.
+            // If specific scopes are mandatory for certain operations, that logic needs to check
+            // for the presence and validity of required scopes in this `scopesFromToken` array.
+            // An empty array here means no specific scopes were granted by this token,
+            // which might restrict access depending on the authorization rules.
+            scopesFromToken = [];
+            // If truly mandatory and must be non-empty for *all* authenticated requests,
+            // an alternative would be to reject the token here:
+            // res.status(401).json({ error: "Unauthorized: Invalid token, missing or invalid scopes." });
+            // return;
+        }
+        // Construct req.auth with only the properties defined in SDK's AuthInfo
+        // All other claims from 'decoded' are not part of req.auth for type safety.
+        req.auth = {
+            token: rawToken,
+            clientId: clientIdFromToken,
+            scopes: scopesFromToken,
+        };
+        // Log separately if other JWT claims like 'sub' (sessionId) are needed for app logic
+        const subClaimForLogging = typeof decoded.sub === "string" ? decoded.sub : undefined;
+        logger.debug("JWT verified successfully. AuthInfo attached to request.", {
+            ...context,
+            mcpSessionIdContext: subClaimForLogging,
+            clientId: req.auth.clientId,
+            scopes: req.auth.scopes,
+        });
+        next();
+    }
+    catch (error) {
+        let errorMessage = "Invalid token";
+        if (error instanceof jwt.TokenExpiredError) {
+            errorMessage = "Token expired";
+            logger.warning("Authentication failed: Token expired.", {
+                ...context,
+                expiredAt: error.expiredAt,
+            });
+        }
+        else if (error instanceof jwt.JsonWebTokenError) {
+            errorMessage = `Invalid token: ${error.message}`;
+            logger.warning(`Authentication failed: ${errorMessage}`, { ...context });
+        }
+        else if (error instanceof Error) {
+            errorMessage = `Verification error: ${error.message}`;
+            logger.error("Authentication failed: Unexpected error during token verification.", { ...context, error: error.message });
+        }
+        else {
+            errorMessage = "Unknown verification error";
+            logger.error("Authentication failed: Unexpected non-error exception during token verification.", { ...context, error });
+        }
+        res.status(401).json({ error: `Unauthorized: ${errorMessage}.` });
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Handles the setup and management of the Streamable HTTP MCP transport.
+ * Implements the MCP Specification 2025-03-26 for Streamable HTTP.
+ * This includes creating an Express server, configuring middleware (CORS, Authentication),
+ * defining request routing for the single MCP endpoint (POST/GET/DELETE),
+ * managing server-side sessions, handling Server-Sent Events (SSE) for streaming,
+ * and binding to a network port with retry logic for port conflicts.
+ *
+ * Specification Reference:
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http
+ * @module src/mcp-server/transports/httpTransport
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestContext } from "../../utils/index.js";
+/**
+ * Sets up and starts the Streamable HTTP transport layer for the MCP server.
+ *
+ * @param createServerInstanceFn - An asynchronous factory function that returns a new `McpServer` instance.
+ * @param parentContext - Logging context from the main server startup process.
+ * @returns A promise that resolves when the HTTP server is successfully listening.
+ * @throws {Error} If the server fails to start after all port retries.
+ */
+export declare function startHttpTransport(createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Promise<void>;