pyResToolbox MCP Server

Instructions

{
    "hc_mw": 18.5,
    "co2": 0.05,
    "h2s": 0.0,
    "n2": 0.01,
    "h2": 0.0
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/gas_tools.py:982-1098 (handler)

  The handler function for the 'gas_sg_from_composition' tool. It uses pyrestoolbox.gas.gas_sg to compute specific gravity from hydrocarbon MW and impurity mole fractions, formats the response with composition breakdown.

  @mcp.tool()
  def gas_sg_from_composition(request: GasSGFromCompositionRequest) -> dict:
      """Calculate gas specific gravity from composition.
  
      **COMPOSITIONAL GAS CHARACTERIZATION** - Computes gas specific gravity from
      hydrocarbon molecular weight and non-hydrocarbon mole fractions. Uses molecular
      weight weighted average method. Essential when gas composition is known but SG
      measurement is unavailable or unreliable.
  
      **Parameters:**
      - **hc_mw** (float, required): Hydrocarbon molecular weight in lb/lbmol.
        Valid: 10-200. Typical: 16-50. Example: 18.5 for typical natural gas.
      - **co2** (float, optional, default=0.0): CO2 mole fraction (0-1).
        Typical: 0-0.20. Example: 0.05 for 5% CO2.
      - **h2s** (float, optional, default=0.0): H2S mole fraction (0-1).
        Typical: 0-0.05. Example: 0.02 for 2% H2S (sour gas).
      - **n2** (float, optional, default=0.0): N2 mole fraction (0-1).
        Typical: 0-0.10. Example: 0.01 for 1% N2.
      - **h2** (float, optional, default=0.0): H2 mole fraction (0-1).
        Typical: 0-0.01. Example: 0.0 (rare in natural gas).
  
      **Calculation Method:**
      Weighted average based on molecular weights:
      - HC fraction: User-provided MW (hc_mw)
      - CO2: MW = 44.01 lb/lbmol
      - H2S: MW = 34.08 lb/lbmol
      - N2: MW = 28.01 lb/lbmol
      - H2: MW = 2.02 lb/lbmol
      - Air: MW = 28.97 lb/lbmol (reference for SG)
  
      Formula: MW_avg = hc_fraction × hc_mw + co2 × 44.01 + h2s × 34.08 + n2 × 28.01 + h2 × 2.02
      SG = MW_avg / 28.97
  
      **Typical Hydrocarbon MW:**
      - Pure methane: 16.04
      - Dry gas (C1-C2): 16-18
      - Associated gas (C1-C4): 18-25
      - Wet gas (C1-C6): 25-35
      - Condensate gas: 35-50
  
      **Applications:**
      - **Compositional Simulation:** Convert composition to SG for black oil models
      - **Gas Plant Feed:** Characterize feed gas from composition analysis
      - **Sales Gas Specs:** Calculate SG for pipeline specifications
      - **Contaminated Gas:** Analyze gas with high non-hydrocarbon content
      - **Laboratory Data:** Convert GC analysis to SG
  
      **Non-Hydrocarbon Effects:**
      - CO2 increases SG (MW=44.01 > air MW=28.97)
      - H2S increases SG (MW=34.08 > air MW=28.97)
      - N2 slightly decreases SG (MW=28.01 ≈ air MW=28.97)
      - H2 significantly decreases SG (MW=2.02 << air MW=28.97)
  
      **Returns:**
      Dictionary with:
      - **gas_specific_gravity** (float): Gas SG (dimensionless, air=1)
      - **composition** (dict): Detailed composition breakdown
        - hydrocarbon_fraction: Mole fraction of hydrocarbons
        - hydrocarbon_mw: Provided hydrocarbon MW
        - co2_fraction: CO2 mole fraction
        - h2s_fraction: H2S mole fraction
        - n2_fraction: N2 mole fraction
        - h2_fraction: H2 mole fraction
      - **method** (str): "Molecular weight weighted average"
      - **units** (str): "dimensionless (air=1)"
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Using weight fraction instead of mole fraction
      - Incorrect hydrocarbon MW (must be average MW of HC fraction)
      - Mole fractions don't sum to 1.0 (should sum to 1.0)
      - Using component MW instead of mixture MW for hydrocarbons
      - Not accounting for all non-hydrocarbon components
  
      **Example Usage:**
      ```python
      {
          "hc_mw": 18.5,
          "co2": 0.05,
          "h2s": 0.0,
          "n2": 0.01,
          "h2": 0.0
      }
      ```
      Result: SG ≈ 0.65-0.70 (typical natural gas with 5% CO2, 1% N2).
  
      **Note:** Mole fractions must sum to 1.0. If only HC fraction is provided,
      ensure hc_fraction = 1.0 - (co2 + h2s + n2 + h2). Hydrocarbon MW should be
      the average MW of the hydrocarbon fraction, not individual component MW.
      """
      sg = gas.gas_sg(
          hc_mw=request.hc_mw,
          co2=request.co2,
          h2s=request.h2s,
          n2=request.n2,
          h2=request.h2
      )
  
      # Calculate composition details
      total_non_hc = request.co2 + request.h2s + request.n2 + request.h2
      hc_fraction = 1.0 - total_non_hc
  
      return {
          "gas_specific_gravity": float(sg),
          "composition": {
              "hydrocarbon_fraction": float(hc_fraction),
              "hydrocarbon_mw": request.hc_mw,
              "co2_fraction": request.co2,
              "h2s_fraction": request.h2s,
              "n2_fraction": request.n2,
              "h2_fraction": request.h2,
          },
          "method": "Molecular weight weighted average",
          "units": "dimensionless (air=1)",
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/gas_models.py:315-335 (schema)

  Pydantic input schema (BaseModel) for the tool, validating hydrocarbon molecular weight and mole fractions of CO2, H2S, N2, H2.

  class GasSGFromCompositionRequest(BaseModel):
      """Request model for gas SG from composition calculation."""
  
      model_config = ConfigDict(
          json_schema_extra={
              "example": {
                  "hc_mw": 20.5,
                  "co2": 0.05,
                  "h2s": 0.01,
                  "n2": 0.02,
                  "h2": 0.0,
              }
          }
      )
  
      hc_mw: float = Field(..., gt=0, description="Hydrocarbon molecular weight (lb/lbmol)")
      co2: float = Field(0.0, ge=0, le=1, description="CO2 mole fraction")
      h2s: float = Field(0.0, ge=0, le=1, description="H2S mole fraction")
      n2: float = Field(0.0, ge=0, le=1, description="N2 mole fraction")
      h2: float = Field(0.0, ge=0, le=1, description="H2 mole fraction")

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

  Registration of all gas tools, including 'gas_sg_from_composition', by calling register_gas_tools which defines the decorated handler functions.

  register_gas_tools(mcp)