pyResToolbox MCP Server

pyResToolbox MCP服务器

将水库工程计算引入人工智能

用行业标准的石油工程计算为您的AI助手提供动力

    

  

快速开始 • 特性 • 示例 • 文档 • 贡献

______________________________________________________________________

108个生产就绪工具|现场和公制单位|零配置

PVT分析 • 井动态 • 节点分析 • DCA • 物料平衡 • 仿真支持 • 盐水性质 • 地质力学 • 异质性分析

______________________________________________________________________

______________________________________________________________________

☕ 支持这个项目

如果你觉得这个项目有用，可以考虑给我买杯咖啡！您的支持有助于维护和改进此开源工具。

______________________________________________________________________

这是什么？

这个MCP服务器弥合了人工智能助手和石油工程工作流程之间的差距。你可以简单地问克劳德，而不是手动计算储层特性或编写复杂的脚本：

*“使用Valko-McCain相关性计算180°F下API 35°油的泡点压力，溶液GOR为800 scf/stb，气体重力为0.75”*

*“为我的井生成IPR曲线，Pi=4000 psia，Pb=3500 psia，API 38°，175°F，层厚75英尺，渗透率150 mD”*

*“创建一个黑色油表，用于模拟500至5000磅/平方英寸的压力”*

Claude将使用行业标准相关性执行计算，并返回准确、格式化的结果。

建立在

• pyResToolbox Mark Burgoyne-用于油藏工程计算的综合Python库
• FastMCP -用于构建MCP服务器的现代Python框架
• 模型上下文协议 Anthropic-人工智能应用集成标准

主要特点

• 108个生产就绪工具 -所有工具都经过测试和验证
• 行业标准相关性 -站立，Valko McCain，Velarde，DAK，Beggs Robinson，Corey，LET等等
• 双单元支持 -现场单位（psia、°F、ft）和公制单位（barsa、°C、m）
• 阵列支持 -同时计算多个压力下的特性
• 零配置 -与Claude Desktop一起开箱即用
• GPL-3.0许可 -免费和开源

______________________________________________________________________

快速开始

安装

先决条件： Python 3.10+（推荐使用UV包管理器，但可选）

# 1. Clone the repository
git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp

# 2. Install UV (optional but 10-100x faster than pip)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Setup and test
make uv-install    # Creates venv and installs dependencies
make uv-test       # Verifies all 108 tools work correctly

连接到克劳德桌面

将此添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

重要： 对两者都使用绝对路径 uv 以及项目目录。像Claude Desktop这样的GUI应用程序不会继承终端的PATH。

找到您的UV路径：

# macOS/Linux
which uv

# Windows (PowerShell)
Get-Command uv | Select-Object -ExpandProperty Source

配置：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

常见UV路径：

• macOS/Linux： /Users/username/.local/bin/uv 或 /home/username/.local/bin/uv
• 窗户： C:\Users\username\.cargo\bin\uv.exe

示例（macOS）：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/Users/john/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/john/projects/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

示例（Linux）：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/home/john/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/home/john/projects/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

示例（Windows）：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "C:\\Users\\john\\.cargo\\bin\\uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\john\\projects\\pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

重新启动克劳德桌面 完全（退出并重新打开，而不仅仅是关闭窗口），您就可以开始了！

______________________________________________________________________

添加AI技能（推荐）

这 SKILL/ 这个存储库中的文件夹包含一个预构建的技能，可以教你的人工智能助手如何正确使用所有108个工具——正确的参数名称、有效的方法代码、验证约束和多步骤工作流。

内容包括：

安装（克劳德代码）：

将技能文件复制到您的Claude技能目录：

cp SKILL/SKILL.md ~/.claude/skills/pyrestoolbox-mcp.md

# Optional but recommended — full parameter reference
mkdir -p ~/.claude/skills/references
cp SKILL/tools-reference.md ~/.claude/skills/references/tools-reference.md

安装后，当您询问储层工程计算、PVT分析、井动态、地质力学或任何pyResToolbox主题时，该技能会自动激活。

