Noctua MCP Server

Instructions

# Find proteins with experimental evidence for a GO term
search_annotations(go_term="GO:0005634", evidence_types="IDA,IPI")

# Find human proteins in nucleus with experimental evidence
search_annotations(
    go_term="GO:0005634",
    taxon="9606",
    evidence_types="IDA,IPI,IMP",
    aspect="C"
)

# Find all UniProt annotations for apoptosis
search_annotations(
    go_term="GO:0006915",
    assigned_by="UniProtKB"
)

Implementation Reference

• src/noctua_mcp/mcp_server.py:1562-1665 (handler)

  The main handler function for the 'search_annotations' MCP tool. It normalizes inputs, calls AmigoClient.search_annotations, formats the results into a structured dictionary, and handles errors.

  @mcp.tool()
  async def search_annotations(
      bioentity: Optional[str] = None,
      go_term: Optional[str] = None,
      evidence_types: Optional[str] = None,
      taxon: Optional[str] = None,
      aspect: Optional[str] = None,
      assigned_by: Optional[str] = None,
      limit: int = 10
  ) -> Dict[str, Any]:
      """
      Search for GO annotations (evidence) with filtering.
  
      Args:
          bioentity: Specific bioentity ID to filter by (e.g., "UniProtKB:P12345")
          go_term: Specific GO term ID to filter by (e.g., "GO:0008150")
          evidence_types: Comma-separated evidence codes (e.g., "IDA,IPI,IMP")
          taxon: Organism filter - accepts numeric (9606) or full ID (NCBITaxon:9606)
          aspect: GO aspect filter - "C" (cellular component), "F" (molecular function), or "P" (biological process)
          assigned_by: Annotation source filter (e.g., "GOC", "UniProtKB", "MGI")
          limit: Maximum number of results (default: 10, max: 1000)
  
      Returns:
          Dictionary containing:
          - annotations: List of annotation results with evidence details
          - total: Number of results returned
  
      Examples:
          # Find all evidence for a specific protein
          search_annotations(bioentity="UniProtKB:P53762")
  
          # Find proteins with experimental evidence for a GO term
          search_annotations(go_term="GO:0005634", evidence_types="IDA,IPI")
  
          # Find human proteins in nucleus with experimental evidence
          search_annotations(
              go_term="GO:0005634",
              taxon="9606",
              evidence_types="IDA,IPI,IMP",
              aspect="C"
          )
  
          # Find all UniProt annotations for apoptosis
          search_annotations(
              go_term="GO:0006915",
              assigned_by="UniProtKB"
          )
      """
      # Normalize taxon ID
      if taxon and not taxon.startswith("NCBITaxon:"):
          if taxon.isdigit():
              taxon = f"NCBITaxon:{taxon}"
  
      # Parse evidence types
      evidence_list = None
      if evidence_types:
          evidence_list = [e.strip() for e in evidence_types.split(",")]
  
      # Limit bounds
      limit = min(max(1, limit), 1000)
  
      try:
          with AmigoClient() as client:
              results = client.search_annotations(
                  bioentity=bioentity,
                  go_term=go_term,
                  evidence_types=evidence_list,
                  taxon=taxon,
                  aspect=aspect,
                  assigned_by=assigned_by,
                  limit=limit
              )
  
              return {
                  "annotations": [
                      {
                          "bioentity": r.bioentity,
                          "bioentity_label": r.bioentity_label,
                          "bioentity_name": r.bioentity_name,
                          "go_term": r.annotation_class,
                          "go_term_label": r.annotation_class_label,
                          "aspect": r.aspect,
                          "evidence_type": r.evidence_type,
                          "evidence": r.evidence,
                          "evidence_label": r.evidence_label,
                          "reference": r.reference,
                          "assigned_by": r.assigned_by,
                          "date": r.date,
                          "taxon": r.taxon,
                          "taxon_label": r.taxon_label,
                          "qualifier": r.qualifier,
                          "annotation_extension": r.annotation_extension
                      }
                      for r in results
                  ],
                  "total": len(results)
              }
  
      except Exception as e:
          return {
              "error": "Failed to search annotations",
              "message": str(e)
          }