🧬 ChatSpatial MCP Server v0.2.0

Production-ready Model Context Protocol server for spatial transcriptomics analysis

🎯 What's New

📚 Documentation & CI Improvements

• FIXED: All broken documentation links in README.md
• ALIGNED: Feature descriptions with actual code implementation
• UPDATED: Installation guides and dependency configuration
• ENHANCED: CI workflow with Python 3.10/3.11 testing matrix
• IMPROVED: Code quality checks and automated testing

🔧 Technical Enhancements

• RESOLVED: Python version compatibility issues in CI
• OPTIMIZED: Package configuration and optional dependencies
• STANDARDIZED: Tool naming conventions (action+object pattern)
• VALIDATED: All 16 MCP tools with comprehensive error handling

🧬 Spatial Analysis Capabilities

Core Tools (16 MCP Tools):

• load_data - Multi-format spatial data loading (10x Visium, Slide-seq, MERFISH, etc.)
• preprocess_data - Quality control and normalization
• visualize_data - Spatial plots, UMAP, heatmaps with MCP-optimized rendering
• annotate_cells - Cell type annotation (Marker-based, Tangram, scANVI, CellAssign)
• find_markers - Differential expression analysis
• find_spatial_genes - GASTON (preferred), SpatialDE, SPARK methods
• identify_spatial_domains - SpaGCN (preferred), STAGATE, BANKSY, Leiden/Louvain
• analyze_cell_communication - LIANA (preferred), CellPhoneDB integration
• deconvolve_data - Cell2location (preferred), DestVI, RCTD, Stereoscope, Tangram, MRVI
• integrate_samples - Harmony, batch correction
• analyze_trajectory_data - Palantir, CellRank, DPT pseudotime
• analyze_enrichment - GSEA, ORA, Enrichr with spatial context
• analyze_spatial_data - Unified spatial analysis pipeline
• get_spatial_analysis_stats - Analysis statistics and metadata
• download_example_data - Example datasets for testing
• get_analysis_help - Interactive help and guidance

Preferred Methods (Based on performance and reliability):

• Spatial Domains: SpaGCN > STAGATE > BANKSY
• Spatial Variable Genes: GASTON > SpatialDE > SPARK
• Cell Communication: LIANA > CellPhoneDB
• Deconvolution: Cell2location > DestVI > RCTD

🚀 Installation

Quick Start

# Full installation (recommended)
pip install -e .[all]

# Or install specific feature sets
pip install -e .[advanced]     # Core spatial analysis methods
pip install -e .[enrichmap]    # EnrichMap spatial enrichment
pip install -e .[experimental] # Experimental features
pip install -e .[dev]          # Development tools

MCP Client Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "chatspatial": {
      "command": "python3",
      "args": ["-m", "chatspatial"],
      "env": {
        "PYTHONPATH": "/path/to/chatspatial"
      }
    }
  }
}

Cherry Studio (Recommended for longer analyses):

• Supports configurable timeouts (>4 minutes)
• Better handling of large spatial datasets
• Enhanced visualization support

📊 Supported Data Formats

• 10x Genomics: Visium, Xenium, Chromium
• Slide-seq: v1, v2
• MERFISH: Vizgen platform
• seqFISH+: Spatial sequencing
• STARmap: 3D spatial transcriptomics
• Standard formats: H5AD, CSV, TSV, HDF5, Zarr

🔬 Example Workflows

Basic Spatial Analysis

1. "Load my 10x Visium dataset from /path/to/data.h5ad"
2. "Preprocess with genes in ≥10 cells and cells with ≥500 genes"
3. "Identify spatial domains using SpaGCN"
4. "Visualize spatial domains"

Cell Communication Analysis

1. "Annotate cell types using marker genes"
2. "Analyze cell communication using LIANA with cosine similarity"
3. "Visualize communication for VEGFA-KDR interaction"

Advanced Deep Learning

1. "Find spatial variable genes using GASTON with GLM-PCA"
2. "Deconvolve spatial data using Cell2location"
3. "Visualize deconvolution results and GASTON isodepth map"

🛠️ System Requirements

