pyResToolbox MCP Server

Instructions

Implementation Reference

• src/pyrestoolbox_mcp/tools/oil_tools.py:653-713 (handler)

  The main handler function for the 'oil_sg_from_api' tool. It is decorated with @mcp.tool() for automatic registration and implements the conversion from API gravity to specific gravity using the pyrestoolbox.oil.oil_sg function.
  @mcp.tool() def oil_sg_from_api(request: APIConversionRequest) -> dict: """Convert API gravity to oil specific gravity. **UNIT CONVERSION TOOL** - Converts API gravity (degrees) to specific gravity (dimensionless, water=1.0). Specific gravity is the ratio of oil density to water density at standard conditions. Essential for calculations requiring specific gravity. **Parameters:** - **api** (float or list, required): Oil API gravity in degrees. Valid range: 0-100. Typical: 20-50. Example: 35.0 or [30, 35, 40]. Can be scalar or array. **Conversion Formula:** SG = 141.5 / (API + 131.5) **Specific Gravity Ranges:** - Heavy oil: SG > 0.922 (API < 22°) - Medium oil: SG 0.850-0.922 (API 22-35°) - Light oil: SG < 0.850 (API > 35°) - Water: SG = 1.0 (API = 10°) **Returns:** Dictionary with: - **value** (float or list): Specific gravity (dimensionless, matches input api shape) - **method** (str): "Standard conversion" - **units** (str): "dimensionless (water=1)" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using gas API gravity instead of oil API gravity - Confusing API gravity with specific gravity (inverse relationship) - Not understanding that lower SG = lighter oil (higher API) - Using wrong conversion formula **Example Usage:** ```python { "api": 35.0 } ``` Result: SG = 141.5 / (35.0 + 131.5) ≈ 0.850 (medium gravity oil) **Note:** Most PVT correlations use API gravity directly, but some require specific gravity. Use this conversion when needed. Remember: API and SG are inversely related - higher API means lower SG (lighter oil). """ sg = oil.oil_sg(api_value=request.api) # Convert numpy array to list for JSON serialization if isinstance(sg, np.ndarray): value = sg.tolist() else: value = float(sg) return { "value": value, "method": "Standard conversion", "units": "dimensionless (water=1)", "inputs": request.model_dump(), }
• src/pyrestoolbox_mcp/models/oil_models.py:208-226 (schema)

  Pydantic model defining the input schema for the tool. Includes 'api' field (float or list[float]) with validation ensuring values are between 0 and 100.
  class APIConversionRequest(BaseModel): """Request model for API to SG conversion.""" api: Union[float, List[float]] = Field( ..., description="API gravity (degrees) - scalar or array" ) @field_validator("api") @classmethod def validate_api(cls, v): """Validate API values.""" if isinstance(v, list): if not all(val > 0 and val <= 100 for val in v): raise ValueError("API gravity must be between 0 and 100") else: if v <= 0 or v > 100: raise ValueError("API gravity must be between 0 and 100") return v
• src/pyrestoolbox_mcp/server.py:16-30 (registration)

  The server.py file imports register_oil_tools from oil_tools.py and calls it with the MCP instance (line 24), which registers the oil_sg_from_api tool among others via the @mcp.tool() decorators in oil_tools.py.
  from .tools.oil_tools import register_oil_tools 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) register_inflow_tools(mcp) register_simtools_tools(mcp) register_brine_tools(mcp) register_layer_tools(mcp) register_library_tools(mcp)