pyResToolbox MCP Server

Instructions

Implementation Reference

• src/pyrestoolbox_mcp/tools/simtools_tools.py:21-224 (handler)

  The core handler function generate_rel_perm_table decorated with @mcp.tool(), implementing the tool logic: constructs parameters from request, calls simtools.rel_perm_table, formats output as dict with table data.
  def generate_rel_perm_table(request: RelPermTableRequest) -> dict: """Generate relative permeability table for reservoir simulation. **CRITICAL SIMULATION TOOL** - Creates saturation-dependent relative permeability curves for ECLIPSE, Intersect, CMG, or other simulators. Relative permeability is essential for multiphase flow simulation and determines fluid mobility. **Parameters:** - **rows** (int, required): Number of saturation points in table. Must be > 0. Typical: 20-50. Example: 25. More rows = smoother curves but larger files. - **krtable** (str, required): Table type. Options: "SWOF", "SGOF", "SGWFN". Example: "SWOF" for water-oil systems. - **krfamily** (str, required): Correlation family. Options: "COR" (Corey), "LET". Example: "COR" for simple power-law, "LET" for flexible fitting. - **kromax** (float, required): Maximum oil relative permeability (0-1). Typical: 0.5-1.0. Example: 1.0. - **swc** (float, required): Connate water saturation (0-1). Must be < 1. Typical: 0.1-0.3. Example: 0.15. - **krwmax** (float, optional): Maximum water rel perm for SWOF (0-1). Typical: 0.1-0.5. Example: 0.25. - **krgmax** (float, optional): Maximum gas rel perm for SGOF/SGWFN (0-1). Typical: 0.5-1.0. Example: 1.0. - **sorw** (float, optional): Residual oil saturation to water (0-1). Typical: 0.1-0.3. Example: 0.15. - **sorg** (float, optional): Residual oil saturation to gas (0-1). Typical: 0.05-0.2. Example: 0.1. - **sgc** (float, optional): Critical gas saturation (0-1). Typical: 0.05-0.15. Example: 0.1. - **swcr** (float, optional): Critical water saturation for Corey (0-1). Typical: 0.15-0.25. Example: 0.2. - **no** (float, optional): Corey exponent for oil (Corey only). Must be > 0. Typical: 2.0-4.0. Example: 2.5. Higher = more curved. - **nw** (float, optional): Corey exponent for water (Corey only). Must be > 0. Typical: 1.5-3.0. Example: 1.5. - **ng** (float, optional): Corey exponent for gas (Corey only). Must be > 0. Typical: 2.0-3.5. Example: 2.0. - **Lo, Eo, To** (float, optional): LET parameters for oil (LET only). Typical: Lo=1-3, Eo=1-2, To=1-3. Example: Lo=2.5, Eo=1.25, To=1.75. - **Lw, Ew, Tw** (float, optional): LET parameters for water (LET only). Typical: Lw=1-3, Ew=1-2, Tw=1-3. Example: Lw=1.5, Ew=1.0, Tw=2.0. - **Lg, Eg, Tg** (float, optional): LET parameters for gas (LET only). Typical: Lg=1-3, Eg=1-2, Tg=1-3. Example: Lg=1.2, Eg=1.5, Tg=2.0. **Correlation Families:** - **Corey (1954):** Simple power-law model, fast, widely used. Formula: Kr = krmax * ((S - Sc) / (1 - Swc - Sor))^n Use for: Quick estimates, standard cases, compatibility. - **LET (2005):** Flexible 3-parameter model, better curve fitting. Formula: Kr = krmax * (S^L) / (S^L + E * (1-S)^T) Use for: History matching, complex curves, accuracy. **Table Types:** - **SWOF:** Water-Oil (waterflood, aquifer influx). Columns: Sw, Krw, Kro, Pcow. - **SGOF:** Gas-Oil (gas cap expansion, gas injection). Columns: Sg, Krg, Krog, Pcog. - **SGWFN:** Three-phase gas-water (gas cycling, WAG). Columns: Sg, Krg, Krw, Pcog, Pcow. **Saturation Endpoints:** - Swc: Connate water (immobile water) - Sorw: Residual oil to water (trapped oil after waterflood) - Sorg: Residual oil to gas (trapped oil after gas injection) - Sgc: Critical gas (minimum gas saturation for flow) **Workflow:** 1. Choose correlation family (Corey or LET) 2. Select table type (SWOF, SGOF, SGWFN) 3. Specify saturation endpoints (Swc, Sor, Sgc) 4. Set maximum rel perms (kromax, krwmax, krgmax) 5. Define correlation parameters (Corey exponents or LET params) 6. Generate table with specified number of rows **Returns:** Dictionary with: - **table** (list): List of dicts with saturation and rel perm values - **columns** (list): Column names (e.g., ["Sw", "Krw", "Kro", "Pcow"]) - **rows** (int): Number of rows in table - **table_type** (str): Table type (SWOF, SGOF, SGWFN) - **correlation** (str): Correlation family (COR, LET) - **note** (str): Usage guidance - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Saturation endpoints don't sum correctly (Swc + Sor < 1.0) - Using wrong table type for simulation (check simulator requirements) - Corey exponents too high (>5) causing unrealistic curves - Not specifying required parameters for chosen table type - Too few rows (<10) causing poor curve resolution - Maximum rel perms > 1.0 (must be dimensionless 0-1) **Example Usage (Corey SWOF):** ```python { "rows": 25, "krtable": "SWOF", "krfamily": "COR", "kromax": 1.0, "krwmax": 0.25, "swc": 0.15, "swcr": 0.2, "sorw": 0.15, "no": 2.5, "nw": 1.5 } ``` **Example Usage (LET SGOF):** ```python { "rows": 25, "krtable": "SGOF", "krfamily": "LET", "kromax": 1.0, "krgmax": 1.0, "swc": 0.2, "sorg": 0.15, "sgc": 0.1, "Lo": 2.5, "Eo": 1.25, "To": 1.75, "Lg": 1.2, "Eg": 1.5, "Tg": 2.0 } ``` **Note:** Relative permeability tables are critical for accurate simulation. Always validate endpoints against core data or literature. Use LET for history matching when Corey doesn't fit data well. Table format is ECLIPSE-compatible and ready for direct inclusion in simulation decks. """ family_enum = getattr(kr_family, request.krfamily) table_enum = getattr(kr_table, request.krtable) # Build kwargs based on correlation family and table type kwargs = { "rows": request.rows, "krtable": table_enum, "krfamily": family_enum, "kromax": request.kromax, "swc": request.swc, } # Add table-specific parameters if request.krtable == "SWOF": if request.krwmax is not None: kwargs["krwmax"] = request.krwmax if request.sorw is not None: kwargs["sorw"] = request.sorw elif request.krtable in ["SGOF", "SGWFN"]: if request.krgmax is not None: kwargs["krgmax"] = request.krgmax if request.sorg is not None: kwargs["sorg"] = request.sorg if request.sgc is not None: kwargs["sgc"] = request.sgc # Add correlation-specific parameters if request.krfamily == "COR": # Corey parameters if request.no is not None: kwargs["no"] = request.no if request.nw is not None: kwargs["nw"] = request.nw if request.ng is not None: kwargs["ng"] = request.ng if request.swcr is not None: kwargs["swcr"] = request.swcr elif request.krfamily == "LET": # LET parameters - Oil if request.Lo is not None: kwargs["Lo"] = request.Lo if request.Eo is not None: kwargs["Eo"] = request.Eo if request.To is not None: kwargs["To"] = request.To # LET parameters - Water if request.Lw is not None: kwargs["Lw"] = request.Lw if request.Ew is not None: kwargs["Ew"] = request.Ew if request.Tw is not None: kwargs["Tw"] = request.Tw # LET parameters - Gas if request.Lg is not None: kwargs["Lg"] = request.Lg if request.Eg is not None: kwargs["Eg"] = request.Eg if request.Tg is not None: kwargs["Tg"] = request.Tg # Generate table df = simtools.rel_perm_table(**kwargs) # Convert DataFrame to list of dicts table_data = df.to_dict(orient="records") return { "table": table_data, "columns": list(df.columns), "rows": len(table_data), "table_type": request.krtable, "correlation": request.krfamily, "note": "Table formatted for ECLIPSE/Intersect simulation input", "inputs": request.model_dump(), }
