rowan-mcp 1.0.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

rowan_mcp/__init__.py

@@ -5,8 +5,8 @@ This package provides MCP (Model Context Protocol) server functionality
 for integrating with Rowan's computational chemistry platform.
 """
 
-__version__ = "1.0.0"
-__author__ = "Rowan MCP Team"
+__version__ = "1.0.2"
+__author__ = "Kat Yenko"
 __description__ = "MCP server for Rowan computational chemistry platform"
 
 from .server import main

rowan_mcp/__main__.py

@@ -2,13 +2,11 @@
 Main entry point for Rowan MCP Server when run as a module.
 
 Usage:
-    python -m src                # STDIO mode (default)
-    python -m src --stdio        # STDIO mode  
-    python -m src --http         # HTTP mode
-    python -m src --help         # Show help
+    python -m rowan_mcp          # HTTP/SSE mode
+    python -m rowan_mcp --help   # Show help
 """
 
 if __name__ == "__main__":
-    # All modes now handled by the unified server
+    # HTTP transport only
     from .server import main
     main() 

rowan_mcp/functions_v2/BENCHMARK.md

@@ -0,0 +1,86 @@
+# Rowan MCP Benchmark Suite
+
+## Overview
+Systematic evaluation of the Rowan MCP server's ability to handle chemistry workflows through natural language queries.
+
+## Evaluation Tiers
+
+### Tier 1: Single Tool Calls
+**Tests**: Basic tool invocation and parameter passing  
+**Characteristics**:
+- Single workflow submission
+- Explicit parameters
+- No dependencies
+- Direct SMILES or common molecule names
+
+**Example Queries**:
+- "Calculate the pKa of phenol"
+- "Optimize water geometry with GFN2-xTB"
+- "Find conformers of ethanol"
+
+### Tier 2: Parameter Interpretation
+**Tests**: Natural language to parameter mapping, molecule name resolution  
+**Characteristics**:
+- Requires interpreting descriptive terms into API parameters
+- Mode selection (rapid/careful/meticulous)
+- Element specification by name vs atomic number
+- Common name to SMILES conversion
+
+**Example Queries**:
+- "Calculate the oxidation potential of caffeine using careful mode"
+- "Find the pKa of aspirin, only considering oxygen atoms"
+- "Dock ibuprofen to CDK2 without optimization"
+
+### Tier 3: Batch Operations
+**Tests**: Multiple independent calculations, result organization  
+**Characteristics**:
+- Multiple molecules or methods
+- Parallel workflow submission
+- Result comparison/aggregation
+- Folder organization
+
+**Example Queries**:
+- "Calculate pKa for phenol, p-nitrophenol, and p-chlorophenol"
+- "Optimize butane with GFN2-xTB, UMA, and R2SCAN-3c methods"
+- "Screen 5 molecules for docking against CDK2"
+
+### Tier 4: Workflow Chaining
+**Tests**: Sequential dependent calculations, data extraction from results  
+**Characteristics**:
+- Output from one workflow feeds into next
+- Requires waiting for completion
+- UUID and result extraction
+- Proper async handling
+
+**Example Queries**:
+- "Find conformers of benzophenone, then calculate redox potential for top 3"
+- "Optimize this transition state, then run IRC from the result"
+- "Calculate pKa, then run conformer search at the predicted pKa value"
+
+### Tier 5: Conditional Logic
+**Tests**: Decision-making based on results, complex multi-step analysis  
+**Characteristics**:
+- Conditional branching based on results
+- Threshold-based decisions
+- Error handling and retries
+- Statistical analysis of results
+
+**Example Queries**:
+- "Screen molecules for docking, only run detailed analysis if score < -8.0"
+- "Calculate conformer energies, identify outliers (>2 kcal/mol from lowest), recalculate outliers with meticulous mode"
+- "Find pKa sites, if any are between 6-8, run pH-dependent calculations at those values"
+
+## Scoring Criteria
+
+### Per Query
+- **Success**: Workflow submitted correctly (1 point)
+- **Parameters**: All parameters correctly mapped (1 point)
+- **Completion**: Workflow completes without error (1 point)
+- **Chaining**: Dependencies handled correctly (1 point, Tier 4-5 only)
+- **Logic**: Conditional logic executed correctly (1 point, Tier 5 only)
+
+### Overall Metrics
+- Success rate per tier
+- Average time to completion
+- Error recovery rate
+- Parameter accuracy rate

