内容
# optivibe-mcp
optivibe-mcp 是一个 **实验性** 的 MCP 服务器，为编码代理（如 Claude Code）提供与 Zemax OpticStudio 接口的工具。
它通过 ZOS-API 将 OpticStudio 操作暴露为类型化的 MCP 工具：加载设计、编辑镜头数据、运行分析、优化和公差，驱动程序通过 ZOS-API 进行，因此代理不必编写原始 API 代码。除工具外，还提供一个参考层，代理可以查询 — 操作数和玻璃查找，以及 OpticStudio 手册的全文搜索。
这是早期阶段，提供即用。预计会有粗糙的边缘；请参见[状态](#状态)。
## 内容
- **工具** (`optivibe-harness`) — 超过 80 个类型化的工具，通过 ZOS-API 驱动 OpticStudio。每个工具返回一个统一的结果信封，而不是引发异常，因此代理检查读回的值，而不是假设调用成功。
- **参考层** (`optivibe-reference`) — 操作数和玻璃查找以及手册搜索，帮助确定代理的选择。无需引擎和许可证；其数据在本地构建（请参见[构建参考数据](#构建参考数据))。
该项目仅提供**代码**。不包含任何供应商数据（玻璃目录、手动文本、操作数描述）— 您需要从自己的许可 OpticStudio 安装中生成这些数据。
## 先决条件
- **Windows.** OpticStudio 和 ZOS-API .NET 界面仅适用于 Windows。
- **Zemax OpticStudio**，具有 ZOS-API 许可证。针对 **2025 R1 (25.1.0, Premium)** 进行开发；其他版本未经测试。启动时在 `IsValidLicenseForAPI` 处进行访问控制。
- **Python 3.11+**.
- **.NET Framework** — 自动使用。引导程序设置 `PYTHONNET_RUNTIME=netfx` 并定位您的安装目录（通过环境变量覆盖、注册表或程序文件扫描）。无需手动设置。
## 安装
克隆存储库，然后从 `packages/optivibe-harness/`:
```bash
pip install -e ../optivibe-reference # 首先安装参考层
pip install -e . # 然后安装 harness
```
首先安装参考包 — harness 在进程中加载它，没有它，参考和查找工具将不可用。
`[manual]` 额外项（PyMuPDF）读取您的 OpticStudio 手册 PDF。它对于**手册搜索**和**操作数/公差描述增强**都是必需的（构建从 PDF 中提取逐字描述）。如果没有它，操作数和公差目录将仅构建**同义词**（仍然可以通过同义词进行搜索 — 但不包含手动描述）。要获取完整的增强构建，请安装：
```bash
pip install -e "../optivibe-reference[manual]"
```
如果您更喜欢 conda，则提供了一个每个包的 `environment.yml`（Python 3.11）。
## 注册到 Claude Code
```bash
claude mcp add optivibe -- /path/to/python -m optivibe_harness
```
`/path/to/python` 是您安装到的环境的解释器 — 指向不同的 Python 是常见的无声失败原因。您可以使用以下命令找到它：
```bash
python -c "import sys; print(sys.executable)"
```
等效的 JSON 配置：
```json
{ "command": "/path/to/python", "args": ["-m", "optivibe_harness"] }
```
## 构建参考数据
参考层的数据从您自己的许可安装中本地构建；不会提交任何供应商衍生的数据。从存储库根目录运行：
```bash
python packages/optivibe-reference/scripts/build_vendor_data.py
```
这从您的 `.agf` 文件（`ZEMAX_GLASSCAT`）读取玻璃目录，如果您将其指向手册 PDF（`OPTIVIBE_MANUAL_PDF`），则会索引它进行搜索。
操作数和公差目录从您安装的 ZOS-API 枚举接口的实时探测中构建。运行两个探测 **一次**（每个启动一个无头 OpticStudio 会话，读取操作数/公差接口，然后回收它）：
```bash
python packages/optivibe-reference/scripts/probe_operands.py
python packages/optivibe-reference/scripts/probe_tolerances.py
```
如果缺少输入，则跳过相应步骤：该工具（玻璃或手册搜索，或操作数/公差查找）返回类型化的“不可用”结果，服务器的其他部分继续工作。详细信息和数据来源账本位于 [PROVENANCE.md](PROVENANCE.md)。
## 运行它
OpticStudio 在启动时不会打开 — 引擎在第一次调用涉及设计的工具时启动，并且它一次处理一个设计。参考和查找工具在没有引擎运行时起作用 — 因此安装、注册、参考构建和每个查找都成功，而不管许可证级别如何；仅当引擎打开时，才检查 ZOS-API 许可证。
关于信任的说明：工具返回结果信封，在失败时不引发异常，因此调用完成不是它按预期工作的证明。请检查返回的值或优化器的判决，而不是错误的有无。
## 技能
存储库包括几个用于常见任务的 Claude Code 技能：
| 技能 | 用于 |
|---|---|
| `design-review` | 评估设计是否符合规格 |
| `design-compare` | 比较设计 |
| `optimize-loop` | 运行优化并进行监控 |
| `zos-api-debug` | 排除 OpticStudio 连接/许可证错误 |
## 状态
实验性。它已针对单个 OpticStudio 版本（2025 R1）在 Windows 上开发和测试；其他版本的行為未经验证。接口和工具覆盖范围可能会发生变化。欢迎报告问题。
## 贡献和联系
通过 [GitHub 问题](../../issues) 和拉取请求欢迎提交错误报告、问题和拉取请求。请不要在问题或拉取请求中包含任何供应商衍生的数据（玻璃目录、手动文本、操作数描述）— 请参见 [PROVENANCE.md](PROVENANCE.md)。
## 许可和来源
optivibe-mcp 在 **Apache License 2.0** 下许可 — 请参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
它是仅限代码的，并驱动您自己的许可 OpticStudio 安装在运行时；不会重新分发供应商数据或 SDK 文件。您在本地构建的参考数据将保留本地（被 gitignore）。optivibe-mcp 是一个独立项目，与 Ansys/Zemax 无关。有关数据来源和许可证账本，请参见 [PROVENANCE.md](PROVENANCE.md)。
