pyResToolbox MCP Server

Instructions

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)