Mass Spectrometry Data (mzML, Bruker TDF, vendor conversion)

质谱数据（mzML、Bruker TDF、供应商格式转换）——MCP 服务

让 AI Agent 通过开放接口查找、读取和分析任意供应商的 LC-MS 数据文件：列出文件夹中的运行数据，报告仪器和采集详情，绘制 TIC/BPC 色谱图，提取离子色谱图并计算峰顶和峰面积，读取质谱，按前体 m/z 查找 MS2 扫描，并执行快速 QC。供应商格式的文件通过你已安装的转换器转换为 mzML。这是一个数据服务：不会控制任何硬件。

软件包	labmcp-ms-data
仪器	以 mzML / mzML.gz / mzMLb 格式保存的任意 LC-MS 运行数据；直接读取 Bruker timsTOF（.d、TDF）；Thermo .raw、Waters .raw 文件夹、Agilent .d、SCIEX .wiff/.wiff2、Shimadzu .lcd、转换后的 Bruker BAF .d
接口	文件（本地或网络数据文件夹）
协议	通过 pyteomics 处理 mzML 1.1；通过 pyteomics + h5py 处理 mzMLb；通过其 SQLite 架构 + timsrust（timsrust-pyo3）处理 Bruker TDF；通过 msconvert 或 ThermoRawFileParser 进行转换
状态	🧪 模拟：已使用合成 LC-MS 运行数据、手工编写和生成的 mzML/mzMLb 文件以及一小组 Bruker TDF 测试数据进行测试；尚未在各种真实仪器文件上验证。报告测试结果

无需数据即可试用

uvx labmcp-ms-data --simulate --check

--simulate 会提供一个合成的 12 分钟 DDA LC-MS/MS 运行数据（simulated_lcms_run.mzML）：包含八种已知分析物（咖啡因、磺胺甲噁唑、亮脑啡肽、血管紧张素 II 2+、维拉帕米、谷氨酰纤维蛋白肽 B 2+、利血平、特非那定），它们以带同位素包络的高斯 LC 峰形式洗脱；还包含聚硅氧烷背景离子、化学噪声、带动态排除和碎片质谱的 top-5 DDA 方法、类似 AGC 的注入时间，以及一次约在 10.6 分钟发生、可由 QC 工具检测的电喷雾信号中断。

指向你的数据

1. 安装（选择你需要的额外依赖）：

   uvx labmcp-ms-data --help                        # mzML / mzML.gz
   uvx --from 'labmcp-ms-data[bruker]' labmcp-ms-data --help   # + Bruker timsTOF spectra/XICs
   uvx --from 'labmcp-ms-data[mzmlb]' labmcp-ms-data --help    # + mzMLb
   

2. 选择数据文件夹，使用 --address（默认为当前目录；如果未指定 --address，服务器会拒绝在文件系统根目录中启动，因为许多 MCP 客户端会在此处启动服务器）。系统会搜索子文件夹。Agent 只能在此文件夹内读取和写入：包含 .. 的路径、指向其他位置的绝对路径，以及指向外部位置的符号链接都会被拒绝。

   uvx labmcp-ms-data --address ~/data/lcms --check
   

3. **供应商文件（可选）：**自行安装转换器；此软件包不会捆绑或下载供应商库。

   • Thermo .raw，任意操作系统： ThermoRawFileParser（--option converter=thermorawfileparser；如果它不在 PATH 中，还需指定 --option converter_path=/opt/trfp/ThermoRawFileParser.dll；在 Linux/macOS 上，.dll 使用 dotnet 启动，.exe 使用 mono 启动）。使用 converter=auto 时，会根据文件名识别 converter_path。
   • 所有供应商，Windows： ProteoWizard msconvert（--option converter=msconvert）。
   • 所有供应商，Linux/macOS： Docker 和 docker pull proteowizard/pwiz-skyline-i-agree-to-the-vendor-licenses（--option converter=docker）。拉取镜像即表示你接受供应商许可。只有输入文件所在文件夹（只读）和输出文件夹会挂载到容器中。在 Apple Silicon 上，它会通过 x86-64 仿真运行（速度较慢）。在 Linux 上，输出文件归 root 所有。
   • converter=auto（默认）会先尝试使用 Thermo 文件对应的 ThermoRawFileParser，然后尝试 msconvert，最后尝试 Docker。

   使用的命令为：ThermoRawFileParser -i=<file> -o=<dir> -f=2 [-p] [-g] 和 msconvert <file> -o <dir> --mzML --zlib [--gzip] [--filter "peakPicking vendor msLevel=1-"]（在 Docker 中通过 wine msconvert 运行）。这些命令不会通过 shell 运行，并设有超时；超时时会终止转换器的整个进程树（以及 Docker 容器），并删除未完成的输出文件。

