Metadata-Version: 2.4
Name: chatspatial
Version: 1.2.6
Summary: ChatSpatial: Natural language-driven spatial transcriptomics analysis via Model Context Protocol (MCP) integration
Author-email: Chen Yang <cafferychen777@tamu.edu>
License: MIT
Project-URL: Homepage, https://github.com/cafferychen777/ChatSpatial
Project-URL: Documentation, https://docs.cafferyang.com/
Project-URL: Repository, https://github.com/cafferychen777/ChatSpatial
Project-URL: Issues, https://github.com/cafferychen777/ChatSpatial/issues
Keywords: spatial-transcriptomics,single-cell,mcp,llm,bioinformatics,scanpy,squidpy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.17.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: scanpy<2.0,>=1.9.0
Requires-Dist: anndata>=0.11.0
Requires-Dist: squidpy>=1.2.0
Requires-Dist: umap-learn>=0.5.0
Requires-Dist: igraph>=0.9.0
Requires-Dist: leidenalg>=0.8.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: jinja2>=3.0.0
Provides-Extra: deep-learning
Requires-Dist: torch<3.0,>=2.0.0; extra == "deep-learning"
Requires-Dist: scvi-tools<2.0,>=1.0.0; extra == "deep-learning"
Requires-Dist: mudata>=0.2.0; extra == "deep-learning"
Provides-Extra: velocity
Requires-Dist: scvelo>=0.2.5; extra == "velocity"
Provides-Extra: cell-communication
Requires-Dist: liana; extra == "cell-communication"
Requires-Dist: cellphonedb<6.0,>=5.0.0; extra == "cell-communication"
Requires-Dist: fastccc>=0.1.0; extra == "cell-communication"
Provides-Extra: integration
Requires-Dist: harmonypy>=0.0.9; extra == "integration"
Requires-Dist: bbknn>=1.5.0; extra == "integration"
Requires-Dist: scanorama>=1.7.0; extra == "integration"
Provides-Extra: spatial-stats
Requires-Dist: esda>=2.4.0; extra == "spatial-stats"
Requires-Dist: libpysal>=4.6.0; extra == "spatial-stats"
Requires-Dist: pysal>=2.6.0; extra == "spatial-stats"
Requires-Dist: statsmodels>=0.13.0; extra == "spatial-stats"
Requires-Dist: networkx>=2.6.0; extra == "spatial-stats"
Provides-Extra: deconvolution
Requires-Dist: flashdeconv>=0.1.0; extra == "deconvolution"
Requires-Dist: cell2location>=0.1.4; extra == "deconvolution"
Provides-Extra: full
Requires-Dist: scvi-tools<2.0,>=1.0.0; extra == "full"
Requires-Dist: mudata>=0.2.0; extra == "full"
Requires-Dist: scvelo>=0.2.5; extra == "full"
Requires-Dist: liana; extra == "full"
Requires-Dist: cellphonedb<6.0,>=5.0.0; extra == "full"
Requires-Dist: fastccc>=0.1.0; extra == "full"
Requires-Dist: harmonypy>=0.0.9; extra == "full"
Requires-Dist: bbknn>=1.5.0; extra == "full"
Requires-Dist: flashdeconv>=0.1.0; extra == "full"
Requires-Dist: esda>=2.4.0; extra == "full"
Requires-Dist: libpysal>=4.6.0; extra == "full"
Requires-Dist: gseapy>=1.0.0; extra == "full"
Requires-Dist: torch<3.0,>=2.0.0; extra == "full"
Requires-Dist: GraphST>=1.1.0; extra == "full"
Requires-Dist: cell2location>=0.1.4; extra == "full"
Requires-Dist: cellrank<3.0,>=2.0.0; extra == "full"
Requires-Dist: palantir>=1.0.0; extra == "full"
Requires-Dist: scanorama>=1.7.0; extra == "full"
Requires-Dist: spatialde>=1.1.3; extra == "full"
Requires-Dist: scikit-misc>=0.5.0; extra == "full"
Requires-Dist: tangram-sc>=1.0.0; extra == "full"
Requires-Dist: singler>=0.4.0; sys_platform != "win32" and extra == "full"
Requires-Dist: singlecellexperiment>=0.4.0; sys_platform != "win32" and extra == "full"
Requires-Dist: celldex>=0.3.0; sys_platform != "win32" and extra == "full"
Requires-Dist: mllmcelltype>=0.1.0; extra == "full"
Requires-Dist: rpy2<3.7,>=3.5.0; extra == "full"
Requires-Dist: anndata2ri>=1.3.0; extra == "full"
Requires-Dist: pysal>=2.6.0; extra == "full"
Requires-Dist: statsmodels>=0.13.0; extra == "full"
Requires-Dist: networkx>=2.6.0; extra == "full"
Requires-Dist: POT>=0.9.0; extra == "full"
Requires-Dist: paste-bio>=1.0.0; extra == "full"
Requires-Dist: infercnvpy>=0.4.0; extra == "full"
Requires-Dist: pydeseq2>=0.4.0; extra == "full"
Requires-Dist: enrichmap; extra == "full"
Requires-Dist: statannotations>=0.2.0; extra == "full"
Requires-Dist: pygam>=0.8.0; extra == "full"
Requires-Dist: scikit-gstat>=1.0.0; extra == "full"
Requires-Dist: adjustText>=0.8.0; extra == "full"
Requires-Dist: splot>=1.1.0; extra == "full"
Requires-Dist: spatialdata>=0.2.0; extra == "full"
Provides-Extra: spatial-domains
Requires-Dist: SpaGCN<2.0,>=1.2.5; extra == "spatial-domains"
Requires-Dist: pybanksy>=1.3.4; extra == "spatial-domains"
Provides-Extra: hpc
Requires-Dist: petsc4py<4.0,>=3.18.0; sys_platform != "win32" and extra == "hpc"
Requires-Dist: slepc4py<4.0,>=3.18.0; sys_platform != "win32" and extra == "hpc"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<2.0,>=0.23.0; extra == "dev"
Requires-Dist: black<26.0,>=22.0.0; extra == "dev"
Requires-Dist: mypy<2.0,>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: pre-commit<5.0,>=3.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