该技能教给AI什么：

• 精确的参数名称(psd 不 pwf, sg 不 sg_g 对于气体工具， zmethod 对比 method)
• 所有有效枚举字符串("VALMC", "DAK", "SWOF", "COR"等等）
• 每个工具的必需参数与可选参数
• 数值验证限制（API 0–100，气体SG 0.5–2.0，泊松比0–0.5）
• 常见的多步骤工作流程（PVT分析、井动态、模拟输入、地质力学钻井窗口）

______________________________________________________________________

您的第一个查询

打开克劳德桌面并尝试：

“在180°F、800 scf/stb溶液GOR和0.75气体重力条件下，35°API油的泡点压力是多少？”

克劳德将使用 oil_bubble_point 工具并返回以下结果：

Bubble Point Pressure: 3,456.7 psia
Method: Valko-McCain (VALMC)
Inputs: API=35°, T=180°F, Rs=800 scf/stb, SG_gas=0.75

______________________________________________________________________

你能做什么？

油PVT分析

• 计算泡点压力（Standing、Valko McCain、Velarde）
• 溶液GOR、地层体积系数、粘度、密度、压缩性
• 为模拟器生成全面的黑油表

气体PVT分析

• Z因子计算（DAK、Hall-Yarborough、WYW、BUR/Peng Robinson EOS）
• 氢气能力 气体PVT通过BUR方法（SPE-229932-MS）-处理包括纯CO在内的任意混合物₂ 30%+H₂
• 污染物（CO）的关键特性₂, H₂S, N₂, H₂)
• 气体粘度、密度、压缩性、假压力
• 地层体积系数、水合物预测、含水量

油井性能和知识产权

• 油气生产率（径向和线性流动）
• 垂直井和水平井IPR曲线生成
• Vogel IPR适用于低于泡点的压力
• 渗透率、表皮、储层压力敏感性分析

油藏模拟支持

• 相对渗透率表（SWOF、SGOF、SGWFN） 科里, 让，以及 杰罗尔德 曲线族
• 重新烫发 -将实验室数据拟合到任何模型族，或自动选择最佳拟合
• 让物理可行性检查
• PVDO/PVDG/PVTO黑油台和PVTW水PVT发电
• ECLIPSE的VFPPROD/VFPINJ升力曲线表
• Van Everdingen&Hurst含水层影响函数（AQUTAB）
• Rachford-Rice闪光相行为计算

节点分析和VLP

• 四种多相VLP相关性： Woldesemayat Ghajar （WG）， 哈格多恩·布朗 （HB）， 灰色, Beggs&Brill （BB）
• 多段斜井和水平完井（不仅仅是垂直管道）
• IPR曲线生成（天然气、石油、水井）
• VLP流出曲线和操作点计算
• 支持生产和注入模式
• ECLIPSE/Intersect模拟器的VFPPROD/VFPINJ表生成
• GasPVT和OilPVT包装物类别，用于一致的流体表征

下降曲线分析（DCA）

• Arps递减（指数、双曲线、调和）
• 速率和累计产量预测
• 欧元估算
• 多阳紧缩/非常规下跌
• 生产率分析（WOR、GOR、WGR）

物料平衡

• 用于OGIP估算的P/Z气体物料平衡
• 用于OOIP估算的Havena Odeh石油物料平衡
• 科尔图诊断和回归

地质力学和井筒稳定性（27种工具）

• 垂直/水平应力、孔隙压力预测（Eaton）
• 裂缝梯度、破裂压力、泥浆重量窗口
• 钻孔破裂、出砂、断层稳定性
• 弹性模量、岩石强度、压实度、热应力
• 原木、应力多边形、临界水位下降的UCS

盐水性质

• CH₄-饱和盐水特性（密度、粘度、FVF、压缩性）
• CO₂-用于封存研究的盐水互溶性
• 索雷德·惠特森VLE 用于多气体盐水系统（CO₂, H₂S, N₂, H₂) 采用Sechenov盐析校正
• IAPWS-IF97淡水密度、Spivey/McCain盐度校正
• 单一框架中的各组分溶解度、含水量和热力学性质