添加到你的 MCP 客户端

Claude Code

claude mcp add ms-data -- uvx --from 'labmcp-ms-data[bruker]' labmcp-ms-data --address /path/to/data

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

{
  "mcpServers": {
    "ms-data": {
      "command": "uvx",
      "args": ["--from", "labmcp-ms-data[bruker]", "labmcp-ms-data", "--address", "/path/to/data",
               "--option", "converter=docker"]
    }
  }
}

添加 --read-only 可隐藏 convert_to_mzml（这是唯一会写入数据文件的工具；仍可在数据文件夹内使用 save_path 导出 CSV）。save_path 必须以 .csv 结尾（不带扩展名的名称会自动添加扩展名），且除非调用中传入 overwrite=true，否则不会替换已有文件。对于其他客户端，可使用 uvx labmcp config ms-data --address /path/to/data --client vscode 生成配置片段（也支持 cursor、codex、claude-code）。

工具

工具	类型	描述
convert_to_mzml	🎛 control	使用用户安装的转换器（Thermo .raw、Waters .raw、Agilent .d、SCIEX .wiff、Shimadzu .lcd、Bruker .d）将厂商文件转换为 mzML（ThermoRawFileParser、ProteoWizard msconvert 或 Docker 中的 msconvert；通过 --option converter=... 选择）。在数据文件夹中写入新文件。可能需要几分钟；如果尚未设置转换器，则会失败并提供安装说明。
extract_ion_chromatogram	👁 read	为一个或多个 m/z 值提取离子色谱图（XIC/EIC）：计算每张 MS1 谱图（或另一个 ms_level）中 ± 容差（ppm 或 Da）范围内的强度总和。每个目标返回峰顶 RT 和强度、峰顶边界、面积（强度 × 分钟，不扣除基线）、半峰全宽（FWHM）以及降采样后的曲线。此工具会读取 RT 窗口内的每张谱图，因此对于较长的运行，请限制 rt_start_min/rt_end_min。
find_ms2_scans	👁 read	查找前体 m/z 在 precursor_mz 的 ± 容差范围内的 MS2（MSn）谱图，可选设置 RT 窗口和电荷态。返回索引、扫描编号、RT、前体 m/z、ppm 误差、电荷和强度；可使用 get_spectrum 打开任意匹配结果。
get_bpc	👁 read	基峰色谱图（每张谱图中最强峰的强度及其 m/z）随保留时间的变化，降采样至 max_points 个点。比 TIC 更适合发现洗脱的化合物；基峰 m/z 可告诉你运行各阶段由哪个离子主导。
get_command_log	👁 read	返回最近发送到仪器的原始命令及收到的回复（最新记录排在最后）。适用于调试和记录操作内容。
get_connection_info	👁 read	报告连接的仪器（身份、地址、模拟或真实）、服务是否为只读，以及当前有效的安全限制。请先调用此工具。
get_run_info	👁 read	描述一次运行：仪器厂商/型号/序列号（文件中有记录时）、采集日期、软件、各 MS 级别的谱图数量、保留时间和 m/z 范围、极性、质心/剖面模式，以及是否存在离子淌度数据。大型文件的首次调用会为其建立索引（可能需要一段时间）；之后的调用会立即返回。
get_spectrum	👁 read	按 index、scan_number、native_id 或最接近的 rt_min 读取一张谱图（必须且只能提供一项）。返回 MS 级别、RT、极性、质心/剖面模式、MS2 的前体 m/z 和电荷、摘要（峰数、TIC、基峰、m/z 范围）以及强度最高的 top_n 个峰；save_path 会将完整峰列表写入 CSV。对于剖面谱图，最高峰是剖面中的局部极大值。
get_tic	👁 read	单个 MS 级别的总离子色谱图（每张谱图的强度总和随保留时间的变化），降采样至 max_points 个点（保留每个区间内的最大值，使峰得以保留）。返回峰顶、中位数和面积；save_path 会将每个数据点写入 CSV。
list_runs	👁 read	查找数据文件夹中的质谱运行，并检测每个运行的厂商和格式（mzML/mzML.gz/mzMLb、Bruker .d TDF 或 BAF、Agilent .d、Thermo .raw、Waters .raw 文件夹、SCIEX .wiff/.wiff2、Shimadzu .lcd、mzXML）。readable_directly=false 表示必须先使用 convert_to_mzml 转换该运行，才能进行分析。
reconnect	🛑 safety	关闭并重新打开与仪器的连接（例如，仪器断电重启或重新插拔线缆后）。
summarise_run	👁 read	对运行进行快速质量控制：MS1/MS2 计数、TIC 稳定性（CV、喷雾中断）、信号洗脱位置、循环时间、每个循环的 MS2 扫描数、中位注入时间、MS2 达到最大注入时间的频率，以及前体电荷态。返回通俗易懂的警告。

