内容
# cyto-mcp
> 一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，将流式细胞分析带到任何支持MCP的AI助手——本地、私有且免费。
---
## 为什么选择cyto-mcp？
流式细胞分析（FCS文件、门控、补偿、聚类）繁琐、容易出错且难以脚本化。 **cyto-mcp** 让像Claude或GitHub Copilot这样的AI助手通过自然语言驱动整个分析流程，同时将您的数据的每个字节保留在您的机器上。
```
云LLM ──HTTPS──► MCP客户端（Claude Desktop / VS Code / Cursor）
│ stdio / 本地HTTP
▼
cyto-mcp 服务器 ──► 您磁盘上的FCS文件
```
**您的数据不会离开您的机器。** LLM只会看到服务器发送的紧凑的摘要、统计数据和图像。
---
## 功能
| 类别 | 工具 |
|---|---|
| **文件I/O** | 列出、加载、验证FCS文件；读取FCS关键词 |
| **预处理** | 应用补偿矩阵；Logicle / asinh / biexp转换 |
| **子采样** | 可复制的下采样以实现快速探索 |
| **统计** | 每通道百分位统计；跨样本比较 |
| **门控** | 矩形和阈值门控；群体频率和MFI |
| **可视化** | 散点图和直方图 — 以PNG + 结构化JSON返回 |
*质量控制（时间漂移、饱和度标记）、多边形/椭圆门控、报告和聚类（FlowSOM、UMAP）计划在v0.2中实现。*
---
## 快速入门
### 先决条件
- Python 3.11+
- 支持MCP的客户端： [Claude Desktop](https://claude.ai/download)、 [VS Code + GitHub Copilot](https://code.visualstudio.com/) 或 [Cursor](https://cursor.sh/)
### 从PyPI安装 *(推荐)*
```bash
pip install cyto-mcp
cyto-mcp --help # 验证它是否正常工作
```
或使用 [uv](https://docs.astral.sh/uv/) （更快、更独立）：
```bash
uv tool install cyto-mcp
cyto-mcp --help
```
### 从源代码安装 *(适用于贡献者/开发)*
```bash
git clone https://github.com/luangxiao/cyto-mcp.git
cd cyto-mcp
uv sync # 创建.venv并安装所有依赖项
uv run cyto-mcp --help # 验证它是否正常工作
```
### 配置您的MCP客户端
**Claude Desktop** — 编辑 `claude_desktop_config.json`:
```jsonc
{
"mcpServers": {
"flow": {
"command": "cyto-mcp",
"args": ["serve", "--data-dir", "/path/to/your/fcs/files"]
}
}
}
```
**VS Code** — 在您的工作区中创建 `.vscode/mcp.json`:
```jsonc
{
"servers": {
"flow": {
"type": "stdio",
"command": "cyto-mcp",
"args": ["serve", "--data-dir", "/path/to/your/fcs/files"]
}
}
}
```
> **VS Code注意：** 如果 `cyto-mcp` 不在VS Code的PATH中，请使用可执行文件的完整路径（例如Windows上的 `C:/Users/you/AppData/Roaming/Python/Scripts/cyto-mcp.exe`，或在macOS/Linux上运行 `which cyto-mcp` 来查找它）。
### 试用
在您的AI助手上，询问：
> *"列出我的数据目录中的FCS文件并加载第一个文件。显示面板通道和FSC-A与SSC-A的散点图。"*
---
## 架构
详见 [ARCHITECTURE.md](ARCHITECTURE.md)，了解代码库布局、设计决策和扩展指南。
```
src/cyto_mcp/
├── server.py # FastMCP应用连接和启动
├── cli.py # click CLI入口点 (`cyto-mcp serve`)
├── config.py # Pydantic设置（data-dir、output-dir、缓存大小）
├── errors.py # 类型错误层次结构
├── cache.py # LRU内存样本缓存
├── tools/
│ ├── io.py # load_fcs、list_fcs、fcs_keywords、validate_fcs
│ ├── preprocess.py # apply_compensation、transform、subsample
│ ├── stats.py # channel_stats、compare_samples
│ ├── gating.py # gate_rectangle、gate_threshold、population_stats
│ └── plots.py # scatter_plot、histogram
└── utils/
├── image.py # fig → PNG字节助手
└── paths.py # 在data-dir沙箱中安全路径解析
```
---
## 设计原则
1. **数据永远不会离开机器。** 服务器只读取配置的 `--data-dir` 中的文件，并将输出写入 `--output-dir`。无网络调用。
2. **返回引用，而不是原始数据。** 大型制品（PNG图、报告）写入磁盘，并通过URI引用。工具响应保持足够小，以适应任何上下文窗口。
3. **为图表返回双重结果。** 每个图表工具返回PNG图像（供人类使用）和结构化JSON摘要（供LLM数值推理）。
4. **沙箱文件访问。** 所有路径参数在 `--data-dir` 中解析并验证，以防止路径遍历攻击。
5. **无状态工具，有状态缓存。** 每个工具调用都是自包含的；LRU样本缓存是一种优化，而不是正确性的要求。
---
## 社区与讨论
我是一名 solo 开发人员，在业余时间构建这个项目——我很乐意听到您的消息，无论您是研究人员、临床医生、生物信息学家还是只是好奇。
- **问题/想法？** → 打开一个 [讨论](https://github.com/luangxiao/cyto-mcp/discussions) — 没有问题太基本。
- **发现了一个bug？** → 打开一个 [问题](https://github.com/luangxiao/cyto-mcp/issues) 并附上重现步骤。
- **想分享一个用例或分析工作流？** → 在 [展示和讲述](https://github.com/luangxiao/cyto-mcp/discussions/categories/show-and-tell) 中发布，我很享受看到现实世界的应用。
---
## 贡献
欢迎所有贡献——从 typo 修复到新工具。以下是开始的方法：
1. **Fork** 仓库并在本地克隆
2. 创建一个功能分支： `git checkout -b feat/my-feature`
3. 安装开发依赖项： `uv sync --extra dev`
4. 运行测试： `uv run pytest`
5. Lint: `uv run ruff check src tests`
6. 打开一个 **拉取请求**，附上清晰的描述内容和原因
对于任何非琐碎的事情，请先打开一个问题或讨论，以便我们在您投入时间编码之前达成一致。我将尽力及时审查拉取请求并提供建设性的反馈。
---
## 许可证
Apache 2.0 — 参见 [LICENSE](LICENSE)。
