LC-MS Worklist Builder

LC-MS 工作列表构建器（MassLynx、SCIEX OS、MassHunter、Xcalibur）：MCP 服务

让 AI Agent 构建 LC-MS 样品队列（工作列表、序列、批次），并将其导出为 Waters MassLynx、SCIEX OS、Agilent MassHunter Acquisition 和 Thermo Xcalibur 的导入文件。Agent 可以在样品盘上排列样品、插入空白样品和 QC、使用有记录的种子随机排列运行顺序、检查列表中的错误、将现有文件从一种供应商格式转换为另一种，并写入文件供人员导入。它仅使用有文档记录的导入格式。它绝不会启动采集，也不会与质谱仪通信。

软件包	labmcp-ms-worklist
软件	Waters MassLynx 4.x、SCIEX OS、Agilent MassHunter Acquisition（LC/TQ、LC/Q-TOF）、Thermo Xcalibur 2.2+
接口	文件（将 CSV/TXT 导入文件写入一个输出文件夹）
协议	供应商样品列表导入格式（来源请参阅格式）
状态	🧪 模拟：已通过黄金文件和往返测试验证，但我们尚未将其导入供应商软件。报告测试

无需仪器即可试用

uvx labmcp-ms-worklist --simulate --check

--simulate 使用一个临时输出文件夹，服务器停止时该文件夹会被删除。其他部分使用的代码完全相同。

设置

“仪器地址”是写入工作列表文件的输出文件夹（默认为 ./worklists，若不存在则会创建）：

uvx labmcp-ms-worklist --address "D:\Worklists" --check        # Windows acquisition PC or a shared drive
uvx labmcp-ms-worklist --address ~/lcms/worklists --check        # macOS / Linux, then copy the files over

• 服务器只会在此文件夹内读取和写入文件。它会拒绝 ..、指向其他位置的绝对路径，以及指向此文件夹之外的符号链接。除非 Agent 传入 overwrite=true，否则绝不会覆盖现有文件。
• 若要编辑或转换现有文件，或使用供应商模板，请先将文件复制到此文件夹中。
• 只有在供应商针对你的设置记录了此行为时，才将 --address 指向采集软件监视的文件夹。否则，请手动导入文件（参阅下方说明）。

添加到 MCP 客户端

Claude Code

claude mcp add ms-worklist -- uvx labmcp-ms-worklist --address ~/lcms/worklists

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "ms-worklist": { "command": "uvx", "args": ["labmcp-ms-worklist", "--address", "/path/to/worklists"] }
  }
}

--read-only 仅保留用于检查内容的工具（list_formats、validate_worklist、import_worklist、get_worklist、list_worklists）。

工具

工具	类型	描述
add_samples	🎛 控制	将样本追加到草稿工作列表中（工作列表的默认设置和自动位置设置会生效；任何空白样本/QC/随机化计划都会使用相同的种子重新应用到更长的列表上）。
create_worklist	🎛 控制	根据样本列表和默认设置（方法、进样量、样品盘位置、数据文件命名模式）创建内存中的草稿工作列表。只有在执行 export_worklist 后才会写入磁盘。超过 max_injection_volume_ul 限值的进样量将被拒绝。
export_worklist	🎛 控制	验证草稿，并将供应商导入文件写入输出文件夹。返回文件路径、前几行的预览、警告和导入说明。如果验证发现错误，或文件已存在（除非 overwrite=true），则拒绝导出。此操作不会启动采集：需要由人员将文件导入采集软件。
get_command_log	👁 读取	返回最近发送给仪器的原始命令及收到的回复（最新记录在最后）。适用于调试和记录操作内容。
get_connection_info	👁 读取	报告已连接的仪器（标识、地址、模拟或真实）、服务是否为只读，以及当前生效的安全限值。请先调用此工具。
get_worklist	👁 读取	按运行顺序显示草稿工作列表，以及其默认设置、空白样本/QC 计划、随机化种子和已应用操作的历史记录。
import_worklist	👁 读取	将输出文件夹中现有的 MassLynx、SCIEX OS、MassHunter 或 Xcalibur 导入文件解析为草稿，以便验证、编辑或导出为其他供应商的格式。没有中性对应项的列将按原样保留。仅读取；不会写入任何内容。
insert_qc_blanks	🎛 控制	插入空白样本和 QC 进样，并可选择随机排列运行顺序（记录所用种子）。此操作会替换任何先前的计划，因此重复调用不会导致空白样本重复插入。添加样本时会重新应用该计划；数据文件名会遵循新的运行顺序。
list_formats	👁 读取	列出支持的导入格式（Waters MassLynx、SCIEX OS、Agilent MassHunter、Thermo Xcalibur）：列、必填字段、样本类型名称、文件扩展名、导入方式、根据供应商文档验证的内容与假设内容，以及来源 URL。还会列出位置模式，以及已研究但未实现的格式。
list_worklists	👁 读取	列出内存中的草稿工作列表和输出文件夹中的文件。
reconnect	🛑 安全	关闭并重新打开与仪器的连接（例如，仪器断电重启或重新插拔电缆后）。
validate_worklist	👁 读取	根据目标格式检查草稿：必填字段、重复的数据文件名、Windows 文件名不允许使用的字符、样品盘/样品瓶位置格式和孔板边界、进样量（> 0 且 <= max_injection_volume_ul 限值）以及方法文件扩展名。错误会阻止导出；警告不会。

