pyResToolbox MCP Server

Instructions

{
    "api": 35.0,
    "degf": 180.0,
    "p": [2000, 3000, 4000],
    "pb": 3500.0,
    "rs": [400, 600, 800],
    "rsb": 800.0,
    "method": "BR"
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/oil_tools.py:329-414 (handler)

  The primary handler function for the 'oil_viscosity' MCP tool. Decorated with @mcp.tool(), it takes OilViscosityRequest input, computes viscosity using oil.oil_viso() from the underlying library, handles scalar/array inputs, and returns a standardized dict with results.

  @mcp.tool()
  def oil_viscosity(request: OilViscosityRequest) -> dict:
      """Calculate oil viscosity (μo).
  
      **CRITICAL PVT PROPERTY** - Computes oil viscosity at reservoir conditions.
      Viscosity affects flow rates, pressure drops, and recovery efficiency.
      Uses Beggs-Robinson (1975) correlation, industry standard for oil viscosity.
  
      **Parameters:**
      - **api** (float, required): Oil API gravity in degrees. Valid: 0-100.
        Example: 35.0. Higher API = lighter oil = lower viscosity.
      - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
        Example: 180.0. Higher temperature = lower viscosity.
      - **p** (float or list, required): Pressure(s) in psia. Must be > 0.
        Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000].
      - **pb** (float, optional, default=0.0): Bubble point pressure in psia.
        Required for accurate calculation. Example: 3500.0.
      - **rs** (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb.
        If 0, will be calculated. Must match p shape. Example: 600.0.
      - **rsb** (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
        Required if pb provided. Example: 800.0.
      - **method** (str, optional, default="BR"): Correlation method. Only "BR" available.
  
      **Viscosity Behavior:**
      - **p < pb**: Viscosity decreases with pressure (more gas dissolves, oil thins)
      - **p = pb**: Viscosity reaches minimum (μob, typically 0.5-5 cP)
      - **p > pb**: Viscosity increases with pressure (oil compression)
  
      **Typical Ranges:**
      - Light oils (API > 35): 0.5-2 cP at bubble point
      - Medium oils (API 25-35): 1-10 cP at bubble point
      - Heavy oils (API < 25): 10-1000+ cP at bubble point
  
      **Returns:**
      Dictionary with:
      - **value** (float or list): Viscosity in cP (matches input p shape)
      - **method** (str): "BR" (Beggs-Robinson)
      - **units** (str): "cP"
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Not providing rs when p < pb (will calculate incorrectly)
      - Using dead oil viscosity instead of live oil viscosity
      - Temperature in Celsius instead of Fahrenheit
      - Pressure in barg/psig instead of psia
  
      **Example Usage:**
      ```python
      {
          "api": 35.0,
          "degf": 180.0,
          "p": [2000, 3000, 4000],
          "pb": 3500.0,
          "rs": [400, 600, 800],
          "rsb": 800.0,
          "method": "BR"
      }
      ```
      Result: Viscosity decreases from ~1.2 cP at 2000 psia to ~0.8 cP at 3500 psia,
      then increases to ~0.85 cP at 4000 psia (above bubble point).
  
      **Note:** Viscosity is highly sensitive to temperature and dissolved gas content.
      Always use reservoir temperature, not separator temperature.
      """
      method_enum = getattr(uo_method, request.method)
  
      uo = oil.oil_viso(
          p=request.p,
          api=request.api,
          degf=request.degf,
          pb=request.pb,
          rs=request.rs,
      )
  
      # Convert numpy array to list for JSON serialization
      if isinstance(uo, np.ndarray):
          value = uo.tolist()
      else:
          value = float(uo)
  
      return {
          "value": value,
          "method": request.method,
          "units": "cP",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/oil_models.py:109-139 (schema)

  Pydantic BaseModel defining the input schema for the oil_viscosity tool, including fields for API gravity, temperature, pressure, bubble point, solution GORs, and method, with validators for array inputs and value ranges.

  class OilViscosityRequest(BaseModel):
      """Request model for oil viscosity calculation."""
  
      api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)")
      degf: float = Field(
          ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)"
      )
      p: Union[float, List[float]] = Field(
          ..., description="Pressure (psia) - scalar or array"
      )
      pb: float = Field(0.0, ge=0, description="Bubble point pressure (psia)")
      rs: Union[float, List[float]] = Field(
          0.0, description="Solution GOR (scf/stb) - scalar or array"
      )
      rsb: float = Field(
          0.0, ge=0, description="Solution GOR at bubble point (scf/stb)"
      )
      method: Literal["BR"] = Field("BR", description="Calculation method")
  
      @field_validator("p", "rs")
      @classmethod
      def validate_arrays(cls, v):
          """Validate array inputs."""
          if isinstance(v, list):
              if not all(val >= 0 for val in v):
                  raise ValueError("All values must be non-negative")
          else:
              if v < 0:
                  raise ValueError("Value must be non-negative")
          return v

• src/pyrestoolbox_mcp/config.py:57-59 (registration)

  Configuration entry in CALCULATION_METHODS dictionary documenting the supported correlation method (BR - Beggs & Robinson) for the oil_viscosity tool.

  "oil_viscosity": {
      "BR": "Beggs & Robinson (1975)",
  },