Lipidmix with LLM

An MCP server (ms-data-parser) that reads MS-DIAL’s binary lipidomics outputs and exposes them to an LLM in a form it can actually reason over.

MS-DIAL writes its alignment results as compressed MessagePack and custom binary blobs. They are unreadable outside the GUI, and far too large to paste into a chat. This server parses them, runs the standard lipidomics analyses server-side, and returns compact summaries — so an LLM client such as Claude Desktop, Claude Code, or a local WebUI can drive a full analysis without ever seeing the raw matrices.

What it does

• Parses MS-DIAL binaries — alignment results, per-measurement peak lists, deconvoluted MS/MS spectra, and extracted ion chromatograms.
• Runs the analysis server-side — preprocessing and QC (normalization, blank subtraction, QC-RSD filtering, drift correction), PCA, and two-group differential analysis with BH-FDR.
• Keeps results out of the context window — plots are rendered to PNG on the server rather than shipped as coordinate lists, and full result tables stay in session state until exported.
• Accumulates knowledge — literature notes and reusable analysis playbooks are served back to the LLM as MCP resources, so findings compound across sessions.
• Can drive MS-DIAL itself (auxiliary) — the main workflow reads output MS-DIAL has already written (for example after processing in the MS-DIAL GUI). Given a folder, the server first checks for such output and goes straight to analysis if it is there. Only when the folder holds raw acquisition files alone does it ask for your permission, then plan and run MS-DIAL Console and load the resulting mzTab-M.

Supported inputs

MS-DIAL sidecars (*_tags.xml, .mddata, .mdproject) are read for tags and sample class assignments where present.

Quick start

Requires Python 3.13+ (developed on 3.14).

python -m pip install -r requirements.txt

Register the server with your MCP client — for example, in .mcp.json:

{
  "mcpServers": {
    "ms-data-parser": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/Lipidmix_with_LLM/server.py"]
    }
  }
}

Point it at your data and ask the client to start:

export LIPIDMIX_DATA_DIR=/path/to/your/msdial/output

Load the dataset in LIPIDMIX_DATA_DIR and show me the PCA.

That calls load_dataset, the entry point: it picks the latest alignment batch, runs the standard overview, and primes the session for everything that follows.

MS-DIAL Console and reference libraries (optional)

Running MS-DIAL Console from raw data (console_*, pipeline_*) or matching against your own .msp library (library_load) needs to know where those files live. Copy lipidmix.example.toml to lipidmix.local.toml next to server.py and fill in the paths (Windows paths in single quotes). The file is not tracked by git and is read on every call, so edits take effect without restarting the server. The environment variables MSDIAL_EXE, MSDIAL_LBM, MSDIAL_MSP_POS and MSDIAL_MSP_NEG still work and take precedence over the file. If something is missing, the tool’s error names the file and the key to fill in.

To run the parsers without an MCP client, see docs/cli.md.

Repository map

server.py is a thin facade that registers tools by import side effect; it must stay at the repository root because MCP client configs reference it by absolute path. The implementation lives under metabolomix/.

Documentation

Tests run from the repository root. They need pytest, which is not part of the runtime dependencies; install it through the development requirements first:

python -m pip install -r requirements-dev.txt
python -m pytest tests -q

Status and caveats

This is a research prototype, developed against one lab’s MS-DIAL outputs. Treat the following as known limits rather than surprises:

• Version-coupled. The binary readers follow MS-DIAL’s internal class layout. A MS-DIAL release that changes those classes will need the key indices in docs/schema/ re-checked.
• Multi-group ANOVA is deliberately unavailable. MS-DIAL metadata carries no factor-to-level mapping, so the server asks you to carve out two groups explicitly instead of guessing a design.
• Identification confidence is reported, not assumed. An MS/MS flag and an actual acquired spectrum are distinguished throughout; check the reported band before claiming an MSI level.
• Analysis records live with the data, not the code. Objectives and reports are written to reports/ inside the analysis folder (next to the raw data and MS-DIAL output), never under the clone; data/ is untracked.

License

MIT.

This project reads MS-DIAL’s output files; it contains no MS-DIAL source code and is not a derivative of it. The MessagePack key indices in docs/schema/ are transcribed from the [Key(N)] attributes of MS-DIAL’s own classes, with the upstream repository and the commit they were checked against recorded in each file. MS-DIAL (systemsomicslab/MsdialWorkbench) is licensed under LGPL-3.0 by its authors.