pyResToolbox MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/pyrestoolbox_mcp/tools/brine_tools.py:13-151 (handler)

  Core implementation of the calculate_brine_properties tool. Computes brine density, viscosity, compressibility, FVF, and solution GOR using pyrestoolbox.brine.brine_props correlation, supporting CH4/CO2 saturation and array inputs.
  @mcp.tool() def calculate_brine_properties(request: BrinePropertiesRequest) -> dict: """Calculate properties of CH4 or CO2 saturated brine. **BRINE PVT TOOL** - Computes comprehensive brine properties including density, viscosity, compressibility, and formation volume factor. Essential for aquifer analysis, water injection, and CO2 sequestration studies. **Parameters:** - **p** (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3000.0 or [1000, 2000, 3000]. - **degf** (float, required): Temperature in °F. Valid: -460 to 1000. Typical: 100-400°F. Example: 180.0. - **wt** (float, required): Salinity in weight percent NaCl (0-30). Typical: 0-20 wt%. Example: 5.0 for 5% NaCl brine. - **ch4** (float, optional, default=0.0): CH4 saturation fraction (0-1). Typical: 0-0.1. Example: 0.05 for 5% CH4 saturation. - **co2** (float, optional, default=0.0): CO2 saturation fraction (0-1). Typical: 0-0.1. Example: 0.03 for 3% CO2 saturation. **Properties Calculated:** - **Density (ρw):** Brine density in lb/cuft. Increases with salinity, pressure. Typical: 60-70 lb/cuft. - **Viscosity (μw):** Brine viscosity in cP. Decreases with temperature, increases with salinity. Typical: 0.3-1.5 cP. - **Compressibility (cw):** Brine compressibility in 1/psi. Critical for aquifer influx. Typical: 2e-6 to 5e-6 1/psi. - **Formation Volume Factor (Bw):** Volume ratio rb/stb. Slightly > 1.0. Typical: 1.01-1.05 rb/stb. - **Solution GOR (Rw):** Gas dissolved in brine in scf/stb. Increases with pressure. Typical: 0-20 scf/stb. **Dissolved Gas Effects:** - **CH4-saturated:** Methane dissolved in formation water (typical in aquifers) - **CO2-saturated:** CO2 dissolution (sequestration, EOR, geothermal) - Mixed systems supported (CH4 + CO2) - Dissolved gas reduces density and increases compressibility **Salinity Range:** 0-30 wt% NaCl (fresh water to highly saline) - Fresh water: 0 wt% - Brackish: 0.1-1 wt% - Seawater: ~3.5 wt% - Formation brine: 5-20 wt% - Highly saline: 20-30 wt% **Correlations:** Uses industry-standard correlations accounting for: - Pressure effects on density and viscosity - Temperature effects (viscosity decreases with T) - Salinity variations (density and viscosity increase with salinity) - Dissolved gas concentrations (reduces density) **Applications:** - **Aquifer Influx:** Calculate water influx rates and volumes - **Water Injection:** Design injection projects and pressure maintenance - **CO2 Sequestration:** Evaluate CO2 storage capacity and brine properties - **Geothermal Reservoirs:** Analyze geothermal brine properties - **Pressure Maintenance:** Evaluate aquifer pressure support - **Material Balance:** Include water drive in material balance calculations **Returns:** Dictionary with: - **formation_volume_factor_rb_stb** (float or list): Bw (matches input p shape) - **density_lb_cuft** (float or list): Brine density (matches input p shape) - **viscosity_cp** (float or list): Brine viscosity (matches input p shape) - **compressibility_1_psi** (float or list): Brine compressibility (matches input p shape) - **solution_gor_scf_stb** (float or list): Gas dissolved in brine (matches input p shape) - **method** (str): "Industry standard correlations" - **salinity_wt_percent** (float): Input salinity - **dissolved_gas_saturation** (float): Combined CH4+CO2 saturation - **note** (str): Usage guidance - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using separator temperature instead of reservoir temperature - Pressure in barg/psig instead of psia (must be absolute) - Salinity in ppm instead of wt% (must convert: wt% = ppm/10000) - Not accounting for dissolved gas (affects density and compressibility) - Temperature in Celsius instead of Fahrenheit - Confusing CH4 and CO2 saturation fractions **Example Usage:** ```python { "p": [1000, 2000, 3000], "degf": 180.0, "wt": 5.0, "ch4": 0.05, "co2": 0.0 } ``` Result: Brine density increases with pressure, viscosity decreases with temperature. Dissolved CH4 reduces density compared to pure brine. **Note:** Brine properties are critical for accurate aquifer modeling. Always account for dissolved gas (CH4 or CO2) as it significantly affects density and compressibility. Salinity has major impact on density and viscosity - use correct formation water salinity. """ # Calculate brine properties # brine_props expects ch4_sat (0-1 saturation), not separate ch4/co2 fractions # Use combined saturation as approximation ch4_saturation = request.ch4 + request.co2 result = brine.brine_props( p=request.p, degf=request.degf, wt=request.wt, ch4_sat=ch4_saturation, ) # Extract properties from result tuple # brine_props returns: (Bw, Density, viscosity, Compressibility, Rw GOR) # Convert numpy arrays to lists for JSON serialization bw, density, viscosity, compressibility, rw_gor = result response = { "formation_volume_factor_rb_stb": ( bw.tolist() if isinstance(bw, np.ndarray) else float(bw) ), "density_lb_cuft": ( density.tolist() if isinstance(density, np.ndarray) else float(density) ), "viscosity_cp": ( viscosity.tolist() if isinstance(viscosity, np.ndarray) else float(viscosity) ), "compressibility_1_psi": ( compressibility.tolist() if isinstance(compressibility, np.ndarray) else float(compressibility) ), "solution_gor_scf_stb": ( rw_gor.tolist() if isinstance(rw_gor, np.ndarray) else float(rw_gor) ), "method": "Industry standard correlations", "salinity_wt_percent": request.wt, "dissolved_gas_saturation": ch4_saturation, "inputs": request.model_dump(), "note": "Properties for NaCl brine with dissolved CH4/CO2", } return response
• src/pyrestoolbox_mcp/models/brine_models.py:7-49 (schema)

  Pydantic input schema for the tool, defining parameters p (pressure), degf (temperature), wt (salinity), ch4 and co2 (gas saturations) with validation and example.
  class BrinePropertiesRequest(BaseModel): """Request model for brine properties calculation.""" model_config = ConfigDict( json_schema_extra={ "example": { "p": 3000.0, "degf": 150.0, "wt": 10.0, "ch4": 0.0, "co2": 0.02, } } ) p: Union[float, List[float]] = Field( ..., description="Pressure (psia) - scalar or array" ) degf: Union[float, List[float]] = Field( ..., description="Temperature (degrees Fahrenheit) - scalar or array" ) wt: float = Field( ..., ge=0, le=30, description="Brine salinity (weight percent NaCl)" ) ch4: float = Field( 0.0, ge=0, description="Dissolved CH4 mole fraction (dimensionless)" ) co2: float = Field( 0.0, ge=0, description="Dissolved CO2 mole fraction (dimensionless)" ) @field_validator("p", "degf") @classmethod def validate_arrays(cls, v): """Validate array inputs.""" if isinstance(v, list): if not all(val > 0 for val in v): raise ValueError("All values must be positive") else: if v <= 0: raise ValueError("Value must be positive") return v
• src/pyrestoolbox_mcp/server.py:20-30 (registration)

  Registration of brine tools (including calculate_brine_properties) via call to register_brine_tools(mcp) in the main FastMCP server initialization.
  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)