BioMCP

Instructions

Retrieves all study locations including:
- Facility names and addresses
- Principal investigator information
- Contact details (when recruiting)
- Recruitment status by site

Useful for finding trials near specific locations or contacting study teams.

Implementation Reference

• src/biomcp/individual_tools.py:431-453 (handler)

  Primary handler function for the 'trial_locations_getter' MCP tool. Includes @mcp_app.tool() decorator for registration and Pydantic schema definition via Annotated types. Calls the core _trial_locations helper.

  @mcp_app.tool()
  @track_performance("biomcp.trial_locations_getter")
  async def trial_locations_getter(
      nct_id: Annotated[
          str,
          Field(description="NCT ID (e.g., 'NCT06524388')"),
      ],
  ) -> str:
      """Fetch contact and location details for a clinical trial.
  
      Retrieves all study locations including:
      - Facility names and addresses
      - Principal investigator information
      - Contact details (when recruiting)
      - Recruitment status by site
  
      Useful for finding trials near specific locations or contacting study teams.
      """
      return await _trial_locations(
          call_benefit="Fetch trial locations and contacts for enrollment information",
          nct_id=nct_id,
      )

• src/biomcp/individual_tools.py:434-437 (schema)

  Input schema definition for the tool: single parameter 'nct_id' as string with description.

  nct_id: Annotated[
      str,
      Field(description="NCT ID (e.g., 'NCT06524388')"),
  ],

• src/biomcp/trials/getter.py:152-174 (helper)

  Core helper function implementing the trial locations fetch logic by calling ClinicalTrials.gov API with specific module 'ContactsLocationsModule'.

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

  Supporting utility function that performs the actual API request to ClinicalTrials.gov and formats the response for the locations module.

  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)