pyResToolbox MCP Server

Instructions

{
    "api": 35.0,
    "degf": 180.0,
    "rsb": 800.0,
    "sg_g": 0.75,
    "method": "VALMC"
}

Implementation Reference

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

  The handler function decorated with @mcp.tool() that implements the core logic for calculating oil bubble point pressure using pyrestoolbox.oil.oil_pbub, with input validation and error handling.

  @mcp.tool()
  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 oil_bubble_point tool, including fields for api, degf, rsb, sg_g, method with validation and example.

  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:15-30 (registration)

  Imports register_oil_tools from oil_tools.py and calls it on the mcp instance to register all oil tools, including oil_bubble_point.

  # Import and register 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)
  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/oil_tools.py:27-27 (registration)

  The register_oil_tools function where the oil_bubble_point handler is defined and registered via @mcp.tool() decorator.

  def register_oil_tools(mcp: FastMCP) -> None: