pyResToolbox MCP Server

Instructions

{
    "pi": 5000.0,
    "sg": 0.7,
    "degf": 180.0,
    "psd": [2000, 3000, 4000],
    "h": 50.0,
    "k": 100.0,
    "s": 0.0,
    "re": 1000.0,
    "rw": 0.5,
    "h2s": 0.0,
    "co2": 0.0,
    "n2": 0.0
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/inflow_tools.py:369-490 (handler)

  The handler function implementing the core logic of the 'gas_rate_radial' MCP tool. It processes input via GasRateRadialRequest, calls pyrestoolbox.gas.gas_rate_radial, and returns formatted results. The @mcp.tool() decorator registers it automatically when register_inflow_tools is called.

  @mcp.tool()
  def gas_rate_radial(request: GasRateRadialRequest) -> dict:
      """Calculate gas production rate for radial flow (vertical well).
  
      **INFLOW PERFORMANCE TOOL** - Computes gas production rate for vertical wells
      with radial 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.
      - **s** (float, optional, default=0.0): Skin factor (dimensionless).
        Negative = stimulation, positive = damage. Typical: -5 to +20.
        Example: 0.0 for undamaged well.
      - **re** (float, required): Drainage radius in feet. Must be > rw.
        Typical: 500-5000 ft. Example: 1000.0.
      - **rw** (float, required): Wellbore radius in feet. Must be > 0.
        Typical: 0.25-0.5 ft. Example: 0.5.
      - **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.
  
      **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:**
      qg = (kh × (m(pi) - m(pwf))) / (1422 × T × (ln(re/rw) + S))
  
      Where PVT properties are integrated over pressure range.
  
      **Returns:**
      Dictionary with:
      - **value** (float or list): Gas rate in MSCF/day (matches input psd shape)
      - **method** (str): "Pseudopressure radial 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)
      - Using wrong drainage radius (re) - should be well spacing/2
      - Confusing net pay (h) with gross thickness
      - Not accounting for skin factor (s)
  
      **Example Usage:**
      ```python
      {
          "pi": 5000.0,
          "sg": 0.7,
          "degf": 180.0,
          "psd": [2000, 3000, 4000],
          "h": 50.0,
          "k": 100.0,
          "s": 0.0,
          "re": 1000.0,
          "rw": 0.5,
          "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.
      """
      # 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_radial with correct parameters
      qg = gas.gas_rate_radial(
          k=request.k,
          h=request.h,
          pr=request.pi,
          pwf=psd_array,
          r_w=request.rw,
          r_ext=request.re,
          degf=request.degf,
          S=request.s,
          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 radial flow",
          "units": "MSCF/day",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/inflow_models.py:91-137 (schema)

  Pydantic model GasRateRadialRequest defining the input schema with validation rules for all parameters required by the gas_rate_radial tool.

  class GasRateRadialRequest(BaseModel):
      """Request model for radial 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)")
      s: float = Field(0.0, description="Skin factor (dimensionless)")
      re: float = Field(..., gt=0, description="Drainage radius (ft)")
      rw: float = Field(..., gt=0, description="Wellbore radius (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
  
      @field_validator("rw")
      @classmethod
      def validate_rw(cls, v, info):
          """Validate wellbore radius is less than drainage radius."""
          if "re" in info.data and v >= info.data["re"]:
              raise ValueError("Wellbore radius must be less than drainage radius")
          return v

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

  Top-level registration in the main server file where register_inflow_tools(mcp) is called, which defines and registers the gas_rate_radial tool via its @mcp.tool() decorator.

  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)