Noctua MCP Server

Instructions

# Create set with evidence
add_entity_set(
    "gomodel:12345",
    [
        {
            "entity_id": "UniProtKB:P04637",
            "label": "TP53",
            "evidence_type": "ECO:0000314",
            "reference": "PMID:87654321"
        },
        {
            "entity_id": "UniProtKB:P04049",
            "label": "RAF1",
            "evidence_type": "ECO:0000314",
            "reference": "PMID:87654321"
        }
    ],
)

Implementation Reference

• src/noctua_mcp/mcp_server.py:569-687 (handler)

  The primary handler for the 'add_entity_set' MCP tool. This async function is decorated with @mcp.tool(), registering it automatically. It handles input validation using Pydantic EntitySetMember models, calls the underlying BaristaClient.add_entity_set, processes the response, and returns structured results including success status, set ID, and member count.

  @mcp.tool()
  async def add_entity_set(
      model_id: str,
      members: List[Dict[str, Any]],
      assign_var: str = "set1"
  ) -> Dict[str, Any]:
      """
      Add an entity set to a GO-CAM model with validated members.
  
      Creates an entity set (CHEBI:33695 "information biomacromolecule" by default)
      representing functionally interchangeable entities. Links members using
      RO:0019003 (has substitutable entity) relation. The operation is atomic -
      either all members are added successfully or the entire operation is rolled back.
  
      Args:
          model_id: The GO-CAM model identifier
          members: List of member dictionaries with keys:
                  - entity_id (required): Entity ID (e.g., "UniProtKB:P12345")
                  - label (optional): Member 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 set (default: "set1")
  
      Returns:
          Barista API response with set ID and member IDs
  
      Examples:
          # Create a set of functionally equivalent kinases
          add_entity_set(
              "gomodel:12345",
              [
                  {"entity_id": "UniProtKB:P31749", "label": "AKT1"},
                  {"entity_id": "UniProtKB:P31751", "label": "AKT2"},
                  {"entity_id": "UniProtKB:Q9Y243", "label": "AKT3"}
              ],
              assign_var="akt_isoforms"
          )
  
          # Create set with evidence
          add_entity_set(
              "gomodel:12345",
              [
                  {
                      "entity_id": "UniProtKB:P04637",
                      "label": "TP53",
                      "evidence_type": "ECO:0000314",
                      "reference": "PMID:87654321"
                  },
                  {
                      "entity_id": "UniProtKB:P04049",
                      "label": "RAF1",
                      "evidence_type": "ECO:0000314",
                      "reference": "PMID:87654321"
                  }
              ],
          )
  
      Notes:
          - All members must have entity_id specified
          - Label validation prevents ID hallucination
          - Evidence and references are optional but recommended
          - Uses RO:0019003 (has substitutable entity) to link members
          - Atomic operation with automatic rollback on failure
          - Entity sets represent functionally interchangeable entities
      """
      client = get_client()
  
      # Convert member dicts to Pydantic models
      try:
          pydantic_members = [EntitySetMember(**member) for member in members]
      except Exception as e:
          return {
              "success": False,
              "error": "Invalid member structure",
              "reason": str(e),
              "hint": "Each member must have 'entity_id' field. Optional: 'label', 'evidence_type', 'reference'"
          }
  
      # Call the new add_entity_set method
      resp = client.add_entity_set(
          model_id,
          pydantic_members,
          assign_var=assign_var,
      )
  
      if resp.validation_failed:
          return {
              "success": False,
              "error": "Validation failed",
              "reason": resp.validation_reason,
              "rolled_back": True,
              "member_count": len(members)
          }
  
      if resp.error:
          return {
              "success": False,
              "error": resp.error,
              "model_id": model_id,
          }
  
      # Get the set ID from model_vars or from the individuals list
      set_id = assign_var
      if resp.model_vars and assign_var in resp.model_vars:
          set_id = resp.model_vars[assign_var]
      elif resp.individuals and len(resp.individuals) > 0:
          # Find the set individual - it should be the first one created
          # Look for an entity set (typically CHEBI:33695 or similar)
          for ind in resp.individuals:
              if hasattr(ind, 'type') and any('CHEBI' in str(t.id) if hasattr(t, 'id') else False for t in ind.type):
                  set_id = ind.id
                  break
  
      return {
          "success": True,
          "set_id": set_id,
          "member_count": len(members),
          "assign_var": assign_var
      }