pyResToolbox MCP Server

Instructions

Implementation Reference

• src/pyrestoolbox_mcp/tools/brine_tools.py:153-311 (handler)

  The main handler function decorated with @mcp.tool(). Implements CO2-brine mutual solubility using pyrestoolbox.brine.CO2_Brine_Mixture class from Duan & Sun (2003) model. Handles input validation via Pydantic and returns comprehensive phase properties, densities, viscosities, etc.
  @mcp.tool() def co2_brine_mutual_solubility(request: CO2BrineMixtureRequest) -> dict: """Calculate CO2-brine mutual solubilities and properties. **CRITICAL CO2-BRINE SYSTEM TOOL** - Computes comprehensive properties for CO2-saturated brine systems using the Duan & Sun (2003) model. Essential for CO2 sequestration, CO2-EOR, and geothermal applications. Accounts for mutual solubility (CO2 in brine, H2O in CO2-rich phase). **Parameters:** - **pres** (float, required): Pressure in psia (field) or bar (metric). Must be > 0. Typical: 1000-5000 psia. Example: 3000.0 psia. - **temp** (float, required): Temperature in °F (field) or °C (metric). Typical: 100-400°F. Example: 180.0°F. - **ppm** (float, required): Salinity in parts per million (ppm) NaCl. Typical: 0-200000 ppm. Example: 50000 ppm (5 wt%). - **metric** (bool, optional, default=False): Unit system flag. False = field units (psia, °F), True = metric (bar, °C). - **cw_sat** (bool, optional, default=True): Compressibility calculation flag. True = saturated compressibility, False = undersaturated. **Properties Calculated:** - **Phase Equilibrium:** - Aqueous phase mole fractions (x_CO2, x_H2O) - Vapor phase mole fractions (y_CO2, y_H2O) - Salt mole fraction - **Densities:** - CO2-rich gas density (gm/cm³) - Brine CO2-saturated density (gm/cm³) - Brine pure density (gm/cm³) - Fresh water density (gm/cm³) - **Viscosities:** - Brine CO2-saturated viscosity (cP) - Brine pure viscosity (cP) - Fresh water viscosity (cP) - **Formation Volume Factors:** - Bw CO2-saturated (rb/stb) - Bw pure (rb/stb) - Bw fresh (rb/stb) - **Compressibility:** - Undersaturated compressibility (1/psi or 1/bar) - Saturated compressibility (1/psi or 1/bar) - **Solution GOR:** CO2 dissolved in brine (scf/stb or m³/m³) **Mutual Solubility:** CO2-brine systems exhibit mutual solubility: - CO2 dissolves in brine (increases with pressure, decreases with salinity) - H2O dissolves in CO2-rich phase (increases with temperature) - Both solubilities depend on pressure, temperature, and salinity **Physics:** Uses Duan & Sun (2003) model for CO2-H2O-NaCl systems accounting for: - Pressure effects on solubility (higher P = more CO2 dissolved) - Temperature effects (higher T = less CO2 dissolved, more H2O in vapor) - Salinity effects (higher salinity = less CO2 dissolved) - Mutual solubility (both phases contain both components) **Applications:** - **CO2 Sequestration:** CCS project design, storage capacity evaluation - **CO2-EOR:** Enhanced oil recovery with CO2 injection, miscibility studies - **Geothermal:** CO2-based geothermal systems, supercritical CO2 - **Aquifer Storage:** Underground CO2 storage capacity, leakage assessment - **Material Balance:** CO2-brine material balance calculations **Salinity Conversion:** - 1 wt% = 10,000 ppm - Seawater ≈ 35,000 ppm (3.5 wt%) - Formation brine: 50,000-200,000 ppm (5-20 wt%) **Returns:** Dictionary with: - **phase_equilibrium** (dict): Mole fractions in aqueous and vapor phases - **densities** (dict): All density values (CO2-rich, saturated, pure, fresh) - **viscosities** (dict): All viscosity values (saturated, pure, fresh) - **formation_volume_factors** (dict): Bw values (saturated, pure, fresh) - **compressibility** (dict): Undersaturated and saturated compressibility - **solution_gor_co2** (float): CO2 dissolved in brine - **viscosibility_per_bar_or_psi** (float): Viscosibility coefficient - **method** (str): "Duan & Sun (2003) CO2-H2O-NaCl model" - **units** (str): "metric" or "field" - **note** (str): Usage guidance - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using wrong unit system (check metric flag) - Salinity in wt% instead of ppm (must convert: ppm = wt% × 10000) - Pressure in barg/psig instead of psia (must be absolute) - Temperature in wrong units (check metric flag) - Not accounting for mutual solubility (both phases contain both components) - Using wrong compressibility (saturated vs undersaturated) **Example Usage (Field Units):** ```python { "pres": 3000.0, "temp": 180.0, "ppm": 50000, "metric": False, "cw_sat": True } ``` Result: CO2 solubility in brine ≈ 20-40 scf/stb, H2O in CO2-rich phase ≈ 0.1-1 mol%. **Note:** CO2-brine mutual solubility is critical for CCS and CO2-EOR projects. Always use correct unit system (field vs metric). The model accounts for mutual solubility which is significant at high pressures and temperatures. Salinity significantly reduces CO2 solubility - use correct formation water salinity. """ # Create CO2_Brine_Mixture object mixture = brine.CO2_Brine_Mixture( pres=request.pres, temp=request.temp, ppm=request.ppm, metric=request.metric, cw_sat=request.cw_sat ) # Extract all properties, handling None values result = { "phase_equilibrium": { "aqueous_phase_mole_fractions": { "x_co2": float(mixture.x[0]) if mixture.x is not None else 0.0, "x_h2o": float(mixture.x[1]) if mixture.x is not None and len(mixture.x) > 1 else 1.0, }, "vapor_phase_mole_fractions": { "y_co2": float(mixture.y[0]) if mixture.y is not None else 0.0, "y_h2o": float(mixture.y[1]) if mixture.y is not None and len(mixture.y) > 1 else 0.0, }, "salt_mole_fraction": float(mixture.xSalt) if mixture.xSalt is not None else 0.0, }, "densities": { "co2_rich_gas_gm_cm3": float(mixture.rhoGas) if mixture.rhoGas is not None else 0.0, "brine_co2_saturated_gm_cm3": float(mixture.bDen[0]) if mixture.bDen is not None else 0.0, "brine_pure_gm_cm3": float(mixture.bDen[1]) if mixture.bDen is not None and len(mixture.bDen) > 1 else 0.0, "fresh_water_gm_cm3": float(mixture.bDen[2]) if mixture.bDen is not None and len(mixture.bDen) > 2 else 0.0, }, "viscosities": { "brine_co2_saturated_cP": float(mixture.bVis[0]) if mixture.bVis is not None else 0.0, "brine_pure_cP": float(mixture.bVis[1]) if mixture.bVis is not None and len(mixture.bVis) > 1 else 0.0, "fresh_water_cP": float(mixture.bVis[2]) if mixture.bVis is not None and len(mixture.bVis) > 2 else 0.0, }, "viscosibility_per_bar_or_psi": float(mixture.bVisblty) if mixture.bVisblty is not None else 0.0, "formation_volume_factors": { "bw_co2_saturated": float(mixture.bw[0]) if mixture.bw is not None else 1.0, "bw_pure": float(mixture.bw[1]) if mixture.bw is not None and len(mixture.bw) > 1 else 1.0, "bw_fresh": float(mixture.bw[2]) if mixture.bw is not None and len(mixture.bw) > 2 else 1.0, }, "solution_gor_co2": float(mixture.Rs) if mixture.Rs is not None else 0.0, "compressibility": { "undersaturated_per_bar_or_psi": float(mixture.Cf_usat) if mixture.Cf_usat is not None else 0.0, "saturated_per_bar_or_psi": float(mixture.Cf_sat) if mixture.Cf_sat is not None else 0.0, }, "method": "Duan & Sun (2003) CO2-H2O-NaCl model", "units": "metric" if request.metric else "field", "inputs": request.model_dump(), "note": "Critical for CO2 sequestration, EOR, and geothermal applications" } return result
