OptiVibe

optivibe-mcp

optivibe-mcp は、Claude Code などのコーディング エージェントが Zemax OpticStudio と連携するためのツールを提供する実験的な MCP サーバーです。

無人の1回の実行：60×対物レンズを10× / NA 0.45のアポクロマートに再設計し、すべての視野点でポリクロマチック・ストレール比 ≥ 0.935を達成しました。設計と測定の方法。

OpticStudioの操作を型付きMCPツールとして公開します。ZOS-APIを通じてエージェントが操作するため、レンズデータの読み込みや編集、解析、最適化、公差解析を実行でき、エージェントが生のAPIコードを書く必要はありません。ツールに加えて、オペランドやガラスの検索、OpticStudioマニュアルの全文検索など、エージェントが照会できるリファレンスレイヤーも備えています。

pip install optivibe-mcp でインストールできます（PyPI）。サーバーは公式の MCP Registry にも io.github.chuang44-tiff/optivibe-mcp として登録されています。インストールを参照してください。

含まれるもの

• ツール（optivibe-mcp、packages/optivibe-harness/ 内）— ZOS-APIを介してOpticStudioを操作する、80種類以上の型付きツールです。各ツールは例外を発生させるのではなく、一貫した結果エンベロープを返すため、エージェントは呼び出しが成功したと仮定せず、読み戻した値を確認できます。球面だけでなく、非球面、座標ブレーク、折り返しミラー、回折格子、屈折率分布型媒体も作成できます。レンズが確定した後は、色収差と像面湾曲の項に影響する要素を表示したり、基準ガラスと比較しながらガラスの交換を試したりできます（ガラスツールを参照）。
• リファレンスレイヤー（optivibe-reference）— エージェントが判断の根拠を得られるよう、オペランドやガラスの検索、マニュアル検索を提供します。エンジンやライセンスは不要で、データはローカルで構築されます（リファレンスデータの構築を参照）。

このプロジェクトにはコードのみが含まれます。ベンダーデータ（ガラスカタログ、マニュアルの本文、オペランドの説明）は含まれません。お使いのライセンス済みOpticStudioのインストール環境から生成してください。

デモ

各デモには、概要、エージェントのステージログ、開始時のレンズ、結果のレンズ、およびそれらを再測定するスクリプトが含まれています。demos/をご覧ください。

エージェントが60×対物レンズを10× / NA 0.45のアポクロマートに無人で再設計 人間が介入しない1回の実行で、4つすべての視野点においてポリクロマティック・ストレール比が0.935以上の10× / NA 0.45対物レンズが生成されました。測定はその後、別のスクリプトで行いました。

ローカルモデルがOptiVibeのスキルとMCP サーバーを使って同じ作業を実行 このタスク向けに調整した概要を与えたところ、ローカルサーバー上のQwen3.8-Flash-Nextは、4つすべての視野点でポリクロマティック・ストレール比0.834以上という同じ目標を達成しました。このページでは、Opusに及ばない点を説明しています。

エージェントが20×ズームを改良するも、昇格ゲートに阻まれる 1回の実行で、ズームの最も悪い位置におけるぼけを半分以下に減らしましたが、歪曲収差の目標には届かず、サーバーは薄いフィルタープレート2枚を超える結果への昇格を拒否しました。保存ファイルを再読み込みしても、主要な数値を再現できました。

エージェントは図面を見られると、より優れたレンズを設計するのでしょうか？ 同じレンズタスクを、各条件でレンズが3本完成するまで人間の介入なしで実行しました。レイアウトレビューを使ったすべての実行で、数値だけを使ったすべての実行より短いレンズが得られました（70～100 mmに対し140～221 mm）。また、視覚情報を使ったすべてのレンズで、4つすべての波長における軸上ストレール比が0.93以上でした。

2種類の顕微鏡対物レンズで、エージェントのガラス選定をOpticStudioのHammerと比較 10× / NA 0.45のアポクロマートでは、エージェントによる2回の実行はいずれもHammerより低いメリット値に達しました（13％と8％低下）。ガラスは14種類中3種類をHammerの10種類に変更し、すべてのレンズがすべての視野で合格しました。20× / NA 0.70の対物レンズでは、Hammerのレンズが最も低いメリット値でしたが、軸上で不合格となりました。エージェントによる2回の実行はいずれも軸上の目標を維持しました。このページでは制限事項を列挙しています。

前提条件

• Windows。 OpticStudioとZOS-API .NETサーフェスはWindows専用です。
• ZOS-APIライセンス付きのZemax OpticStudio。 **2025 R1（25.1.0、Premium）**を対象に開発されています。他のバージョンは未テストです。最初のエンジン起動時にIsValidLicenseForAPIでアクセスが確認されます。
• Python 3.11以上。
• .NET Framework — 自動的に使用されます。ブートストラップがPYTHONNET_RUNTIME=netfxを設定し、環境変数による上書き、レジストリ、またはProgram Filesの検索によってインストールディレクトリを特定します。手動設定は不要です。

