EPICS Channel Access

EPICS Channel Access — MCP 服务

让 AI Agent 通过 Channel Access 读取、监控，并在你允许时谨慎写入 EPICS 过程变量（PV）。EPICS 是大多数粒子加速器、同步辐射和中子束线、大型望远镜、聚变实验及许多物理实验室背后的控制系统。本服务使用 caproto，这是一个纯 Python CA 实现，因此无需编译，也无需安装 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 网关
接口	以太网：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"]
    }
  }
}

已授权的写入（示例：束线科学家允许 Agent 只移动样品台和滤光轮，并配置紧急安全状态）：

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	🛑 安全	紧急操作：写入科学家配置的安全状态 PV（--option safe_state，例如电机 STOP 字段、关闭快门、关闭高压），即使其中一项失败，也会写入全部 PV。在只读模式下也可用。它不能替代设施自身的联锁和停止按钮。
get_command_log	👁 读取	返回最近发送给仪器的原始命令及收到的回复（最新的排在最后）。适用于调试和记录已执行的操作。
get_connection_info	👁 读取	报告连接的仪器（身份、地址、模拟或真实）、服务是否为只读，以及当前生效的安全限值。请先调用此工具。
get_pv	👁 读取	读取一个 PV 及其元数据：值、单位、精度、报警严重性／状态、IOC 时间戳和时龄、显示／报警／警告／控制限值以及枚举状态名称。波形数据会经过降采样，并附带最小值／最大值／平均值统计。
get_pvs	👁 读取	一次读取多个 PV（例如束线上的所有电机或真空计）。无法访问的 PV 会列在 errors 中，不会导致整个调用失败。
monitor_pv	👁 读取	订阅一个 PV，并在 duration_s 秒内（或达到 max_updates 时）收集每次值变更，然后返回统计信息（最小值／最大值／平均值／标准差、漂移率）和更新记录。
put_pv	⚠️ 危险	写入一个 PV。此操作可能移动电机、打开快门、更改磁体或高压设定值，以及加热或冷却样品：请先明确告知用户具体会发生哪些变化。只有当 PV 符合写入允许列表、IOC 授予写入权限，且值的类型正确并处于 PV 控制限值（DRVL/DRVH）内时，才会执行写入。返回读回值。
put_pvs	⚠️ 危险	按顺序写入多个 PV（例如同时设置两片狭缝叶片）。每次写入都会先经过验证（允许列表、访问权限、类型、控制限值）；若有任何一项无效，则不会写入任何内容。写入会在首次失败时停止，其余项会报告为未写入。整个批次必须在一小时内完成：预计会在一小时后才开始的写入不会发送。
pv_info	👁 读取	PV 的连接详情：提供服务的 IOC 主机和端口、原生类型、元素数量，以及此客户端是否具有读写权限（EPICS 访问安全机制）并通过写入允许列表检查。
reconnect	🛑 安全	关闭并重新打开与仪器的连接（例如仪器断电重启或重新插接电缆后）。

安全限制

限制	默认值	含义
max_monitor_duration_s	60 s	monitor_pv 采集的最长时长
max_put_batch	10 PVs	一次 put_pvs 调用最多可写入的 PV 数量
max_put_wait_s	60 s	等待一次 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 拒绝写入
类型检查	枚举状态必须是有效名称或索引；整数必须为整数且在范围内；32 位 FLOAT 值必须在可表示范围内；字符串最多 39 个 latin-1 字符；数组元素数量不得超限
PV 名称	不得包含空白字符或引号，记录名称最多 59 个字符（EPICS 3.14+）；其他情况会在发送搜索前拒绝
批量写入	put_pvs 会在发送前验证每项写入；遇到首个失败即停止；一小时预算（在工具超时范围内）用尽后，不再发送任何写入
写入完成	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，……）和 age_s（自 IOC 时间戳以来经过的时间），因此过时的值会一目了然。
• 波形 会通过分块平均降采样至 max_elements，并提供最小值、最大值、平均值和 argmax 统计信息。CHAR 波形也会解码为文本（as_string），这是常见的 EPICS 长字符串约定。写入时，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 中包含逗号，请通过命令行传入，或以 JSON 格式提供 LABMCP_OPTIONS（{"put_allowlist": "BL7:(A|B){1,2}"}），因为 a=1,b=2 格式会按逗号拆分。
• get_command_log 会记录每次写入（caput -c NAME value）及其读回值。

硬件验证

设施 / IOC	EPICS 版本	接口	验证者	日期
暂无：成为首位贡献者