• Python: 3.10+ (3.11 recommended)
• Memory: 8GB+ RAM (16GB+ for large datasets)
• Storage: 2GB+ free space
• OS: macOS, Linux, Windows (WSL2)

📖 Documentation

| Document | Description |
|----------|-------------|
| INSTALLATION.md | Detailed installation and setup guide |
| Error Handling Guide | Troubleshooting and error resolution |
| Dataset Guide | Dataset management and organization |
| Project Structure | Codebase architecture and organization |

🔄 Migration from v0.1.x

• Tool Names: Updated to consistent action+object pattern
• Dependencies: Moved CellPhoneDB from experimental to advanced
• Python Version: Now requires Python 3.10+ (was 3.8+)
• CI/CD: Enhanced testing and quality checks

🐛 Known Issues & Limitations

• Claude Desktop: 4-minute timeout limit (use Cherry Studio for longer analyses)
• Large Datasets: >50k cells may require memory optimization
• Visualization: Images displayed as object references in Claude Desktop

🤝 Contributing

We welcome contributions! Please see:

• CONTRIBUTING.md - Contribution guidelines
• SECURITY.md - Security policy
• PROJECT_STRUCTURE.md - Technical documentation

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Model Context Protocol: Anthropic's MCP specification
• Spatial Analysis Methods: GASTON, SpaGCN, LIANA, Cell2location communities
• Python Ecosystem: scanpy, squidpy, anndata, and spatial transcriptomics tools

Full Changelog: v0.1.2...v0.2.0

Installation: pip install -e .[all]
MCP Integration: See INSTALLATION.md for client setup
Support: Open an issue for help

🚀 Release v0.1.1

🛠 GitHub Actions Improvements

• ✅ Fixed all GitHub Actions workflows
• ✅ Resolved dependency resolution issues
• ✅ Added minimal test workflow for quick validation
• ✅ Improved CI/CD pipeline reliability

📊 Current Status

All workflows now passing with 100% success rate:

• CI ✅
• Tests ✅
• Code Quality ✅
• ChatSpatial Test Suite ✅
• Minimal Test ✅

🐛 Bug Fixes

• Fixed missing requirements.txt references
• Fixed pip install dependency resolution depth issues
• Fixed black formatter strict mode failures
• Fixed missing run_tests.py references

📦 Package Improvements

• Improved pyproject.toml dependency management
• Better error handling in workflows
• Simplified test matrix for faster CI

Full Changelog: https://github.com/cafferychen777/ChatSpatial/compare/v0.1.0...v0.1.1

ChatSpatial v0.1.0 - Initial Release

🎉 Features

Core Functionality:

• Interactive spatial transcriptomics analysis through Model Context Protocol (MCP)
• Support for multiple spatial data formats (10x Visium, Slide-seq, MERFISH, seqFISH)
• Enhanced data preprocessing with user-controlled filtering and subsampling
• Comprehensive spatial visualization capabilities

Advanced Analysis Methods:

• GASTON Integration: Deep learning-based spatial variable gene identification
• LIANA+ Cell Communication: Fast ligand-receptor interaction analysis
• scvi-tools Integration: CellAssign, scANVI, DestVI, Stereoscope methods
• Spatial Domain Identification: SpaGCN and clustering-based methods
• Spatial Statistics: Moran's I, Getis-Ord Gi* hot/cold spot analysis

Deconvolution Methods:

• Cell2location, DestVI, Stereoscope integration
• Traditional NNLS and RCTD methods
• Apple MPS acceleration support

Data Integration:

• Multi-sample integration with Harmony, BBKNN, Scanorama
• Trajectory analysis with CellRank and scVelo
• Comprehensive cell type annotation tools

🛠️ Technical Improvements

• Standardized image processing module
• Optimized performance for interactive usage
• Comprehensive error handling and validation
• Modular architecture with clean separation of concerns

📚 Documentation

• Complete installation and usage guide
• Claude Desktop integration instructions
• Comprehensive API documentation
• Example workflows and use cases

🔧 Installation

pip install -e .
pip install -e .[all]  # Install all optional dependencies

🚀 Usage with Claude Desktop

See README.md for detailed Claude Desktop integration instructions.

📋 Requirements

• Python >=3.8
• See pyproject.toml for complete dependency list