# lineageverse-mcp

An [MCP](https://modelcontextprotocol.io) server for **single-cell lineage tracing
analysis**. It wraps the scverse-style lineage stack —
[Cassiopeia](https://github.com/YosefLab/Cassiopeia) (reconstruction),
[pycea](https://pycea.readthedocs.io) (plotting + heritability), and
[treedata](https://treedata.readthedocs.io) (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).

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

```bash
# 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

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

### Claude Code

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

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

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

```json
{
  "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

```bash
pip install -e ".[test]"
pytest
```

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