• src/pyrestoolbox_mcp/models/simtools_models.py:7-67 (schema)

  Pydantic BaseModel RelPermTableRequest defining all input fields with types, validators, descriptions, constraints (e.g., ge=0 le=1 for saturations), and example.
  class RelPermTableRequest(BaseModel): """Request model for relative permeability table generation.""" model_config = ConfigDict( json_schema_extra={ "example": { "rows": 25, "krtable": "SWOF", "krfamily": "LET", "kromax": 1.0, "krwmax": 0.25, "swc": 0.15, "sorw": 0.15, "Lo": 2.5, "Eo": 1.25, "To": 1.75, "Lw": 2.0, "Ew": 1.5, "Tw": 2.0, } } ) rows: int = Field(25, gt=0, le=100, description="Number of table rows") krtable: Literal["SWOF", "SGOF", "SGWFN"] = Field( "SWOF", description="Table type (SWOF, SGOF, SGWFN)") krfamily: Literal["COR", "LET"] = Field( "LET", description="Correlation family (Corey or LET)") # Max rel perms kromax: float = Field(1.0, ge=0, le=1, description="Max oil rel perm") krwmax: Optional[float] = Field(None, ge=0, le=1, description="Max water rel perm (SWOF)") krgmax: Optional[float] = Field(None, ge=0, le=1, description="Max gas rel perm (SGOF/SGWFN)") # Saturations swc: float = Field(0.0, ge=0, le=1, description="Connate water saturation") swcr: Optional[float] = Field(None, ge=0, le=1, description="Critical water sat (Corey)") sorg: Optional[float] = Field(None, ge=0, le=1, description="Residual oil to gas") sorw: Optional[float] = Field(None, ge=0, le=1, description="Residual oil to water") sgc: Optional[float] = Field(None, ge=0, le=1, description="Critical gas saturation") # Corey exponents no: Optional[float] = Field(None, gt=0, description="Oil Corey exponent") nw: Optional[float] = Field(None, gt=0, description="Water Corey exponent") ng: Optional[float] = Field(None, gt=0, description="Gas Corey exponent") # LET parameters - Oil Lo: Optional[float] = Field(None, gt=0, description="Oil L parameter (LET)") Eo: Optional[float] = Field(None, gt=0, description="Oil E parameter (LET)") To: Optional[float] = Field(None, gt=0, description="Oil T parameter (LET)") # LET parameters - Water Lw: Optional[float] = Field(None, gt=0, description="Water L parameter (LET)") Ew: Optional[float] = Field(None, gt=0, description="Water E parameter (LET)") Tw: Optional[float] = Field(None, gt=0, description="Water T parameter (LET)") # LET parameters - Gas Lg: Optional[float] = Field(None, gt=0, description="Gas L parameter (LET)") Eg: Optional[float] = Field(None, gt=0, description="Gas E parameter (LET)") Tg: Optional[float] = Field(None, gt=0, description="Gas T parameter (LET)")
• src/pyrestoolbox_mcp/server.py:19-27 (registration)

  Imports register_simtools_tools and calls it with the MCP server instance to register all simtools including generate_rel_perm_table.
  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) register_simtools_tools(mcp)