rowan_mcp/functions_v2/molecule_lookup.py

@@ -0,0 +1,232 @@
+"""
+Molecule name to SMILES converter using Chemical Identifier Resolver (CIR).
+Enables natural language molecule input for Rowan workflows.
+"""
+
+from typing import List, Dict, Annotated
+from urllib.request import urlopen
+from urllib.parse import quote
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def molecule_lookup(
+    molecule_name: Annotated[str, "Common name, IUPAC name, or CAS number of molecule (e.g., 'aspirin', 'caffeine', '50-78-2')"],
+    fallback_to_input: Annotated[bool, "If lookup fails, return the input string assuming it might be SMILES"] = False
+) -> str:
+    """Convert molecule names to SMILES using Chemical Identifier Resolver (CIR).
+    
+    Args:
+        molecule_name: Common name, IUPAC name, or CAS number of molecule (e.g., 'aspirin', 'caffeine', '50-78-2')
+        fallback_to_input: If lookup fails, return the input string assuming it might be SMILES
+    
+    This tool enables natural language input for molecules by converting common names,
+    IUPAC names, CAS numbers, and other identifiers to SMILES strings that can be
+    used with Rowan workflows.
+    
+    Supported Input Types:
+    - Common names: 'aspirin', 'caffeine', 'benzene', 'glucose'
+    - IUPAC names: '2-acetoxybenzoic acid', '1,3,7-trimethylpurine-2,6-dione'
+    - CAS numbers: '50-78-2' (aspirin), '58-08-2' (caffeine)
+    - InChI strings
+    - Already valid SMILES (will be validated)
+    
+    Returns:
+        SMILES string if successful, error message if not found
+        
+    Examples:
+        # Common drug name
+        result = molecule_lookup("aspirin")
+        # Returns: "CC(=O)Oc1ccccc1C(=O)O"
+        
+        # IUPAC name
+        result = molecule_lookup("2-acetoxybenzoic acid")
+        # Returns: "CC(=O)Oc1ccccc1C(=O)O"
+        
+        # CAS number
+        result = molecule_lookup("50-78-2")
+        # Returns: "CC(=O)Oc1ccccc1C(=O)O"
+        
+        # Complex molecule
+        result = molecule_lookup("paracetamol")
+        # Returns: "CC(=O)Nc1ccc(O)cc1"
+    """
+    try:
+        # Clean input
+        molecule_name = molecule_name.strip()
+        
+        # Check if already SMILES-like (contains typical SMILES characters)
+        smiles_chars = {'=', '#', '(', ')', '[', ']', '@', '+', '-'}
+        if any(char in molecule_name for char in smiles_chars):
+            logger.info(f"Input '{molecule_name}' appears to be SMILES, returning as-is")
+            return molecule_name
+        
+        # Query CIR service
+        logger.info(f"Looking up molecule: {molecule_name}")
+        url = f'http://cactus.nci.nih.gov/chemical/structure/{quote(molecule_name)}/smiles'
+        
+        response = urlopen(url, timeout=10)
+        smiles = response.read().decode('utf8').strip()
+        
+        # CIR may return multiple SMILES for some queries, take the first one
+        if '\n' in smiles:
+            smiles = smiles.split('\n')[0]
+        
+        logger.info(f"Successfully converted '{molecule_name}' to SMILES: {smiles}")
+        return smiles
+        
+    except Exception as e:
+        logger.warning(f"Failed to lookup '{molecule_name}': {e}")
+        
+        if fallback_to_input:
+            logger.info(f"Returning original input as fallback: {molecule_name}")
+            return molecule_name
+        else:
+            return f"Could not find SMILES for '{molecule_name}'. Please check the name or provide a valid SMILES string."
+
+
+def batch_molecule_lookup(
+    molecule_names: Annotated[List[str], "List of molecule names to convert to SMILES"],
+    skip_failures: Annotated[bool, "Skip molecules that fail lookup instead of stopping"] = True
+) -> Dict[str, str]:
+    """Convert multiple molecule names to SMILES in batch.
+    
+    Args:
+        molecule_names: List of molecule names to convert to SMILES
+        skip_failures: Skip molecules that fail lookup instead of stopping
+    
+    Useful for preparing multiple molecules for workflows or screening.
+        
+    Returns:
+        Dictionary mapping input names to SMILES strings (or error messages)
+        
+    Examples:
+        # Drug screening set
+        result = batch_molecule_lookup([
+            "aspirin",
+            "ibuprofen", 
+            "paracetamol",
+            "caffeine"
+        ])
+        # Returns: {
+        #     "aspirin": "CC(=O)Oc1ccccc1C(=O)O",
+        #     "ibuprofen": "CC(C)Cc1ccc(C(C)C(=O)O)cc1",
+        #     "paracetamol": "CC(=O)Nc1ccc(O)cc1",
+        #     "caffeine": "CN1C=NC2=C1C(=O)N(C(=O)N2C)C"
+        # }
+        
+        # Mixed input types
+        result = batch_molecule_lookup([
+            "benzene",           # Common name
+            "50-78-2",          # CAS number
+            "ethanoic acid"     # IUPAC name
+        ])
+    """
+    results = {}
+    
+    for name in molecule_names:
+        try:
+            smiles = molecule_lookup(name, fallback_to_input=False)
+            results[name] = smiles
+        except Exception as e:
+            error_msg = f"Lookup failed: {str(e)}"
+            if skip_failures:
+                logger.warning(f"Skipping {name}: {error_msg}")
+                results[name] = error_msg
+            else:
+                raise ValueError(f"Failed to lookup '{name}': {error_msg}")
+    
+    return results
+
+
+def validate_smiles(
+    smiles: Annotated[str, "SMILES string to validate"]
+) -> Dict[str, any]:
+    """Validate a SMILES string and return basic molecular properties.
+    
+    Args:
+        smiles: SMILES string to validate
+    
+    Uses RDKit to validate SMILES and extract basic properties.
+        
+    Returns:
+        Dictionary with validation status and properties if valid
+        
+    Examples:
+        result = validate_smiles("CC(=O)O")
+        # Returns: {
+        #     "valid": True,
+        #     "canonical_smiles": "CC(=O)O",
+        #     "molecular_formula": "C2H4O2",
+        #     "molecular_weight": 60.05
+        # }
+    """
+    try:
+        from rdkit import Chem
+        from rdkit.Chem import Descriptors
+        
+        mol = Chem.MolFromSmiles(smiles)
+        
+        if mol is None:
+            return {
+                "valid": False,
+                "error": "Invalid SMILES string"
+            }
+        
+        return {
+            "valid": True,
+            "canonical_smiles": Chem.MolToSmiles(mol),
+            "molecular_formula": Chem.rdMolDescriptors.CalcMolFormula(mol),
+            "molecular_weight": round(Descriptors.MolWt(mol), 2),
+            "num_atoms": mol.GetNumAtoms(),
+            "num_bonds": mol.GetNumBonds()
+        }
+        
+    except ImportError:
+        return {
+            "valid": "unknown",
+            "error": "RDKit not available for validation"
+        }
+    except Exception as e:
+        return {
+            "valid": False,
+            "error": str(e)
+        }
+
+
+# Common molecules reference (for documentation)
+COMMON_MOLECULES = {
+    # Drugs
+    "aspirin": "CC(=O)Oc1ccccc1C(=O)O",
+    "paracetamol": "CC(=O)Nc1ccc(O)cc1",
+    "acetaminophen": "CC(=O)Nc1ccc(O)cc1",  # Same as paracetamol
+    "ibuprofen": "CC(C)Cc1ccc(C(C)C(=O)O)cc1",
+    "caffeine": "CN1C=NC2=C1C(=O)N(C(=O)N2C)C",
+    "penicillin": "CC1(C)SC2C(NC(=O)Cc3ccccc3)C(=O)N2C1C(=O)O",
+    
+    # Solvents
+    "water": "O",
+    "ethanol": "CCO",
+    "methanol": "CO",
+    "acetone": "CC(=O)C",
+    "dmso": "CS(=O)C",
+    "chloroform": "C(Cl)(Cl)Cl",
+    "benzene": "c1ccccc1",
+    "toluene": "Cc1ccccc1",
+    
+    # Organic compounds
+    "glucose": "C(C1C(C(C(C(O1)O)O)O)O)O",
+    "acetic acid": "CC(=O)O",
+    "ethanoic acid": "CC(=O)O",  # IUPAC for acetic acid
+    "phenol": "Oc1ccccc1",
+    "aniline": "Nc1ccccc1",
+    "naphthalene": "c1ccc2c(c1)cccc2",
+    
+    # Amino acids
+    "glycine": "C(C(=O)O)N",
+    "alanine": "CC(C(=O)O)N",
+    "valine": "CC(C)C(C(=O)O)N",
+    "leucine": "CC(C)CC(C(=O)O)N",
+    "lysine": "C(CCN)CC(C(=O)O)N",
+}

