Noctua MCP Server

Instructions

# Add a protein/gene product with validation
add_individual("gomodel:12345", "UniProtKB:P38398", "BRCA1", "gp1")

# Add a cellular component with validation
add_individual("gomodel:12345", "GO:0005737", "cytoplasm", "cc1")

# Add a biological process with validation
add_individual("gomodel:12345", "GO:0016055", "Wnt signaling pathway", "bp1")

# Add an evidence instance with validation
add_individual("gomodel:12345", "ECO:0000353", "physical interaction evidence", "ev1")

# Variables like "mf1", "gp1" can be referenced in subsequent
# add_fact calls within the same batch operation

Implementation Reference

• src/noctua_mcp/mcp_server.py:155-240 (handler)

  The main handler function for the 'add_individual' MCP tool. It validates input, calls BaristaClient.add_individual with label checksum, handles errors/rollback, and returns the individual ID or error details.

  @mcp.tool()
  async def add_individual(
      model_id: str,
      class_curie: str,
      class_label: str,
      assign_var: str = "x1"
  ) -> Dict[str, Any]:
      """
      Add an individual (instance) of a class to a GO-CAM model with label validation.
  
      This tool requires providing the expected label for the class to prevent
      accidental use of wrong IDs (e.g., GO:0003924 vs GO:0003925). The operation
      will automatically rollback if the created individual doesn't match the
      expected label.
  
      Args:
          model_id: The GO-CAM model identifier (e.g., "gomodel:12345")
          class_curie: The class to instantiate (e.g., "GO:0003674")
          class_label: The expected rdfs:label of the class (e.g., "molecular_function")
          assign_var: Variable name for referencing in the same batch
  
      Returns:
          Barista API response with message-type and signal fields.
          If validation fails, includes rolled_back=true and validation error.
  
      Examples:
          # Add a molecular function activity with validation
          add_individual("gomodel:12345", "GO:0004672", "protein kinase activity", "mf1")
  
          # Add a protein/gene product with validation
          add_individual("gomodel:12345", "UniProtKB:P38398", "BRCA1", "gp1")
  
          # Add a cellular component with validation
          add_individual("gomodel:12345", "GO:0005737", "cytoplasm", "cc1")
  
          # Add a biological process with validation
          add_individual("gomodel:12345", "GO:0016055", "Wnt signaling pathway", "bp1")
  
          # Add an evidence instance with validation
          add_individual("gomodel:12345", "ECO:0000353", "physical interaction evidence", "ev1")
  
          # Variables like "mf1", "gp1" can be referenced in subsequent
          # add_fact calls within the same batch operation
  
      Notes:
          - The label acts as a checksum to prevent ID hallucination
          - If the label doesn't match, the operation is automatically rolled back
          - This prevents corrupt models from incorrect IDs
      """
      client = get_client()
      resp = client.add_individual(model_id, class_curie, assign_var, expected_label=class_label)
  
      if resp.validation_failed:
          return {
              "success": False,
              "error": "Validation failed",
              "reason": resp.validation_reason,
              "rolled_back": True,
              "expected_label": class_label,
              "class_curie": class_curie
          }
  
      if resp.error:
          return {
              "success": False,
              "error": resp.error,
              "model_id": model_id,
              "class_curie": class_curie
          }
  
      # Get the actual individual ID from model_vars or from the individuals list
      individual_id = assign_var
      if resp.model_vars and assign_var in resp.model_vars:
          individual_id = resp.model_vars[assign_var]
      elif resp.individuals and len(resp.individuals) > 0:
          # If model_vars is empty, get the ID from the last individual (the one just created)
          individual_id = resp.individuals[-1].id
  
      # Return minimal success response
      return {
          "success": True,
          "individual_id": individual_id,
          "class_curie": class_curie,
          "assign_var": assign_var
      }