BioMCP

Instructions

Retrieves essential protocol details including:
- Official title and brief summary
- Study status and sponsor information
- Study design (type, phase, allocation, masking)
- Eligibility criteria
- Primary completion date

Implementation Reference

• src/biomcp/individual_tools.py:360-381 (handler)

  The main handler function for the 'trial_protocol_getter' MCP tool. It defines the tool interface with input validation (nct_id parameter) and delegates to the _trial_protocol helper function.

  @mcp_app.tool()
  @track_performance("biomcp.trial_protocol_getter")
  async def trial_protocol_getter(
      nct_id: Annotated[
          str,
          Field(description="NCT ID (e.g., 'NCT06524388')"),
      ],
  ) -> str:
      """Fetch core protocol information for a clinical trial.
  
      Retrieves essential protocol details including:
      - Official title and brief summary
      - Study status and sponsor information
      - Study design (type, phase, allocation, masking)
      - Eligibility criteria
      - Primary completion date
      """
      return await _trial_protocol(
          call_benefit="Fetch trial protocol information for eligibility assessment",
          nct_id=nct_id,
      )

• src/biomcp/trials/getter.py:127-150 (helper)

  Helper function _trial_protocol specifically called by the handler. It invokes get_trial with Module.PROTOCOL to fetch the protocol section from ClinicalTrials.gov.

  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:53-125 (helper)

  Core helper function get_trial that performs the HTTP request to ClinicalTrials.gov API, processes the response, handles errors, and renders to Markdown (or JSON). This contains the primary execution logic.

  async def get_trial(
      nct_id: str,
      module: Module = Module.PROTOCOL,
      output_json: bool = False,
  ) -> str:
      """Get details of a clinical trial by module."""
      fields = ",".join(modules[module])
      params = {"fields": fields}
      url = f"{CLINICAL_TRIALS_BASE_URL}/{nct_id}"
  
      logger.debug(f"Fetching trial {nct_id} with module {module.value}")
      logger.debug(f"URL: {url}, Params: {params}")
  
      parsed_data: dict[str, Any] | None
      error_obj: http_client.RequestError | None
      parsed_data, error_obj = await http_client.request_api(
          url=url,
          request=params,
          method="GET",
          tls_version=TLSVersion.TLSv1_2,
          response_model_type=None,
          domain="clinicaltrials",
      )
  
      data_to_return: dict[str, Any]
  
      if error_obj:
          logger.error(
              f"API Error for {nct_id}: {error_obj.code} - {error_obj.message}"
          )
          data_to_return = {
              "error": f"API Error {error_obj.code}",
              "details": error_obj.message,
          }
      elif parsed_data:
          # ClinicalTrials.gov API returns data wrapped in a "studies" array
          # Extract the first study if it exists
          if isinstance(parsed_data, dict) and "studies" in parsed_data:
              studies = parsed_data.get("studies", [])
              if studies and len(studies) > 0:
                  data_to_return = studies[0]
                  data_to_return["URL"] = (
                      f"https://clinicaltrials.gov/study/{nct_id}"
                  )
              else:
                  logger.warning(f"No studies found in response for {nct_id}")
                  data_to_return = {
                      "error": f"No studies found for {nct_id}",
                      "details": "API returned empty studies array",
                  }
          else:
              # Handle case where API returns data in unexpected format
              logger.debug(
                  f"Unexpected response format for {nct_id}: {type(parsed_data)}"
              )
              data_to_return = parsed_data
              data_to_return["URL"] = (
                  f"https://clinicaltrials.gov/study/{nct_id}"
              )
      else:
          logger.warning(
              f"No data received for {nct_id} with module {module.value}"
          )
          data_to_return = {
              "error": f"No data found for {nct_id} with module {module.value}",
              "details": "API returned no data",
          }
  
      if output_json:
          return json.dumps(data_to_return, indent=2)
      else:
          return render.to_markdown(data_to_return)

• src/biomcp/trials/getter.py:12-50 (schema)

  Schema definitions: Module enum and modules dict that specify the API fields fetched for PROTOCOL (used by trial_protocol_getter). Defines the data structure and fields for the protocol section.

  class Module(StrEnum):
      PROTOCOL = "Protocol"
      LOCATIONS = "Locations"
      REFERENCES = "References"
      OUTCOMES = "Outcomes"
      ALL = "All"
  
  
  modules: dict[Module, list[str]] = {
      Module.PROTOCOL: [
          "IdentificationModule",
          "StatusModule",
          "SponsorCollaboratorsModule",
          "OversightModule",
          "DescriptionModule",
          "ConditionsModule",
          "DesignModule",
          "ArmsInterventionsModule",
          "EligibilityModule",
      ],
      Module.LOCATIONS: ["ContactsLocationsModule"],
      Module.REFERENCES: ["ReferencesModule"],
      Module.OUTCOMES: ["OutcomesModule", "ResultsSection"],
      Module.ALL: [
          "IdentificationModule",
          "StatusModule",
          "SponsorCollaboratorsModule",
          "OversightModule",
          "DescriptionModule",
          "ConditionsModule",
          "DesignModule",
          "ArmsInterventionsModule",
          "EligibilityModule",
          "ContactsLocationsModule",
          "ReferencesModule",
          "OutcomesModule",
          "ResultsSection",
      ],
  }

• src/biomcp/individual_tools.py:360-360 (registration)

  Registration decorators: @mcp_app.tool() registers the function as an MCP tool named 'trial_protocol_getter'; @track_performance adds metrics tracking.

  @mcp_app.tool()