• src/pyrestoolbox_mcp/models/brine_models.py:51-73 (schema)

  Pydantic model defining the input schema with validation for pres, temp, ppm, metric, cw_sat parameters, including example and descriptions.
  class CO2BrineMixtureRequest(BaseModel): """Request model for CO2-brine mutual solubility calculation.""" model_config = ConfigDict( json_schema_extra={ "example": { "pres": 3000.0, "temp": 150.0, "ppm": 50000.0, "metric": False, "cw_sat": 0.0, } } ) pres: float = Field(..., gt=0, description="Pressure (psia if metric=False, bar if metric=True)") temp: float = Field(..., gt=0, description="Temperature (degF if metric=False, degC if metric=True)") ppm: float = Field(..., ge=0, description="Brine salinity (ppm)") metric: bool = Field(False, description="Use metric units (True) or field units (False)") cw_sat: float = Field( 0.0, ge=0, description="Cw at saturation pressure (1/psi or 1/bar) - 0 for auto-calculate" )
• src/pyrestoolbox_mcp/server.py:20-30 (registration)

  Imports register_brine_tools from brine_tools.py and calls it with the MCP server instance, which defines and registers the co2_brine_mutual_solubility tool (along with calculate_brine_properties).
  from .tools.brine_tools import register_brine_tools from .tools.layer_tools import register_layer_tools from .tools.library_tools import register_library_tools register_oil_tools(mcp) register_gas_tools(mcp) register_inflow_tools(mcp) register_simtools_tools(mcp) register_brine_tools(mcp) register_layer_tools(mcp) register_library_tools(mcp)
• src/pyrestoolbox_mcp/tools/brine_tools.py:10-12 (registration)

  The register_brine_tools function where the tool functions are defined with @mcp.tool() decorators inside it, effectively registering them when called.
  def register_brine_tools(mcp: FastMCP) -> None: """Register all brine-related tools with the MCP server."""