pyResToolbox MCP Server

Instructions

{
    "pi": 4000.0,
    "pb": 3500.0,
    "api": 35.0,
    "degf": 180.0,
    "sg_g": 0.75,
    "psd": [1500, 2000, 2500],
    "h": 50.0,
    "k": 100.0,
    "area": 1000.0,
    "length": 500.0,
    "rsb": 800.0
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/inflow_tools.py:207-367 (handler)

  The core handler function for the 'oil_rate_linear' tool. It processes input parameters, computes necessary PVT properties (Rs, Bo, μo) at average reservoir-sandface pressure, and calls the underlying pyrestoolbox.oil.oil_rate_linear function to compute the oil rate for linear flow regime.

  @mcp.tool()
  def oil_rate_linear(request: OilRateLinearRequest) -> dict:
      """Calculate oil production rate for linear flow.
  
      **INFLOW PERFORMANCE TOOL** - Computes oil production rate for horizontal wells
      or wells with linear flow geometry using Darcy's law. Automatically calculates PVT
      properties (Rs, Bo, μo) at average pressure. Essential for horizontal well
      performance analysis and completion design.
  
      **Parameters:**
      - **pi** (float, required): Initial/reservoir pressure in psia. Must be > 0.
        Example: 4000.0.
      - **pb** (float, required): Bubble point pressure in psia. Must be ≥ 0.
        Example: 3500.0. If pi < pb, reservoir is saturated (gas cap present).
      - **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.
      - **sg_g** (float, required): Gas specific gravity (air=1). Valid: 0-3.
        Typical: 0.6-1.2. Example: 0.75.
      - **psd** (float or list, required): Sandface/draining pressure(s) in psia.
        Must be > 0 and < pi. Can be scalar or array. Example: 1500.0 or [1000, 1500, 2000].
      - **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.
      - **rsb** (float, required): Solution GOR at bubble point in scf/stb.
        Must be ≥ 0. Example: 800.0.
  
      **Flow Geometry:**
      Linear flow occurs in:
      - Horizontal wells (early-time flow)
      - Hydraulically fractured vertical wells (fracture flow)
      - Channelized reservoirs
      - Edge water drive systems
  
      **Darcy's Law Formula (Linear):**
      qo = (0.001127 × k × area × (pi - pwf)) / (μo × Bo × length)
  
      Where PVT properties (μo, Bo) are calculated at average pressure (pi + pwf)/2.
  
      **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): Oil rate in STB/day (matches input psd shape)
      - **method** (str): "Darcy linear flow"
      - **units** (str): "STB/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)
      - Confusing flow area (perpendicular to flow) with wellbore area
      - Using wrong flow length (should be distance from boundary to well)
      - Not accounting for net pay thickness correctly
      - Confusing linear flow (horizontal wells) with radial flow (vertical wells)
  
      **Example Usage:**
      ```python
      {
          "pi": 4000.0,
          "pb": 3500.0,
          "api": 35.0,
          "degf": 180.0,
          "sg_g": 0.75,
          "psd": [1500, 2000, 2500],
          "h": 50.0,
          "k": 100.0,
          "area": 1000.0,
          "length": 500.0,
          "rsb": 800.0
      }
      ```
      Result: Oil rate decreases as sandface pressure increases (typical IPR curve).
  
      **Note:** This tool automatically calculates PVT properties. You don't need to
      provide Rs, Bo, or μo - they are computed internally at average pressure.
      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])
      
      # Calculate oil specific gravity from API
      sg_o = oil.oil_sg(api_value=request.api)
      
      # Calculate average pressures for PVT
      avg_pressures = (request.pi + psd_array) / 2.0
      
      # Calculate Rs at average pressures
      rs_avg = oil.oil_rs(
          api=request.api,
          degf=request.degf,
          p=avg_pressures,
          sg_sp=request.sg_g,  # Use sg_g as separator gas SG
          pb=request.pb,
          rsb=request.rsb,
          rsmethod=rs_method.VELAR,
      )
      
      # Calculate Bo and uo at average pressures
      bo_values = oil.oil_bo(
          p=avg_pressures,
          pb=request.pb,
          degf=request.degf,
          rs=rs_avg,
          rsb=request.rsb,
          sg_o=sg_o,
          sg_g=request.sg_g,
          bomethod=bo_method.MCAIN,
      )
      
      uo_values = oil.oil_viso(
          p=avg_pressures,
          api=request.api,
          degf=request.degf,
          pb=request.pb,
          rs=rs_avg,
      )
      
      # Convert to scalars if needed
      if is_scalar:
          bo_values = float(bo_values[0]) if isinstance(bo_values, np.ndarray) else float(bo_values)
          uo_values = float(uo_values[0]) if isinstance(uo_values, np.ndarray) else float(uo_values)
          psd_array = psd_array[0]
      
      # Call oil_rate_linear with correct parameters
      qo = oil.oil_rate_linear(
          k=request.k,
          pr=request.pi,
          pwf=psd_array,
          area=request.area,
          length=request.length,
          uo=uo_values,
          bo=bo_values,
          vogel=False,
          pb=request.pb,
      )
  
      # Convert numpy array to list for JSON serialization
      if isinstance(qo, np.ndarray):
          value = qo.tolist()
      else:
          value = float(qo)
  
      return {
          "value": value,
          "method": "Darcy linear flow",
          "units": "STB/day",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/inflow_models.py:55-89 (schema)

  Pydantic BaseModel defining the input schema and validation for the oil_rate_linear tool, including fields for reservoir pressures, fluid properties, and geometric parameters with appropriate constraints.

  class OilRateLinearRequest(BaseModel):
      """Request model for linear oil inflow performance calculation."""
  
      pi: float = Field(..., gt=0, description="Initial reservoir pressure (psia)")
      pb: float = Field(..., ge=0, description="Bubble point pressure (psia)")
      api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)")
      degf: float = Field(
          ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)"
      )
      sg_g: float = Field(
          ..., ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)"
      )
      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)")
      rsb: float = Field(
          0.0, ge=0, description="Solution GOR at bubble point (scf/stb)"
      )
  
      @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:18-26 (registration)

  The server.py file imports and calls register_inflow_tools(mcp), which in turn defines and registers the oil_rate_linear tool via @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)

• src/pyrestoolbox_mcp/tools/inflow_tools.py:21-21 (registration)

  The register_inflow_tools function defines the @mcp.tool() decorated oil_rate_linear handler, effectively registering it with the MCP server when called.

  def register_inflow_tools(mcp: FastMCP) -> None: