Noctua MCP Server

Instructions

# Connect molecular function to cellular component (occurs_in)
add_fact("gomodel:12345", "mf1", "cc1", "BFO:0000066")

# Connect molecular function to biological process (part_of)
add_fact("gomodel:12345", "mf1", "bp1", "BFO:0000050")

# Add causal relationship between activities
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002411")  # causally upstream of
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002629")  # directly positively regulates
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002630")  # directly negatively regulates
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002413")  # provides input for

# Add regulates relationships
add_fact("gomodel:12345", "mf1", "bp1", "RO:0002211")  # regulates
add_fact("gomodel:12345", "mf1", "bp1", "RO:0002213")  # positively regulates
add_fact("gomodel:12345", "mf1", "bp1", "RO:0002212")  # negatively regulates

# Add indirect regulation relationships
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002407")  # indirectly positively regulates
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002409")  # indirectly negatively regulates

# Add causal relationships with effects
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002304")  # causally upstream of, positive effect
add_fact("gomodel:12345", "mf1", "mf2", "RO:0002305")  # causally upstream of, negative effect

# Add small molecule regulation relationships
add_fact("gomodel:12345", "sm1", "mf1", "RO:0012005")  # is small molecule activator of
add_fact("gomodel:12345", "sm1", "mf1", "RO:0012006")  # is small molecule inhibitor of

# Use with existing individual IDs from model
add_fact("gomodel:12345", "gomodel:12345/abc123", "gomodel:12345/def456", "RO:0002333")

Implementation Reference

• src/noctua_mcp/mcp_server.py:242-336 (handler)

  The primary handler for the 'add_fact' MCP tool. It resolves subject/object identifiers using BaristaClient._resolve_identifier, constructs a req_add_fact request, executes it via m3_batch, handles validation errors with rollback info, and returns success/failure responses.

  @mcp.tool()
  async def add_fact(
      model_id: str,
      subject_id: str,
      object_id: str,
      predicate_id: str
  ) -> Dict[str, Any]:
      """
      Add a fact (edge/relation) between two individuals in a model.
  
      Args:
          model_id: The GO-CAM model identifier
          subject_id: Subject individual ID or variable
          object_id: Object individual ID or variable
          predicate_id: Relation predicate (e.g., "RO:0002333" for enabled_by)
  
      Returns:
          Barista API response
  
      Examples:
          # Connect molecular function to gene product (enabled_by)
          add_fact("gomodel:12345", "mf1", "gp1", "RO:0002333")
  
          # Connect molecular function to cellular component (occurs_in)
          add_fact("gomodel:12345", "mf1", "cc1", "BFO:0000066")
  
          # Connect molecular function to biological process (part_of)
          add_fact("gomodel:12345", "mf1", "bp1", "BFO:0000050")
  
          # Add causal relationship between activities
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002411")  # causally upstream of
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002629")  # directly positively regulates
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002630")  # directly negatively regulates
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002413")  # provides input for
  
          # Add regulates relationships
          add_fact("gomodel:12345", "mf1", "bp1", "RO:0002211")  # regulates
          add_fact("gomodel:12345", "mf1", "bp1", "RO:0002213")  # positively regulates
          add_fact("gomodel:12345", "mf1", "bp1", "RO:0002212")  # negatively regulates
  
          # Add indirect regulation relationships
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002407")  # indirectly positively regulates
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002409")  # indirectly negatively regulates
  
          # Add causal relationships with effects
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002304")  # causally upstream of, positive effect
          add_fact("gomodel:12345", "mf1", "mf2", "RO:0002305")  # causally upstream of, negative effect
  
          # Add small molecule regulation relationships
          add_fact("gomodel:12345", "sm1", "mf1", "RO:0012005")  # is small molecule activator of
          add_fact("gomodel:12345", "sm1", "mf1", "RO:0012006")  # is small molecule inhibitor of
  
          # Use with existing individual IDs from model
          add_fact("gomodel:12345", "gomodel:12345/abc123", "gomodel:12345/def456", "RO:0002333")
      """
      client = get_client()
  
      # Resolve any variables to actual IDs
      resolved_subject = client._resolve_identifier(model_id, subject_id)
      resolved_object = client._resolve_identifier(model_id, object_id)
  
      req = client.req_add_fact(model_id, resolved_subject, resolved_object, predicate_id)
      resp = client.m3_batch([req])
  
      if resp.validation_failed:
          return {
              "success": False,
              "error": "Validation failed",
              "reason": resp.validation_reason,
              "rolled_back": True,
              "fact": {
                  "subject": subject_id,
                  "predicate": predicate_id,
                  "object": object_id
              }
          }
  
      if resp.error:
          return {
              "success": False,
              "error": resp.error,
              "model_id": model_id,
              "fact": {
                  "subject": subject_id,
                  "predicate": predicate_id,
                  "object": object_id
              }
          }
  
      # Return minimal success response
      return {
          "success": True,
          "fact_added": True
      }