bc_search_pride_projects

Instructions

Implementation Reference

• src/biocontext_kb/core/pride/_search_pride_projects.py:10-139 (handler)

  The search_pride_projects function handles searching PRIDE database for mass spectrometry proteomics projects. It accepts keyword, organism_filter, instrument_filter, experiment_type_filter, page_size, sort_field, and sort_direction parameters. It queries the PRIDE REST API v3, processes results, and returns a dict with results, count, and search_criteria.

  def search_pride_projects(
      keyword: Annotated[
          Optional[str],
          Field(description="Search keywords (e.g., 'proteome', 'cancer', 'human')"),
      ] = None,
      organism_filter: Annotated[
          Optional[str],
          Field(description="Organism filter (e.g., 'Homo sapiens', 'human')"),
      ] = None,
      instrument_filter: Annotated[
          Optional[str],
          Field(description="Instrument type filter (e.g., 'Orbitrap', 'LTQ')"),
      ] = None,
      experiment_type_filter: Annotated[
          Optional[str],
          Field(description="Experiment type filter (e.g., 'TMT', 'Label-free')"),
      ] = None,
      page_size: Annotated[
          int,
          Field(description="Number of results to return (max 100)"),
      ] = 20,
      sort_field: Annotated[
          str,
          Field(description="Sort field: submissionDate or publicationDate"),
      ] = "submissionDate",
      sort_direction: Annotated[
          str,
          Field(description="Sort direction: ASC or DESC"),
      ] = "DESC",
  ) -> dict:
      """Search PRIDE database for mass spectrometry proteomics projects using keywords and filters.
  
      Returns:
          dict: Results array with project accessions, titles, descriptions, organisms, instruments, experiment types, count, search_criteria or error message.
      """
      base_url = "https://www.ebi.ac.uk/pride/ws/archive/v3/search/projects"
  
      # Build query parameters
      params: dict[str, str | int] = {}
  
      if page_size > 100:
          page_size = 100
      params["pageSize"] = page_size
      params["page"] = 0
  
      # Add keyword search
      if keyword:
          params["keyword"] = keyword
  
      # Build filter string for specific criteria
      filters = []
      if organism_filter:
          filters.append(f"organisms=={organism_filter}")
      if instrument_filter:
          filters.append(f"instruments=={instrument_filter}")
      if experiment_type_filter:
          filters.append(f"experimentTypes=={experiment_type_filter}")
  
      if filters:
          params["filter"] = ",".join(filters)
  
      # Validate and set sort parameters - use only known working fields
      valid_sort_fields = ["submissionDate", "publicationDate"]
      if sort_field not in valid_sort_fields:
          sort_field = "submissionDate"
      params["sortFields"] = sort_field
  
      valid_sort_directions = ["ASC", "DESC"]
      if sort_direction.upper() not in valid_sort_directions:
          sort_direction = "DESC"
      params["sortDirection"] = sort_direction.upper()
  
      try:
          response = requests.get(base_url, params=params)
          response.raise_for_status()
  
          search_results = response.json()
  
          if not search_results:
              return {
                  "results": [],
                  "count": 0,
                  "message": "No PRIDE projects found matching the search criteria",
                  "search_criteria": {
                      "keyword": keyword,
                      "organism_filter": organism_filter,
                      "instrument_filter": instrument_filter,
                      "experiment_type_filter": experiment_type_filter,
                      "sort_field": sort_field,
                      "sort_direction": sort_direction,
                  },
              }
  
          # Process results to include key information
          processed_results = []
          for project in search_results:
              processed_project = {
                  "accession": project.get("accession"),
                  "title": project.get("title"),
                  "description": project.get("projectDescription", "")[:500] + "..."
                  if len(project.get("projectDescription", "")) > 500
                  else project.get("projectDescription", ""),
                  "submission_date": project.get("submissionDate"),
                  "publication_date": project.get("publicationDate"),
                  "organisms": project.get("organisms", []),
                  "instruments": project.get("instruments", []),
                  "experiment_types": project.get("experimentTypes", []),
                  "keywords": project.get("keywords", []),
                  "submitters": project.get("submitters", []),
                  "download_count": project.get("downloadCount", 0),
              }
              processed_results.append(processed_project)
  
          return {
              "results": processed_results,
              "count": len(processed_results),
              "search_criteria": {
                  "keyword": keyword,
                  "organism_filter": organism_filter,
                  "instrument_filter": instrument_filter,
                  "experiment_type_filter": experiment_type_filter,
                  "sort_field": sort_field,
                  "sort_direction": sort_direction,
              },
          }
  
      except requests.exceptions.HTTPError as e:
          return {"error": f"HTTP error: {e}"}
      except Exception as e:
          return {"error": f"Exception occurred: {e!s}"}

• src/biocontext_kb/core/pride/_search_pride_projects.py:11-38 (schema)

  Pydantic-annotated parameters defining the input schema for the search_pride_projects tool: keyword, organism_filter, instrument_filter, experiment_type_filter (all optional strings), page_size (int, default 20, max 100), sort_field (str, default 'submissionDate'), sort_direction (str, default 'DESC').

  keyword: Annotated[
      Optional[str],
      Field(description="Search keywords (e.g., 'proteome', 'cancer', 'human')"),
  ] = None,
  organism_filter: Annotated[
      Optional[str],
      Field(description="Organism filter (e.g., 'Homo sapiens', 'human')"),
  ] = None,
  instrument_filter: Annotated[
      Optional[str],
      Field(description="Instrument type filter (e.g., 'Orbitrap', 'LTQ')"),
  ] = None,
  experiment_type_filter: Annotated[
      Optional[str],
      Field(description="Experiment type filter (e.g., 'TMT', 'Label-free')"),
  ] = None,
  page_size: Annotated[
      int,
      Field(description="Number of results to return (max 100)"),
  ] = 20,
  sort_field: Annotated[
      str,
      Field(description="Sort field: submissionDate or publicationDate"),
  ] = "submissionDate",
  sort_direction: Annotated[
      str,
      Field(description="Sort direction: ASC or DESC"),
  ] = "DESC",

• src/biocontext_kb/core/pride/_search_pride_projects.py:9-10 (registration)

  The @core_mcp.tool() decorator registers search_pride_projects as an MCP tool named 'search_pride_projects' via the core_mcp FastMCP server instance.

  @core_mcp.tool()
  def search_pride_projects(

• src/biocontext_kb/core/pride/__init__.py:2-9 (registration)

  Imports and re-exports search_pride_projects from the private module, making it available when the pride package is imported.

  from ._search_pride_projects import search_pride_projects
  from ._search_pride_proteins import search_pride_proteins
  
  __all__ = [
      "get_pride_project",
      "search_pride_projects",
      "search_pride_proteins",
  ]

• src/biocontext_kb/core/_server.py:1-4 (helper)

  Core MCP server instance (core_mcp) created via FastMCP, which is used to register all tools including search_pride_projects via the @core_mcp.tool() decorator.

  from fastmcp import FastMCP
  
  core_mcp = FastMCP(  # type: ignore
      "BC",