Ocean Insight Spectrometer

Ocean Insight 光谱仪 — MCP 服务

让 AI Agent 使用 Ocean Insight（Ocean Optics）光谱仪采集光谱、设置或自动调节积分时间、存储暗光谱和参考光谱，并测量吸光度和透射率，同时获取峰位和半峰全宽（FWHM）。该服务通过开源库 python-seabreeze 工作。

软件包	labmcp-ocean-spectrometer
仪器	python-seabreeze 支持的所有型号：USB2000+、USB2000、USB4000、USB650、Flame-S、Flame-NIR/X、HR2000/HR2000+、HR4000、Maya2000/Pro/LSL、QE65000、QE Pro、STS、NIRQuest256/512、Jaz、Torus、Spark、Apex、Ventana、HDX、ADC1000-USB、HR2/4/6、SR2/4/6、ST-VIS（支持列表；部分型号需要特定后端）
接口	USB
协议	python-seabreeze 2.x（文档、源代码），用于实现 Ocean 的 SeaBreeze（OOI / OBP USB 协议）。TEC 详情：Ocean QE Pro 安装和操作手册，MNL-0000
状态	🧪 模拟：已使用基于物理模型的虚拟光谱仪和 seabreeze Spectrometer 接口进行测试，尚未在硬件上验证。报告硬件测试

无需硬件即可试用

uvx labmcp-ocean-spectrometer --simulate --check
uvx labmcp-ocean-spectrometer --simulate --option sim_source=hg-ar --check      # Hg-Ar calibration lamp
uvx labmcp-ocean-spectrometer --simulate --option sim_model=QE-PRO --check      # TE-cooled, 1044 pixels

模拟器模拟 USB2000+（或 QE Pro）观测钨卤素灯、白色 LED 或 Hg-Ar 灯的情况。它包含散粒噪声和读出噪声、暗偏置和暗电流、电暗像素、探测器非线性、饱和，以及更改积分时间后出现的首个过期光谱。在模拟中，“虚拟用户”会在 store_dark_reference 前遮挡光束，在 store_reference 前放入空白样品，并在 measure_absorbance/measure_transmittance 前放入染料样品（520 nm 处有 0.8 AU 的吸光带）。使用真实硬件时，请由实验人员完成这些步骤。

连接光谱仪

1. 驱动程序 / 权限（每台计算机仅需设置一次），请参阅 python-seabreeze 文档：

   uvx --from seabreeze seabreeze_os_setup      # or, inside the environment: seabreeze_os_setup
   

   • **Linux：**此操作会安装 udev 规则（/etc/udev/rules.d/10-oceanoptics.rules，需要 sudo）。之后请重新插拔光谱仪。
   • **Windows：**此操作会安装 USB 驱动程序文件。pyseabreeze 后端还需要 libusb-1.0.dll（请参阅 seabreeze README）。
   • **macOS：**开箱即用。
2. 关闭 OceanView（或任何其他正在使用光谱仪的程序）。一次只能有一个程序打开光谱仪。
3. 测试连接：

   uvx labmcp-ocean-spectrometer --check                        # the only connected spectrometer
   uvx labmcp-ocean-spectrometer --address USB2+H01234 --check  # choose by serial number
   uvx labmcp-ocean-spectrometer --option backend=pyseabreeze --check
   

   --address 是光谱仪的序列号，仅在连接了多台光谱仪时需要（list_spectrometers 会列出它们）。默认后端为 cseabreeze（已编译的 libseabreeze）；如果无法加载，seabreeze 会回退到纯 Python pyseabreeze（pyusb）。

连接后，服务会将积分时间设为 10 ms（--option integration_ms=…），并将其限制在设备范围内。必须设置该值，因为 seabreeze 无法读取积分时间。

添加到 MCP 客户端

Claude Code

claude mcp add spectrometer -- uvx labmcp-ocean-spectrometer

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

{
  "mcpServers": {
    "spectrometer": {
      "command": "uvx",
      "args": ["labmcp-ocean-spectrometer", "--address", "USB2+H01234"]
    }
  }
}

添加 --read-only，即可使用当前设置进行采集和吸光度测量，同时禁止更改积分时间、存储参考光谱以及控制 TEC。对于其他客户端，请使用 uvx labmcp config ocean-spectrometer --client vscode 生成配置片段（也支持 cursor、codex、claude-code）。

