ipm14-mcp 1.0.0__tar.gz

ipm14_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,263 @@
+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 的商标，
+本包仅做协议封装，与该公司无隶属关系。

ipm14_mcp-1.0.0/README.md

@@ -0,0 +1,246 @@
+# 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 的商标，
+本包仅做协议封装，与该公司无隶属关系。

ipm14_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ipm14-mcp"
+version = "1.0.0"
+description = "MCP server for Petroleum Experts IPM 14.0 (PROSPER / MBAL / GAP) driven through OpenServer COM"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+keywords = ["mcp", "ipm", "prosper", "mbal", "gap", "openserver", "petroleum", "well-analysis"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: Microsoft :: Windows",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pywin32>=306; sys_platform == 'win32'",
+    "mcp>=1.2.0",
+    "openpyxl>=3.1.0",
+    "matplotlib>=3.7.0",
+    "pandas>=2.0.0",
+]
+
+[project.scripts]
+ipm14-mcp = "ipm_mcp_server:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+py-modules = [
+    "ipm_mcp_server",
+    "prosper_openserver",
+    "prosper_variables",
+    "gap_variables",
+    "mbal_variables",
+    "plot_utils",
+    "prosper_exporter",
+]

ipm14_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ipm14_mcp-1.0.0/src/gap_variables.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""gap_variables.py — GAP (IPM 管网/地面网络优化) OpenServer 变量/命令表。
+
+数据来源：
+  - PE Limited《OpenServer User Guide》(OpenServer.pdf, IPM 14.0) 中出现的 GAP.* 变量名
+    （用 pymupdf 提取，共 58 个真实 token，其中 GAP.MOD 出现 227 次为最核心的模型导航命令）。
+  - 应用命令（START/OPENFILE/SAVEFILE/SHUTDOWN/NEWFILE/ISREADY）沿用与 PROSPER/MBAL
+    一致的通用 OpenServer 约定（本机待实测确认，机制与 PROSPER/MBAL 平行）。
+
+分档：
+  - COMMAND_DB 中 6 个标准应用命令：与 PROSPER/MBAL 同构，按通用约定标注。
+  - COMMAND_DB 中 GAP 特有命令：来自官方手册 PDF；描述依据命名/上下文推断，非官方逐条定义，
+    使用前务必先用 run_command / get_variable 实测确认。
+  - REFERENCE_VARS：值类后缀（UNITNAME/RAWVAL/LASTCMDRET）与少量依据命名推断的项。
+
+重要（与 MBAL 同理）：OpenServer 变量名随 IPM 版本/模块略有差异，不确定时务必先
+get_variable 实测；读取失败（GetLastError 报错）则说明变量名不符，应反馈用户确认。
+"""
+
+# 已验证变量（本机暂无实测读取成功的 GAP 数值变量，待逐个实测补充）
+VERIFIED_VARS = {}
+
+# 命令表（DoCommand / run_command 可用）
+COMMAND_DB = {
+    # ---- 6 个标准应用命令（与 PROSPER/MBAL 同构）----
+    "GAP.START": "启动 GAP（通用启动命令；本机待实测确认，机制与 PROSPER/MBAL 平行）",
+    "GAP.ISREADY": "GAP 就绪状态（0=未就绪 / 1=就绪 / 2=未启动或无许可）",
+    "GAP.SHUTDOWN": "关闭 GAP，释放实例与许可证",
+    "GAP.OPENFILE": "打开模型文件（用法 GAP.OPENFILE(\"路径\")）",
+    "GAP.SAVEFILE": "保存模型（GAP.SAVEFILE 或 GAP.SAVEFILE(\"路径\") 另存）",
+    "GAP.NEWFILE": "新建（重置数据）",
+    # ---- GAP 特有命令（来自 OpenServer.pdf）----
+    "GAP.MOD": "GAP 模型导航/选择项（出现 227 次，最核心命令；用法 GAP.MOD(\"路径/项\")，待实测）",
+    "GAP.NEWITEM": "新建模型项",
+    "GAP.COPYITEM": "复制模型项",
+    "GAP.DELITEM": "删除模型项",
+    "GAP.LINKITEMS": "建立模型项链接",
+    "GAP.LINKITEMPORTS": "建立端口链接",
+    "GAP.UNLINKITEMS": "断开模型项链接",
+    "GAP.APPLYSCHEDULETO": "应用计划到指定项",
+    "GAP.CLEARAPPLIEDSCHEDULE": "清除已应用计划",
+    "GAP.ExtractArchive": "提取归档文件",
+    "GAP.WELLCALC": "井计算（Well calculation）",
+    "GAP.PACALC": "分配计算（Allocation calculation）",
+    "GAP.ACTUALCALC": "实际计算（Actual calculation）",
+    "GAP.SOLVENETWORK": "求解管网网络（Solve network）",
+    "GAP.TRANSFERPROSPERIPR": "从 PROSPER 传入 IPR 曲线",
+    "GAP.PCCALC": "PCC 计算",
+    "GAP.PCCMANIPRES": "PCC 操作压力",
+    "GAP.PCCGASINJ": "PCC 注气",
+    "GAP.PCCANS": "PCC 求解答案",
+    "GAP.PCCDANSDG": "PCC DANS DG",
+    "GAP.REFITPC": "重新拟合 PC 曲线",
+    "GAP.RESETALLOCINPUTS": "重置分配输入",
+    "GAP.PURGEALLRESULTS": "清除全部计算结果",
+    "GAP.VLPIMPORT": "导入 VLP 数据",
+    "GAP.VLPIPRPCGEN": "生成 VLP/IPR/PC 数据",
+    "GAP.PREDINIT": "预测初始化",
+    "GAP.PREDDOSTEP": "预测执行一步",
+    "GAP.PREDEND": "预测结束",
+    "GAP.PREDRESTART": "预测重启",
+    "GAP.PREDCURDATE.DATESTR": "预测当前日期（字符串）",
+    "GAP.PREDCURSTEPDATE": "预测当前步日期",
+    "GAP.PREDPREVSTEPDATE": "预测上一步日期",
+    "GAP.PREDSTEPLENGTH": "预测步长",
+    "GAP.PREDSNAPSHOT.LOAD": "加载预测快照",
+    "GAP.PREDSNAPSHOT.TIME": "预测快照时间",
+    "GAP.PREDSNAPSHOT.TIME.COUNT": "预测快照时间计数",
+    "GAP.PREDSNAPSHOT.UNLOAD": "卸载预测快照",
+    "GAP.STARTASYNC": "异步启动 GAP",
+    "GAP.InputUnitSystem": "输入单位系统",
+    "GAP.OutputUnitSystem": "输出单位系统",
+    "GAP.Preferences.DefaultInputUnitSystem": "默认输入单位系统",
+    "GAP.Preferences.DefaultOutputUnitSystem": "默认输出单位系统",
+    "GAP.Preferences.AlwaysUseDefaultUnitSystems": "总是使用默认单位系统",
+    "GAP.OpenServerUseKeywords": "OpenServer 关键字使用开关",
+    "GAP.EnableNetworkValidation": "启用管网校验",
+}
+
+# 参考变量（值类后缀与少量依据命名推断的项）
+REFERENCE_VARS = {
+    "GAP.UNITNAME": "变量单位名后缀（如 GAP.xxx.UNITNAME）",
+    "GAP.RAWVAL": "原始值后缀（如 GAP.xxx.RAWVAL，忽略当前界面单位）",
+    "GAP.LASTCMDRET": "最近一次命令的返回值",
+    "GAP.PIPH2S": "管流 H2S 相关（依据命名推断）",
+    "GAP.PIPGOR": "管流 GOR 相关（依据命名推断）",
+}
+
+# 函数表（GAP 的 DoGet 检索函数，待实测补充）
+FUNCTIONS = {}
+
+# 动作变量（只写不读，待实测补充）
+ACTION_VARS = {}
+
+# 合并变量表（供 search_variables 使用）
+ALL_VARS = {**VERIFIED_VARS, **REFERENCE_VARS}