pyResToolbox MCP Server

Instructions

Implementation Reference

• src/pyrestoolbox_mcp/tools/simtools_tools.py:432-525 (handler)

  The handler function decorated with @mcp.tool() that implements the core logic: parses Eclipse/Intersect PRT files to extract and summarize convergence problem cells using pyrestoolbox.simtools.ix_extract_problem_cells.

  def extract_eclipse_problem_cells(request: ExtractProblemCellsRequest) -> dict:
      """Extract convergence problem cells from ECLIPSE/Intersect PRT file.
  
      **SIMULATION DIAGNOSTICS TOOL** - Parse ECLIPSE/Intersect PRT output
      files to extract cells with convergence failures, material balance
      errors, or other simulation problems.
  
      **What It Does:**
      - Scans ECLIPSE .PRT files for error/warning messages
      - Identifies problem cells by (I, J, K) grid coordinates
      - Extracts timestep and iteration information
      - Reports error types and severity
  
      **Applications:**
      - **Convergence Debugging:** Find cells causing timestep cuts
      - **Model QC:** Identify grid initialization issues
      - **Performance Tuning:** Locate problematic regions
      - **Numerical Stability:** Track material balance errors
  
      **Common Problems Detected:**
      - Material balance errors
      - Negative saturations
      - Pressure/temperature out of range
      - Flash calculation failures
      - Linear solver issues
      - Severe saturation changes
  
      **Workflow:**
      1. Run ECLIPSE/Intersect simulation
      2. Locate the .PRT output file
      3. Use this tool to extract problem cell locations
      4. Investigate problematic cells in pre-processor
      5. Refine initialization or grid properties
  
      **Output Format:** List of problem cells with timestep, iteration,
      cell coordinates (I,J,K), error type, and severity.
  
      Args:
          request: Path to PRT file and output options
  
      Returns:
          Dictionary with list of problem cells and summary statistics
      """
      try:
          # Extract problem cells from PRT file
          results = simtools.ix_extract_problem_cells(
              filename=request.filename,
              silent=request.silent
          )
  
          if not results:
              return {
                  "problem_cells": [],
                  "total_problems": 0,
                  "message": "No convergence problems detected in PRT file",
                  "file": request.filename,
                  "inputs": request.model_dump(),
              }
  
          # Process results into structured format
          problem_list = []
          for problem in results:
              problem_list.append({
                  "timestep": problem.get("timestep", "Unknown"),
                  "iteration": problem.get("iteration", "Unknown"),
                  "i": problem.get("i", -1),
                  "j": problem.get("j", -1),
                  "k": problem.get("k", -1),
                  "error_type": problem.get("error_type", "Unknown"),
                  "message": problem.get("message", ""),
              })
  
          return {
              "problem_cells": problem_list,
              "total_problems": len(problem_list),
              "file": request.filename,
              "method": "ECLIPSE/Intersect PRT file parsing",
              "inputs": request.model_dump(),
              "note": "Investigate problem cells in grid pre-processor to resolve convergence issues",
          }
  
      except FileNotFoundError:
          return {
              "error": f"PRT file not found: {request.filename}",
              "suggestion": "Verify file path and ensure ECLIPSE/Intersect simulation completed",
              "inputs": request.model_dump(),
          }
      except Exception as e:
          return {
              "error": str(e),
              "file": request.filename,
              "inputs": request.model_dump(),
          }

• src/pyrestoolbox_mcp/models/simtools_models.py:131-136 (schema)

  Pydantic BaseModel defining the input schema with filename (required path to PRT file) and silent (optional boolean to suppress console output).

  class ExtractProblemCellsRequest(BaseModel):
      """Request model for ECLIPSE problem cell extraction."""
  
      filename: str = Field(..., description="Path to ECLIPSE/Intersect PRT file")
      silent: bool = Field(True, description="Suppress console output")

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

  Top-level registration in the MCP server: imports register_simtools_tools from simtools_tools.py and calls it with the mcp instance, which defines and registers extract_eclipse_problem_cells among other simtools.

  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)