# ChatSpatial

**MCP server for spatial transcriptomics analysis via natural language**

[![Paper](https://img.shields.io/badge/bioRxiv-2026.02.26.708361-b31b1b.svg)](https://doi.org/10.64898/2026.02.26.708361)
[![MLGenX @ ICLR 2026](https://img.shields.io/badge/MLGenX%20@%20ICLR%202026-Oral-blue.svg)](https://openreview.net/forum?id=xZ814yNaUW)
[![ENAR 2026](https://img.shields.io/badge/ENAR%202026-Oral-blue.svg)](https://www.enar.org/meetings/spring2026/)
[![IBC 2026](https://img.shields.io/badge/IBC%202026-Oral-blue.svg)](https://www.ibc2026.org/home)
[![CI](https://github.com/cafferychen777/ChatSpatial/actions/workflows/ci.yml/badge.svg)](https://github.com/cafferychen777/ChatSpatial/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/chatspatial)](https://pypi.org/project/chatspatial/)
[![Python 3.11-3.13](https://img.shields.io/badge/python-3.11--3.13-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-available-blue)](https://docs.cafferyang.com/)

</div>

<p align="center">
  <img src="assets/images/overview.jpg" alt="ChatSpatial Overview" width="900">
</p>

ChatSpatial replaces ad-hoc LLM code generation with **schema-enforced orchestration**. Instead of generating arbitrary scripts, the LLM selects tools and parameters from a curated registry, making spatial transcriptomics workflows more reproducible across sessions and clients.

It exposes **60+ spatial transcriptomics methods** as MCP tools, so any MCP-compatible client can analyze data through natural language.

---

## Start Here

1. **Install ChatSpatial** — [Installation Guide](INSTALLATION.md)
2. **Configure your MCP client** — [Configuration Guide](docs/advanced/configuration.md)
3. **Run your first analysis** — [Quick Start](docs/quickstart.md)

**Minimal example prompt:**

```text
Load /absolute/path/to/spatial_data.h5ad and show me the tissue structure
```

> ChatSpatial works with **any MCP-compatible client** — Claude Code, Claude Desktop, Codex, OpenCode, and other MCP-capable tools.

---

## Capabilities

60+ methods across 11 categories. Supports 10x Visium, Xenium, Slide-seq v2, MERFISH, seqFISH.

| Category | Methods |
|----------|---------|
| **Spatial Domains** | SpaGCN, STAGATE, GraphST, BANKSY, Leiden, Louvain |
| **Deconvolution** | FlashDeconv, Cell2location, RCTD, DestVI, Stereoscope, SPOTlight, Tangram, CARD |
| **Cell Communication** | LIANA+, CellPhoneDB, CellChat (`cellchat_r`), FastCCC |
| **Cell Type Annotation** | Tangram, scANVI, CellAssign, mLLMCelltype, scType, SingleR |
| **Differential Expression** | Wilcoxon, t-test, Logistic Regression, pyDESeq2 |
| **Trajectory & Velocity** | CellRank, Palantir, DPT, scVelo, VeloVI |
| **Spatial Statistics** | Moran's I, Local Moran, Geary's C, Getis-Ord Gi*, Ripley's K, Co-occurrence, Neighborhood Enrichment, Centrality Scores, Local Join Count, Network Properties |
| **Enrichment** | GSEA, ORA, Enrichr, ssGSEA, Spatial EnrichMap |
| **Spatial Genes** | SpatialDE, SPARK-X, FlashS |
| **Integration** | Harmony, BBKNN, Scanorama, scVI |
| **Other** | CNV Analysis (InferCNVPy, Numbat), Spatial Registration (PASTE, STalign) |

---

## Documentation

| Guide | Owns |
|-------|------|
| [Installation](INSTALLATION.md) | Environment setup, package install, platform notes |
| [Quick Start](docs/quickstart.md) | First successful analysis after setup |
| [Concepts](docs/concepts.md) | Method selection and analysis reasoning |
| [Examples](docs/examples.md) | Prompt recipes and workflow examples |
| [Configuration](docs/advanced/configuration.md) | Exact MCP client configuration syntax |
| [Troubleshooting](docs/advanced/troubleshooting.md) | Symptom → fix guidance |
| [Methods Reference](docs/advanced/methods-reference.md) | Canonical tool parameters and defaults |
| [Full Docs](https://docs.cafferyang.com/) | Complete documentation site |

---

## Citation

If you use ChatSpatial in your research, please cite:

```bibtex
@article{Yang2026.02.26.708361,
  author = {Yang, Chen and Zhang, Xianyang and Chen, Jun},
  title = {ChatSpatial: Schema-Enforced Agentic Orchestration for Reproducible and Cross-Platform Spatial Transcriptomics},
  elocation-id = {2026.02.26.708361},
  year = {2026},
  doi = {10.64898/2026.02.26.708361},
  publisher = {Cold Spring Harbor Laboratory},
  URL = {https://www.biorxiv.org/content/early/2026/03/01/2026.02.26.708361},
  journal = {bioRxiv}
}
```

ChatSpatial orchestrates many excellent third-party methods. **Please also cite the original tools your analysis used.**

---

## Contributing

Documentation improvements, bug reports, and new analysis methods are all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

<div align="center">

**MIT License** · [GitHub](https://github.com/cafferychen777/ChatSpatial) · [Issues](https://github.com/cafferychen777/ChatSpatial/issues)

</div>

<!-- mcp-name: io.github.cafferychen777/chatspatial -->