高级计算

• 储层非均质性分析（洛伦兹系数、贝塔参数）
• 地层渗透率分布
• 成分库（100多种碳氢化合物的关键特性）
• 敏感性分析（参数扫描、龙卷风图）
• 方法推荐引擎

配置和帮助

• 查询可用的计算方法和相关性
• 接入单元系统文档
• 获取物理常数
• 全面的使用指南

______________________________________________________________________

Claude的查询示例

基本PVT计算

"Calculate Z-factor for gas with SG 0.7 at 3500 psia and 180°F using DAK method"

"What's the oil formation volume factor for 38° API oil at 3000 psia, 175°F with Rs=600?"

"Compare bubble point pressures using Standing, Valko-McCain, and Velarde for 35° API oil"

油井性能分析

"Generate IPR curve for well: Pi=4000 psia, Pb=3500 psia, API 38, T=175°F,
 h=75 ft, k=150 mD, skin=-2, re=1500 ft, rw=0.5 ft"

"Calculate oil production rate at 2000 psia flowing pressure for the same well"

"Show me how permeability affects production - test 50, 100, 150, 200, 250 mD"

模拟准备

"Generate a SWOF relative permeability table using Corey correlation with 25 rows,
 kromax=1.0, krwmax=0.25, swc=0.15, sorw=0.15, no=2.5, nw=1.5"

"Create aquifer influence functions for dimensionless radius 10.0"

"Generate black oil table from 500 to 5000 psia for 38° API oil at 175°F"

储层非均质性

"Convert Lorenz coefficient 0.5 to Dykstra-Parsons beta"

"Generate layered permeability distribution for Lorenz coefficient 0.6,
 10 layers, average permeability 100 mD"

多步骤工作流

"Perform complete reservoir analysis: Calculate bubble point, generate PVT table,
 create IPR curve, and analyze well performance for 38° API oil at 175°F with
 initial pressure 4000 psia"

"Design a well completion: Calculate optimal flowing pressure, generate IPR,
 and compare different skin factors"

"Evaluate a gas reservoir: Calculate critical properties, generate IPR,
 and compare different Z-factor methods"

高级查询

全面的PVT工作流程

"Generate a complete PVT table for API 38 oil at 175°F with gas gravity 0.68
 and solution GOR 750 scf/stb. Include pressures from 500 to 4000 psia and
 show Rs, Bo, viscosity, and density"

"Compare bubble point pressures using Standing, Valko-McCain, and Velarde
 correlations for API 35 oil at 180°F with GOR 800 scf/stb"

"Calculate PVT properties at multiple pressures: 1000, 2000, 3000, and 4000 psia
 for API 38 oil at 175°F"

气体分析

"Calculate the critical properties (Tc and Pc) for a gas with specific gravity 0.7
 containing 2% CO2, 1% H2S, and 3% N2"

"Compare Z-factors using DAK, HY, and WYW methods for a gas at 3500 psia and 180°F"

"Calculate gas pseudopressure from 1000 to 3500 psia for a gas with SG 0.7 at 180°F"

油井性能和知识产权

"Generate an IPR curve for an oil well with reservoir pressure 4000 psia,
 bubble point 3500 psia, API 38 oil at 175°F. Well has 75 ft net pay,
 150 mD permeability, skin -2, drainage radius 1500 ft"

"What's the oil production rate at 2000 psia flowing pressure for a well with
 Pi=4000 psia, Pb=3500 psia, API 35, 180°F, 50 ft pay, 100 mD permeability?"

"Generate a Vogel IPR curve for pressures below bubble point for API 38 oil"

敏感性分析

"How does oil rate change with permeability? Test values from 50 to 250 mD"

"What's the impact of skin factor on production? Compare rates for skin values
 from -5 to +10"

"Analyze the effect of net pay thickness on production rate: test 25, 50, 75,
 and 100 ft"

"How does reservoir pressure depletion affect production? Calculate rates at
 4000, 3500, 3000, and 2500 psia"

