pyResToolbox MCP Server

Instructions

{
    "sg": 0.7,
    "h2s": 0.0,
    "co2": 0.05,
    "n2": 0.01,
    "method": "PMC"
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/gas_tools.py:132-215 (handler)

  The handler function for the 'gas_critical_properties' tool. It is decorated with @mcp.tool() and implements the core logic using pyrestoolbox.gas.gas_tc_pc to compute pseudo-critical temperature and pressure.

  @mcp.tool()
  def gas_critical_properties(request: CriticalPropertiesRequest) -> dict:
      """Calculate gas pseudo-critical properties (Tc and Pc).
  
      **CRITICAL GAS PROPERTY CALCULATION** - Computes pseudo-critical temperature and
      pressure for real gas mixtures. Required for Z-factor calculations and all gas
      property correlations. Pseudo-critical properties are weighted averages of pure
      component critical properties, adjusted for non-hydrocarbon components.
  
      **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.
      - **h2s** (float, optional, default=0.0): H2S mole fraction (0-1).
        Typical: 0-0.05. Example: 0.02 for 2% H2S. High H2S significantly affects Tc/Pc.
      - **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="PMC"): Correlation method.
        Options: "PMC", "SUT", "BUR". PMC recommended.
  
      **Pseudo-Critical Properties:**
      - **Tc (Pseudo-critical Temperature)**: Temperature above which gas cannot be
        liquefied regardless of pressure. Typical: 300-500°R for natural gas.
      - **Pc (Pseudo-critical Pressure)**: Pressure at critical temperature.
        Typical: 600-800 psia for natural gas.
  
      **Method Selection:**
      - **PMC** (Piper, McCain & Corredor 1993): **RECOMMENDED**. Most accurate for
        wide range of gas compositions. Accounts for non-hydrocarbon effects.
      - **SUT** (Sutton 1985): Classic method. Use for compatibility with older methods.
      - **BUR** (Burrows 1981): Alternative method. Use for specific applications.
  
      **Non-Hydrocarbon Effects:**
      - H2S: Increases both Tc and Pc significantly
      - CO2: Increases Tc, decreases Pc slightly
      - N2: Increases Pc, decreases Tc slightly
      - Always account for non-hydrocarbons for accurate Z-factor calculations
  
      **Returns:**
      Dictionary with:
      - **value** (dict): Contains "tc" (degR) and "pc" (psia)
      - **method** (str): Method used
      - **units** (dict): {"tc": "degR", "pc": "psia"}
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Not accounting for non-hydrocarbon fractions (H2S, CO2, N2)
      - Using wrong gas gravity (must be separator gas, not sales gas)
      - Confusing pseudo-critical with true critical properties
      - Using critical properties for pure components instead of mixtures
  
      **Example Usage:**
      ```python
      {
          "sg": 0.7,
          "h2s": 0.0,
          "co2": 0.05,
          "n2": 0.01,
          "method": "PMC"
      }
      ```
      Result: Tc ≈ 380-420°R, Pc ≈ 650-750 psia for typical natural gas.
  
      **Note:** Critical properties are used internally by gas_z_factor and other
      gas property tools. Always use PMC method unless specific compatibility required.
      Account for all non-hydrocarbon components - even small amounts affect results.
      """
      method_enum = getattr(c_method, request.method)
  
      tc, pc = gas.gas_tc_pc(
          sg=request.sg,
          h2s=request.h2s,
          co2=request.co2,
          n2=request.n2,
          cmethod=method_enum,
      )
  
      return {
          "value": {"tc": float(tc), "pc": float(pc)},
          "method": request.method,
          "units": {"tc": "degR", "pc": "psia"},
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/gas_models.py:45-63 (schema)

  Pydantic model defining the input parameters and validation for the gas_critical_properties tool.

  class CriticalPropertiesRequest(BaseModel):
      """Request model for critical properties calculation."""
  
      sg: float = Field(
          ..., ge=0.5, le=2.0, description="Gas specific gravity (air=1, dimensionless)"
      )
      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["PMC", "SUT", "BUR"] = Field(
          "PMC", description="Calculation method (PMC recommended)"
      )

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

  Registration of the gas tools module, which includes the gas_critical_properties tool, by calling register_gas_tools(mcp) on the FastMCP server instance.

  from .tools.gas_tools import register_gas_tools
  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)