pyResToolbox MCP Server

Instructions

{
    "sg": 0.7,
    "degf": 180.0,
    "p": [1000, 2000, 3000, 4000],
    "h2s": 0.0,
    "co2": 0.05,
    "n2": 0.01,
    "method": "DAK"
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/gas_tools.py:30-131 (handler)

  The handler function for the 'gas_z_factor' tool. It takes ZFactorRequest, computes Z-factor using pyrestoolbox.gas.gas_z with specified method, handles array inputs, and returns formatted response.

  def gas_z_factor(request: ZFactorRequest) -> dict:
      """Calculate gas compressibility factor (Z-factor).
  
      **CRITICAL GAS PVT PROPERTY** - The Z-factor corrects the ideal gas law (PV=nRT)
      for real gas behavior. Z = 1.0 for ideal gas, Z < 1.0 for most real gases at
      reservoir conditions. Essential for all gas reservoir calculations including
      material balance, reserve estimation, and flow calculations.
  
      **Parameters:**
      - **sg** (float, required): Gas specific gravity (air=1.0). Valid: 0.55-3.0.
        Typical: 0.6-1.2. Example: 0.7 for dry gas, 0.85 for associated gas.
      - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
        Typical: 100-400°F. Example: 180.0.
      - **p** (float or list, required): Pressure(s) in psia. Must be > 0.
        Can be scalar or array. Example: 3500.0 or [1000, 2000, 3000, 4000].
      - **h2s** (float, optional, default=0.0): H2S mole fraction (0-1).
        Typical: 0-0.05. Example: 0.02 for 2% H2S. High H2S requires special handling.
      - **co2** (float, optional, default=0.0): CO2 mole fraction (0-1).
        Typical: 0-0.20. Example: 0.05 for 5% CO2.
      - **n2** (float, optional, default=0.0): N2 mole fraction (0-1).
        Typical: 0-0.10. Example: 0.01 for 1% N2.
      - **method** (str, optional, default="DAK"): Correlation method.
        Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
  
      **Z-Factor Behavior:**
      - Low pressure: Z ≈ 1.0 (ideal gas behavior)
      - Medium pressure: Z < 1.0 (attractive forces dominate)
      - High pressure: Z > 1.0 (repulsive forces dominate)
      - Typical range: 0.7-1.2 for reservoir conditions
  
      **Method Selection:**
      - **DAK** (Dranchuk & Abou-Kassem 1975): **RECOMMENDED**. Most accurate,
        widely validated. Use for: All applications, high accuracy requirements.
      - **HY** (Hall & Yarborough 1973): Classic method, fast. Use for: Quick estimates,
        compatibility with older methods.
      - **WYW** (Wang, Ye & Wu 2021): Newer correlation. Use for: Comparison studies,
        modern applications.
      - **BUR** (Burrows 1981): Alternative method. Use for: Specific regional correlations.
  
      **Non-Hydrocarbon Effects:**
      - H2S and CO2 increase Z-factor (reduce compressibility)
      - N2 has minimal effect
      - For sour gas (H2S > 5%), use Wichert-Aziz correction (not included here)
  
      **Returns:**
      Dictionary with:
      - **value** (float or list): Z-factor (dimensionless, matches input p shape)
      - **method** (str): Method used
      - **units** (str): "dimensionless"
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Using separator temperature instead of reservoir temperature
      - Pressure in barg/psig instead of psia (must be absolute)
      - Not accounting for non-hydrocarbon fractions (H2S, CO2, N2)
      - Using wrong gas gravity (must be separator gas gravity, not sales gas)
      - Temperature in Celsius instead of Fahrenheit
  
      **Example Usage:**
      ```python
      {
          "sg": 0.7,
          "degf": 180.0,
          "p": [1000, 2000, 3000, 4000],
          "h2s": 0.0,
          "co2": 0.05,
          "n2": 0.01,
          "method": "DAK"
      }
      ```
      Result: Z decreases from ~0.95 at 1000 psia to ~0.85 at 3000 psia,
      then increases to ~0.90 at 4000 psia (typical behavior).
  
      **Note:** Z-factor is critical for accurate gas calculations. Always use DAK method
      unless specific compatibility requirements exist. Account for all non-hydrocarbon
      components for accurate results.
      """
      method_enum = getattr(z_method, request.method)
  
      z = gas.gas_z(
          sg=request.sg,
          degf=request.degf,
          p=request.p,
          h2s=request.h2s,
          co2=request.co2,
          n2=request.n2,
          zmethod=method_enum,
      )
  
      # Convert numpy array to list for JSON serialization
      if isinstance(z, np.ndarray):
          value = z.tolist()
      else:
          value = float(z)
  
      return {
          "value": value,
          "method": request.method,
          "units": "dimensionless",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/gas_models.py:7-43 (schema)

  Pydantic model defining the input schema and validation rules for the gas_z_factor tool.

  class ZFactorRequest(BaseModel):
      """Request model for gas Z-factor calculation."""
  
      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)"
      )
      p: Union[float, List[float]] = Field(
          ..., description="Pressure (psia) - scalar or array"
      )
      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)"
      )
      method: Literal["DAK", "HY", "WYW", "BUR"] = Field(
          "DAK", description="Calculation method (DAK recommended)"
      )
  
      @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:24-30 (registration)

  Invocation of register_gas_tools(mcp) in the main server.py file, which registers all gas tools including gas_z_factor.

  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/gas_tools.py:26-30 (registration)

  The register_gas_tools function where the @mcp.tool() decorator registers the gas_z_factor handler.

  def register_gas_tools(mcp: FastMCP) -> None:
      """Register all gas-related tools with the MCP server."""
  
      @mcp.tool()
      def gas_z_factor(request: ZFactorRequest) -> dict: