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.

• Drives MS-DIAL itself — an optional path plans and runs MS-DIAL Console over raw acquisition files, then loads the resulting mzTab-M as a canonical dataset.

• Accumulates knowledge — literature notes and reusable analysis playbooks are served back to the LLM as MCP resources, so findings compound across sessions.

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.

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 lipidmix/.

Documentation

Tests run from the repository root:

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.

• Generated artifacts are not checked in. data/, analyses/, and reports/ are untracked; a clean checkout will not have them.

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.