CODE V MCP

English · Windows · CODE V 10.2 · Python 3.10+ · 实验性 0.1.0

把本机的 CODE V 10.2 接入 MCP 客户端（如 Claude Desktop、Claude Code）。客户端可以用自然语言让它打开镜头、读取和修改参数、运行一阶／点列／MTF／波前分析、导出 CODE V 原生图，并把结果另存。服务通过 Windows COM 驱动一个自己启动的无界面 CODE V 会话，只在本机经 stdio 通信。

除 MCP 工具外，仓库还提供一组独立命令行工具，用于镜头评价与对比、参数扫描、整体缩放、换玻璃、受控 AUT 优化候选、多方案比较和报告素材整理。

能做什么

MCP 工具

每项的参数边界、数值精度与口径见支持能力与限制。

独立命令行工具

均以 python -m codev_mcp.<名称> 运行，复用上面的工具或服务自己的会话，不提供任意命令入口。

命令行工具的引擎工作目录由安装位置决定，请按下面的步骤在仓库根目录做可编辑安装后使用。

Related MCP server: zemax-mcp

怎么保证不弄坏镜头

MCP 客户端 ──stdio──> codev-mcp 服务 ──JSON 行──> 工作进程 ──COM──> 无界面 CODE V 会话

• 工作副本：打开镜头时复制一份再操作，原文件不动；另存拒绝覆盖源文件和已存在的文件。

• 事务式修改：每批修改前建恢复点，修改后逐项回读；任何一项不符（包括 CODE V 静默忽略修改）整批回滚。

• 检查点：每次成功修改都保存、重新载入并比对后才报告成功；引擎中途崩溃时自动重建会话并从最近的检查点恢复。

• 没有任意命令：发给 CODE V 的命令都由服务按类型化参数构造，路径、玻璃名和数值先经过校验。

• 只管自己的进程：只清理确认由本服务启动的 CODE V 进程，不接管你打开的 CODE V 窗口。

• 结果可追溯：每个结果带来源（codev 或 simulated）、单位、分析设置和原生输出；失败返回结构化错误类别。

快速开始

1. 安装

需要 Windows 和 Python 3.10 及以上（推荐 64 位；64 位 Python 可以驱动 32 位的 CODE V COM 服务）。克隆仓库后在根目录执行 PowerShell：

git clone https://github.com/MERURUXD/codev-mcp.git
cd codev-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
.\.venv\Scripts\python.exe -m pip install --no-deps -e .

2. 用模拟后端试运行

不需要 CODE V。下面的脚本经真实 MCP 协议新建一个模拟单透镜、做一阶分析并另存，结果写到 .codev-run/demo/result.json：

.\.venv\Scripts\python.exe examples/simulated_quickstart.py --output .codev-run/demo

输入与输出说明见模拟入门。

3. 接入 MCP 客户端

在客户端的 MCP 配置里加入下面这段，把路径换成你的仓库位置（JSON 里反斜杠要写两次）。没有 CODE V 时把 com 改成 simulated：

{
  "mcpServers": {
    "codev": {
      "command": "D:\\path\\to\\codev-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "codev_mcp", "--backend", "com",
               "--working-directory", "D:\\path\\to\\codev-mcp\\.codev-run"]
    }
  }
}

重启客户端后先调用 get_status，确认后端为 com 且能读到 CODE V 版本。工作目录存放会话、检查点和结果图片，必须可写，建议使用较短的纯英文路径。其他选项（超时、解释器、环境变量）和故障排查见安装说明。

4. 开始使用

可以直接对客户端这样说：

• “打开 D:\lenses\design.len，列出每个面的半径、厚度和玻璃。”

• “把第 3 面的厚度改成 5 mm，再给出 EFL 和后焦距。”

• “画第 2 视场的点列图，并告诉我 RMS 半径。”

• “计算 10、30、50 lp/mm 的 MTF。”

• “导出 CODE V 的光路图（layout）。”

• “另存为 D:\lenses\design-v2.len。”

用设计规格评价一个镜头（命令行）：

.\.venv\Scripts\python.exe -m codev_mcp.compare --lens D:\lenses\design.len --spec docs\design\design-spec-dbgauss.json

示例规格里的阈值只是演示值，实际使用时按自己的指标填写，格式见设计规格。

不支持的内容

• 任意 CODE V 命令或宏；

• 在 MCP 工具里自动优化、做公差或灵敏度分析（AUT 只通过 aut 命令行生成候选，并且需要显式接受）；

• 对任意已有镜头增删表面、改面型或特殊面型（结构编辑只开放给本服务新建的简单球面镜头）；

• 远程访问，或控制用户已经打开的 CODE V 窗口；

• 无焦系统 MTF、几何 MTF；多变焦镜头的原生绘图与波前分析。

完整清单与注意事项（长会话、同步／异步分析、精度、孔径编辑边界等）见支持能力与限制。

文档

开发

自动化测试使用模拟后端和假 COM 会话，不需要 CODE V 或许可证：

$env:PYTHONPATH = Join-Path (Get-Location).Path 'src'
.\.venv\Scripts\python.exe -m unittest discover -s tests -t .

提交约定与架构约束见 CONTRIBUTING.md。问题与建议请提交 Issue。

许可

MIT