盐水和一氧化碳₂ 扣押

"Calculate brine properties for fresh water at 3000 psia and 175°F"

"What are the properties of saline brine (5% NaCl) at reservoir conditions:
 3000 psia, 175°F?"

"Calculate CO₂-brine mutual solubility at 3000 psia and 180°F with salinity
 50000 ppm"

"Compare brine properties with and without CO₂ saturation at sequestration conditions"

储层非均质性

"Convert Lorenz coefficient 0.5 to Dykstra-Parsons beta parameter"

"Calculate Lorenz coefficient from production logging data: flow fractions
 [0.45, 0.25, 0.15, 0.10, 0.05] and permeability fractions [0.30, 0.25, 0.20, 0.15, 0.10]"

"Generate a layered permeability distribution for Lorenz coefficient 0.5,
 10 layers, average permeability 100 mD"

相位行为和闪光计算

"Solve Rachford-Rice flash for a mixture with compositions [0.5, 0.3, 0.2]
 and K-values [2.5, 1.8, 0.6]"

"Calculate vapor-liquid equilibrium for a three-component system"

构件库

"What are the critical properties for methane?"

"Get critical temperature and pressure for ethane, propane, and butane"

"What's the molecular weight of n-heptane?"

经济与优化

"What's the optimal flowing pressure to maximize production? Generate IPR
 and find the sweet spot"

"Compare production rates for stimulated (skin -2) vs damaged (skin +5) wells"

"Analyze the impact of reservoir pressure depletion on well performance over time"

比较和基准测试

"Compare Standing vs Valko-McCain vs Velarde bubble point correlations for the same oil"

"Compare DAK vs HY vs WYW Z-factor methods and their impact on gas rate calculations"

"Compare radial vs linear flow geometries for the same reservoir properties"

教育查询

"Explain what bubble point pressure means and calculate it for API 35 oil"

"What's the difference between solution GOR and producing GOR? Calculate both"

"How does gas gravity affect Z-factor? Show me calculations for different gravities"

"Explain Lorenz coefficient and calculate it for a heterogeneous reservoir"

故障排除和验证

"Validate my PVT data: bubble point 3500 psia, API 38, 175°F, GOR 750 scf/stb -
 does this make sense?"

"Check if my gas composition is realistic: SG 0.7 with 5% CO2, 3% H2S, 2% N2"

"Verify my well performance calculation: Are these rates reasonable for the
 given reservoir properties?"

更好查询的提示

1. 具体 -包括所有相关参数（API、温度、压力等）
2. 指定方法 -说出你想要的相关性（VALMC、DAK、Corey、LET等）
3. 包括单位 -始终指定单位（psia、华氏度、mD、英尺等）
4. 要求比较 -请求方法或场景之间的比较
5. 请求表 -当你需要多个值时，要求提供表格结果
6. 后续问题 -基于之前对复杂工作流程的回答

______________________________________________________________________

单位制

所有计算默认为 油田单位（美国油田） 按照行业标准。集 metric: true 使用任何工具 公制单位 （Eclipse METRIC惯例：barsa、°C、米、sm³/d），无需手动转换。ECLIPSE关键字输出会自动切换到METRIC标头。

通过询问Claude随时访问完整的单元文档： *“pyRestToolbox使用什么单位？”*

______________________________________________________________________

建筑

项目结构

