Metadata-Version: 2.4
Name: ipm14-mcp
Version: 1.0.0
Summary: MCP server for Petroleum Experts IPM 14.0 (PROSPER / MBAL / GAP) driven through OpenServer COM
License-Expression: LicenseRef-Proprietary
Keywords: mcp,ipm,prosper,mbal,gap,openserver,petroleum,well-analysis
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pywin32>=306; sys_platform == "win32"
Requires-Dist: mcp>=1.2.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: pandas>=2.0.0

# IPM 14.0 连接器（ipm14-mcp）

把 **Petroleum Experts IPM 套件**（PROSPER 单井 / MBAL 油藏 / GAP 油田）通过 **OpenServer（Windows COM）**
封装成标准 MCP Server，让 WorkBuddy 等 AI 客户端用自然语言完成
「打开模型 → 改参数 → 重算 → 读结果 → 敏感性扫描 → 导出绘图」全流程。

> 连接器在客户端中的显示名为 **IPM 14.0**，MCP 服务标识为 `IPM14.0`（工具前缀 `mcp__IPM14.0__*`）。

---

## 1. 前置条件（重要）

本连接器是**本地型**（stdio + COM），不是云端服务，因此：

| 项 | 要求 |
| --- | --- |
| 操作系统 | Windows x64 |
| 石油工程软件 | 本机已安装 IPM **14.0 或 11.0**，且 `prosper.exe / mbal.exe / gap.exe` 可正常启动 |
| OpenServer | IPM 安装时勾选 OpenServer 组件，并具备可用授权（license） |
| Python | 3.10+（`uvx` 方式由 uv 自动准备，无需预装） |
| 客户端 | WorkBuddy ≥ 4.22.12 |

**IPM 软件与授权需用户自行购买安装，本包不包含、不代理任何商业授权。**

---

## 2. 安装方式

### 方式 A：作为 WorkBuddy 连接器安装（推荐）

连接器包结构（符合 WorkBuddy 开放平台提交规范 `open.workbuddy.cn/docs/connector`）：

```
ipm14-connector/
├── connector-meta.json             # ★ 连接器元信息（平台注册 / 市场展示）
├── mcp.json                        # ★ MCP 服务定义（stdio / uvx，仅一个 Server）
├── icon.svg                        # ★ 市场图标
├── skills/ipm-openserver/SKILL.md  # AI 使用说明（教模型何时、如何调用这些工具）
├── src/                            # 连接器本体，7 个 Python 模块
│   ├── ipm_mcp_server.py           #   MCP 入口，17 个工具
│   ├── prosper_openserver.py       #   OpenServer COM 封装（连接 / 读写 / 命令）
│   ├── prosper_variables.py        #   PROSPER 变量表 + 双版本映射
│   ├── mbal_variables.py           #   MBAL 变量表
│   ├── gap_variables.py            #   GAP 变量表
│   ├── plot_utils.py               #   绘图
│   └── prosper_exporter.py         #   导出 xlsx / csv / txt
├── pyproject.toml                  # 发行配置（发布 PyPI，供 uvx 拉取）
└── README.md
```

**为什么代码必须随包**：本连接器没有远程服务，逻辑全部在本机 Python 进程内通过 COM 调用 IPM，
因此 `src/` 的 7 个模块就是产品本体，不可精简为配置——其中 `prosper_variables.py`（59 KB）
是 PROSPER / MBAL / GAP 三套变量字典与 v11/v14 映射表，是这套连接器最核心的资产。

客户端安装态清单（`.codebuddy-plugin/plugin.json`）与 512×512 客户端图标由平台发布时自动生成，
包内不再冗余提供。

`mcp.json` 通过 `uvx ipm14-mcp` 拉起服务，因此需先把源码发布到 Python 包索引（见第 6 节），
或在客户端里改为本机直跑（方式 C）。

### 方式 B：pip 安装

```bash
pip install .            # 在包根目录执行
ipm14-mcp                # 验证：能启动并打印日志即为正常
```

安装后手动在 MCP 配置中登记：

```json
{
  "mcpServers": {
    "IPM14.0": {
      "type": "stdio",
      "command": "ipm14-mcp",
      "env": { "PYTHONUTF8": "1" }
    }
  }
}
```

