BioMCP

Instructions

Implementation Reference

• src/biomcp/individual_tools.py:407-429 (handler)

  MCP tool handler function 'trial_outcomes_getter'. This is the main entrypoint registered with the MCP server. It defines the tool schema via Annotated parameters, handles the tool call, passes a call_benefit, and delegates to the core _trial_outcomes implementation.
  @mcp_app.tool() @track_performance("biomcp.trial_outcomes_getter") async def trial_outcomes_getter( nct_id: Annotated[ str, Field(description="NCT ID (e.g., 'NCT06524388')"), ], ) -> str: """Fetch outcome measures and results for a clinical trial. Retrieves detailed outcome information including: - Primary outcome measures - Secondary outcome measures - Results data (if available) - Adverse events (if reported) Note: Results are only available for completed trials that have posted data. """ return await _trial_outcomes( call_benefit="Fetch trial outcome measures and results for efficacy assessment", nct_id=nct_id, )
• src/biomcp/trials/getter.py:176-198 (helper)

  Core helper function _trial_outcomes that fetches outcomes data from ClinicalTrials.gov API using the shared get_trial function with Outcomes module. This contains the domain-specific logic invoked by the tool handler.
  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:52-125 (helper)

  Shared helper function get_trial that performs the actual HTTP request to ClinicalTrials.gov API, parses the response, handles errors, and renders to Markdown. Used by all trial section getters including outcomes.
  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/individual_tools.py:24-30 (registration)

  Import statement that brings in the core trial getter functions, including _trial_outcomes, for use by the MCP tool handlers.
  from biomcp.trials.getter import ( _trial_locations, _trial_outcomes, _trial_protocol, _trial_references, ) from biomcp.trials.search import _trial_searcher
• src/biomcp/individual_tools.py:410-412 (schema)

  Pydantic schema definition for the tool input parameter 'nct_id' via Annotated Field.
  nct_id: Annotated[ str, Field(description="NCT ID (e.g., 'NCT06524388')"),