工具

工具	类型	描述
acquire_spectrum	👁 读取	获取强度光谱（原始计数），可选择平均、箱形平滑和校正。返回降采样后的（波长、计数）、摘要统计数据、最显著峰及其 FWHM，以及饱和检查结果；save_path 会将完整光谱写入新的 .csv 文件（不会覆盖现有文件）。
auto_integration_time	🎛 控制	调整积分时间，直到最亮的原始像素（可选限定在某个波长范围内）处于目标饱和度区间（默认 70-85 %）。积分时间不会超出设备限制和安全上限 max_integration_time_ms。之后请重新采集暗光谱/参考光谱。
detector_cooling_off	🛑 安全	关闭探测器热电制冷器（探测器会升至环境温度）。不适用于没有 TEC 的光谱仪。
find_peaks	👁 读取	在最新的光谱（强度、吸光度或透射率）中查找峰（或谷），并返回其位置、高度、突出度和 FWHM。如果尚未采集光谱，则会采集新的强度光谱。
get_command_log	👁 读取	返回最近发送给仪器的原始命令及收到的回复（最新记录排在最后）。可用于调试和记录操作。
get_connection_info	👁 读取	报告当前连接的仪器（标识、地址、模拟或真实）、服务是否为只读，以及当前生效的安全限制。请先调用此工具。
get_device_info	👁 读取	型号、序列号、像素数、波长范围、积分时间限制、饱和水平、支持的校正、是否配备 TEC，以及已存储的暗光谱/参考光谱。
list_spectrometers	👁 读取	列出 seabreeze 可检测到的 Ocean 光谱仪（型号、序列号、是否已打开），以及此服务连接的光谱仪。使用序列号作为 --address 来选择设备。
measure_absorbance	👁 读取	使用已存储的暗光谱 D 和参考光谱 R（设置相同），测量当前置于光路中的样品的吸光度光谱 A = -log10((S - D) / (R - D))。请先让用户放入样品。还会返回 wavelengths_nm 处的值和吸光度最大值。
measure_transmittance	👁 读取	使用已存储的暗光谱和参考光谱，测量当前置于光路中的样品的透射率光谱 %T = 100 (S - D) / (R - D)。请先让用户放入样品。还会返回 wavelengths_nm 处的值和透射率最低谷。
read_detector_temperature	👁 读取	读取探测器的温度，适用于带热电制冷器的型号（例如 QE Pro，且 seabreeze 为其公开了 thermo_electric 功能）。
reconnect	🛑 安全	关闭并重新打开与仪器的连接（例如设备断电重启或重新插接线缆后）。
set_detector_cooling	⚠️ 危险	在 setpoint_c 设定值下启用探测器热电制冷器（仅限带热电制冷的型号）。探测器需要数分钟才能达到稳定状态；冷却后暗电流（和噪声）会降低。TEC 只能冷却至比环境温度低约 15-40 °C 的温度（QE Pro 手册）。会检查是否低于 min_tec_setpoint_c。
set_integration_time	🎛 控制	设置探测器积分时间（ms），并确保处于 get_device_info 返回的设备限制范围内。更改积分时间后，已存储的暗光谱/参考光谱将失效，直到重新采集。
store_dark_reference	🎛 控制	采集并在内存中存储暗光谱，用于吸光度/透射率测量。调用前，请让用户遮挡光路（关闭快门、关闭光源或盖住光纤），并等待确认。使用当前积分时间。
store_reference	🎛 控制	在内存中采集并存储参考光谱（100 % 透射率）。调用前，请让用户在光源开启时将空白样品（装有溶剂的比色皿或空比色皿）放入光路，并等待确认。设置须与暗光谱相同。
get_connection_info、get_command_log 和 reconnect 内置于每个 LabMCP 服务中。

安全限制

限制	默认值	含义
max_integration_time_ms	10000 ms	Agent 可设置的最长积分时间（也会限制 auto_integration_time）
max_acquisition_duration_s	300 s	单次采集的最长时间（扫描次数 × 积分时间）
min_tec_setpoint_c	−20 °C	TEC 设定温度的最低值（适用于 TE 制冷型号）。QE Pro 的温度读数已针对 −20…40 °C 范围进行线性化

