pyResToolbox MCP Server

Instructions

{
    "pz": 5000.0,
    "sg": 0.7,
    "degf": 180.0,
    "h2s": 0.0,
    "co2": 0.0,
    "n2": 0.0,
    "zmethod": "DAK"
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/gas_tools.py:704-801 (handler)

  Main handler function implementing the tool logic using pyrestoolbox.gas.gas_ponz2p for iterative pressure calculation from P/Z value.

  @mcp.tool()
  def gas_pressure_from_pz(request: GasPressureFromPZRequest) -> dict:
      """Calculate pressure from P/Z value.
  
      **MATERIAL BALANCE TOOL** - Solves for pressure given a P/Z (pressure/Z-factor) value.
      Essential for gas material balance analysis where P/Z vs cumulative production is plotted.
      Uses iterative solution to find pressure that yields the specified P/Z value.
  
      **Parameters:**
      - **pz** (float or list, required): P/Z value(s) in psia. Must be > 0.
        Can be scalar or array. Example: 5000.0 or [4000, 5000, 6000].
      - **sg** (float, required): Gas specific gravity (air=1.0). Valid: 0.55-3.0.
        Typical: 0.6-1.2. Example: 0.7.
      - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
        Typical: 100-400°F. Example: 180.0.
      - **h2s** (float, optional, default=0.0): H2S mole fraction (0-1).
        Typical: 0-0.05. Example: 0.0.
      - **co2** (float, optional, default=0.0): CO2 mole fraction (0-1).
        Typical: 0-0.20. Example: 0.0.
      - **n2** (float, optional, default=0.0): N2 mole fraction (0-1).
        Typical: 0-0.10. Example: 0.0.
      - **zmethod** (str, optional, default="DAK"): Z-factor method for calculation.
        Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
  
      **P/Z Method Applications:**
      - **Volumetric Gas Reserves:** P/Z vs Gp plot gives GIIP (Gas Initially In Place)
      - **Aquifer Influx Detection:** Deviation from straight line indicates water drive
      - **Drive Mechanism Identification:** Volumetric vs water drive vs gas cap
      - **Production Forecasting:** Extrapolate P/Z to abandonment pressure
  
      **Material Balance Principle:**
      For volumetric gas reservoirs: P/Z = (Pi/Zi) × (1 - Gp/G)
      Where Gp = cumulative production, G = GIIP
  
      A straight line on P/Z vs Gp indicates volumetric depletion.
      Deviation suggests water influx, changing pore volume, or gas cap expansion.
  
      **Solution Method:**
      Iterative Newton-Raphson method to solve: P/Z - pz_target = 0
      Converges rapidly for well-posed problems.
  
      **Returns:**
      Dictionary with:
      - **value** (float or list): Pressure in psia (matches input pz shape)
      - **method** (str): Iterative solution method with Z-factor method
      - **units** (str): "psia"
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Using separator temperature instead of reservoir temperature
      - Not accounting for non-hydrocarbon fractions
      - Confusing P/Z (pressure/Z-factor) with pressure
      - Using wrong Z-factor method (must match method used in material balance)
      - Temperature in Celsius instead of Fahrenheit
  
      **Example Usage:**
      ```python
      {
          "pz": 5000.0,
          "sg": 0.7,
          "degf": 180.0,
          "h2s": 0.0,
          "co2": 0.0,
          "n2": 0.0,
          "zmethod": "DAK"
      }
      ```
      Result: Pressure ≈ 4500-5500 psia (depends on Z-factor at that pressure).
  
      **Note:** P/Z method is fundamental to gas material balance. Always use the same
      Z-factor method throughout your analysis for consistency. Account for all
      non-hydrocarbon components as they affect Z-factor and thus P/Z values.
      """
      method_enum = getattr(z_method, request.zmethod)
  
      p = gas.gas_ponz2p(
          poverz=request.pz,  # Function expects poverz not pz
          sg=request.sg,
          degf=request.degf,
          h2s=request.h2s,
          co2=request.co2,
          n2=request.n2,
          zmethod=method_enum,
      )
  
      # Convert numpy array to list for JSON serialization
      if isinstance(p, np.ndarray):
          value = p.tolist()
      else:
          value = float(p)
  
      return {
          "value": value,
          "method": f"Iterative solution using {request.zmethod}",
          "units": "psia",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/gas_models.py:246-270 (schema)

  Pydantic BaseModel defining input parameters and validation for the gas_pressure_from_pz tool.

  class GasPressureFromPZRequest(BaseModel):
      """Request model for pressure from P/Z calculation."""
  
      pz: Union[float, List[float]] = Field(
          ..., description="P/Z value (psia) - scalar or array"
      )
      sg: float = Field(
          ..., ge=0.5, le=2.0, description="Gas specific gravity (air=1, dimensionless)"
      )
      degf: float = Field(
          ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)"
      )
      h2s: float = Field(
          0.0, ge=0.0, le=1.0, description="H2S mole fraction (dimensionless)"
      )
      co2: float = Field(
          0.0, ge=0.0, le=1.0, description="CO2 mole fraction (dimensionless)"
      )
      n2: float = Field(
          0.0, ge=0.0, le=1.0, description="N2 mole fraction (dimensionless)"
      )
      zmethod: Literal["DAK", "HY", "WYW", "BUR"] = Field(
          "DAK", description="Z-factor calculation method"
      )

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

  Registration of all tool groups to the FastMCP server, including gas tools which contain the gas_pressure_from_pz handler.

  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)

• test_tools.py:120-125 (helper)

  Test invocation of the gas_pressure_from_pz tool to validate functionality.

  ("gas_pressure_from_pz", {"request": {
      "pz": 5000.0, "sg": 0.7, "degf": 180.0, "method": "DAK"
  }}),
  ("gas_sg_from_gradient", {"request": {
      "grad": 0.1, "degf": 180.0, "p": 3500.0
  }}),