### 方式 C：源码直跑（本地内测，最快）

无需安装，直接指向源码脚本（`src` 目录会自动进入 `sys.path`）：

```json
{
  "mcpServers": {
    "IPM14.0": {
      "type": "stdio",
      "command": "python",
      "args": ["<包根绝对路径>/src/ipm_mcp_server.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}
```

依赖：`pip install pywin32 mcp openpyxl matplotlib pandas`（与 `pyproject.toml` 的 dependencies 一致）。

> ⚠️ 若同一台机器已存在名为 `IPM14.0` 的 MCP 配置，**先移除旧条目**再启用连接器，
> 否则两个实例会抢占同一 OpenServer 会话与 license。

---

## 3. 工具清单（17 个）

**会话 / 文件**

| 工具 | 作用 |
| --- | --- |
| `ping` | 健康检查，确认能连上本机 OpenServer |
| `start_app` | 启动 PROSPER / MBAL / GAP 并等待就绪 |
| `open_model` | 打开 `.Out` 模型（程序未启动时自动拉起） |
| `save_model` | 保存 / 另存当前模型 |

**通用读写**

| 工具 | 作用 |
| --- | --- |
| `get_variable` | 读取 OpenServer 变量（`raw=true` 取油田单位原始值） |
| `set_variable` | 写入变量（数值自动转 float；拒绝空值） |
| `run_command` | 执行 OpenServer 命令（`slow=true` 等待耗时计算完成） |
| `set_unit_system` | 切换单位制（oilfield / norsi / cansi / gersi / fresi / latsi） |
| `array_count` | 取可变长数组元素个数（`.COUNT`） |
| `list_variables` | 按关键词检索内置变量/命令表（PROSPER + MBAL + GAP） |

**版本兼容**

| 工具 | 作用 |
| --- | --- |
| `detect_ipm_version` | 探测本机 IPM 版本（`v11` / `v14`，读 `prosper.exe` 文件版本） |
| `resolve_variable` | 逻辑名 → 版本化变量路径（如「产液量」→ v14 `SOL[0].QLIQ` / v11 `Results[0].Sol.LiqRate`） |

**业务计算 / 输出**

| 工具 | 作用 |
| --- | --- |
| `run_system_analysis` | 设压力 + 含水率 → 跑系统分析 → 返回产液量 |
| `run_calc` | 对任意 IPM 程序执行一次计算（可带清除命令） |
| `sensitivity_sweep` | 变量敏感性扫描：设值 → 计算 → 读结果，可选导出 |
| `export_result` | 导出 xlsx / csv / txt（默认写入 `outputs/`） |
| `plot_result` | 把扫描结果绘成折线图并保存 PNG |

---

## 4. 双版本兼容（IPM 11.0 / 14.0）

两个版本的 OpenServer 变量命名风格完全不同：

- **14.0**：缩写风格 —— `SOL[0].QLIQ`
- **11.0**：全称风格 —— `Results[0].Sol.LiqRate`

**使用铁律**：首次驱动变量前先 `detect_ipm_version`，再用 `resolve_variable` 按逻辑名取路径，
不要裸写某一版本的变量字符串。探测到未收录版本（如 v15）会明确返回警告，此时应停止套用映射表。

---

## 5. 安全与隐私

- **数据不出本机**：连接器只通过本机 COM 与 IPM 进程通信，不含任何网络上传、遥测或统计上报。
- **模型文件位置**：只读写用户显式传入的路径；导出与绘图默认落在包目录 `outputs/`。
- **日志**：运行日志写 `logs/ipm_mcp.log`（本地文件），仅记录调用名与错误，不记录模型内容。
- **无凭据处理**：不需要账号、密钥或 Token。

---

## 6. 打包与发布

### 6.1 先发布 Python 包（`uvx` 分发的前提）

```bash
# 1) 构建 wheel + sdist
python -m pip install --upgrade build
python -m build

# 2) 发布到 PyPI（先配置 ~/.pypirc 或用环境变量 TWINE_PASSWORD）
python -m twine upload dist/*

# 3) 校验：新机器上直接跑通即为可分发给客户
uvx ipm14-mcp
```

发布后 `mcp.json` 中的 `uvx ipm14-mcp` 即可正常工作。

