EPICS Channel Access

EPICS Channel Access — MCP サーバー

AI エージェントが Channel Access 経由で EPICS プロセス変数（PV） を読み取り、監視し、許可された場合は慎重に書き込めるようにします。EPICS は、ほとんどの粒子加速器、シンクロトロンや中性子ビームライン、大型望遠鏡、核融合実験、そして多くの物理学研究室で使われている制御システムです。このサーバーは純粋な Python 実装の CA である caproto を使用するため、コンパイルも libca のインストールも不要です。

⚠️ 施設の制御システムは安全上重要です。 PV への書き込みによって、モーターやサンプルステージの移動、シャッターの開放、磁石や高電圧のランプ、極低温システムや真空システムの変更が起こる可能性があります。施設の規則に従ってください。書き込みを有効にする前に、責任者である科学者または制御室スタッフの許可を得てください。また、書き込みが明示的に許可されていない限り、--read-only を指定して実行してください。 このサーバーはインターロックでも人員保護システムでもなく、それらに取って代わることは決してありません。可能な場合は、アクセスセキュリティ規則が適用されている施設の CA ゲートウェイ経由で接続し、--option put_allowlist= で書き込みを制限してください。

パッケージ	labmcp-epics
機器	Channel Access を提供する任意の EPICS IOC：EPICS Base 3.14–7.x のソフトウェア／ハードウェア IOC、areaDetector、motor、asyn、StreamDevice、caproto/pythonSoftIOC IOC、CA ゲートウェイ
インターフェース	Ethernet：UDP 5064 での CA 検索、TCP 5064 での回路、UDP 5065 でのリピーター
プロトコル	EPICS Channel Access v4.13（プロトコル仕様、ao レコード：DRVH/DRVL、caproto スレッド対応クライアント）
ステータス	🧪 シミュレーション済み：プロセス内の caproto IOC（localhost 経由の実 CA）でテスト済み。施設での検証はまだ行われていません。ハードウェアテストを報告

ハードウェアなしで試す

uvx labmcp-epics --simulate --check

シミュレーターは、プロセス内で実行される本物の Channel Access サーバーです。ランダムな空きポートを使って 127.0.0.1 にバインドされ、クライアントはそのアドレスだけを参照するため（アドレスリストの自動設定はオフ）、ネットワークにブロードキャストせず、ネットワーク上の通信にも応答しません。SIM:TEMP（°C、アラーム限界付き。SIM:HEATER が On の間は SIM:TEMP:SP に追従）、SIM:MTR（移動が完了したときにのみ put コールバックが完了するモーター。SIM:MTR:RBV、:DMOV、:STOP、:VELO を含む）、SIM:DET:FRAMES、SIM:SAMPLE（文字列）、SIM:SPECTRUM（512 点の波形）、SIM:BEAM:CURRENT、SIM:STATUS を提供します。

制御システムに接続する

1. ネットワーク： コンピューターから IOC または施設の CA ゲートウェイに到達できる必要があります。ファイアウォール経由で UDP 5064/5065 および TCP 5064 に接続できるようにしてください。多くの施設では制御ネットワークがゲートウェイの背後にあるため、制御担当グループにアドレスを問い合わせてください。
2. アドレスリスト： Channel Access は UDP 検索によって PV を見つけます。普段使用している EPICS 環境（EPICS_CA_ADDR_LIST、EPICS_CA_AUTO_ADDR_LIST）を使うか、明示的に渡してください。

   uvx labmcp-epics --read-only --address 10.0.1.20 --option check_pv=SR:CURRENT --check   # one IOC / gateway
   uvx labmcp-epics --read-only --option ca_addr_list="gw1.facility.org 10.0.1.21:5064" --option check_pv=BL7:RING:I --check
   uvx labmcp-epics --read-only --option check_pv=BL7:RING:I --check                        # use the environment as-is
   

   アドレスリストを渡すと、--option auto_addr_list=yes を追加しない限り、自動（ブロードキャスト）リストはオフになります。--option check_pv=<a PV you know exists> を指定すると、--check はその PV を読み取って値を出力するか、到達できない理由を表示します。指定しない場合、--check で確認できるのは CA クライアントが起動することだけです。

MCP クライアントに追加する

Claude Code（読み取り専用、推奨）

claude mcp add epics -- uvx labmcp-epics --read-only --address gw1.facility.org

Claude Desktop / Cursor / Windsurf（claude_desktop_config.json、.cursor/mcp.json、…）

{
  "mcpServers": {
    "epics": {
      "command": "uvx",
      "args": ["labmcp-epics", "--read-only", "--address", "gw1.facility.org"]
    }
  }
}