rowan_mcp/functions_v2/protein_management.py

@@ -0,0 +1,141 @@
+"""
+Rowan v2 API: Protein Management
+Tools for creating, retrieving, and managing protein structures.
+"""
+
+from typing import List, Dict, Any, Annotated
+import rowan
+
+
+def create_protein_from_pdb_id(
+    name: Annotated[str, "Name for the protein"],
+    code: Annotated[str, "PDB ID code (e.g., '1HCK')"]
+) -> Dict[str, Any]:
+    """Create a protein from a PDB ID.
+    
+    Args:
+        name: Name for the protein
+        code: PDB ID code (e.g., '1HCK')
+    
+    Returns:
+        Dictionary containing protein information
+    """
+    protein = rowan.create_protein_from_pdb_id(name=name, code=code)
+    
+    return {
+        "uuid": protein.uuid,
+        "name": protein.name,
+        "sanitized": protein.sanitized,
+        "created_at": str(protein.created_at) if protein.created_at else None
+    }
+
+
+def retrieve_protein(
+    uuid: Annotated[str, "UUID of the protein to retrieve"]
+) -> Dict[str, Any]:
+    """Retrieve a protein by UUID.
+    
+    Args:
+        uuid: UUID of the protein to retrieve
+    
+    Returns:
+        Dictionary containing the protein data
+    """
+    protein = rowan.retrieve_protein(uuid)
+    
+    return {
+        "uuid": protein.uuid,
+        "name": protein.name,
+        "sanitized": protein.sanitized,
+        "created_at": str(protein.created_at) if protein.created_at else None
+    }
+
+
+def list_proteins(
+    page: Annotated[int, "Page number (0-indexed)"] = 0,
+    size: Annotated[int, "Number per page"] = 20
+) -> List[Dict[str, Any]]:
+    """List proteins.
+    
+    Args:
+        page: Page number (0-indexed)
+        size: Number per page
+    
+    Returns:
+        List of protein dictionaries
+    """
+    proteins = rowan.list_proteins(page=page, size=size)
+    
+    return [
+        {
+            "uuid": p.uuid,
+            "name": p.name,
+            "sanitized": p.sanitized,
+            "created_at": str(p.created_at) if p.created_at else None
+        }
+        for p in proteins
+    ]
+
+
+def upload_protein(
+    name: Annotated[str, "Name for the protein"],
+    file_path: Annotated[str, "Path to PDB file"]
+) -> Dict[str, Any]:
+    """Upload a protein from a PDB file.
+    
+    Args:
+        name: Name for the protein
+        file_path: Path to PDB file
+    
+    Returns:
+        Dictionary containing protein information
+    """
+    from pathlib import Path
+    protein = rowan.upload_protein(name=name, file_path=Path(file_path))
+    
+    return {
+        "uuid": protein.uuid,
+        "name": protein.name,
+        "sanitized": protein.sanitized,
+        "created_at": str(protein.created_at) if protein.created_at else None
+    }
+
+
+def delete_protein(
+    uuid: Annotated[str, "UUID of the protein to delete"]
+) -> Dict[str, str]:
+    """Delete a protein.
+    
+    Args:
+        uuid: UUID of the protein to delete
+    
+    Returns:
+        Dictionary with confirmation message
+    """
+    protein = rowan.retrieve_protein(uuid)
+    protein.delete()
+    
+    return {
+        "message": f"Protein {uuid} deleted",
+        "uuid": uuid
+    }
+
+
+def sanitize_protein(
+    uuid: Annotated[str, "UUID of the protein to sanitize"]
+) -> Dict[str, Any]:
+    """Sanitize a protein for docking.
+    
+    Args:
+        uuid: UUID of the protein to sanitize
+    
+    Returns:
+        Dictionary with sanitization status
+    """
+    protein = rowan.retrieve_protein(uuid)
+    protein.sanitize()
+    
+    return {
+        "uuid": uuid,
+        "message": f"Protein {uuid} sanitized"
+    }