启动时覆盖：--limit max_integration_time_ms=60000。无论限制值如何，单次采集（扫描次数 × 积分时间，加上积分时间变更后丢弃的光谱）都必须在 540 s 内完成，这是单次工具调用允许的时长；auto_integration_time 也会基于同一原因提前停止，并说明原因。

示例提示词

• “自动调整灯的积分时间，然后采集一张 20 次扫描平均光谱，告诉我峰值的位置和宽度。”
• “我要测量一组 Beer–Lambert 系列。请引导我完成暗场、空白样品和我的五个标准样品，并报告每个样品在 520 nm 处的吸光度。”
• “这是 Hg-Ar 灯。找出 400 至 600 nm 之间的谱线，并告诉我它们与 404.66、435.83 和 546.07 nm 的差值。”
• “测量这个滤光片在 400 至 700 nm 范围内的透射率，并将其保存到 ~/data/filter_T.csv。”
• “将 QE Pro 冷却到 −10 °C，并告诉我探测器温度何时稳定下来。”

注意事项

• 原始计数。 强度是探测器计数，并非辐照度。辐射定标不在本项目范围内。
• 饱和。 根据每次平均扫描的原始 ADC 计数判断饱和：像素计数达到 max_intensity 的 98 % 或以上即为饱和。饱和像素会被标记，并从吸光度／透射率计算中排除（应用 boxcar 平滑时，其 boxcar 半宽范围内的像素也会被排除）。seabreeze 指出，某些探测器会在低于 max_intensity 时饱和，因此请将峰值保持在 70–85 %。
• 校正。 correct_dark_counts 会减去光学遮蔽电暗像素的平均值；correct_nonlinearity 会应用 EEPROM 多项式。驱动程序读取原始光谱，并使用与 seabreeze.spectrometers.Spectrometer.intensities 相同的公式应用这两项校正，因此仍可根据原始数据检测饱和。吸光度计算仍需要已存储的暗参考（store_dark_reference），因为电暗校正不会消除固定模式暗信号。
• 吸光度。 A = −log10((S − D)/(R − D))。参考信号高于暗信号的峰值低于 0.5 % 的像素，以及参考光谱或样品光谱中饱和的像素，都会返回 null。暗光谱、参考光谱和样品光谱必须使用相同的积分时间、boxcar 和校正设置；服务端会对此进行强制检查，并在设置不同时要求重新采集参考光谱。
• 更改积分时间后的首张光谱会被丢弃。 这张光谱可能部分使用旧设置完成积分；QE Pro 手册指出，它会返回最近一张已完成的光谱。
• Boxcar。 遵循 OceanView 的惯例：boxcar_half_width 表示每侧参与平均的像素数。峰值会在全分辨率光谱上查找。返回的曲线会按箱平均降采样至 max_points。
• TEC 工具使用 seabreeze 的 thermo_electric 功能（enable_tec、set_temperature_setpoint_degrees_celsius、read_temperature_degrees_celsius），仅当后端为你的型号提供该功能时才可使用。在 pyseabreeze 2.11 中，该功能仅适用于 NIRQuest512。QE Pro 是否支持取决于 libseabreeze（cseabreeze）；尚未在硬件上验证。QE Pro 手册指出，TEC 的制冷温度仅比环境温度低约 15–40 °C。
• 未提供的功能： 快门和灯（light_source/strobe_lamp）控制、触发模式和辐照度定标。seabreeze 对这些功能有相关说明，但未明确设备支持情况，且 pyseabreeze 尚未实现其中若干功能，因此无法验证。
• 无效像素旁的峰值。 无效（null）像素会被视为未知值：其相邻像素不会被报告为峰值，峰显著度和半峰全宽（FWHM）也不会跨越这些像素。如果无效像素位于请求的范围内（例如无法测量的过强波段中心），吸光度／透射率结果会附带警告。
• 暗光谱和参考光谱存储在服务端内存中，在 reconnect 或重启后会丢失。使用 save_path 保存数据：路径必须以 .csv 结尾；缺失的文件夹会自动创建；已有文件绝不会被覆盖（请另选文件名）。该路径会在采集光谱前检查。

硬件验证

型号	固件	接口	验证者	日期
暂无： 率先提交