pyResToolbox MCP Server

Instructions

{
    "api": 35.0,
    "degf": 180.0,
    "p": [2000, 3000, 4000],
    "sg_g": 0.75,
    "pb": 3500.0,
    "rsb": 800.0,
    "method": "VELAR"
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/oil_tools.py:144-231 (handler)

  The main handler function for the 'oil_solution_gor' tool. It takes a SolutionGORRequest, calls pyrestoolbox.oil.oil_rs with the provided parameters, handles array conversion, and returns the Rs value(s) in scf/stb along with metadata.

  @mcp.tool()
  def oil_solution_gor(request: SolutionGORRequest) -> dict:
      """Calculate solution gas-oil ratio (Rs) at specified pressure.
  
      **CRITICAL PVT PROPERTY** - Computes volume of gas dissolved in oil at given
      pressure and temperature. Rs increases with pressure up to bubble point, then
      remains constant (equal to rsb) above bubble point.
  
      **Parameters:**
      - **api** (float, required): Oil API gravity in degrees. Valid: 0-100.
        Example: 35.0.
      - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
        Example: 180.0.
      - **p** (float or list, required): Pressure(s) in psia. Must be > 0.
        Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000].
      - **sg_g** (float, optional, default=0.0): Separator gas specific gravity (air=1).
        Valid: 0-3. Typical: 0.6-1.2. Example: 0.75.
      - **pb** (float, optional, default=0.0): Bubble point pressure in psia.
        If 0, will be calculated. Must be ≥ 0. Example: 3500.0.
      - **rsb** (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
        If 0 and pb provided, will be calculated. Must be ≥ 0. Example: 800.0.
      - **method** (str, optional, default="VELAR"): Correlation method.
        Options: "VELAR", "STAN", "VALMC".
  
      **Pressure Behavior:**
      - **p < pb**: Rs calculated from correlation (increases with pressure)
      - **p ≥ pb**: Rs = rsb (constant, no additional gas dissolves)
  
      **Method Selection:**
      - **VELAR** (Velarde 1997): Default, good accuracy. Use for most cases.
      - **STAN** (Standing 1947): Classic, widely used. Use for compatibility.
      - **VALMC** (Valko-McCain 2003): Alternative method.
  
      **Returns:**
      Dictionary with:
      - **value** (float or list): Rs in scf/stb (matches input p shape)
      - **method** (str): Method used
      - **units** (str): "scf/stb"
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Using separator gas gravity instead of separator gas gravity (sg_g parameter)
      - Not providing pb when p > pb (will calculate incorrectly)
      - Pressure in barg/psig instead of psia (must be absolute)
      - Confusing rsb (at bubble point) with separator GOR
  
      **Example Usage:**
      ```python
      {
          "api": 35.0,
          "degf": 180.0,
          "p": [2000, 3000, 4000],
          "sg_g": 0.75,
          "pb": 3500.0,
          "rsb": 800.0,
          "method": "VELAR"
      }
      ```
      Result: Rs increases from ~400 scf/stb at 2000 psia to 800 scf/stb at 3500 psia,
      then remains 800 scf/stb at 4000 psia (above bubble point).
  
      **Note:** Always provide pb and rsb when available for accurate results.
      If unknown, set pb=0 and rsb=0 to auto-calculate, but accuracy may be reduced.
      """
      method_enum = getattr(rs_method, request.method)
  
      rs = oil.oil_rs(
          api=request.api,
          degf=request.degf,
          p=request.p,
          sg_sp=request.sg_g,  # oil_rs uses sg_sp not sg_g
          pb=request.pb,
          rsb=request.rsb,
          rsmethod=method_enum,
      )
  
      # Convert numpy array to list for JSON serialization
      if isinstance(rs, np.ndarray):
          value = rs.tolist()
      else:
          value = float(rs)
  
      return {
          "value": value,
          "method": request.method,
          "units": "scf/stb",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/oil_models.py:38-70 (schema)

  Pydantic model defining the input schema, validation rules, and types for the oil_solution_gor tool parameters including API gravity, temperature, pressure, gas gravity, bubble point pressure, Rsb, and method.

  class SolutionGORRequest(BaseModel):
      """Request model for solution gas-oil ratio calculation."""
  
      api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)")
      degf: float = Field(
          ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)"
      )
      p: Union[float, List[float]] = Field(
          ..., description="Pressure (psia) - scalar or array"
      )
      sg_g: float = Field(
          0.0, ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)"
      )
      pb: float = Field(0.0, ge=0, description="Bubble point pressure (psia)")
      rsb: float = Field(
          0.0, ge=0, description="Solution GOR at bubble point (scf/stb)"
      )
      method: Literal["VELAR", "STAN", "VALMC"] = Field(
          "VELAR", description="Calculation method"
      )
  
      @field_validator("p")
      @classmethod
      def validate_pressure(cls, v):
          """Validate pressure values."""
          if isinstance(v, list):
              if not all(p > 0 for p in v):
                  raise ValueError("All pressure values must be positive")
          else:
              if v <= 0:
                  raise ValueError("Pressure must be positive")
          return v

• src/pyrestoolbox_mcp/server.py:16-24 (registration)

  Import and call to register_oil_tools(mcp) which registers the oil_solution_gor tool (and other oil tools) with the FastMCP server.

  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)

• src/pyrestoolbox_mcp/resources/config_resources.py:82-88 (helper)

  Documentation listing the oil_solution_gor tool in the overview of available Oil PVT Tools.

  - oil_bubble_point: Calculate bubble point pressure
  - oil_solution_gor: Calculate solution gas-oil ratio (Rs)
  - oil_formation_volume_factor: Calculate oil FVF (Bo)
  - oil_viscosity: Calculate oil viscosity
  - oil_density: Calculate oil density
  - oil_compressibility: Calculate oil compressibility