pyResToolbox MCP Server

Instructions

{
    "pres": 3000.0,
    "temp": 180.0,
    "ppm": 50000,
    "metric": False,
    "cw_sat": True
}

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."""