# 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

| Format | Contents |
|---|---|
| `.arf` | Alignment result, per-sample peaks. The main source for cross-sample comparison and PCA. |
| `.arf2` | Alignment result, spot representatives. Dataset-wide catalog and annotations. |
| `.pai2` | A single measurement's detected peaks. |
| `.dcl` | Deconvoluted MS/MS spectra. MS-DIAL's own binary format — not MessagePack. |
| `.EIC.aef` | Extracted ion chromatograms. |
| mzTab-M 2.0 | Standard exchange format, produced by the MS-DIAL Console path. |

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).

```bash
python -m pip install -r requirements.txt
```

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

```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:

```bash
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](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/`.

| Package | Responsibility |
|---|---|
| `lipidmix/core/` | FastMCP instance, configuration, session state, path resolution. Depends on nothing else in the tree. |
| `lipidmix/{arf,arf2,pai2,dcl,eic}/` | One `reader.py` (parser) and `tools.py` (MCP surface) per input format. |
| `lipidmix/mztab/` | mzTab-M reader and canonical `DatasetState`. |
| `lipidmix/console/` | MS-DIAL Console execution: job planning, running, output collection. |
| `lipidmix/analysis/` | Format-independent numerics: preprocessing/QC, PCA, differential analysis, the export contract. |
| `lipidmix/plots/` | Renderer-neutral plot payloads and matplotlib rendering. |
| `lipidmix/msdial/` | MS-DIAL-specific sidecars, identification, peak verification. |
| `lipidmix/corpus/` | Pure logic for the knowledge and playbook notes. |
| `lipidmix/tools/` | MCP tools not tied to a single input format. |

## Documentation

| To find out | Read |
|---|---|
| What each MCP tool takes and does | [USAGE.md](USAGE.md) |
| What an output field *means* — row granularity, lipid-name grammar, caveats | [docs/output_format/](docs/output_format/core.md), also served as the MCP resource `lipidmix://docs/output-format` |
| Which functions a tool calls, in what order | [docs/workflow/](docs/workflow/index.md) |
| MessagePack key indices, transcribed from MS-DIAL's `[Key(N)]` attributes | [docs/schema/](docs/schema/AlignmentSpotProperty.md) |
| Running the parsers from the command line | [docs/cli.md](docs/cli.md) |
| Deploying for a team, with knowledge on a shared NAS | [DEPLOY.md](DEPLOY.md), [docs/local_shared_knowledge_setup.md](docs/local_shared_knowledge_setup.md) |
| Working on this repository | [CLAUDE.md](CLAUDE.md) |

Tests run from the repository root:

```bash
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](LICENSE).

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/](docs/schema/AlignmentSpotProperty.md)
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](https://github.com/systemsomicslab/MsdialWorkbench)) is
licensed under LGPL-3.0 by its authors.