BioMCP

Instructions

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()