BioMCP

Instructions

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

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)