get_connection_info、get_command_log 和 reconnect 是每个 LabMCP 服务内置的工具（此处的 reconnect 会关闭缓存的运行）。没有 HAZARD 工具，因为此处不会控制任何物理设备，所以不需要 SAFETY 停止工具。

安全限制

限制	默认值	含义
max_conversion_time_s	3600 s	convert_to_mzml 调用在转换器停止前允许运行的最长时间
max_xic_targets	50	单次 extract_ion_chromatogram 调用中的 m/z 值数量上限

启动时覆盖：--limit max_conversion_time_s=7200。

示例提示词

• “这个文件夹里有哪些运行数据，哪些需要转换？”
• “请告诉我 QC_2024_03_01.mzML 的仪器、采集日期和扫描次数。”
• “以 5 ppm 的质量精度为咖啡因（195.0877）和维拉帕米（455.2904）提取 XIC，并报告峰顶 RT 和面积。”
• “找出 5 到 7 分钟之间所有 m/z 为 523.7745 的 MS2 扫描，并展示强度最高扫描的碎片。”
• “对最近三次运行进行 QC：是否有喷雾中断？每个周期有多少个 MS2？”
• “将 sample_07.raw 转换为 mzML，然后绘制其基峰色谱图。”

备注

• **格式支持：**通过 pyteomics（Apache-2.0）支持 mzML（有索引或无索引，也可为 .gz），并使用 psims 随附的 PSI-MS 词汇表（无需下载）。mzMLb 需要 [mzmlb] 附加组件（h5py、hdf5plugin）。压缩的 mzML 会解压到临时文件，以支持随机访问。
• **Bruker timsTOF（TDF）：**运行元数据（仪器、序列号、日期、m/z 和 1/K0 范围）、TIC（Frames.SummedIntensities）、BPC 强度（Frames.MaxIntensity，任意迁移率扫描中的最强单峰；其 m/z 未存储）和 DDA 前体列表会直接从 analysis.tdf SQLite 表（GlobalMetadata、Frames、Precursors、PasefFrameMsMsInfo）读取，因此无需安装附加组件即可使用。谱图和 XIC 需要 [bruker] 附加组件（timsrust-pyo3，Apache-2.0，提供适用于 Linux/macOS/Windows 的 wheel）。MS1 和 diaPASEF 帧会对离子迁移率求和（diaPASEF MS2 帧混合所有隔离窗口）；每个 ddaPASEF 前体对应一个 MS2 谱图。输出中不会区分离子迁移率。Bruker BAF .d 文件夹需要先转换。
• **厂商格式：**Thermo、Waters、Agilent、SCIEX、Shimadzu 和 Bruker BAF 文件只能通过各厂商自有库解码，这些库的许可证不允许再分发。服务会检测这些格式，并使用你已安装的工具进行转换（见上文）。它绝不会下载厂商代码。
• **数值：**保留时间以分钟为单位（mzML 扫描起始时间若以秒为单位，会根据单位 accession 转换）；XIC 强度为容差范围 ± 内所有峰的强度总和；面积是以 RT 分钟为单位的梯形积分，不扣除基线，积分范围从信号降至峰顶强度的 1% 或到达谷值处开始。FWHM 在这些边界内测量（若共洗脱峰使信号始终高于半高，则为 null）。这些值适用于相对比较。
• **大文件：**首次访问某次运行时，会遍历所有谱图一次以建立索引（TIC、前体、RT）。最多缓存 4 次运行（--option cache_size=N）。文件发生变化（修改时间或大小）时，会自动重新打开运行数据。XIC 会读取 RT 窗口内的每个谱图，因此对于较长的运行，请缩小窗口。
• **轮廓数据：**色谱图和 XIC 可直接使用。get_spectrum 会将局部最大值报告为“峰”。若要获得正确的质心，请通过寻峰进行转换。

硬件验证

仪器 / 文件类型	软件版本	接口	验证者	日期
暂无：成为首位验证者