Metadata-Version: 2.4
Name: cyto-mcp
Version: 0.1.1
Summary: A Model Context Protocol (MCP) server for flow cytometry data analysis
Project-URL: Homepage, https://github.com/luangxiao/cyto-mcp
Project-URL: Repository, https://github.com/luangxiao/cyto-mcp
Project-URL: Issues, https://github.com/luangxiao/cyto-mcp/issues
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
           "License" shall mean the terms and conditions for use, reproduction,
           and distribution as defined by Sections 1 through 9 of this document.
        
           "Licensor" shall mean the copyright owner or entity authorized by
           the copyright owner that is granting the License.
        
           "Legal Entity" shall mean the union of the acting entity and all
           other entities that control, are controlled by, or are under common
           control with that entity. For the purposes of this definition,
           "control" means (i) the power, direct or indirect, to cause the
           direction or management of such entity, whether by contract or
           otherwise, or (ii) ownership of fifty percent (50%) or more of the
           outstanding shares, or (iii) beneficial ownership of such entity.
        
           "You" (or "Your") shall mean an individual or Legal Entity
           exercising permissions granted by this License.
        
           "Source" form shall mean the preferred form for making modifications,
           including but not limited to software source code, documentation
           source, and configuration files.
        
           "Object" form shall mean any form resulting from mechanical
           transformation or translation of a Source form, including but
           not limited to compiled object code, generated documentation,
           and conversions to other formats.
        
           "Work" shall mean the work of authorship made available under
           the License, as indicated by a copyright notice that is included
           in or attached to the work.
        
           "Derivative Works" shall mean any work, whether in Source or Object
           form, that is based on (or derived from) the Work and for which the
           editorial revisions, annotations, elaborations, or other modifications
           represent, as a whole, an original work of authorship.
        
           "Contribution" shall mean, as submitted to the Licensor for inclusion
           in the Work by the copyright owner or by an individual or Legal Entity
           authorized to submit on behalf of the copyright owner.
        
           "Contributor" shall mean Licensor and any Legal Entity on behalf of
           whom a Contribution has been received by the Licensor and included
           within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of
           this License, each Contributor hereby grants to You a perpetual,
           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
           copyright license to reproduce, prepare Derivative Works of,
           publicly display, publicly perform, sublicense, and distribute the
           Work and such Derivative Works in Source or Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of
           this License, each Contributor hereby grants to You a perpetual,
           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
           (except as stated in this section) patent license to make, have made,
           use, offer to sell, sell, import, and otherwise transfer the Work,
           where such license applies only to those patent claims licensable
           by such Contributor that are necessarily infringed by their
           Contribution(s) alone or by their combined contributions in Work.
        
        4. Redistribution. You may reproduce and distribute copies of the
           Work or Derivative Works thereof in any medium, with or without
           modifications, and in Source or Object form, provided that You
           meet the following conditions:
        
           (a) You must give any other recipients of the Work or Derivative
               Works a copy of this License; and
        
           (b) You must cause any modified files to carry prominent notices
               stating that You changed the files; and
        
           (c) You must retain, in the Source form of any Derivative Works
               that You distribute, all copyright, patent, trademark, and
               attribution notices from the Source form of the Work,
               excluding those notices that do not pertain to any part of
               the Derivative Works; and
        
           (d) If the Work includes a "NOTICE" text file, as part of your
               distribution, you must include a readable copy of the
               attribution notices contained within such NOTICE file.
        
        5. Submission of Contributions. Unless You explicitly state otherwise,
           any Contribution intentionally submitted for inclusion in the Work
           by You to the Licensor shall be under the terms and conditions of
           this License, without any additional terms or conditions.
        
        6. Trademarks. This License does not grant permission to use the trade
           names, trademarks, service marks, or product names of the Licensor,
           except as required for reasonable and customary use in describing the
           origin of the Work.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed
           to in writing, Licensor provides the Work (and each Contributor
           provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
           OR CONDITIONS OF ANY KIND, either express or implied.
        
        8. Limitation of Liability. In no event and under no legal theory,
           whether in tort (including negligence), contract, or otherwise,
           unless required by applicable law, shall any Contributor be liable
           to You for damages, including any direct, indirect, special,
           incidental, or exemplary damages of any character arising as a
           result of this License or out of the use or inability to use the
           Work.
        
        9. Accepting Warranty or Additional Liability. While redistributing
           the Work or Derivative Works thereof, You may choose to offer,
           and charge a fee for, acceptance of support, warranty, indemnity,
           or other liability obligations and/or rights consistent with this
           License. However, in accepting such obligations, You may offer
           such obligations only on Your own behalf and on Your sole
           responsibility, not on behalf of any other Contributor.
        
        END OF TERMS AND CONDITIONS
License-File: LICENSE
Keywords: bioinformatics,cyto-mcp,fcs,flow-cytometry,immunology,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: flowkit>=1.1.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: scipy>=1.12.0
Requires-Dist: seaborn>=0.13.0
Provides-Extra: advanced
Requires-Dist: anndata>=0.10.0; extra == 'advanced'
Requires-Dist: scikit-learn>=1.4.0; extra == 'advanced'
Requires-Dist: umap-learn>=0.5.0; extra == 'advanced'
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# cyto-mcp

> A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings
> flow cytometry analysis to any MCP-capable AI assistant — locally, privately, and for free.

---

## Why cyto-mcp?

Flow cytometry analysis (FCS files, gating, compensation, clustering) is tedious, error-prone,
and hard to script. **cyto-mcp** lets an AI assistant like Claude or GitHub Copilot drive the
entire analysis pipeline through natural language — while keeping every byte of your data on
your own machine.

```
Cloud LLM  ──HTTPS──►  MCP Client (Claude Desktop / VS Code / Cursor)
                               │  stdio / local HTTP
                               ▼
                        cyto-mcp server  ──►  FCS files on your disk
```

**No data leaves your machine.** The LLM only sees compact summaries, statistics, and images
that the server sends back.

---

## Features

| Category | Tools |
|---|---|
| **File I/O** | List, load, validate FCS files; read FCS keywords |
| **Preprocessing** | Apply compensation matrix; Logicle / asinh / biexp transform |
| **Quality control** | Time-drift detection, saturated-event flagging |
| **Subsampling** | Reproducible down-sampling for fast exploration |
| **Statistics** | Per-channel percentile stats; cross-sample comparison |
| **Gating** | Rectangle, polygon, ellipse, quadrant, threshold gates |
| **Visualization** | Scatter plots, histograms, density overlays — returned as PNG + structured JSON |
| **Reporting** | Markdown / HTML summary reports |

*Advanced clustering (FlowSOM, UMAP) is planned for v0.2.*

---

## Quickstart

### Prerequisites

- Python 3.11+
- An MCP-capable client: [Claude Desktop](https://claude.ai/download),
  [VS Code + GitHub Copilot](https://code.visualstudio.com/), or [Cursor](https://cursor.sh/)

### Install from PyPI *(recommended)*

```bash
pip install cyto-mcp
cyto-mcp --help               # verify it works
```

Or with [uv](https://docs.astral.sh/uv/) (faster, isolated):

```bash
uv tool install cyto-mcp
cyto-mcp --help
```

### Install from source *(for contributors / development)*

```bash
git clone https://github.com/luangxiao/cyto-mcp.git
cd cyto-mcp
uv sync                       # creates .venv and installs all deps
uv run cyto-mcp --help        # verify it works
```

### Configure your MCP client

**Claude Desktop** — edit `claude_desktop_config.json`:

```jsonc
{
  "mcpServers": {
    "flow": {
      "command": "cyto-mcp",
      "args": ["serve", "--data-dir", "/path/to/your/fcs/files"]
    }
  }
}
```

**VS Code** — create `.vscode/mcp.json` in your workspace:

```jsonc
{
  "servers": {
    "flow": {
      "type": "stdio",
      "command": "cyto-mcp",
      "args": ["serve", "--data-dir", "/path/to/your/fcs/files"]
    }
  }
}
```

> **Note for VS Code:** if `cyto-mcp` is not on VS Code's PATH, use the full path to the
> executable (e.g. `C:/Users/you/AppData/Roaming/Python/Scripts/cyto-mcp.exe` on Windows, or
> run `which cyto-mcp` on macOS/Linux to find it).

### Try it

In your AI assistant, ask:

> *"List FCS files in my data directory and load the first one. Show me the panel channels and a
> scatter plot of FSC-A vs SSC-A."*

---

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for a detailed description of the codebase layout,
design decisions, and extension guide.

```
src/flow_mcp/
├── server.py          # FastMCP app wiring and startup
├── cli.py             # click CLI entry point  (`cyto-mcp serve`)
├── config.py          # Pydantic settings (data-dir, output-dir, cache size)
├── errors.py          # Typed error hierarchy
├── cache.py           # LRU in-memory sample cache
├── tools/
│   ├── io.py          # load_fcs, list_fcs, fcs_keywords, validate_fcs
│   ├── preprocess.py  # apply_compensation, transform
│   ├── qc.py          # quality_check
│   ├── stats.py       # channel_stats, compare_samples
│   ├── gating.py      # gate_*, population_stats
│   └── plots.py       # scatter_plot, histogram, density_plot
└── utils/
    ├── image.py       # fig → PNG bytes helper
    └── paths.py       # safe path resolution within data-dir sandbox
```

---

## Design principles

1. **Data never leaves the machine.** The server only reads files from the configured `--data-dir`
   and writes outputs to `--output-dir`. No network calls.
2. **Return references, not raw data.** Large artefacts (PNG plots, reports) are written to disk
   and referenced by URI. Tool responses stay small enough to fit in any context window.
3. **Dual return for plots.** Every plot tool returns both a PNG image (for the human) *and* a
   structured JSON summary (for the LLM to reason about numerically).
4. **Sandboxed file access.** All path arguments are resolved relative to `--data-dir` and
   validated to prevent path traversal attacks.
5. **Stateless tools, stateful cache.** Each tool call is self-contained; the LRU sample cache is
   an optimisation, not a requirement for correctness.

---

## Community & Discussion

I'm a solo developer building this in my spare time — I'd genuinely love to hear from you, whether you're a researcher, clinician, bioinformatician, or just curious.

- **Questions / ideas?** → open a [Discussion](https://github.com/luangxiao/cyto-mcp/discussions) — no question is too basic.
- **Found a bug?** → open an [Issue](https://github.com/luangxiao/cyto-mcp/issues) with steps to reproduce.
- **Want to share a use-case or analysis workflow?** → post it in [Show and Tell](https://github.com/luangxiao/cyto-mcp/discussions/categories/show-and-tell), I genuinely enjoy seeing real-world applications.

---

## Contributing

All contributions are welcome — from typo fixes to new tools. Here's how to get started:

1. **Fork** the repository and clone it locally
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Install dev dependencies: `uv sync --extra dev`
4. Run tests: `uv run pytest`
5. Lint: `uv run ruff check src tests`
6. Open a **pull request** with a clear description of what and why

For anything non-trivial, please open an issue or discussion first so we can align on approach before you invest time coding. I'll do my best to review PRs promptly and give constructive feedback.

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