get_connection_info、get_command_log 和 reconnect 是每个 LabMCP 服务内置的。没有 HAZARD 工具：此处的任何工具都不会移动、加热、进样或采集。该服务只会写入文件。CONTROL 工具会更改内存中的草稿或写入文件，而 --read-only 会隐藏这些工具。

典型流程：create_worklist → add_samples（可选）→ insert_qc_blanks → validate_worklist → export_worklist，然后在供应商软件中导入该文件。

格式

下表区分供应商文档所述内容（已验证）与服务的假设。list_formats 会向 Agent 返回相同的信息。若要确认软件版本对应的表头，请从自己的系统中导出一个空批次、序列或工作列表，将其放入输出文件夹，并将其作为 template_path 传递给 export_worklist。随后，服务会原样写入该表头和分隔符。

Waters MassLynx：样品列表工作表（waters_masslynx）

• 导入： Sample list > File > Import Worksheet，文件类型选择 "Comma Delimited (*.CSV, *.TXT)"。
• 已验证：
  • 第 1 行包含区分大小写的 MassLynx FIELD ID。列可以按任意顺序排列，系统会添加一个 Index 列。来源：WKB63781。
  • 必需列为 FILE_NAME、INLET_FILE、MS_FILE、SAMPLE_LOCATION 和 INJ_VOL。来源：MassLynx 4.2 入门指南 715009602，表 5-1。“Bottle”列的 FIELD ID 是 SAMPLE_LOCATION，而不是 BOTTLE。
  • WKB63781 附带的示例文件使用 CRLF 换行符和未加引号的字段，TYPE 值为 Blank/Standard/QC/Analyte，方法名称不带扩展名。
• 映射： FILE_NAME = 数据文件、FILE_TEXT = 样品名称、MS_FILE、MS_TUNE_FILE、INLET_FILE、SAMPLE_LOCATION、TYPE、ID、INJ_VOL、Index。每个样品还可以通过 extra 添加其他任意 FIELD ID（例如 CONC_A 或 QUAN_REF）。
• 假设：
  • solvent 和 double_blank 会写为 Blank。
  • 扩展名检查：MS_FILE 使用 .exp，调谐文件使用 .ipr；仅当提供扩展名时才检查。
  • 文件为 UTF-8 编码且不带 BOM。非 ASCII 文本会被标记。
  • waters_plate_well 位置模式（1:A,1）是一种常见约定。其中的逗号会使用 CSV 引号括起。

SCIEX OS：批次导入（sciex_os）