pyrestoolbox-mcp/
├── src/pyrestoolbox_mcp/
│   ├── server.py              # Main MCP server (FastMCP)
│   ├── config.py              # Server configuration & constants
│   ├── tools/                 # 108 MCP tool implementations
│   │   ├── oil_tools.py       # 19 oil PVT tools
│   │   ├── gas_tools.py       # 15 gas PVT tools
│   │   ├── inflow_tools.py    # 4 well performance tools
│   │   ├── simtools_tools.py  # 11 simulation support tools
│   │   ├── nodal_tools.py     # 6 nodal analysis / VLP tools
│   │   ├── dca_tools.py       # 9 decline curve analysis tools
│   │   ├── matbal_tools.py    # 2 material balance tools
│   │   ├── brine_tools.py     # 3 brine property tools
│   │   ├── geomech_tools.py   # 27 geomechanics tools
│   │   ├── layer_tools.py     # 5 heterogeneity tools
│   │   ├── recommend_tools.py # 4 method recommendation tools
│   │   ├── sensitivity_tools.py # 2 sensitivity analysis tools
│   │   ├── library_tools.py   # 1 component library tool
│   │   └── gas_fixes.py       # Upstream bug workarounds
│   ├── models/                # Pydantic validation models
│   │   ├── oil_models.py
│   │   ├── gas_models.py
│   │   ├── inflow_models.py
│   │   ├── simtools_models.py
│   │   ├── nodal_models.py
│   │   ├── dca_models.py
│   │   ├── matbal_models.py
│   │   ├── brine_models.py
│   │   ├── geomech_models.py
│   │   ├── layer_models.py
│   │   ├── recommend_models.py
│   │   ├── sensitivity_models.py
│   │   ├── library_models.py
│   │   └── common_models.py
│   └── resources/             # MCP configuration resources
│       └── config_resources.py
├── tests/                     # Test suite (52 pytest tests)
│   ├── test_oil_tools.py
│   ├── test_gas_tools.py
│   ├── test_geomech_tools.py
│   ├── test_simtools_new.py
│   ├── test_dca_tools.py
│   ├── test_brine_new.py
│   ├── test_nodal_tools.py
│   ├── test_matbal_tools.py
│   ├── test_recommend_tools.py
│   └── conftest.py
├── examples/                  # 12 comprehensive workflow examples
│   ├── basic_usage.py
│   ├── pvt_workflow.py
│   ├── gas_well_analysis.py
│   └── ...
├── server.py                  # Entry point
├── pyproject.toml            # UV/pip configuration
├── Makefile                  # Development commands
├── Dockerfile                # Docker deployment
└── docker-compose.yml        # Multi-transport deployment

运作原理

1. FastMCP服务器 -处理MCP协议通信（STDIO、HTTP、SSE）
2. Pydantic模型 -使用描述性错误消息验证所有输入
3. 工具层 -108个函数封装pyrestoolbox计算
4. pyRestToolbox -执行实际的水库工程计算
5. 类型转换 -处理JSON的numpy/pandas/mpmath序列化

工具类别

______________________________________________________________________

pyResToolbox v3功能覆盖率

此MCP服务器包装 pyResToolbox v3.0.4。下表显示了在 v3发布帖子:

未作为MCP工具公开的功能

一些pyResToolbox函数在内部使用，但不作为独立的MCP工具公开：

______________________________________________________________________

发展

运行测试

# Quick validation (all 108 tools)
make uv-test
# or
uv run python test_tools.py

# Full pytest suite
uv run pytest

# With coverage report
uv run pytest --cov=pyrestoolbox_mcp --cov-report=html

# Specific test modules
uv run pytest tests/test_oil_tools.py
uv run pytest tests/test_gas_tools.py

看 TEST_RESULTS.md 完整的验证报告。

运行示例

# Run all examples
make uv-examples

# Run specific example
make uv-example EXAMPLE=basic_usage.py
make uv-example EXAMPLE=gas_well_analysis.py

# Or manually
cd examples
uv run python basic_usage.py

代码质量

# Format code
uv run black src/ tests/

# Lint
uv run ruff check src/ tests/

# Type checking (if mypy added)
uv run mypy src/

Docker部署

# Build image
make docker-build

# Run HTTP server (port 8000)
make docker-up-http

# Run SSE server (port 8001)
make docker-up-sse

# View logs
make docker-logs

# Stop services
make docker-down

看 医生.md 查看完整的Docker文档。

添加新工具

看 贡献.md 详细说明。快速概述：

1. 定义Pydantic模型 在 src/pyrestoolbox_mcp/models/
2. 机具功能 不恰当的 src/pyrestoolbox_mcp/tools/ 文件
3. 注册工具 在模块的 register_*_tools() 功能
4. 添加测试 到 test_tools.py 以及适当的pytest文件
5. 更新文档 在README和示例中