許可された書き込み（例：ビームラインの科学者が、エージェントによるサンプルステージとフィルターホイールのみの移動を許可し、緊急時の安全状態を設定する場合）

uvx labmcp-epics --address 10.0.7.10 \
  --option put_allowlist='BL7:(SAMPLE:(X|Y)|FILTER:POS)' \
  --option require_ctrl_limits=true \
  --option safe_state='BL7:SAMPLE:X.STOP=1;BL7:SAMPLE:Y.STOP=1;BL7:SHUTTER:CMD=Close'

ツール

ツール	種類	説明
apply_safe_state	🛑 safety	緊急操作です。科学者が設定した安全状態の PV（--option safe_state。例：モーターの STOP フィールド、シャッターの閉鎖、高電圧のオフ）を、いずれかの操作が失敗してもすべて書き込みます。読み取り専用モードでも利用できます。施設独自のインターロックや停止ボタンの代わりにはなりません。
get_command_log	👁 read	装置に送信した直近の生コマンドと、装置から受信した応答を返します（新しいものが末尾）。デバッグや実行内容の記録に役立ちます。
get_connection_info	👁 read	接続中の装置（識別情報、アドレス、シミュレーションか実機か）、サーバーが読み取り専用かどうか、現在有効な安全制限を報告します。最初に呼び出してください。
get_pv	👁 read	メタデータとともに、1 つの PV を読み取ります。値、単位、精度、アラームの重大度／状態、IOC のタイムスタンプと経過時間、表示／アラーム／警告／制御の各制限、列挙状態名が含まれます。波形は最小値／最大値／平均値の統計を付けてダウンサンプリングされます。
get_pvs	👁 read	複数の PV を一度に読み取ります（例：ビームラインのすべてのモーターや真空計）。アクセスできない PV は、呼び出し全体を失敗させずに errors に一覧表示されます。
monitor_pv	👁 read	PV をサブスクライブし、duration_s 秒間（または max_updates に達するまで）値の変更をすべて収集してから、統計（最小値／最大値／平均値／標準偏差、ドリフト率）と更新内容を返します。
put_pv	⚠️ hazard	PV に書き込みます。モーターの移動、シャッターの開放、磁石や高電圧の設定値の変更、試料の加熱または冷却が発生する可能性があります。まず、何が変わるのかをユーザーに正確に伝えてください。PV が書き込み許可リストに一致し、IOC が書き込みアクセスを許可し、値の型が適切で PV の制御制限（DRVL/DRVH）の範囲内にない限り、書き込みは拒否されます。書き込み後の読み戻し値を返します。
put_pvs	⚠️ hazard	複数の PV に順番に書き込みます（例：両方のスリットブレードの設定）。各書き込みは事前に検証されます（許可リスト、アクセス権、型、制御制限）。いずれかが無効な場合、何も書き込まれません。最初の失敗時点で書き込みを停止し、残りは未書き込みとして報告されます。バッチ全体は 1 時間以内に完了する必要があります。開始がそれより遅くなる書き込みは送信されません。
pv_info	👁 read	PV の接続詳細を表示します。接続を提供する IOC のホスト：ポート、ネイティブ型、要素数、さらにこのクライアントに読み取り／書き込みアクセス権（EPICS アクセスセキュリティ）があるか、書き込み許可リストを通過するかを確認できます。
reconnect	🛑 safety	装置への接続を閉じて再度開きます（例：装置の電源を入れ直した後や、ケーブルを抜き差しした後）。

安全制限

制限	デフォルト	意味
max_monitor_duration_s	60 s	monitor_pv の収集時間の上限
max_put_batch	10 PVs	1 回の put_pvs 呼び出しで書き込める PV 数の上限
max_put_wait_s	60 s	1 回の put コールバック（完了）を待つ時間の上限

起動時に上書きできます。例：--limit max_put_batch=4。書き込みの主なガードは、数値制限ではなくオプションです。