• 导入： Batch workspace > Open > Import from file，然后选择 Save As。
• 已验证：
  • 批次可从 .txt 或 .csv 文件导入，列布局必须来自 SCIEX OS 导出的批次。来源：SCIEX 知识库。
  • 列名包括 Sample Name（< 252 个字符）、MS Method、Sample Type、Data File 和 Processing Method。来源：SCIEX OS 功能指南 RUO-IDV-05-15796-C，表 4-1。
  • 还包括 Rack Type、Rack Position、Plate Type、Plate Position 和 Vial Position 列。来源：SCIEX 知识库。
  • 样品类型包括 Unknown、Blank、Standard、QualityControl、Solvent 和 Double blank。
  • 多个样品可以共用一个数据文件。
• 假设：
  • **SCIEX 未公开导出批次的确切表头文本。**默认表头（Sample Name,Sample ID,Sample Type,MS Method,LC Method,Rack Type,Rack Position,Plate Type,Plate Position,Vial Position,Injection Volume,Data File,Processing Method,Comment）是根据经验推测的。请使用 template_path 指定自己的导出文件。未使用模板时，validate_worklist 和 export_worklist 会发出警告。
  • 扩展名 .msm、.lcm 和 .qmethod 仅会触发警告。
  • Rack 和 plate 列通过 vendor_columns 设置，或通过每个样品的 extra 设置。

Agilent MassHunter 采集：导入工作列表 CSV（agilent_masshunter）

• 导入：“工作列表”中右键单击 >“从……添加/追加样品（csv、xlsx）”。旧版本中此选项称为“导入工作列表……”。无需映射文件，因为标题与工作列表列名相符。
• 已验证：
  • 标题 Sample Name,Barcode,Rack Code,Sample Position,Method,Data File,Sample Type,Level Name,Inj Vol (µL),Comment、类似 P1-A1 的位置，以及 Calibration 和 Sample 类型，均来自 D:\MassHunter\Worklist_Import 中随附的示例文件，Agilent 社区对此有引用：Agilent Community。
  • 文件包含 µ 时，请另存为 UTF-8。来源：Agilent Community。
  • Inj Vol = -1 表示“按方法设置”。来源：Agilent Known Problem Report。
  • Sample Position、Method 和 Data File 必须填写。来源：Study Manager Quick Start G3335-90140。
• 假设：
  • 文件带有 UTF-8 BOM，且使用 CRLF 换行符。
  • 数据文件以 .d 为后缀。
  • 方法文件应以 .m 结尾。
  • 示例中没有 Blank、QC 和 DoubleBlank 样品类型；solvent 写作 Blank。

Thermo Xcalibur：导入序列 CSV（thermo_xcalibur）

• 导入：“序列设置” >“文件” >“导入序列”。
• 已验证，依据 Xcalibur 2.2 Acquisition and Processing User Guide XCALI-97209 Rev. D 附录 A：
  • 仅接受 .csv 文件。
  • 第一个单元格必须为 Bracket Type=n（1 表示 Overlapped，2 表示 None，3 表示 Non-Overlapped，4 表示 Open）。
  • 分隔符必须与 Windows 列表分隔符一致。如果分隔符为 ;，请使用 delimiter=";"。
  • 序列列名，以及 Unknown、Blank、QC、Std Bracket、Std Clear 和 Std Update 样品类型。
• **有佐证，但 Thermo 未发布：**第 2 行的确切标题字符串（Sample Type,File Name,Sample ID,Path,Instrument Method,Process Method,Calibration File,Position,Inj Vol,Level,Sample Wt,Sample Vol,ISTD Amt,Dil Factor,L1 Study,L2 Client,L3 Laboratory,L4 Company,L5 Phone,Comment,Sample Name）。针对 Xcalibur 导入的开源生成器使用了这些标题：protti、fgcz/qg 和 lcms-sequencer。本机导出文件以单独一行 Bracket Type=4 开头（Rapid-QC-MS #83）。如需确保格式正确，请从 Xcalibur 导出一个序列作为模板。
• 假设：
  • Sample Wt 0、Sample Vol 0、ISTD Amt 0 和 Dil Factor 1 均作为默认值写入。
  • standard 写作 Std Bracket，适用于括号类型 4。
  • 扩展名检查：仪器方法使用 .meth，处理方法使用 .pmd。

尚未实现

