PubMed MCP Server

Instructions

Implementation Reference

• src/mcp-server/tools/pubmedResearchAgent/logic/planOrchestrator.ts:120-470 (handler)

  Core handler logic: generates the full structured PubMed research plan JSON from granular input fields, intelligently omitting empty sections, optionally embedding detailed agent prompts, and ensuring clean output.
  export function generateFullResearchPlanOutline( input: PubMedResearchAgentInput, parentRequestContext: RequestContext, ): PubMedResearchPlanGeneratedOutput { const logContext = requestContextService.createRequestContext({ parentRequestId: parentRequestContext.requestId, operation: "generateFullResearchPlanOutlineLog", input: sanitizeInputForLogging({ input }), // Add sanitized input here }); logger.debug("Generating full research plan outline.", logContext); const inferredGoal = input.primary_research_goal || `to investigate the roles and mechanisms of ${input.research_keywords.join(" and ")}${input.organism_focus ? ` in ${input.organism_focus}` : ""}.`; const planTitle = input.project_title_suggestion || `Research Plan Outline: ${inferredGoal}`; const addPrompts = input.include_detailed_prompts_for_agent; const overallInstructions = `This document is a structured research plan outline, primarily assembled from detailed inputs for project: "${planTitle}". As the research agent, critically evaluate this plan. Your primary function is to fulfill the user's research request by leveraging this structured information alongside your comprehensive knowledge and all available tools (e.g., PubMed search, web search, data analysis, file operations). Key responsibilities: - Synthesize information to generate scientifically sound content, analyses, or answers. - Adapt the level of detail in your final response to precisely match the user's specific query. If a concise answer is requested, use this plan as foundational background. - Proactively identify and address potential ambiguities, biases, or limitations in the provided plan or data. - Ensure methodological rigor: consider controls, statistical power, reproducibility, and alternative explanations. - If critical information is missing or ambiguities hinder robust execution, formulate specific, targeted follow-up questions for the user before proceeding with extensive investigation. - Always prioritize accuracy, objectivity, and adherence to scientific best practices.`; const p1s1Content: Phase1Step1_1_Content = { primary_research_question: C( input.p1_specific_research_question, "Critically evaluate and refine the primary research question for clarity, focus, and feasibility", addPrompts, ), knowledge_gap_statement: C( input.p1_knowledge_gap, "Validate and expand on the identified knowledge gap, ensuring it's well-supported by current literature", addPrompts, ), primary_hypothesis: C( input.p1_primary_hypothesis, "Assess the primary hypothesis for testability, specificity, and falsifiability. Consider alternative hypotheses", addPrompts, ), pubmed_search_strategy: C( input.p1_pubmed_search_strategy_description, "Develop a comprehensive PubMed search strategy. Consider MeSH terms, keywords, Boolean operators, and inclusion/exclusion criteria", addPrompts, ), guidance_notes: G( [ "Ensure the research question is SMART (Specific, Measurable, Achievable, Relevant, Time-bound).", "Verify the knowledge gap is current and significant.", "The hypothesis should directly address the research question.", "Consider publication type filters and date ranges for the literature search.", ], addPrompts, ), }; const p1s2Content: Phase1Step1_2_Content = { literature_review_scope: C( input.p1_literature_review_scope, "Define and justify the scope of the literature review, including timeframes, study types, and key themes to investigate", addPrompts, ), key_databases_and_search_approach: C( input.p1_lit_review_databases_and_approach, "Detail the systematic search approach across specified databases (e.g., PubMed, EMBASE, Scopus). Include strategy for citation searching or snowballing", addPrompts, ), guidance_notes: G( [ "Document search queries and results for reproducibility.", "Consider using reference management software.", "Plan for screening and selection of articles based on predefined criteria.", ], addPrompts, ), }; const p1s3Content: Phase1Step1_3_Content = { experimental_paradigm: C( input.p1_experimental_paradigm, "Elaborate on the chosen experimental paradigm, justifying its appropriateness for testing the hypothesis", addPrompts, ), data_acquisition_plan_existing_data: C( input.p1_data_acquisition_plan_existing_data, "Strategize the identification, retrieval, and validation of relevant existing datasets. Specify databases, data types, and access protocols", addPrompts, ), data_acquisition_plan_new_data: C( input.p1_data_acquisition_plan_new_data, "Outline the plan for generating novel data, including experimental models, key procedures, sample size considerations, and data deposition strategy", addPrompts, ), blast_utilization_plan: C( input.p1_blast_utilization_plan, "Specify how sequence alignment tools (e.g., NCBI BLAST) will be employed, including purpose, programs, databases, and interpretation of results", addPrompts, ), controls_and_rigor_measures: C( input.p1_controls_and_rigor, "Detail crucial experimental controls (positive, negative, internal) and measures to ensure scientific rigor, reproducibility, and minimization of bias", addPrompts, ), methodological_challenges_and_mitigation: C( input.p1_methodological_challenges_and_mitigation, "Anticipate potential methodological challenges, their impact, and robust mitigation strategies", addPrompts, ), guidance_notes: G( [ "Ensure sample sizes are adequately powered.", "Consider blinding and randomization where appropriate.", "Define clear endpoints and outcome measures.", "Address potential confounders in the experimental design.", ], addPrompts, ), }; const p2s1Content: Phase2Step2_1_Content = { data_collection_methods_wet_lab: C( input.p2_data_collection_methods_wet_lab, "Provide detailed wet-lab protocols, including sample preparation, experimental treatments, instrument settings, and data recording procedures", addPrompts, ), data_collection_methods_dry_lab: C( input.p2_data_collection_methods_dry_lab, "Specify execution details for computational data retrieval, including precise queries, API usage, versioning of tools, and data provenance tracking", addPrompts, ), guidance_notes: G( [ "Standardize protocols to ensure consistency.", "Implement robust data labeling and organization from the outset.", "Document any deviations from planned protocols.", ], addPrompts, ), }; const p2s2Content: Phase2Step2_2_Content = { data_preprocessing_and_qc_plan: C( input.p2_data_preprocessing_and_qc_plan, "Describe the comprehensive pipeline for data cleaning, normalization, transformation, and quality control. Specify metrics, thresholds, and tools for each step", addPrompts, ), guidance_notes: G( [ "Define criteria for outlier detection and handling.", "Assess data quality before and after preprocessing.", "Ensure preprocessing steps are appropriate for downstream analyses.", ], addPrompts, ), }; const p3s1Content: Phase3Step3_1_Content = { data_analysis_strategy: C( input.p3_data_analysis_strategy, "Outline the core statistical and computational methods for data analysis. Specify tests, software, parameters, and how they address the hypotheses", addPrompts, ), bioinformatics_pipeline_summary: C( input.p3_bioinformatics_pipeline_summary, "Summarize the bioinformatics pipeline for high-throughput data, detailing tools, algorithms, parameter settings, and workflow for downstream analyses", addPrompts, ), guidance_notes: G( [ "Justify the choice of statistical tests based on data distribution and assumptions.", "Address multiple testing corrections if applicable.", "Consider sensitivity analyses to assess robustness of findings.", ], addPrompts, ), }; const p3s2Content: Phase3Step3_2_Content = { results_interpretation_framework: C( input.p3_results_interpretation_framework, "Establish a clear framework for interpreting analytical findings in the context of the hypotheses, considering statistical significance, effect sizes, and biological relevance", addPrompts, ), comparison_with_literature_plan: C( input.p3_comparison_with_literature_plan, "Develop a strategy for systematically contextualizing results with existing literature, addressing consistencies, discrepancies, and novel contributions", addPrompts, ), guidance_notes: G( [ "Distinguish correlation from causation.", "Acknowledge limitations of the study and their impact on interpretation.", "Discuss clinical or translational implications if relevant.", ], addPrompts, ), }; const p4s1Content: Phase4Step4_1_Content = { dissemination_manuscript_plan: C( input.p4_dissemination_manuscript_plan, "Formulate a plan for manuscript preparation, including core message, target journal profile, key figures/tables, and authorship contributions", addPrompts, ), dissemination_data_deposition_plan: C( input.p4_dissemination_data_deposition_plan, "Outline a strategy for depositing research data in public repositories, specifying data types, repository choices, metadata standards, and adherence to FAIR principles", addPrompts, ), guidance_notes: G( [ "Follow journal-specific author guidelines.", "Ensure data is de-identified if it contains sensitive information.", "Obtain DOIs or accession numbers for deposited data.", ], addPrompts, ), }; const p4s2Content: Phase4Step4_2_Content = { peer_review_and_publication_approach: C( input.p4_peer_review_and_publication_approach, "Describe the approach to journal submission, navigating peer review, and addressing reviewer comments constructively for publication", addPrompts, ), guidance_notes: G( [ "Prepare a compelling cover letter.", "Respond to reviewer comments point-by-point and respectfully.", "Consider pre-print servers for early dissemination.", ], addPrompts, ), }; const p4s3Content: Phase4Step4_3_Content = { future_research_directions: C( input.p4_future_research_directions, "Identify and articulate potential next steps, new research questions, or translational applications arising from the current study's findings and limitations", addPrompts, ), guidance_notes: G( [ "Base future directions on the study's actual outcomes.", "Consider how new technologies or approaches could address remaining questions.", ], addPrompts, ), }; const ccContent: CrossCuttingContent = { record_keeping_and_data_management: C( input.cc_record_keeping_and_data_management, "Detail the comprehensive plan for meticulous record-keeping, version control (code, data, manuscripts), secure data storage, backup strategy, and Data Management Plan (DMP) adherence", addPrompts, ), collaboration_strategy: C( input.cc_collaboration_strategy, "If applicable, describe the strategy for effective collaboration, including communication channels, role delineation, data sharing protocols, and authorship agreements", addPrompts, ), ethical_considerations: C( input.cc_ethical_considerations, "Thoroughly outline all ethical considerations, including plans for IRB/IACUC approval, informed consent, data privacy/anonymization, responsible conduct of research (RCR) training, and conflict of interest management", addPrompts, ), guidance_notes: G( [ "Ensure compliance with institutional and funding agency requirements.", "Regularly review and update the DMP.", "Promote open science practices where appropriate.", ], addPrompts, ), }; const plan = { plan_title: planTitle, overall_instructions_for_research_agent: addPrompts ? overallInstructions : undefined, input_summary: { keywords_received: input.research_keywords, primary_goal_stated_or_inferred: inferredGoal, organism_focus: input.organism_focus || "Not Specified", // Correctly use the input flag name included_detailed_prompts_for_agent: input.include_detailed_prompts_for_agent, }, phase_1_conception_and_planning: { title: "Phase 1: Conception and Planning", step_1_1_research_question_and_hypothesis: allPropertiesUndefined( p1s1Content, ) ? {} : p1s1Content, step_1_2_literature_review_strategy: allPropertiesUndefined(p1s2Content) ? {} : p1s2Content, step_1_3_experimental_design_and_data_acquisition: allPropertiesUndefined( p1s3Content, ) ? {} : p1s3Content, }, phase_2_data_collection_and_processing: { title: "Phase 2: Data Collection and Processing", step_2_1_data_collection_retrieval: allPropertiesUndefined(p2s1Content) ? {} : p2s1Content, step_2_2_data_preprocessing_and_qc: allPropertiesUndefined(p2s2Content) ? {} : p2s2Content, }, phase_3_analysis_and_interpretation: { title: "Phase 3: Analysis and Interpretation", step_3_1_data_analysis_plan: allPropertiesUndefined(p3s1Content) ? {} : p3s1Content, step_3_2_results_interpretation: allPropertiesUndefined(p3s2Content) ? {} : p3s2Content, }, phase_4_dissemination_and_iteration: { title: "Phase 4: Dissemination and Iteration", step_4_1_dissemination_strategy: allPropertiesUndefined(p4s1Content) ? {} : p4s1Content, step_4_2_peer_review_and_publication: allPropertiesUndefined(p4s2Content) ? {} : p4s2Content, step_4_3_further_research_and_iteration: allPropertiesUndefined( p4s3Content, ) ? {} : p4s3Content, }, cross_cutting_considerations: { title: "Cross-Cutting Considerations", content: allPropertiesUndefined(ccContent) ? {} : ccContent, }, }; return removeEmptyObjectsRecursively( plan, ) as PubMedResearchPlanGeneratedOutput; }
• src/mcp-server/tools/pubmedResearchAgent/logic/inputSchema.ts:10-219 (schema)

  Zod input schema and TypeScript type for the tool, defining all granular parameters across research phases.
  export const PubMedResearchAgentInputSchema = z.object({ // Overall Project Information project_title_suggestion: z .string() .min(5) .describe("A concise and descriptive title for the research project."), primary_research_goal: z .string() .min(10) .describe( 'The main scientific objective or central question the research aims to address (e.g., "To investigate the role of TREM2 in microglial response to amyloid-beta plaques").', ), research_keywords: z .array(z.string().min(1)) .min(1) .describe( 'Core scientific keywords or MeSH terms defining the research domain (e.g., ["neuroinflammation", "Alzheimer\'s disease", "TREM2"]).', ), organism_focus: z .string() .optional() .describe( 'Primary organism(s) or model systems (e.g., "Homo sapiens (iPSC-derived microglia)", "Mus musculus (5xFAD model)").', ), // Phase 1: Conception and Planning Inputs p1_introduction_and_background: z .string() .optional() .describe( "Brief overview of the research area, its significance, and relevant background information leading to this study.", ), p1_specific_research_question: z .string() .optional() .describe( "The precise, focused primary research question the study will answer.", ), p1_knowledge_gap: z .string() .optional() .describe( "Statement clearly identifying the specific gap in current knowledge this research addresses.", ), p1_primary_hypothesis: z .string() .optional() .describe( "The main, testable hypothesis. Should be clear, specific, and falsifiable.", ), p1_secondary_questions_or_hypotheses: z .array(z.string()) .optional() .describe("Any secondary questions or hypotheses to be explored."), p1_pubmed_search_strategy_description: z .string() .optional() .describe( "Description of the primary literature search strategy (e.g., for PubMed), including key terms and database considerations.", ), p1_literature_review_scope: z .string() .optional() .describe( "The defined scope for the literature review (e.g., timeframes, study types, key themes).", ), p1_lit_review_databases_and_approach: z .string() .optional() .describe( "Key databases (e.g., PubMed, EMBASE) and the search approach (e.g., iterative queries, snowballing).", ), p1_experimental_paradigm: z .string() .optional() .describe( "The overarching experimental design or study type (e.g., 'comparative multi-omics analysis', 'longitudinal cohort study').", ), p1_data_acquisition_plan_existing_data: z .string() .optional() .describe( "Strategy for identifying and retrieving relevant existing datasets (databases, data types, tools).", ), p1_data_acquisition_plan_new_data: z .string() .optional() .describe( "Plan for generating novel data (data types, experimental models, key procedures, deposition plan).", ), p1_blast_utilization_plan: z .string() .optional() .describe( "If applicable, how sequence alignment services (e.g., NCBI BLAST) will be used (purpose, programs, databases).", ), p1_controls_and_rigor: z .string() .optional() .describe( "Description of key experimental controls and measures to ensure scientific rigor and reproducibility.", ), p1_methodological_challenges_and_mitigation: z .string() .optional() .describe( "Anticipated methodological challenges and proposed mitigation strategies.", ), // Phase 2: Data Collection and Processing Inputs p2_data_collection_methods_wet_lab: z .string() .optional() .describe( "Specific wet-lab protocols if new data is generated (sample prep, treatments, instruments).", ), p2_data_collection_methods_dry_lab: z .string() .optional() .describe( "Execution details for data retrieval from databases (queries, tools, accessioning).", ), p2_data_preprocessing_and_qc_plan: z .string() .optional() .describe( "Pipeline for data cleaning, preprocessing (e.g., alignment, normalization), and quality control (metrics, thresholds, tools).", ), // Phase 3: Analysis and Interpretation Inputs p3_data_analysis_strategy: z .string() .optional() .describe( "Core statistical and computational methods to analyze data and test hypotheses (tests, software, ML models if any).", ), p3_bioinformatics_pipeline_summary: z .string() .optional() .describe( "Summary of the bioinformatics pipeline for high-throughput data analysis (tools, downstream analyses).", ), p3_results_interpretation_framework: z .string() .optional() .describe( "Framework for evaluating findings against hypotheses (statistical significance, biological relevance).", ), p3_comparison_with_literature_plan: z .string() .optional() .describe( "Strategy for contextualizing results with existing literature and addressing discrepancies.", ), // Phase 4: Dissemination and Iteration Inputs p4_dissemination_manuscript_plan: z .string() .optional() .describe( "Plan for manuscript preparation (core message, target journal profile, key figures).", ), p4_dissemination_data_deposition_plan: z .string() .optional() .describe( "Strategy for depositing data in public repositories (types, repositories, FAIR principles).", ), p4_peer_review_and_publication_approach: z .string() .optional() .describe("Approach to journal submission and addressing peer review."), p4_future_research_directions: z .string() .optional() .describe( "Potential next steps, new questions, or translational applications arising from the research.", ), // Cross-Cutting Considerations Inputs cc_record_keeping_and_data_management: z .string() .optional() .describe( "Plan for record-keeping, version control, data storage, and DMP.", ), cc_collaboration_strategy: z .string() .optional() .describe( "If applicable, strategy for collaboration, communication, roles, and authorship.", ), cc_ethical_considerations: z .string() .optional() .describe( "Ethical considerations, IRB/IACUC approval plans, data privacy, RCR training.", ), // Meta-parameter from previous iterations, still useful include_detailed_prompts_for_agent: z .boolean() .optional() .default(false) // Default to false, meaning the tool primarily structures the detailed input. .describe( "If true, the tool will add more detailed instructive prompts/guidance within the output fields for a research agent. If false (default), it will primarily structure the provided inputs with minimal additional prompting.", ), });
• src/mcp-server/tools/pubmedResearchAgent/registration.ts:25-107 (registration)

  Function that registers the 'pubmed_research_agent' tool with the MCP server, providing name, description, input schema, and handler implementation.
  export async function registerPubMedResearchAgentTool( server: McpServer, ): Promise<void> { const operation = "registerPubMedResearchAgentTool"; const toolName = "pubmed_research_agent"; const toolDescription = "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."; const context = requestContextService.createRequestContext({ operation }); await ErrorHandler.tryCatch( async () => { server.tool( toolName, toolDescription, PubMedResearchAgentInputSchema.shape, async ( input: PubMedResearchAgentInput, mcpProvidedContext: unknown, ): Promise<CallToolResult> => { const richContext: RequestContext = requestContextService.createRequestContext({ parentRequestId: context.requestId, operation: "pubmedResearchAgentToolHandler", mcpToolContext: mcpProvidedContext, input, }); try { const result = await pubmedResearchAgentLogic(input, richContext); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) }, ], isError: false, }; } catch (error) { const handledError = ErrorHandler.handleError(error, { operation: "pubmedResearchAgentToolHandler", context: richContext, input, rethrow: false, }); const mcpError = handledError instanceof McpError ? handledError : new McpError( BaseErrorCode.INTERNAL_ERROR, "An unexpected error occurred while generating the research plan.", { originalErrorName: handledError.name, originalErrorMessage: handledError.message, }, ); return { content: [ { type: "text", text: JSON.stringify({ error: { code: mcpError.code, message: mcpError.message, details: mcpError.details, }, }), }, ], isError: true, }; } }, ); logger.notice(`Tool '${toolName}' registered.`, context); }, { operation, context, errorCode: BaseErrorCode.INITIALIZATION_FAILED, critical: true, }, ); }
• src/mcp-server/tools/pubmedResearchAgent/logic.ts:20-48 (helper)

  Wrapper function invoked by the tool handler: sets up logging context and delegates to the core plan generation orchestrator.
  export async function pubmedResearchAgentLogic( input: PubMedResearchAgentInput, parentRequestContext: RequestContext, ): Promise<PubMedResearchPlanGeneratedOutput> { const operationContext = requestContextService.createRequestContext({ parentRequestId: parentRequestContext.requestId, operation: "pubmedResearchAgentLogicExecution", input: sanitizeInputForLogging(input), }); logger.info( `Executing 'pubmed_research_agent' to generate research plan outline. Keywords: ${input.research_keywords.join( ", ", )}`, operationContext, ); const researchPlanOutline = generateFullResearchPlanOutline( input, operationContext, ); logger.notice("Successfully generated research plan outline.", { ...operationContext, projectTitle: input.project_title_suggestion, }); return researchPlanOutline; }
• src/mcp-server/server.ts:91-95 (registration)

  Server initialization sequence where the pubmed_research_agent tool registration is invoked among other tools.
  await registerPubMedArticleConnectionsTool(server); await registerPubMedFetchContentsTool(server); await registerPubMedGenerateChartTool(server); await registerPubMedResearchAgentTool(server); await registerPubMedSearchArticlesTool(server);