Noctua MCP Server

Instructions

# Create complex with evidence
add_protein_complex(
    "gomodel:12345",
    [
        {
            "entity_id": "UniProtKB:P68400",
            "label": "CSNK1A1",
            "evidence_type": "ECO:0000353",
            "reference": "PMID:12345678"
        },
        {
            "entity_id": "UniProtKB:P49841",
            "label": "GSK3B",
            "evidence_type": "ECO:0000353",
            "reference": "PMID:12345678"
        }
    ],
    assign_var="destruction_complex"
)

# Create a complex with specific assignment variable
add_protein_complex(
    "gomodel:12345",
    [
        {"entity_id": "UniProtKB:P62191", "label": "PSMC1"},
        {"entity_id": "UniProtKB:P62195", "label": "PSMC5"}
    ],
    assign_var="proteasome"
)

Implementation Reference

• src/noctua_mcp/mcp_server.py:440-567 (handler)

  The primary handler function for the 'add_protein_complex' MCP tool. It validates input components using ProteinComplexComponent Pydantic models, delegates execution to BaristaClient.add_protein_complex, handles responses, validation failures with rollback, and returns structured results including the complex ID.

  async def add_protein_complex(
      model_id: str,
      components: List[Dict[str, Any]],
      assign_var: str = "complex1"
  ) -> Dict[str, Any]:
      """
      Add a protein complex to a GO-CAM model with validated components.
  
      Creates a protein-containing complex (GO:0032991 by default) and links
      all components using BFO:0000051 (has part) relation. The operation is
      atomic - either all components are added successfully or the entire
      operation is rolled back.
  
      Args:
          model_id: The GO-CAM model identifier
          components: List of component dictionaries with keys:
                     - entity_id (required): Protein/gene product ID (e.g., "UniProtKB:P12345")
                     - label (optional): Component label for validation
                     - evidence_type (optional): ECO code (e.g., "ECO:0000353")
                     - reference (optional): Source reference (e.g., "PMID:12345678")
          assign_var: Variable name for the complex (default: "complex1")
  
      Returns:
          Barista API response with complex ID and component IDs
  
      Examples:
          # Create a simple dimer complex
          add_protein_complex(
              "gomodel:12345",
              [
                  {"entity_id": "UniProtKB:P04637", "label": "TP53"},
                  {"entity_id": "UniProtKB:P04637", "label": "TP53"}
              ],
          )
  
          # Create complex with evidence
          add_protein_complex(
              "gomodel:12345",
              [
                  {
                      "entity_id": "UniProtKB:P68400",
                      "label": "CSNK1A1",
                      "evidence_type": "ECO:0000353",
                      "reference": "PMID:12345678"
                  },
                  {
                      "entity_id": "UniProtKB:P49841",
                      "label": "GSK3B",
                      "evidence_type": "ECO:0000353",
                      "reference": "PMID:12345678"
                  }
              ],
              assign_var="destruction_complex"
          )
  
          # Create a complex with specific assignment variable
          add_protein_complex(
              "gomodel:12345",
              [
                  {"entity_id": "UniProtKB:P62191", "label": "PSMC1"},
                  {"entity_id": "UniProtKB:P62195", "label": "PSMC5"}
              ],
              assign_var="proteasome"
          )
  
      Notes:
          - All components must have entity_id specified
          - Label validation prevents ID hallucination
          - Evidence and references are optional but recommended
          - Uses BFO:0000051 (has part) to link components
          - Atomic operation with automatic rollback on failure
      """
      client = get_client()
  
      # Convert component dicts to Pydantic models
      try:
          pydantic_components = [ProteinComplexComponent(**comp) for comp in components]
      except Exception as e:
          return {
              "success": False,
              "error": "Invalid component structure",
              "reason": str(e),
              "hint": "Each component must have 'entity_id' field. Optional: 'label', 'evidence_type', 'reference'"
          }
  
      # Call the new add_protein_complex method
      resp = client.add_protein_complex(
          model_id,
          pydantic_components,
          assign_var=assign_var
      )
  
      if resp.validation_failed:
          return {
              "success": False,
              "error": "Validation failed",
              "reason": resp.validation_reason,
              "rolled_back": True,
              "component_count": len(components)
          }
  
      if resp.error:
          return {
              "success": False,
              "error": resp.error,
              "model_id": model_id
          }
  
      # Get the complex ID from model_vars or from the individuals list
      complex_id = assign_var
      if resp.model_vars and assign_var in resp.model_vars:
          complex_id = resp.model_vars[assign_var]
      elif resp.individuals and len(resp.individuals) > 0:
          # Find the complex individual (it should be the first one created in this operation)
          # The complex is created first, then components are added
          for ind in resp.individuals:
              # Check if it's a protein-containing complex
              if hasattr(ind, 'type') and any('GO:0032991' in str(t.id) if hasattr(t, 'id') else False for t in ind.type):
                  complex_id = ind.id
                  break
  
      return {
          "success": True,
          "complex_id": complex_id,
          "component_count": len(components),
          "assign_var": assign_var
      }

• src/noctua_mcp/mcp_server.py:440-440 (registration)

  The @mcp.tool() decorator registers 'add_protein_complex' as an available MCP tool in the FastMCP server.

  async def add_protein_complex(

• src/noctua_mcp/mcp_server.py:516-516 (schema)

  Uses ProteinComplexComponent Pydantic model (imported from noctua.models) for input schema validation of protein complex components.

  pydantic_components = [ProteinComplexComponent(**comp) for comp in components]