• MassHunter Walkup 自定义样品导入（G2725-90026）：无法获取指南（HTTP 403），因此无法验证其格式。
• 原生工作列表和序列文件（MassHunter .wkl XML、Xcalibur .sld、MassLynx .spl）：尚未实现。我们未找到这些文件的公开规范，因此服务使用上述 CSV 导入方式。

验证

validate_worklist（export_worklist 也会运行此验证）会报告错误和警告；错误会阻止导出：

• 缺少该格式的必填字段。
• 数据文件名重复（不区分大小写）。对于 SCIEX OS，允许共享数据文件，但同一个数据文件中样品名称重复则属于错误。
• 包含 Windows 文件名不允许的字符（< > : " / \ | ? *、控制字符）、以句点或空格结尾，或使用保留名称（CON、NUL、COM1…）。
• 位置与所选的 position_pattern（vial_number、well、agilent_plate_well、waters_plate_well、tray_well）不匹配，或超出 plate_size（24/48/54/96/384）或 max_vial 的范围。
• 进样体积 ≤ 0、不是数字，或超过 max_injection_volume_ul 限制。这包括通过 extra 或 vendor_columns 设置的进样体积列。
• 文本字段或 extra 值包含换行符或其他控制字符，这会导致导入文件无法正常使用。
• 方法文件的扩展名错误，例如在 SCIEX OS 批次中使用 Analyst .dam 文件，或在 Xcalibur 序列中使用 MassHunter .m 文件。
• 目标格式没有对应列的字段，以及不含 BOM 的格式中的非 ASCII 文本。

安全限制

限制	默认值	含义
max_injection_volume_ul	100 µL	工作列表中允许的最大进样体积。添加样品时和导出时都会强制执行，包括通过 extra 或 vendor_columns 原样设置的体积列。import_worklist 会对更大的体积发出警告，此类草稿无法导出。

启动时可覆盖此限制，例如使用 --limit max_injection_volume_ul=20 将上限设为 20 µL。

示例提示词

• “为此列表中的 40 个血浆样品创建一个 Xcalibur 序列：放在 R 托盘的 A1 起始位置，进样量为 2 µL，方法为 C:\Xcalibur\methods\DIA_60min。每 10 个样品后，从 R:H12 加入一个空白样品，并在开头和结尾分别从 R:H11 加入一个混合 QC。随机排列样品，并告诉我随机种子。”
• “从工作列表文件夹导入 old_batch.csv，并将其转换为使用方法 D:\MassHunter\methods\Panel.m 的 MassHunter 工作列表。”
• “我把 blank_batch.txt（从我们的 SCIEX OS 导出）放在文件夹里了。将它用作此批次的模板。”
• “在导入之前，检查此 MassLynx 样品列表是否存在重复文件名和错误的样品瓶位置。”

说明

• 草稿存储在内存中。reconnect（或重启服务）会丢弃草稿。在 --simulate 模式下，还会删除临时文件夹。请导出需要保留的文件。
• 默认情况下，export_worklist 还会在工作列表旁边写入 <file>.provenance.json（例如 Plasma.csv.provenance.json）。与工作列表本身一样，除非设置 overwrite=true，否则不会覆盖该文件。它包含操作历史、随机种子以及随机化前的样品顺序，因此可以复现运行顺序。传入 write_provenance=false 可跳过此操作。
• 如果样品数量可被 blank_every_n / qc_every_n 整除，这些设置也会在最后一个样品之后添加一个控制样品，除非 blank_at_end / qc_at_end 已在此处添加一个。
• 将草稿导出为其他供应商的格式时，对于新供应商自身有映射的列，不会复制原供应商中原样保留的值（例如 Xcalibur 的 Std Clear 样品类型）；导出说明中会注明这一点。
• 随机化只会使用 Python 的 random.Random(seed)，在 randomize_types 中指定的类型（默认是未知样品）各自的槽位之间打乱样品。标准品、空白样品和 QC 会保留原位。
• 方法名称必须与采集 PC 上现有的方法匹配。服务无法检查这一点。

验证情况

软件	版本	格式	验证者	日期
暂无：欢迎成为首位验证者