インストール

PyPIから

Python 3.11以上の仮想環境で、次を実行します。

pip install optivibe-mcp "optivibe-reference[manual]"
optivibe-build-data --probe
optivibe-doctor

両方のパッケージはPyPIで公開されており、バージョンを揃えて同時にリリースされています。optivibe-mcpとoptivibe-referenceをご利用ください。optivibe-mcpがサーバーで、リファレンスレイヤー（optivibe-reference）も同梱しています。[manual]エクストラ（PyMuPDF）は任意で、OpticStudioのマニュアルPDFを読み込みます（マニュアルのインストールを参照）。optivibe-build-dataは、お使いのOpticStudioインストールからリファレンスデータを構築します。また、--probeはOpticStudioを起動する2つのオペランドプローブも実行するため、ZOS-APIライセンスが必要です。optivibe-doctorはインストール状況を確認します。次に、Claude Codeにサーバーを登録してください。

optivibe-build-dataは、インストールされたパッケージのdata/およびdata/captures/ディレクトリに書き込みます。そのため、optivibe-mcpは仮想環境（またはpip install --user）にインストールし、site-packagesに書き込みできないシステムPythonへのインストールは避けてください。

クローンからのインストール

リポジトリをクローンし、ルートディレクトリから次のコマンドを実行します。

powershell -ExecutionPolicy Bypass -File install.ps1

.venv に仮想環境を作成し、両方のパッケージをインストールして、OpticStudio のインストールから参照データをビルドし、doctor を実行した後、Claude Code にサーバーを登録するコマンドを表示します。OpticStudio のセッションは開きません。オプション：

• -Python <path>：PATH 上の python が古い場合に、環境の構築に使用する Python 3.11 以降を指定します。
• -Probe：2 つのオペランドプローブも実行します。OpticStudio が開き、ZOS-API ライセンスが必要です（参照データのビルドを参照）。
• -Register：claude mcp add コマンドを代わりに実行します。

このスクリプトが実行するのは以下の手順のみです。これらの手順は手動でも実行できます。

手動インストール

packages/optivibe-harness/ から実行します。

pip install -e ../optivibe-reference   # reference layer first
pip install -e .                        # then the harness

ハーネスは参照パッケージをプロセス内で読み込むため、まず参照パッケージをインストールしてください。インストールしないと、参照ツールと検索ツールを利用できません。

[manual] エクストラ（PyMuPDF）は、OpticStudio のマニュアル PDF を読み込みます。マニュアル検索とオペランド／許容差の説明の補完の両方に必要です（ビルド時に PDF から説明文を原文のまま抽出します）。これがない場合、オペランドカタログと許容差カタログは同義語のみでビルドされます（グラウンディングは機能し、各エントリを同義語で検索できますが、マニュアルの説明は含まれません）。説明を完全に補完したビルドを行うには、インストールしてください。

pip install -e "../optivibe-reference[manual]"

conda を使う場合は、パッケージごとに environment.yml（Python 3.11）が用意されています。

次に、インストールを確認します。

python -m optivibe_doctor

インタープリター、2 つのパッケージ、それらの依存関係、参照データ、OpticStudio のインストールディレクトリを確認し、チェックごとに 1 行で結果を表示します。問題がある場合は対処方法も表示します。指定しない限り OpticStudio のセッションは開きません。--engine を指定するとセッションも開いて ZOS-API ライセンスを確認し、--boot を指定すると実際のサーバーを 1 回起動します。新規インストール直後は、参照データをビルドするまで、参照データのチェック結果は WARN になります。警告が 1 つでもある間は終了コードが 1 になります。

Claude Code への登録

claude mcp add optivibe -- /path/to/python -m optivibe_harness

/path/to/python は、インストール先の環境のインタープリターを指す必要があります。別の Python を指定すると、気付かないうちに失敗することがよくあります。次のコマンドで確認できます。

python -c "import sys; print(sys.executable)"

同等の JSON 設定：

{ "command": "/path/to/python", "args": ["-m", "optivibe_harness"] }

PyPI からインストールした場合は、代わりに optivibe-mcp コマンドを登録できます。フルパスを指定してください（環境が有効なときに where optivibe-mcp を実行すると表示されます）。

claude mcp add optivibe -- C:/path/to/venv/Scripts/optivibe-mcp.exe

ガラスツール

オプティマイザーでレンズの最適化が完了した後、ガラスの選定を支援する 2 つのツールを利用できます。explain_glass_swaps は読み取り専用で、色収差項とペッツバール項を担うガラス要素を一覧表示します。trial_glass_swaps は最大 4 組の交換を試し、それぞれを変更しない対照系と並べて再最適化し、測定した画像品質を基準に評価します。実行中は開いているレンズを編集し、最後に元に戻します。substitute_glass は 1 回の交換を行い、その状態を維持します。この手順は design-glass-matching スキルで実行します。

レンズを編集するいずれかのツールが実行される前に Claude Code から確認を求められるようにするには、設定に ask ルールを追加してください（例：.claude/settings.json）。