______________________________________________________________________

可用的计算方法

石油相关性

泡点压力

• VALMC 白与麦凯恩 White & McCain （2003） *推荐用于大多数应用*
• 斯坦 -站立（1947）- *经典相关性*
• 舌根音 -维拉德（1997）- *针对特定地区*

解决方案GOR（Rs）

• 舌根音 -维拉德（1997）
• 斯坦 -站立（1947）
• VALMC 白与麦凯恩 White & McCain （2003）

地层体积系数（Bo）

• 麦凯恩 -麦凯恩等人（1988）- *推荐*
• 斯坦 -站立（1947）

黏度

• 巴西 -贝格斯和罗宾逊（1975）

气体相关性

z因子

• DAK -Dranchuk&Abou Kassem（1975）- *建议用于碳氢化合物气体*
• 嗨 -霍尔和亚堡（1973）- *快速，适用于大多数条件*
• WYW -王、叶、吴（2021）- *相当快*
• BUR -伯戈因、尼尔森和斯坦科（2025）- *基于EOS的通用相关性（5组分Peng Robinson），最适合高浓度非烃（CO₂, H₂S, N₂, H₂),包括纯CO₂ 以及高达30%+的氢气。唯一支持H的方法₂. （速度-229932-MS）*

关键属性

• 私人军事公司 -派珀、麦凯恩和科雷多（1993）- *建议用于碳氢化合物气体*
• 被测系统 -萨顿（1985）
• BUR -伯戈因、尼尔森和斯坦科（2025）- *通用相关性，最适合非烃含量高的气体（SPE-229932-MS）*

黏度

• 乐金电子 -李、冈萨雷斯和埃金（1966）

相对渗透率

曲线类型

• COR -科里（1954）- *幂律，简单*
• 让 -埃贝托夫特和托马斯·洛梅兰（2005）- *灵活、复杂的形状*

表类型

• SWOF -油水饱和度函数
• SGOF -气油饱和度函数
• SGWFN -气水饱和度函数（三相）

______________________________________________________________________

程序化使用

虽然此服务器是为Claude Desktop集成而设计的，但您也可以通过编程方式使用它：

Python客户端

import asyncio
from fastmcp.client import InMemoryTransport
from pyrestoolbox_mcp import mcp

async def calculate_pvt():
    transport = InMemoryTransport(mcp)

    async with transport.get_client() as client:
        # Calculate bubble point
        pb_result = await client.call_tool(
            "oil_bubble_point",
            {
                "api": 35.0,
                "degf": 180.0,
                "rsb": 800.0,
                "sg_g": 0.75,
                "method": "VALMC"
            }
        )
        pb = pb_result['value']
        print(f"Bubble Point: {pb:.2f} psia")

        # Calculate Rs at multiple pressures
        rs_result = await client.call_tool(
            "oil_solution_gor",
            {
                "api": 35.0,
                "degf": 180.0,
                "p": [1000, 2000, 3000, pb, 4000],
                "sg_g": 0.75,
                "pb": pb,
                "rsb": 800.0,
                "method": "VELAR"
            }
        )
        print(f"Rs values: {rs_result['value']}")

        # Access configuration resources
        methods = await client.read_resource("config://methods")
        print(f"Available methods:\n{methods.content}")

asyncio.run(calculate_pvt())

HTTP/SSE传输

# Start HTTP server
uv run fastmcp run server.py --transport http --port 8000

# Or using Docker
docker-compose --profile http up -d

然后使用任何支持MCP协议的MCP客户端或HTTP客户端进行连接。

______________________________________________________________________

故障排除

安装问题

“uv：找不到命令”

• 安装UV后关闭并重新打开终端
• 验证： uv --version
• 替代方案：改用pip(pip install -e .)

“make：找不到命令”（Windows）

• 使用Makefile中的手动命令
• 或者通过Chocolatey安装Windows版Make： choco install make

UV同步失败

