pyResToolbox MCP Server

Instructions

{
    "pi": 5000.0,
    "sg": 0.7,
    "degf": 180.0,
    "psd": [2000, 3000, 4000],
    "h": 50.0,
    "k": 100.0,
    "area": 1000.0,
    "length": 500.0,
    "h2s": 0.0,
    "co2": 0.0,
    "n2": 0.0
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/inflow_tools.py:492-622 (handler)

  The main handler function for the 'gas_rate_linear' tool. It is decorated with @mcp.tool() for automatic registration and implements the core logic by calling pyrestoolbox.gas.gas_rate_linear with validated inputs and formatting the response.

  @mcp.tool()
  def gas_rate_linear(request: GasRateLinearRequest) -> dict:
      """Calculate gas production rate for linear flow.
  
      **INFLOW PERFORMANCE TOOL** - Computes gas production rate for horizontal wells
      or wells with linear flow geometry using real gas pseudopressure formulation.
      This accounts for pressure-dependent gas properties (Z-factor, viscosity) which
      are significant for gas systems. More accurate than simplified Darcy's law for gas.
  
      **Parameters:**
      - **pi** (float, required): Initial/reservoir pressure in psia. Must be > 0.
        Example: 5000.0.
      - **sg** (float, required): Gas specific gravity (air=1). Valid: 0.55-3.0.
        Typical: 0.6-1.2. Example: 0.7.
      - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
        Example: 180.0.
      - **psd** (float or list, required): Sandface/draining pressure(s) in psia.
        Must be > 0 and < pi. Can be scalar or array. Example: 2000.0 or [1000, 2000, 3000].
      - **h** (float, required): Net pay thickness in feet. Must be > 0.
        Typical: 10-200 ft. Example: 50.0.
      - **k** (float, required): Permeability in millidarcies (mD). Must be > 0.
        Typical: 1-1000 mD. Example: 100.0.
      - **area** (float, required): Cross-sectional flow area in square feet.
        Must be > 0. Typical: 100-10000 ft². Example: 1000.0.
      - **length** (float, required): Flow length in feet. Must be > 0.
        Typical: 100-5000 ft. Example: 500.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.
  
      **Flow Geometry:**
      Linear flow occurs in:
      - Horizontal wells (early-time flow)
      - Hydraulically fractured vertical wells (fracture flow)
      - Channelized gas reservoirs
      - Edge water drive systems
  
      **Pseudopressure Method:**
      Uses real gas pseudopressure (m(p)) which linearizes the gas diffusivity equation:
      m(p) = 2∫(p/(μZ))dp from pb to p
  
      This accounts for:
      - Z-factor variation with pressure
      - Gas viscosity variation with pressure
      - Non-linear pressure behavior
  
      **Flow Formula (Linear):**
      qg = (k × area × (m(pi) - m(pwf))) / (1422 × T × length)
  
      Where PVT properties are integrated over pressure range.
  
      **Linear vs Radial Flow:**
      - Linear: Flow perpendicular to wellbore (horizontal wells)
      - Radial: Flow converging to wellbore (vertical wells)
      - Linear flow typically has higher productivity than radial
  
      **Returns:**
      Dictionary with:
      - **value** (float or list): Gas rate in MSCF/day (matches input psd shape)
      - **method** (str): "Pseudopressure linear flow"
      - **units** (str): "MSCF/day"
      - **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)
      - Confusing flow area (perpendicular to flow) with wellbore area
      - Using wrong flow length (should be distance from boundary to well)
      - Confusing linear flow (horizontal wells) with radial flow (vertical wells)
      - Not accounting for net pay thickness correctly
  
      **Example Usage:**
      ```python
      {
          "pi": 5000.0,
          "sg": 0.7,
          "degf": 180.0,
          "psd": [2000, 3000, 4000],
          "h": 50.0,
          "k": 100.0,
          "area": 1000.0,
          "length": 500.0,
          "h2s": 0.0,
          "co2": 0.0,
          "n2": 0.0
      }
      ```
      Result: Gas rate decreases as sandface pressure increases (typical IPR curve).
  
      **Note:** This tool uses pseudopressure method which is more accurate than
      simplified Darcy's law for gas. Always account for non-hydrocarbon components
      (H2S, CO2, N2) as they affect Z-factor and flow calculations significantly.
      Linear flow is characteristic of horizontal wells and hydraulically fractured wells.
      """
      # Convert psd to numpy array for processing
      psd_array = np.asarray(request.psd)
      is_scalar = psd_array.ndim == 0
      if is_scalar:
          psd_array = np.array([psd_array])
      
      # Call gas_rate_linear with correct parameters
      qg = gas.gas_rate_linear(
          k=request.k,
          pr=request.pi,
          pwf=psd_array,
          area=request.area,
          length=request.length,
          degf=request.degf,
          sg=request.sg,
          h2s=request.h2s,
          co2=request.co2,
          n2=request.n2,
      )
  
      # Convert numpy array to list for JSON serialization
      if isinstance(qg, np.ndarray):
          value = qg.tolist()
      else:
          value = float(qg)
  
      return {
          "value": value,
          "method": "Pseudopressure linear flow",
          "units": "MSCF/day",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/inflow_models.py:140-178 (schema)

  Pydantic BaseModel defining the input schema and validation for the gas_rate_linear tool parameters.

  class GasRateLinearRequest(BaseModel):
      """Request model for linear gas inflow performance calculation."""
  
      pi: float = Field(..., gt=0, description="Initial reservoir pressure (psia)")
      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)"
      )
      psd: Union[float, List[float]] = Field(
          ..., description="Sandface pressure (psia) - scalar or array"
      )
      h: float = Field(..., gt=0, description="Net pay thickness (ft)")
      k: float = Field(..., gt=0, description="Permeability (mD)")
      area: float = Field(..., gt=0, description="Drainage area (sq ft)")
      length: float = Field(..., gt=0, description="Well length (ft)")
      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)"
      )
  
      @field_validator("psd")
      @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 sandface pressure values must be positive")
          else:
              if v <= 0:
                  raise ValueError("Sandface pressure must be positive")
          return v

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

  Invocation of register_inflow_tools(mcp) in the main server.py file, which defines and registers the gas_rate_linear tool using @mcp.tool() decorator.

  register_inflow_tools(mcp)