rowan_mcp/functions_v2/submit_basic_calculation_workflow.py

@@ -0,0 +1,195 @@
+"""
+Rowan v2 API: Basic Calculation Workflow
+Submit basic quantum chemistry calculations with various methods and tasks.
+"""
+
+# Simplified imports - no complex typing needed
+from typing import Annotated
+import rowan
+import stjames
+import json
+
+
+def submit_basic_calculation_workflow(
+    initial_molecule: Annotated[str, "SMILES string or molecule JSON for quantum chemistry calculation"],
+    method: Annotated[str, "Computational method (e.g., 'gfn2-xtb', 'uma_m_omol', 'b3lyp-d3bj')"] = "uma_m_omol",
+    tasks: Annotated[str, "JSON array or comma-separated list of tasks (e.g., '[\"optimize\"]', 'optimize, frequencies')"] = "",
+    mode: Annotated[str, "Calculation mode: 'rapid', 'careful', 'meticulous', or 'auto'"] = "auto", 
+    engine: Annotated[str, "Computational engine: 'omol25', 'xtb', 'psi4'"] = "omol25",
+    name: Annotated[str, "Workflow name for identification and tracking"] = "Basic Calculation Workflow",
+    folder_uuid: Annotated[str, "UUID of folder to organize this workflow. Empty string uses default folder"] = "",
+    max_credits: Annotated[int, "Maximum credits to spend on this calculation. 0 for no limit"] = 0
+):
+    """Submit a basic calculation workflow using Rowan v2 API.
+    
+    Performs fundamental quantum chemistry calculations with configurable methods
+    and computational tasks. Returns a workflow object for tracking progress.
+    
+    Examples:
+        # Simple water optimization with GFN2-xTB
+        result = submit_basic_calculation_workflow(
+            initial_molecule="O",
+            method="gfn2-xtb",
+            tasks=["optimize"],
+            engine="xtb",
+            name="Water Optimization"
+        )
+        
+        # Butane optimization from SMILES
+        result = submit_basic_calculation_workflow(
+            initial_molecule="CCCC",
+            method="gfn2-xtb",
+            tasks=["optimize"],
+            mode="rapid",
+            engine="xtb",
+            name="Butane Optimization"
+        )
+        
+        # Using a molecule dict (from data.json)
+        molecule_dict = {
+            "smiles": "CCCC",
+            "charge": 0,
+            "multiplicity": 1,
+            "atoms": [...]  # atomic positions
+        }
+        result = submit_basic_calculation_workflow(
+            initial_molecule=molecule_dict,
+            method="gfn2-xtb",
+            tasks=["optimize"],
+            engine="xtb"
+        )
+    """
+    
+    # Parse tasks parameter - handle string input
+    parsed_tasks = None
+    if tasks:  # If not empty string
+        tasks = tasks.strip()
+        if tasks.startswith('[') and tasks.endswith(']'):
+            # JSON array format like '["optimize"]'
+            try:
+                parsed_tasks = json.loads(tasks)
+            except (json.JSONDecodeError, ValueError):
+                # Failed to parse as JSON, try as comma-separated
+                tasks = tasks.strip('[]').replace('"', '').replace("'", "")
+                parsed_tasks = [t.strip() for t in tasks.split(',') if t.strip()]
+        elif ',' in tasks:
+            # Comma-separated format like 'optimize, frequencies'  
+            parsed_tasks = [t.strip() for t in tasks.split(',') if t.strip()]
+        else:
+            # Single task as string like 'optimize'
+            parsed_tasks = [tasks]
+    
+    
+    try:
+        # Handle initial_molecule parameter - could be JSON string, SMILES, or dict
+        if isinstance(initial_molecule, str):
+            # Check if it's a JSON string (starts with { or [)
+            initial_molecule_str = initial_molecule.strip()
+            if (initial_molecule_str.startswith('{') and initial_molecule_str.endswith('}')) or \
+               (initial_molecule_str.startswith('[') and initial_molecule_str.endswith(']')):
+                try:
+                    # Parse the JSON string to dict
+                    initial_molecule = json.loads(initial_molecule_str)
+                    
+                    # Now handle as dict (fall through to dict handling below)
+                    if isinstance(initial_molecule, dict) and 'smiles' in initial_molecule:
+                        smiles = initial_molecule.get('smiles')
+                        if smiles:
+                            try:
+                                initial_molecule = stjames.Molecule.from_smiles(smiles)
+                            except Exception as e:
+                                initial_molecule = smiles
+                except (json.JSONDecodeError, ValueError) as e:
+                    # Not valid JSON, treat as SMILES string
+                    try:
+                        initial_molecule = stjames.Molecule.from_smiles(initial_molecule)
+                    except Exception as e:
+                        pass
+            else:
+                # Regular SMILES string
+                try:
+                    initial_molecule = stjames.Molecule.from_smiles(initial_molecule)
+                except Exception as e:
+                    pass
+        elif isinstance(initial_molecule, dict) and 'smiles' in initial_molecule:
+            # If we have a dict with SMILES, extract and use just the SMILES
+            smiles = initial_molecule.get('smiles')
+            if smiles:
+                try:
+                    initial_molecule = stjames.Molecule.from_smiles(smiles)
+                except Exception as e:
+                    initial_molecule = smiles
+        
+        # Convert to appropriate format
+        if hasattr(initial_molecule, 'model_dump'):
+            initial_molecule_dict = initial_molecule.model_dump()
+        elif isinstance(initial_molecule, dict):
+            initial_molecule_dict = initial_molecule
+        else:
+            # Try to convert to StJamesMolecule if it's a string
+            try:
+                mol = stjames.Molecule.from_smiles(str(initial_molecule))
+                initial_molecule_dict = mol.model_dump()
+            except:
+                # If that fails, pass as-is
+                initial_molecule_dict = initial_molecule
+        
+        # Convert method string to Method object to get the correct name
+        if isinstance(method, str):
+            # Handle common method name variations
+            method_map = {
+                'gfn2_xtb': 'gfn2-xtb',
+                'gfn1_xtb': 'gfn1-xtb',
+                'gfn0_xtb': 'gfn0-xtb',
+                'r2scan_3c': 'r2scan-3c',
+                'wb97x_d3': 'wb97x-d3',
+                'wb97m_d3bj': 'wb97m-d3bj',
+                'b3lyp_d3bj': 'b3lyp-d3bj',
+                'uma_m_omol': 'uma_m_omol',  # This one stays the same
+            }
+            method = method_map.get(method, method)
+            
+            try:
+                method_obj = stjames.Method(method)
+                method_name = method_obj.name
+            except:
+                # If Method conversion fails, use the string as-is
+                method_name = method
+        else:
+            method_name = method
+        
+        # Use parsed tasks or default
+        final_tasks = parsed_tasks if parsed_tasks else ["optimize"]
+        
+        # Build workflow_data following the official API structure
+        workflow_data = {
+            "settings": {
+                "method": method_name,
+                "tasks": final_tasks,
+                "mode": mode,
+            },
+            "engine": engine,
+        }
+        
+        # Build the API request
+        data = {
+            "name": name,
+            "folder_uuid": folder_uuid if folder_uuid else None,
+            "workflow_type": "basic_calculation", 
+            "workflow_data": workflow_data,
+            "initial_molecule": initial_molecule_dict,
+            "max_credits": max_credits if max_credits > 0 else None,
+        }
+        
+        # Submit directly to API
+        from rowan.utils import api_client
+        from rowan import Workflow
+        
+        with api_client() as client:
+            response = client.post("/workflow", json=data)
+            response.raise_for_status()
+            return Workflow(**response.json())
+        
+    except Exception as e:
+        # Re-raise the exception so MCP can handle it
+        raise