• 清除缓存： rm -rf .venv && make uv-install
• 检查Python版本： python --version （需要3.10+）

Claude桌面集成

错误：“生成uv ENOONT”

• 这意味着Claude Desktop无法找到 uv 命令
• GUI应用程序不继承终端的PATH
• 解决方案： 使用绝对路径 uv 在您的配置中
• 查找UV路径： which uv （macOS/Linux）或 Get-Command uv （Windows）
• 常见位置：

- macOS/Linux： /Users/username/.local/bin/uv 或 /home/username/.local/bin/uv - 窗户： C:\Users\username\.cargo\bin\uv.exe

克劳德没有看到工具

1. 使用 绝对路径 对两者 uv 命令和项目目录（否 ~，使用完整路径）
2. 验证路径是否正确： ls /path/to/uv 和 ls /path/to/pyrestoolbox-mcp
3. 完全重新启动Claude Desktop（退出，而不仅仅是关闭窗口）
4. 检查克劳德桌面日志：

- macOS： ~/Library/Logs/Claude/ - 窗户： %APPDATA%\Claude\logs\ - Linux： ~/.config/Claude/logs/

1. 手动测试服务器： cd /path/to/pyrestoolbox-mcp && make uv-server

工具因错误而失败

• 验证所有输入是否使用现场单位（psia、°F、ft、mD）
• 检查参数名称是否完全匹配（区分大小写）
• 运行验证： uv run python test_tools.py

运行时问题

导入错误

# Reinstall dependencies
make uv-install
# or
uv sync --force

计算错误

• 检查单位（必须为psia、°F等）
• 验证输入是否真实（例如，API 10-50，温度60-300°F）
• 一些相关性有有效范围——尝试不同的方法
• 检查 pyResToolbox文档 相关极限

性能问题

• 通过numpy优化数组计算
• 对于大型数据集，考虑批处理请求
• Docker部署增加了最小的开销

获取帮助

• 检查 兴趣\_ QUERIES.md 查询示例
• 审查 示例/ 工作代码目录
• 看 贡献.md 用于开发设置
• 打开一个 问题 对于bug或功能请求

______________________________________________________________________

贡献

欢迎投稿！此项目遵循上游pyResToolbox库的GPL-3.0许可证。

如何做出贡献

