内容
# zemax-mcp-server
**通过Claude Code驱动Ansys Zemax OpticStudio — 实时，通过ZOS-API — 无需触及Zemax的源代码或二进制文件。**
该项目将本地安装的 **Ansys Zemax OpticStudio** 转化为一组命名、自我描述的工具，[Claude Code](https://claude.com/claude-code)（或任何MCP客户端）可以调用这些工具。每个工具将一个ZOS-API操作与一个简单的描述相结合，以便AI代理可以从 *意图* → *光学设计动作* → *数值结果*。
它是 **非侵入式的**：它只加载OpticStudio附带的三个公共ZOS-API .NET程序集（`ZOSAPI.dll`、`ZOSAPI_Interfaces.dll`、`ZOSAPI_NetHelper.dll`）通过 [`pythonnet`](https://github.com/pythonnet/pythonnet)。Zemax安装程序中没有任何修改。
> 已验证 **Ansys Zemax OpticStudio 2025 R2.02**。
---
## 为什么存在
OpticStudio中的光学设计是一个重度依赖GUI和专业知识的循环。ZOS-API公开了几乎整个对象模型 — 编辑器、分析、优化器、光线追踪 — 给外部代码。该仓库为AI代理包装了该接口，以便您可以 *对话* 完成设计：
> "以扩展模式连接，设置光圈为F/4，添加可见波长，构建单透镜，使半径可变，运行向导，然后优化并告诉我RMS斑点大小。"
---
## 架构
```
┌─────────────────┐ MCP (stdio) ┌──────────────────────┐ pythonnet/.NET ┌───────────────────────┐
│ Claude Code │◄──────────────►│ zemax_mcp.server │◄─────────────────►│ OpticStudio (ZOS-API) │
│ (WSL / Linux) │ python.exe │ (Windows Python) │ ZOSAPI.dll etc. │ GUI or headless │
└─────────────────┘ └──────────────────────┘ └───────────────────────┘
工具： zemax_connect · zemax_set_aperture · zemax_lde_* · zemax_optimize · zemax_run_analysis · zemax_nsc_* · zemax_eval
```
支持两种官方连接模式：
| 模式 | 调用 | 用途 |
|---|---|---|
| **交互式扩展** | `ConnectAsExtension(0)` | 附加到 **正在运行的GUI** 以便实时编辑。启用 *编程 ▸ 交互式扩展*。 |
| **独立/无头** | `CreateNewApplication()` | 启动 **无头** OpticStudio用于批处理/自动化（需要Pro/Premium级别）。 |
> ⚠️ **WSL注意：** `pythonnet`加载Windows .NET，因此服务器在 **Windows Python**（`python.exe`）下运行，从WSL中的Claude Code调用。参见 [`setup/INSTALL.md`](setup/INSTALL.md)。
---
## 仓库布局
| 路径 | 内容 |
|---|---|
| `zemax_mcp/connection.py` | 非侵入式双模式连接器（扩展+独立）通过 `ZOSAPI_NetHelper`。 |
| `zemax_mcp/server.py` | **MCP服务器** — 每个ZOS-API功能都作为描述的工具公开。 |
| `docs/function-to-feature-catalog.md` | 主映射：**GUI功能 ↔ ZOS-API成员 ↔ 功能描述 ↔ AI用例**。 |
| `skills/sequential-design.md` | **顺序**成像设计手册（光圈/视场/波长 → 变量/求解 → 优值函数 → 局部/全局优化 →像差控制），带有可运行的ZOS-API代码片段。 |
| `skills/non-sequential-design.md` | **非顺序**工作手册（照明、杂散光、散射、光源/探测器、光线分裂、重要性采样）。 |
| `examples/smoke_test.py` | 端到端：构建单透镜、优化、打印RMS斑点大小。 |
| `examples/beam_stabilization.py` | 闭环 **2-FSM瞄准稳定** 在真实反射式望远镜上（将其转换为NSC，感知返回，驱动两个FSM）。参见 [`docs/beam-stabilization-demo.md`](docs/beam-stabilization-demo.md)。 |
| `examples/atmosphere_1080nm_2km.py` | **大气通道** 用于1.08 µm光束超过2公里 — 吸收（链路预算）+闪烁（孔径平均、衰减）+湍流倾斜馈送FSM环路，以及 `delivered_power()` 具有一阶热晕效应。参见 [`docs/atmosphere-1080nm-2km.md`](docs/atmosphere-1080nm-2km.md)。 |
| `examples/blooming_split_step.py` | **波光学分步（BPM）** 热晕模型 — 将复场传播到2公里目标，具有非线性热相位；值得信赖的热晕Strehl/光束弯曲数。经验证与衍射理论+链路预算一致。 |
| `setup/INSTALL.md` | 完整设置 + 故障排除。 |
---
## 快速开始
```powershell
# 1. 在Windows Python下安装依赖项（推荐3.11–3.13）
python -m pip install pythonnet "mcp[cli]"
```
```bash
# 3. 从WSL注册到Claude Code
claude mcp add zemax -- python.exe -m zemax_mcp.server
```
然后只需与Claude讨论您的光学系统。
---
## 工具表面（v0.1）
**连接：** `zemax_connect` · `zemax_disconnect` · `zemax_info`
**系统：** `zemax_new_system` · `zemax_open_file` · `zemax_save_file` ·
`zemax_set_aperture` · `zemax_set_wavelengths` · `zemax_set_fields`
**镜头数据编辑器：** `zemax_lde_summary` · `zemax_lde_insert_surface` ·
`zemax_lde_set_surface` · `zemax_set_variable`
**优化：** `zemax_merit_wizard` · `zemax_merit_value` · `zemax_optimize`
（局部/全局）· `zemax_quick_focus`
**分析：** `zemax_run_analysis`（RayFan、StandardSpot、FftPsf、FftMtf、WavefrontMap、…） ·
`zemax_spot_rms` · `zemax_analysis_series`（x/y曲线用于光线扇区/MTF） ·
`zemax_batch_ray_trace`（快速归一化光线追踪）
**多配置：** `zemax_mce_summary` · `zemax_mce_add_config` · `zemax_mce_add_operand`
**公差：** `zemax_tde_summary` · `zemax_tolerance_wizard` · `zemax_run_tolerancing`
**非顺序：** `zemax_nsc_summary` · `zemax_nsc_ray_trace` · `zemax_nsc_detector_data`
**高级：** `zemax_eval`（门控逃脱口用于未包装的调用）
工具集是故意可扩展的 — [功能到功能目录](docs/function-to-feature-catalog.md)是包装剩余API的路线图。
---
## 状态和注意事项
- **v0.1 — 已验证。** 所有31个MCP工具都已在 **OpticStudio 2025 R2.02（企业版）** 上进行了端到端的运行，包括完整的构建→优化循环（优值1.03→0.08，RMS斑点大小1453→56 µm），批量光线追踪，光线扇区/MTF曲线提取，多配置编辑，21个操作数的公差向导 + 蒙特卡罗运行，以及`Diode`样本上的NSC探测器读数（50×50，总通量15625）。成员名称探针确认了33/35个成员在第一次通过；两个遗漏的被修复并重新验证：RMS斑点大小是 `SpotData.GetRMSSpotSizeFor(field, 0)`（多色），波前分析IDM是 `WavefrontMap`（不是`Wavefront`）。工具输出是JSON清理的，因此非有限值（例如，平坦表面的`radius = Infinity`）可以安全地序列化。
- **会话健康。** 许多快速的`connect → New（）→ disconnect`循环可能会卡住OpticStudio会话（`New_Analysis`返回`None`；轴上光线报告错误）。长寿命的MCP服务器执行一次连接并持有它，因此不会遇到这个问题；分析工具现在会在检测到卡住状态时引发明确的“重启&重新连接”消息。
- **扩展模式每次点击激活一个连接。** *编程 ▸ 交互式扩展* 接受单个`ConnectAsExtension`然后停止监听；长寿命的MCP服务器获取它一次并持有它，因此如果您运行多个一次性的脚本（每次之间重新点击），这才重要。
- **独立/无头** 在此许可证上不可用，尽管是企业版 — `CreateNewApplication（）` 成功但 `IsValidLicenseForAPI` 为false。使用扩展模式。
- 第三方包装存在且值得了解：
[**ZOSPy**](https://github.com/MREYE-LUMC/ZOSPy) （MIT，pythonnet，积极维护 — 推荐用于更重度使用）和较旧的基于COM的
[PyZOS](https://github.com/xzos/pyzos) （自〜2016年以来基本未维护）。
## 许可证
MIT（参见项目所有者）。
---
*使用官方Ansys/Zemax ZOS-API文档和知识库的引用深度研究构建。非侵入式构造。*
MCP 市场