lineageverse-mcp

An MCP server for single-cell lineage tracing analysis. It wraps the scverse-style lineage stack — Cassiopeia (reconstruction), pycea (plotting + heritability), and treedata (the shared TreeData object) — behind a small set of MCP tools so an assistant can drive analyses conversationally:

• "Reconstruct a lineage tree from this character-matrix CSV."
• "Plot the tree next to its character matrix."
• "Which genes are most heritable on this tree (Moran's I)?"

Install

Requires Python ≥ 3.12. Cassiopeia builds Cython extensions, so you need a C compiler (Xcode Command Line Tools on macOS, build-essential on Linux).

# 1. The MCP server + its PyPI dependencies (treedata, pycea, scanpy, anndata, mcp, ...)
pip install lineageverse-mcp          # from PyPI once published
# ...or from a checkout:  pip install -e .

# 2. Cassiopeia v3 (the functional TreeData API). Not yet on PyPI — install from GitHub:
pip install "cassiopeia-lineage @ git+https://github.com/YosefLab/Cassiopeia.git@3.0.0"

Optional extras:

# Interactive web viewer; install only if you want launch_viewer:
pip install cellxlineage
# Exact-ILP reconstruction (methods "ilp"/"hybrid") additionally needs a licensed Gurobi:
pip install gurobipy

If cellxlineage cannot go in the same environment (its dependency pins conflict with your stack), install it separately and point the server at it with LINEAGEVERSE_CELLXLINEAGE_BIN=/path/to/cellxlineage.

Run

lineageverse-mcp                          # STDIO transport (what MCP clients launch)
mcp dev src/lineageverse_mcp/server.py    # MCP Inspector for interactive testing

Claude Code

claude mcp add lineageverse -- lineageverse-mcp

Claude Desktop

Edit the config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows) and point it at the installed executable:

{
  "mcpServers": {
    "lineageverse": { "command": "/path/to/your/env/bin/lineageverse-mcp" }
  }
}

If installed in a conda env, use conda run instead:

{
  "mcpServers": {
    "lineageverse": {
      "command": "conda",
      "args": ["run", "--no-capture-output", "-n", "YOUR_ENV", "lineageverse-mcp"]
    }
  }
}

Running the server on a remote host (e.g. an HPC cluster where the data lives): Desktop is macOS/Windows only, so launch the server over SSH. Set command to ssh and args to ["-T", "user@host", "/abs/path/to/env/bin/lineageverse-mcp"]. SSH must be non-interactive (key-based auth) and must not print anything to stdout (call the binary by absolute path so login rc files aren't sourced), or the JSON-RPC stream will be corrupted.

Tools

Tool	Purpose
load_dataset / import_character_matrix	Load a .h5td/.h5ad, or import a character-matrix CSV → a dataset_id.
load_example_dataset	Load a built-in pycea example dataset (packer19, yang22, koblan25).
dataset_info / list_datasets	Inspect loaded datasets.
reconstruct_tree	Build a tree (greedy, nj, upgma, ilp, hybrid).
compute_dissimilarity	Pairwise distance map (for nj/upgma).
compute_heritability	Rank features by Moran's I / Geary's C on a tree.
label_clades / reconstruct_ancestral_states / calculate_parsimony	Characterize a tree.
compare_trees	Robinson-Foulds / triplets between two trees.
plot_tree	Render a tree (+ character-matrix / annotation heatmap).
simulate_tree / simulate_characters	Generate ground-truth trees and character matrices.
save_dataset / export_newick	Persist results.
launch_viewer	Open the interactive cellxlineage web viewer on a dataset (optional).

Design

Datasets are held in an in-memory session store keyed by dataset_id and mutated in place across calls (matching the AnnData/TreeData idiom); save_dataset persists to <workspace>/<id>.h5td. The workspace defaults to ~/.lineageverse (override with LINEAGEVERSE_WORKSPACE). Each tool module registers itself with the FastMCP app via register(mcp), so adding a capability is just adding a function.

To try it end-to-end without your own data, ask for load_example_dataset (downloads a small .h5td from Zenodo), then plot_tree and compute_heritability on it.

Development

pip install -e ".[test]"
pytest

Heavy ilp reconstructions can be slow; on a shared cluster, run those on a compute node.