{
  "permissions": {
    "ask": ["mcp__optivibe__trial_glass_swaps", "mcp__optivibe__substitute_glass"]
  }
}

ask ルールは allow ルールより優先され、bypassPermissions の場合も確認を求めます。ヘッドレス実行（claude -p）または dontAsk モードでは確認する相手がいないため、一致する呼び出しは拒否されます。

リファレンスデータのビルド

リファレンスレイヤーのデータは、お使いのライセンス済みインストールからローカルでビルドされます。ベンダー由来のデータは一切コミットされません。PyPI からインストールした後、optivibe-build-data を実行します（先に以下の 2 つのプローブを実行するには --probe を追加します）。クローンは不要です。クローンから実行する場合は、リポジトリのルートで実行します。

python packages/optivibe-reference/scripts/build_vendor_data.py

これは .agf ファイル（ZEMAX_GLASSCAT）からガラスカタログを読み込み、マニュアル PDF（OPTIVIBE_MANUAL_PDF）を指定した場合は、検索用にインデックスを作成します。

オペランドカタログと公差カタログは、お使いのインストール環境の ZOS-API 列挙型サーフェスをライブプローブしてビルドされます。まず 2 つのプローブを一度だけ実行してください（それぞれ、ヘッドレスの OpticStudio セッションを起動し、オペランド／公差のサーフェスを読み込んでから終了します）。

python packages/optivibe-reference/scripts/probe_operands.py
python packages/optivibe-reference/scripts/probe_tolerances.py

入力が欠けている場合、該当する手順はスキップされます。そのツール（ガラス、マニュアル検索、オペランド／公差の検索）は、型付きの「利用不可」結果を返し、サーバーの残りの機能は引き続き動作します。詳細とデータソース台帳については、PROVENANCE.md を参照してください。

実行方法

起動時に OpticStudio が開かれることはありません。設計にアクセスする最初のツール呼び出しでエンジンが起動し、一度に 1 つの設計を処理します。リファレンスツールと検索ツールは、エンジンを起動せずに動作します。そのため、ライセンスの種類にかかわらず、インストール、登録、リファレンスデータのビルド、すべての検索が成功します。ZOS-API ライセンスの確認は、エンジンを開くときにのみ行われます。

信頼性に関する注意：ツールは結果をエンベロープで返し、失敗時にも例外を発生させません。そのため、呼び出しが完了したことは、意図した処理が行われた証拠にはなりません。エラーが発生しなかったことではなく、返された値またはオプティマイザーの判定を確認してください。

スキル

このリポジトリには、一般的なタスク向けの Claude Code スキルがいくつか含まれています。

スキル	用途
design-review	仕様に照らして設計を評価します
design-compare	設計を並べて比較します
design-vision-review	レンダリングされたレイアウトを観察し、レンズデータからは分からないことを報告します（参考情報）
design-aberration-review	レイファンと像面湾曲／歪曲プロットを読み取り、収差のバランスを報告します（参考情報）
optimize-loop	監視しながら最適化を実行します
design-glass-matching	確定したレンズに適したガラスを選びます。色収差または像面湾曲の項を担う要素を見つけ、基準設計と比較しながら置き換えを試し、全体的な画質が向上した場合にのみ置き換えを採用します
bench-catalog	レンズ設計のフォルダーを、目標仕様または相互に対してベンチマークし、順位付けします
zos-api-debug	OpticStudio の接続エラー／ライセンスエラーをトラブルシューティングします

ステータス

実験段階の初期バージョンとして現状のまま提供されており、未完成な部分があることをご了承ください。単一の OpticStudio バージョン（2025 R1）を Windows 上で使用して開発・検証されています。他のバージョンでの動作は未確認です。インターフェースやツールの対応範囲は変更される可能性があります。

別の OpticStudio バージョンまたはライセンスの種類をお使いですか？ python -m optivibe_doctor --engine の出力を添えて、issue を作成してください。動作する場合もしない場合もお知らせください。お使いのバージョンで動作するという報告も、バグ報告と同じくらい役立ちます。

コントリビューションとお問い合わせ

バグ報告、質問、プルリクエストは、GitHub Issues とプルリクエストから歓迎します。CONTRIBUTING.md をご覧ください。issue や PR には、ベンダー由来のデータ（ガラスカタログ、マニュアルのテキスト、オペランドの説明）を含めないでください。PROVENANCE.md をご覧ください。

ライセンスとデータの由来

optivibe-mcp は Apache License 2.0 のもとでライセンスされています。LICENSE と NOTICE をご覧ください。

これはコードのみで構成され、実行時にお使いのライセンス済み OpticStudio インストールを操作します。ベンダーデータや SDK ファイルは再配布されません。ローカルでビルドするリファレンスデータはローカルに保持されます（gitignore の対象です）。optivibe-mcp は独立したプロジェクトであり、Ansys/Zemax との提携関係はなく、推奨も受けていません。データソースとライセンスの台帳については、PROVENANCE.md をご覧ください。