1. 分叉存储库
2. 创建要素分支 (git checkout -b feature/amazing-feature)
3. 进行更改 （遵循代码风格指南）
4. 彻底测试 (uv run pytest -所有测试必须通过）
5. 格式代码 (uv run black src/ tests/)
6. 提交 (git commit -m 'Add amazing feature')
7. 推 (git push origin feature/amazing-feature)
8. 打开拉取请求

开发设置

git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp
make uv-install
uv run python test_tools.py  # Verify all 108 tools pass

指南

• 对所有函数参数和返回值使用类型提示
• 编写谷歌风格的文档字符串
• 为所有新工具添加测试
• 遵循现有代码结构
• 更新文档

看 贡献.md 详细指南。

______________________________________________________________________

许可证

GNU通用公共许可证v3.0（GPL-3.0）

此MCP服务器基于 pyResToolbox，根据GPL-3.0获得许可。该项目完全符合GPL-3.0许可条款。

要点：

• 免费开源软件
• 您可以根据GPL-3.0条款使用、修改和分发
• 任何修改也必须根据GPL-3.0发布
• 不提供保修（详见许可证）
• 根据GPL-3.0条款，允许商业使用

看 许可证 获取完整的许可证文本。

______________________________________________________________________

项目状态

特性	状态	详细信息
测试		100%工具覆盖率
生产	✅ 就绪	所有工具均已验证
文档	✅ 完成	README、示例、指南
许可证	GPL-3.0	上游比赛
python	3.10+	全程键入提示
框架	FastMCP 3.1+	现代MCP实施

看 生产_READY.md 查看详细的验证结果。

版本历史记录

v2.0.0版本 （2026-03-11）-pyResToolbox 3.0.4的重大升级

• 108个生产就绪工具（高于47个）
• 双单元支持（现场+公制）
• 新模块：DCA、物料平衡、节点分析、地质力学、敏感性、推荐
• FastMCP 3.x兼容性
• 52项pytest测试通过

v1.0.0 （2024-11-15）-首次生产发布

• 47个生产就绪工具
• Docker部署支持
• GPL-3.0许可证合规性

看 更改日志.md 查看详细的版本历史。

______________________________________________________________________

路线图

计划的功能

• \[\]具有交互式表单的HTTP传输Web UI
• \[\]常见任务的其他工作流示例
• \[\]性能基准测试套件
• \[\]扩展仿真工具（网格处理、ECLIPSE实用程序）
• \[\]Jupyter笔记本集成示例
• \[\]API文件网站（Sphinx/MkDocs）
• \[\]HTTP部署的速率限制和身份验证
• \[\]普罗米修斯指标导出

看 未解决的问题 有关建议功能和已知问题的完整列表。

上游一体化

我们正在探索机会，为改进做出贡献 pyResToolbox，包括：

• 独立 gas_grad2sg 实现（bug修复）
• 增强的类型提示
• 其他验证实用程序

______________________________________________________________________

相关项目

核心依赖关系

• pyResToolbox -Mark Burgoyne的水库工程图书馆
• FastMCP -MCP服务器的Python框架
• 模型上下文协议 -Anthropic的MCP规范

类似的MCP服务器

• mcp服务器 -官方MCP服务器示例
• 很棒的mcp服务器 -MCP服务器的整理列表

石油工程工具

• PVTpy -Python中的PVT计算
• 宠物箱 -石油工程工具箱

______________________________________________________________________

致谢

如果没有以下内容，这个项目就不会存在：

• 马克·伯戈因 -创造者 pyResToolbox，此MCP服务器的基础
• 马文AI团队 -开发商 FastMCP 框架
• 人类 -对于克劳德和 模型上下文协议 规格
• 水库工程界 -用于开发和完善本项目中实施的相关性

特别感谢所有帮助改进这个项目的贡献者！

______________________________________________________________________

引用

如果您在学术或商业工作中使用此MCP服务器，请引用原始的pyResToolbox库：

@software{pyrestoolbox,
  author = {Burgoyne, Mark W.},
  title = {pyResToolbox: A Collection of Reservoir Engineering Utilities},
  url = {https://github.com/mwburgoyne/pyResToolbox},
  version = {3.0.4},
  year = {2025}
}

对于此MCP服务器：

@software{pyrestoolbox_mcp,
  author = {Serrao, Gabriel},
  title = {pyResToolbox MCP Server: AI-Powered Reservoir Engineering Calculations},
  url = {https://github.com/gabrielserrao/pyrestoolbox-mcp},
  version = {2.0.0},
  year = {2026},
  note = {Built on pyResToolbox by Mark W. Burgoyne}
}

______________________________________________________________________

支持

获取帮助

对于MCP服务器问题：

• 检查 故障排除 部分
• 审查 示例/ 目录
• 搜索 现存问题
• 打开A 新发行的

对于计算精度或pyResToolbox功能：

• 看 pyResToolbox文档
• 检查 pyResToolbox问题

对于FastMCP框架：

• 看 FastMCP文档

对于模型上下文协议：

• 看 MCP规范
• 加入 MCP故障 （如果可用）

社区

• 讨论：
• 问题：
• 拉取请求： 贡献指南

______________________________________________________________________

支持与星级

⭐ 明星这个项目

如果你觉得这个项目有用，请在GitHub上给它一颗星！明星帮助其他人发现这个项目，并激励他们继续发展。

☕ 请我喝杯咖啡

支持该项目的开发和维护：

您的支持有助于使这个项目对石油工程社区保持免费和开源！

📈 明星历史


______________________________________________________________________

______________________________________________________________________

内置于❤️ 面向石油工程界

由...创建 加布里埃尔·塞拉奥

______________________________________________________________________

报告Bug · 请求功能 · 文档 · 示例

](https://github.com/gabrielserrao/pyrestoolbox-mcp/stargazers)