Thermo Orbitrap (Instrument API)

Thermo Orbitrap（仪器 API）：MCP 服务

让 AI Agent 实时监控并操控 Thermo Fisher Orbitrap 质谱仪：检查仪器模式和真空状态，读取仪器持续输出的扫描数据（按 MS 阶数筛选，并显示强度最高的质心），提交经过验证的自定义扫描并获取其结果，设置重复扫描，以及启动、暂停或停止采集并写入 raw 文件。它通过 Thermo 自有的 Instrument API (IAPI) 完成这些操作。

重要

这是一个适配器，不包含任何 Thermo 软件。 IAPI 是 Windows .NET API。要使用它，你需要与 Thermo Fisher Scientific 签署正式的 IAPI 软件许可协议，并将许可应用于你的仪器（法律要求、许可常见问题、如何获取许可）。此软件包绝不会捆绑或下载 IAPI 程序集：你需要指定自己获取的程序集。**它从未在真实硬件上经过测试。**以下所有内容均基于官方 IAPI 接口定义、示例和模拟器开发。

软件包	labmcp-thermo-iapi（在仪器 PC 上安装 [windows] 附加项以使用 pythonnet）
仪器	Orbitrap Tribrid（Fusion、Fusion Lumos、Eclipse、Ascend）、Orbitrap Exploris 240/480、Q Exactive 系列。不包括 Orbitrap Astral：Thermo 表示 Astral 系列不支持 IAPI（截至 2025 年秋季）。不包括 Exploris 120：Thermo 的示例称其不支持该 API。
接口	Windows 仪器 PC 上的 .NET API（通过 pythonnet）
协议	Thermo Fisher Instrument API (IAPI)：接口定义位于 lib/*.xml，示例位于 examples/
状态	🧪 模拟：已针对模拟 Orbitrap（FakeOrbitrap）测试，尚未在硬件上验证。报告硬件测试结果

无需硬件即可试用

uvx labmcp-thermo-iapi --simulate --check

默认情况下，模拟器使用 Orbitrap Exploris 480（其他型号使用 --option sim_model=eclipse 或 qexactive-hf）。它会运行一个合成胰蛋白酶解消化物：On 模式下的 MS1 全扫描、采集期间的数据依赖型 top-10 方法、会返回其访问 ID 的自定义扫描和重复扫描、逼真的瞬态时间和注入时间，以及每隔约 5 秒记录真空读数的状态日志。

连接仪器

在Windows 仪器 PC 上，安装好 Tune 并应用 IAPI 许可证后：

1. 获取许可证附带的 IAPI 程序集（对于 Tribrid：Tune 4.3 使用 API-2.0.dll、Spectrum-1.0.dll、Thermo.TNG.Factory.dll 和 Fusion.API-2.0.dll；Tune 4.2 及更早版本使用 Fusion.API-1.0.dll）。将它们放在一个文件夹中，例如 C:\IAPI。
2. 安装 Python 3.10+ 和使用 pythonnet 的服务：

   pip install "labmcp-thermo-iapi[windows]"
   

3. 测试连接（仪器系列会根据 IAPI 示例选择连接方案）：

   labmcp-thermo-iapi --option instrument=tribrid  --option assembly_dir=C:\IAPI --check   # Fusion/Lumos/Eclipse/Ascend
   labmcp-thermo-iapi --option instrument=exploris --option assembly_dir=C:\IAPI --check   # Exploris 240/480
   labmcp-thermo-iapi --option instrument=exactive --option assembly_dir=C:\IAPI --check   # Q Exactive family
   

系列	服务的连接方式（来自 IAPI 仓库）	assembly_dir 中预期的程序集
tribrid	Factory<IFusionInstrumentAccessContainer>.Create()、StartOnlineAccess()、Get(1)	API-2.0.dll、Spectrum-1.0.dll、Thermo.TNG.Factory.dll、Fusion.API-2.0.dll 或 Fusion.API-1.0.dll
exploris	HKLM\SOFTWARE\Thermo Exploris → DataSystem.xml（ApiFileName、ApiClassName）	Thermo.API.NetStd-1.0.dll、Thermo.API.Exploris.NetStd-1.0.dll、Thermo.API.Spectrum.NetStd-1.0.dll（4.3+）或 Thermo.API-2.0 / Thermo.API.Exploris-1.0 / Thermo.API.Spectrum-1.x 套件
exactive	HKLM\SOFTWARE\Finnigan\Xcalibur\Devices\Thermo Exactive（ApiFileName_Clr2_32_V1、ApiClassName_Clr2_32_V1）	API-2.0.dll（或 1.x）、Spectrum-1.0.dll、ESAPI-1.1.dll（或 1.0）

如果服务未在 Windows 上运行、缺少 pythonnet、文件夹或程序集缺失、IAPI 服务未能连接（Tune 未运行），或 IAPI 因缺少许可证而拒绝命令，服务会显示相应的提示信息。

其他选项：readbacks=Name1;Name2（要在 get_instrument_status 中显示的仪器值；该工具会列出仪器提供的名称）、exclusive_scans=true（独占而非协作式访问 IScans）、runtime=coreclr、connect_timeout_s、buffer_size（内存中保留的扫描数，默认 500）。

添加到 MCP 客户端

claude mcp add orbitrap -- labmcp-thermo-iapi --option instrument=tribrid --option assembly_dir=C:\IAPI

{
  "mcpServers": {
    "orbitrap": {
      "command": "labmcp-thermo-iapi",
      "args": ["--option", "instrument=exploris", "--option", "assembly_dir=C:\\IAPI"]
    }
  }
}

添加 --read-only，让 Agent 可以查看扫描和状态，但不能提交扫描或启动采集。停止和取消工具仍可用。若要从另一台计算机访问服务，请在仪器 PC 上使用 --transport http --host 0.0.0.0 --port 8000 运行服务，并保护该端口。

工具

工具	类型	描述
cancel_custom_scans	🛑 safety	取消所有待处理的自定义扫描及其处理延迟（IAPI CancelCustomScan）。
cancel_repeating_scan	🛑 safety	取消通过 set_repeating_scan 设置的重复扫描（IAPI CancelRepetition）。
get_command_log	👁 read	返回最近发送到仪器的原始命令及收到的回复（最新的排在最后）。适用于调试和记录操作。
get_connection_info	👁 read	报告连接的仪器（身份、地址、模拟或真实）、服务是否为只读，以及当前生效的安全限制。请先调用此工具。
get_instrument_status	👁 read	报告仪器型号、IAPI 服务/仪器连接、系统模式和状态（On/Standby/Off；Running/ReadyToDownload/...）、采集是否可以暂停或恢复、IAPI 是否提供许可证信息、请求的读回值、最新扫描状态日志（真空、离子源），以及已到达的扫描数量。
get_possible_scan_parameters	👁 read	列出此仪器接受的自定义扫描和重复扫描参数（IScans.PossibleParameters）：名称、允许的范围或选项、默认值和帮助信息。参数集合取决于型号、许可证和 Tune 版本。
get_recent_scans	👁 read	返回从仪器收到的最近扫描（按时间从早到晚），可选择仅返回一个 MS 阶数或一个自定义扫描的访问 ID：扫描编号、MS 阶数、前体 m/z、AGC 目标值、注入时间和强度最高的质心。只有在 On 模式下才会收到扫描。
pause_acquisition	🛑 safety	暂停正在运行的采集（IAPI Pause）。如果仪器报告无法暂停，则调用失败。
reconnect	🛑 safety	关闭并重新打开与仪器的连接（例如，仪器断电重启或重新插拔线缆后）。
resume_acquisition	⚠️ hazard	恢复已暂停的采集（IAPI Resume）。样品消耗将继续。
set_repeating_scan	⚠️ hazard	定义或替换在没有方法或自定义扫描运行时由仪器重复执行的扫描（IAPI CreateRepeatingScan/SetRepetitionScan）。参数值的验证方式与 submit_custom_scan 相同。使用 cancel_repeating_scan 取消。
start_acquisition	⚠️ hazard	使用仪器当前设置开始采集（IAPI StartAcquisition），并将数据记录到原始文件。此操作会消耗样品。仪器必须处于 On 状态，且不得已有采集在运行。使用 stop_acquisition 停止采集。达到 max_acquisition_duration_s 后，scan_count 和 until_stopped 采集会自动取消。
stop_acquisition	🛑 safety	停止正在运行的采集（IAPI CancelAcquisition），默认也会取消自定义扫描和重复扫描，并可选择将仪器切换到 Standby（在 Tune 中切回 On）。即使前一步失败，也会尝试执行每一步；失败情况会报告出来。
submit_custom_scan	⚠️ hazard	放置一次待运行的自定义扫描（IAPI CreateCustomScan/SetCustomScan）；未设置的值将使用仪器默认值。发送任何内容之前，会根据 PossibleParameters 和安全限制检查每个值，并限制调用频率。使用 wait_for_scan(access_id=running_number) 获取结果。
wait_for_scan	👁 read	等待本次调用后到达的下一次扫描（可选择指定一个 MS 阶数，或通过访问 ID 获取某个自定义扫描的结果），并返回该扫描。对于通过 submit_custom_scan 放置的自定义扫描，如果放置后已有结果到达，则会立即返回。如果在 timeout_s 后仍未收到匹配的扫描（例如仪器处于 Standby），则返回 found=false。

get_connection_info、get_command_log 和 reconnect 内置于每个 LabMCP 服务中。每次 IAPI 控制调用（包括发送的确切扫描值）都会记录在命令日志中。

安全限制

限制	默认值	含义
max_custom_scans_per_minute	60 scans/min	Agent 可在任意 60 s 时间窗口内安排的自定义扫描次数（服务端速率限制；reconnect 不会重置此限制）
max_injection_time_ms	1000 ms	自定义扫描或重复扫描中的最大注入时间上限（MaxIT，多值 MaxIT 中的每个元素都受此限制）
max_acquisition_duration_s	7200 s	Agent 可启动的最长采集时长：超过此时长的 duration 会被拒绝；达到此时长后，scan_count / until_stopped 采集会自动取消（按墙上时钟计算，包含暂停时间）

启动时覆盖：--limit max_custom_scans_per_minute=600。

除这些限制外，发送任何内容之前，系统都会根据仪器自身的 IScans.PossibleParameters 检查每个自定义扫描值和重复扫描值：参数名称必须存在，数值必须在仪器的取值范围内（例如 FirstMass/LastMass 的 m/z 范围），而 OrbitrapResolution 等选项参数必须是允许的值。IAPI 本身会静默忽略非法值，因此服务会先进行检查，并且会使用仪器自身的拼写形式发送接受的值（hcd 会以 HCD 发送，整数参数的 2.0 会以 2 发送）。

stop_acquisition 会尝试执行每个步骤（取消采集、自定义扫描、重复扫描、Standby），即使某个步骤失败也会继续，并报告失败的步骤。

示例提示词

• “Orbitrap 是否处于 On 模式？真空读数是多少？过去一分钟内收到了多少次扫描？”
• “显示最近 5 次 MS2 扫描及其前体 m/z、注入时间和前 10 个碎片。”
• “在 m/z 524.26 处安排一次 120k SIM 扫描，窗口为 10 m/z，并告诉我你看到的最强峰。”
• “启动一次 30 分钟的采集，将数据保存到 D:\Data\HeLa_test.raw，样品名称为 HeLa 200 ng，然后每隔几分钟检查一次是否仍有 MS2 扫描到达。”

说明

• 仪器模式： 只有处于 On 模式时才会收到扫描数据，自定义扫描和采集也需要此模式。stop_acquisition(standby=true) 会切换到 Standby。此服务没有可切回 On 的工具（请在 Tune 中操作）。
• 自定义扫描： 未指定的值会采用仪器默认值，正如 Thermo 对 IScanDefinition.Values 的说明。running_number 会以扫描的 access_id 返回（尾部项目 Access Id:）。如果你未指定扫描编号，服务会自动编号。自定义扫描通常会在 Agent 发起下一次工具调用前完成，因此 wait_for_scan(access_id=...) 也会返回在放置扫描后、开始等待前到达的结果。若在仪器处理完之前一项自定义扫描前放置多项自定义扫描，IAPI 不保证结果；速率限制会对此加以控制。
• 参数名称因型号和 Tune 版本而异（例如 Tribrid 上的 Analyzer）。请使用 get_possible_scan_parameters，并将没有对应命名参数的内容传入 extra_parameters。
• 扫描标头： scan_number、ms_order、scan_mode 和 precursor_mz 来自 Thermo 示例中使用的标头键（Scan、MSOrder、ScanMode、PrecursorMass[0]）。master_scan_number、agc_target 和 injection_time_ms 取自 Thermo RAW 文件使用的尾部名称（Master Scan Number:、AGC Target:、Ion Injection Time (ms):）。IAPI 仓库未对此进行说明，因此这些值在你的仪器上可能为 null。使用 include_header_trailer=true 可查看它发送的确切内容。
• 读回值： IAPI 没有固定的读回值名称列表（真空计、电压）。get_instrument_status 会显示 IInstrumentValues.ValueNames 中的名称，以及最新扫描的 StatusLog；真空读数通常会出现在其中。
• 许可证检查： 在 Exploris 仪器上，服务会报告是否存在 API 许可证（IExplorisInstrumentAccess.Licenses）。Tribrid 和 Exactive 仪器会在仪器服务中强制执行许可证要求；命令被拒绝时会报告相关信息。
• 已验证的 API 接口： pythonnet 后端调用的每个 IAPI 成员及其源文件都列在 iapi_members.py 中（已对照 thermofisherlsms/iapi@c246dcc 检查）。如果后端使用的名称不在该列表中，测试会失败。
• 扫描数据： 每个扫描的 .NET 对象都会立即复制并释放，正如 Thermo 的示例所要求的那样（否则仪器的共享内存会一直被占用）。每次扫描最多保留 5 000 个质心。max_centroids 限制工具返回的内容，而 get_recent_scans(save_path=...) 会将所有保留的质心写入新的 CSV 文件（路径必须以 .csv 结尾，且文件必须尚不存在：绝不会覆盖现有文件）。

硬件验证

型号	固件	接口	验证者	日期
尚无： 抢先验证