pyResToolbox MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/pyrestoolbox_mcp/tools/oil_tools.py:31-142 (handler)

  The main execution logic for the 'oil_bubble_point' tool. Calculates bubble point pressure using pyrestoolbox correlations (VALMC, STAN, VELAR). Includes input validation, error handling for sys.exit(), and detailed docstring with examples and common mistakes.
  def oil_bubble_point(request: BubblePointRequest) -> dict: """Calculate oil bubble point pressure (Pb). **CRITICAL PVT PROPERTY** - The bubble point is the pressure at which gas first begins to evolve from solution in oil. Essential for all oil reservoir calculations. **Parameters:** - **api** (float, required): Oil API gravity in degrees. Valid range: 0-100. Typical values: 20-50. Example: 35.0 for medium gravity crude. - **degf** (float, required): Reservoir temperature in degrees Fahrenheit. Valid range: -460 to 1000. Typical: 100-300°F. Example: 180.0. - **rsb** (float, required): Solution gas-oil ratio at bubble point in scf/stb. Must be ≥ 0. Typical: 100-3000 scf/stb. Example: 800.0. - **sg_g** (float, optional, default=0.0): Gas specific gravity (air=1.0). Valid range: 0-3. Typical: 0.6-1.2. Example: 0.75 for associated gas. - **method** (str, optional, default="VALMC"): Correlation method. Options: "STAN", "VALMC", "VELAR". VALMC recommended for wider applicability. **Method Selection:** - **VALMC** (Valko-McCain 2003): Recommended. Best for wide range of conditions. Use for: Most applications, high GOR oils, wide temperature ranges. - **STAN** (Standing 1947): Classic correlation. Use for: Standard conditions, quick estimates, compatibility with older methods. - **VELAR** (Velarde 1997): Alternative method. Use for: Specific regional correlations, comparison studies. **Returns:** Dictionary with: - **value** (float): Bubble point pressure in psia - **method** (str): Method used - **units** (str): "psia" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using separator temperature instead of reservoir temperature - Confusing rsb (solution GOR at bubble point) with separator GOR - Using gas gravity from wrong separator stage - Temperature in Celsius instead of Fahrenheit **Example Usage:** ```python { "api": 35.0, "degf": 180.0, "rsb": 800.0, "sg_g": 0.75, "method": "VALMC" } ``` Expected result: Pb ≈ 3000-4000 psia for typical oil. **Note:** If Pb > reservoir pressure, reservoir is undersaturated (no free gas). If Pb < reservoir pressure, reservoir is saturated (gas cap present). """ method_enum = getattr(pb_method, request.method) # VALMC and VELAR methods require sg_sp (separator gas), STAN requires sg_g # If sg_sp is not provided but method needs it, use sg_g as fallback # This is a common assumption when separator gas gravity is not available if request.method in ['VALMC', 'VELAR']: sg_sp = getattr(request, 'sg_sp', None) or request.sg_g sg_g_param = 0 else: # STAN method sg_sp = 0 sg_g_param = request.sg_g # Validate inputs before calling to avoid sys.exit() in pyrestoolbox if request.api <= 0 or request.degf <= 0 or request.rsb <= 0: raise ValueError( f"Invalid input parameters: api ({request.api}), degf ({request.degf}), " f"and rsb ({request.rsb}) must all be greater than 0" ) if request.method in ['VALMC', 'VELAR'] and sg_sp <= 0: raise ValueError( f"Invalid input: {request.method} method requires sg_sp (separator gas gravity) > 0. " f"Provided: sg_g={request.sg_g}. Please provide a valid gas specific gravity." ) if request.method == 'STAN' and sg_g_param <= 0: raise ValueError( f"Invalid input: STAN method requires sg_g (weighted average gas gravity) > 0. " f"Provided: sg_g={request.sg_g}" ) try: pbub = oil.oil_pbub( api=request.api, degf=request.degf, rsb=request.rsb, sg_g=sg_g_param, sg_sp=sg_sp, pbmethod=method_enum, ) except (SystemExit, BaseException) as e: # Catch sys.exit() calls from pyrestoolbox validation # SystemExit is a BaseException, not Exception if isinstance(e, SystemExit): raise ValueError( f"Invalid input parameters for {request.method} method. " f"For VALMC/VELAR: requires sg_sp (separator gas gravity) > 0. " f"For STAN: requires sg_g (weighted average gas gravity) > 0. " f"All methods require: api > 0, degf > 0, rsb > 0" ) from None raise return { "value": float(pbub), "method": request.method, "units": "psia", "inputs": request.model_dump(), }
• src/pyrestoolbox_mcp/models/oil_models.py:8-36 (schema)

  Pydantic BaseModel defining the input schema for the tool, with fields: api (float, 0<api<=100), degf (float, -460<degf<1000), rsb (float >=0), sg_g (float 0-3, default 0), method (Literal['STAN','VALMC','VELAR'], default 'VALMC'). Includes example in json_schema_extra.
  class BubblePointRequest(BaseModel): """Request model for bubble point pressure calculation.""" model_config = ConfigDict( json_schema_extra={ "example": { "api": 35.0, "degf": 180.0, "rsb": 800.0, "sg_g": 0.75, "method": "VALMC", } } ) api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)") degf: float = Field( ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)" ) rsb: float = Field( ..., ge=0, description="Solution GOR at bubble point (scf/stb)" ) sg_g: float = Field( 0.0, ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)" ) method: Literal["STAN", "VALMC", "VELAR"] = Field( "VALMC", description="Calculation method (VALMC recommended)" )
• src/pyrestoolbox_mcp/server.py:16-24 (registration)

  The server.py file imports register_oil_tools from oil_tools.py and calls it with the FastMCP instance (line 24), which defines and registers the oil_bubble_point tool using @mcp.tool() decorator inside register_oil_tools.
  from .tools.oil_tools import register_oil_tools from .tools.gas_tools import register_gas_tools from .tools.inflow_tools import register_inflow_tools from .tools.simtools_tools import register_simtools_tools 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)