ガード	方法
読み取り専用モード	--read-only を指定すると、put_pv と put_pvs が完全に非表示になります
許可リスト	--option put_allowlist=<regex>：PV 名がこの正規表現に完全一致した場合にのみ書き込みます。レコードフィールドを除外するパターンを推奨します（BL7:SAMPLE:.* ではなく BL7:SAMPLE:[^.]*）
制限フィールド	制限を設定するフィールド（.DRVH、.DRVL、.HOPR、.LOPR、およびモーターレコードの .HLM、.LLM、.DHLM、.DLLM）への書き込みは拒否されるため、制限を引き上げてから書き込みを通すことはできません。--option allow_limit_field_writes=true を指定すると許可されます
EPICS アクセスセキュリティ	IOC またはゲートウェイがこのクライアントに読み取り専用アクセスを許可している場合、書き込みは事前に拒否されます
制御制限	PV の制御制限を超える数値の書き込みは拒否されます。出力レコードの場合、制御制限は DRVL／DRVH であり、これを超える値は IOC によって暗黙にクリップされます。制限値が NaN の場合、その側には制限がありません
制限未設定	警告付きで許可されます。--option require_ctrl_limits=true を指定すると拒否されます
型チェック	enum の状態は有効な名前またはインデックスである必要があります。整数は整数値かつ範囲内である必要があります。32 ビット FLOAT の値は表現可能な範囲内である必要があります。文字列は latin-1 で最大 39 文字です。配列は要素数の上限内である必要があります
PV 名	空白文字や引用符を含まず、レコード名は最大 59 文字（EPICS 3.14 以降）である必要があります。それ以外は検索を送信する前に拒否されます
バッチ	put_pvs は送信前にすべての書き込みを検証し、最初の失敗で停止します。また、ツールのタイムアウト内に設定された 1 時間の予算を使い切った後は、書き込みを送信しません
書き込み完了	put_pv は IOC の put コールバックを待ちます。タイムアウト時は、IOC が処理を続けている可能性があることと、むやみに繰り返さないよう通知します
安全状態	apply_safe_state（SAFETY。読み取り専用モードでも利用可能）は、科学者が --option safe_state で設定した PV のみを書き込みます

プロンプトの例

• 「蓄積リングの電流はいくつですか？ また、BL7 の真空計にアラームが出ていますか？」
• 「BL7:MONO:ENERGY とその読み戻し値を読み取り、単位と制御制限を教えてください。」
• 「サンプル温度を 30 s 監視し、まだ変動しているか教えてください。」
• 「サンプルステージ X を 12.5 mm に移動し、移動完了後に読み戻し値を確認してください。」
• 「検出器のスペクトル波形を記録し、ピークの位置を教えてください。」
• 「すべて停止してください。安全状態を適用してください。」

補足

• 設定値と読み戻し値： モーターレコードでは、NAME（VAL）が目標値で、NAME.RBV が実際の位置です。put_pv は書き込んだ PV から読み戻した値を返すため、物理的な動作を確認するには読み戻し PV を別途読み取ってください。
• 制御限界値は CA の DBR_CTRL レスポンスから取得します。EPICS の慣例では、下限値と上限値が等しい場合（通常は 0/0）は「未設定」とみなされ、これらの PV は型チェックのみ行われます。
• NaN と無限大： JSON にはこれらの値がありません。NaN または無限大のスカラー値はテキスト "nan"、"inf"、"-inf" として返され、配列要素は null になります。NaN の限界値（EPICS 3.16 以降では未設定のアラーム限界値がこの形式で報告されます）は null になり、波形とモニターの統計ではそのような値を除外して件数を記録します（non_finite、non_finite_updates）。
• アラーム： すべての読み取り値には、重大度（NO_ALARM、MINOR_ALARM、MAJOR_ALARM、INVALID_ALARM）、ステータス（HIHI、LOLO、UDF、COMM、…）、および IOC タイムスタンプからの経過時間を示す age_s が含まれるため、古い値を判別できます。
• 波形は、最大値、最小値、平均値、argmax の統計情報とともに、ブロック平均化によって max_elements までダウンサンプリングされます。CHAR 波形は通常の EPICS ロング文字列の規約に従って、テキスト（as_string）にもデコードされます。書き込み時には、CHAR 波形にテキスト値を指定できます。
• pvAccess： サポートされているのは Channel Access のみです。caproto 1.x が実装しているのは CA のみであり、pvAccess には p4p が必要ですが、これはコンパイル済みの EPICS Base バインディングであり、意図的に依存関係から除外されています。EPICS 7 の IOC はレコードを CA と PVA の両方で提供するため、通常のレコードには対応しています。PVA 専用のデータ（たとえば、areaDetector の PVA プラグインによる NTNDArray 画像や QSRV グループ PV）は読み取れません。
• CA クライアントは、EPICS Base と同様に EPICS_CA_* 環境変数を通じて設定されます。サーバーは --address／--option の値を自身のプロセスに設定し、切断時に元の値に戻します。put_allowlist にカンマが含まれる場合は、コマンドラインで渡すか、LABMCP_OPTIONS に JSON 形式（{"put_allowlist": "BL7:(A|B){1,2}"}）で指定してください。a=1,b=2 形式ではカンマで分割されるためです。
• get_command_log は、すべての書き込み（caput -c NAME value）と、その読み戻し値を記録します。

ハードウェアでの検証

施設／IOC	EPICS バージョン	インターフェース	検証者	日付
まだありません。最初の検証者になる