pyResToolbox MCP Server

Instructions

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