> **镜像坑（2026-10-30 实测）**：`mcp.json` 默认**不指定** PyPI 镜像，走官方源。
> 原因：清华源（`pypi.tuna.tsinghua.edu.cn`）实测拉不到 `pywin32`（`No matching distribution found`），
> 一旦把 `UV_DEFAULT_INDEX` 指向该镜像，安装会直接失败。
> 如需加速，先确认目标镜像上 `pywin32`、`mcp`、`matplotlib` 均可获取，再写入 `env`。
>
> **首次启动耗时**：干净环境下完整安装依赖实测约 **3 分 35 秒**（官方源，含 matplotlib / pandas），
> 之后走 uv 缓存为秒级。这是 `uvx` 首次冷启动的正常表现，不是卡死。

### 6.2 提交 WorkBuddy 开放平台（open.workbuddy.cn）

1. 注册并完成开发者认证（企业认证可开放全部能力；个人认证不支持 Buddy 应用与硬件）。
2. 进入后台 → **连接器** → 新建 → 上传本目录打包的 zip。
3. 平台会解析 `connector-meta.json` 与 `mcp.json`；只需再选**分类**、**服务类目**、**头像**。
4. 提交审核，常规 7 个工作日；通过后进入连接器市场，更新版本需重新提交。

审核重点（本包已逐条对齐）：

| 检查项 | 本包状态 |
| --- | --- |
| 目录结构符合 MCP + Skill 规范 | ✅ `connector-meta.json` + `mcp.json` + `icon.svg` + `skills/` |
| `source` 为 kebab-case 且全局唯一 | ✅ `ipm14-mcp` |
| 中英文名称/描述/示例齐全（示例各 2~5 条） | ✅ 各 5 条 |
| 仅配置一个 MCP Server | ✅ 只有 `IPM14.0` |
| 声明 `minWorkbuddyVersion` | ✅ `4.24.0`（`examples_*` 字段自 4.24.0 起生效） |
| 图标清晰、透明底 | ✅ `icon.svg` + `icon.png` 64×64 |
| 文件中无真实凭证 | ✅ 无需 Token / 无密钥 |
| Skill 覆盖全部核心能力 | ✅ 17 个工具 + 铁律 + 故障速查 |

> **审核可能追问的一点**：本连接器是**本地 stdio + COM**，工具价值依赖用户本机已装 IPM 与 OpenServer 授权，
> 无法在云端环境演示。建议在提交说明里写明「面向已购买 IPM 的石油工程师，本地运行、数据不出本机」，
> 并说明 `uvx` 首次拉取依赖约 100 MB、启动较慢属正常。

---

## 7. 常见问题

**Q：首次连接很慢（十几秒到一分钟）？**
`uvx` 首次会解析并下载 matplotlib / pandas 等依赖（约 100 MB+）。之后走缓存，启动在秒级。
对时效敏感可改用方式 B（预装到本机 Python），或配置 `UV_DEFAULT_INDEX` 指向内网镜像。

**Q：工具调用报「尚未调用 CoInitialize」？**
已修复：服务对每个工作线程做一次线程级 COM 初始化（`threading.local` + `CoInitialize`）。
若仍出现，确认 `pywin32` 已正确安装，且未在非 Windows 环境运行。

**Q：报 RPC_E_WRONG_THREAD / 「已为另一线程整理的接口」？**
OpenServer 的 COM 对象是套间（STA）绑定的。服务已按线程维护独立会话，避免跨线程传对象；
自定义扩展代码时不要跨线程复用 `ProsperServer` 实例。

**Q：IPM 窗口越开越多 / license 被占满？**
任务收尾必须同时调用 `shutdown("PROSPER")` 与 `disconnect()`：
`disconnect()` 只释放 OpenServer 连接，**不会**关掉 IPM GUI 实例窗口。详见配套技能文档。

**Q：`get_variable` 返回空值？**
多为变量名不存在或该字段确实为空。先用 `list_variables` 检索，或 `resolve_variable` 取正确路径。

---

## 8. 许可

Proprietary / 内部使用。IPM、PROSPER、MBAL、GAP、OpenServer 为 Petroleum Experts 的商标，
本包仅做协议封装，与该公司无隶属关系。
