BioMCP

Instructions

Implementation Reference

• src/biomcp/individual_tools.py:303-358 (handler)

  Primary handler function for the 'trial_getter' MCP tool. Decorated with @mcp_app.tool() for registration. Defines input schema (nct_id parameter) and orchestrates calls to four helper functions to fetch comprehensive trial details from ClinicalTrials.gov.
  @mcp_app.tool() @track_performance("biomcp.trial_getter") async def trial_getter( nct_id: Annotated[ str, Field(description="NCT ID (e.g., 'NCT06524388')"), ], ) -> str: """Fetch comprehensive details for a specific clinical trial. Retrieves all available information for a clinical trial by its NCT ID. This includes protocol details, locations, outcomes, and references. For specific sections only, use the specialized getter tools: - trial_protocol_getter: Core protocol information - trial_locations_getter: Site locations and contacts - trial_outcomes_getter: Primary/secondary outcomes and results - trial_references_getter: Publications and references """ results = [] # Get all sections protocol = await _trial_protocol( call_benefit="Fetch comprehensive trial details for analysis", nct_id=nct_id, ) if protocol: results.append(protocol) locations = await _trial_locations( call_benefit="Fetch comprehensive trial details for analysis", nct_id=nct_id, ) if locations: results.append(locations) outcomes = await _trial_outcomes( call_benefit="Fetch comprehensive trial details for analysis", nct_id=nct_id, ) if outcomes: results.append(outcomes) references = await _trial_references( call_benefit="Fetch comprehensive trial details for analysis", nct_id=nct_id, ) if references: results.append(references) return ( "\n\n".join(results) if results else f"No data found for trial {nct_id}" )
• src/biomcp/trials/getter.py:127-150 (helper)

  Helper function _trial_protocol called by trial_getter to fetch core protocol details (identification, status, design, eligibility, etc.) using get_trial with Module.PROTOCOL.
  async def _trial_protocol( call_benefit: Annotated[ str, "Define and summarize why this function is being called and the intended benefit", ], nct_id: str, ): """ Retrieves core protocol information for a single clinical trial identified by its NCT ID. Parameters: - call_benefit: Define and summarize why this function is being called and the intended benefit - nct_id: A single NCT ID (string, e.g., "NCT04280705") Process: Fetches standard "Protocol" view modules (like ID, Status, Sponsor, Design, Eligibility) from the ClinicalTrials.gov v2 API. Output: A Markdown formatted string detailing title, status, sponsor, purpose, study design, phase, interventions, eligibility criteria, etc. Returns error if invalid. """ return await get_trial(nct_id, Module.PROTOCOL)
• src/biomcp/trials/getter.py:152-174 (helper)

  Helper function _trial_locations called by trial_getter to fetch trial site locations and contacts using get_trial with Module.LOCATIONS.
  async def _trial_locations( call_benefit: Annotated[ str, "Define and summarize why this function is being called and the intended benefit", ], nct_id: str, ) -> str: """ Retrieves contact and location details for a single clinical trial identified by its NCT ID. Parameters: - call_benefit: Define and summarize why this function is being called and the intended benefit - nct_id: A single NCT ID (string, e.g., "NCT04280705") Process: Fetches the `ContactsLocationsModule` from the ClinicalTrials.gov v2 API for the given NCT ID. Output: A Markdown formatted string detailing facility names, addresses (city, state, country), and contact info. Returns an error message if the NCT ID is invalid. """ return await get_trial(nct_id, Module.LOCATIONS)
• src/biomcp/trials/getter.py:176-198 (helper)

  Helper function _trial_outcomes called by trial_getter to fetch outcome measures and results using get_trial with Module.OUTCOMES.
  async def _trial_outcomes( call_benefit: Annotated[ str, "Define and summarize why this function is being called and the intended benefit", ], nct_id: str, ) -> str: """ Retrieves outcome measures, results (if available), and adverse event data for a single clinical trial. Parameters: - call_benefit: Define and summarize why this function is being called and the intended benefit - nct_id: A single NCT ID (string, e.g., "NCT04280705") Process: Fetches the `OutcomesModule` and `ResultsSection` from the ClinicalTrials.gov v2 API for the NCT ID. Output: A Markdown formatted string detailing primary/secondary outcomes, participant flow, results tables (if posted), and adverse event summaries. Returns an error if invalid. """ return await get_trial(nct_id, Module.OUTCOMES)
• src/biomcp/trials/getter.py:200-222 (helper)

  Helper function _trial_references called by trial_getter to fetch publications and references using get_trial with Module.REFERENCES.
  async def _trial_references( call_benefit: Annotated[ str, "Define and summarize why this function is being called and the intended benefit", ], nct_id: str, ): """ Retrieves publications and other references associated with a single clinical trial identified by its NCT ID. Parameters: - call_benefit: Define and summarize why this function is being called and the intended benefit - nct_id: A single NCT ID (string, e.g., "NCT04280705") Process: Fetches the `ReferencesModule` from the ClinicalTrials.gov v2 API for the NCT ID. Output: A Markdown formatted string listing citations, associated PubMed IDs (PMIDs), and reference types (e.g., result publication). Returns error if invalid. """ return await get_trial(nct_id, Module.REFERENCES)