scvi-tools-mcp block diagram

Architecture map for the scvi-tools-mcp package: MCP client consumers, a FastMCP stdio server, nine tool-module groups (model guidance, data preparation, tutorials, workflows, API reference, hub, scviva-tools, scib-metrics, troubleshooting), shared utilities, a structured Markdown/JSON knowledge base bundled with the package, and an offline build-script pipeline that populates the knowledge base from upstream notebooks, documentation, community sources, and Hugging Face Hub metadata.

Layer colors

MCP clients
FastMCP server
Tool modules
Shared utilities
Knowledge base
Build scripts

Arrows

MCP protocol / call chain
file read (knowledge base)
Consumer

MCP clients

Any MCP-compatible AI client connects over the Model Context Protocol. Claude Desktop and Claude Code are the primary consumers; any agent framework that supports MCP (Zed, Cursor, custom LLM agents) works out of the box. The server exposes 25 registered tools.

Claude Desktop Claude Code MCP agent SDKs 25 tools exposed
stdio · MCP
MCP Server · FastMCP · src/scvi_tools_mcp/

scvi-tools-mcp server

main.py is the CLI entry point — run_app() calls mcp.run(transport="stdio"). mcp.py holds the FastMCP singleton and its system prompt. Tool modules self-register via @mcp.tool() on import — no manual wiring needed. Deployable as a Docker container or via pip install.

main.py · run_app() mcp.py · FastMCP Dockerfile pip install
@mcp.tool()

Tool modules

src/scvi_tools_mcp/tools/ — 9 modules · 25 registered tools

Model guidance · _model_guidance.py

Model Guidance

Recommends and explains scvi-tools models ranked by suitability for a given task and data type. Entry point for any model-selection workflow.

recommend_model get_model_overview get_model_parameters
Data preparation · _data_prep.py

Data Preparation

Generates exact setup_anndata() calls and validates AnnData obs / var requirements for each model before training.

get_setup_anndata_guide validate_data_requirements
Hub models · _hub.py

Hugging Face Hub

Lists, inspects, and suggests official scvi-tools Hugging Face Hub model repos from a bundled quarterly snapshot. No runtime network calls.

list_hub_models get_hub_model suggest_hub_models
scviva-tools · _scviva.py

scviva-tools

Lists and retrieves API reference + user guide docs for the companion spatial toolkit (ResolVI, DestVI, scVIVA, GIMVI, DiagVI, Stereoscope, Tangram, Harreman) plus its embedded tutorials. Synced monthly, no runtime network calls.

list_scviva_models get_scviva_model list_scviva_tutorials get_scviva_tutorial
scib-metrics · _scib_metrics.py

scib-metrics

Lists and retrieves API reference for the 12 scib-metrics integration-benchmarking functions and the Benchmarker/BioConservation/BatchCorrection orchestration classes, plus its tutorials. Synced monthly, no runtime network calls.

list_scib_metrics get_scib_metric list_scib_metrics_tutorials get_scib_metrics_tutorial
Tutorials · _tutorials.py

Tutorials

Lists, retrieves, and keyword-searches paginated Markdown tutorials derived from scvi-tools Jupyter notebooks across 12 categories.

list_tutorials get_tutorial search_tutorials
Workflows · _workflows.py

Workflow Templates

Returns runnable, commented Python templates for common analysis tasks and downstream result extraction after training.

get_workflow_template get_downstream_guide
API reference · _api_reference.py

API Reference

Looks up and keyword-searches the full scvi-tools public API surface — class signatures, method docs, and parameter tables.

get_api_reference search_api
Troubleshooting · _troubleshooting.py

Troubleshooting & FAQ

Surfaces FAQ answers from Discourse community threads and runs broad keyword search across all knowledge files.

get_faq search_knowledge
call
Shared utilities · tools/utils.py

Utilities

get_knowledge_dir() resolves the package-bundled knowledge path at runtime. truncate() enforces MCP response size limits. paginate() handles multi-page tutorial delivery, returning page and total_pages for large files.

get_knowledge_dir() truncate() paginate()
Constants · tools/_constants.py

Constants

MODEL_NAMES — a typed Literal union of all 30+ supported model names. Shared across tool modules for Pydantic parameter validation.

MODEL_NAMES 30+ models
file I/O

Knowledge base

src/scvi_tools_mcp/knowledge/ — static Markdown and JSON, bundled with the package

models/

Model Docs

30+ MD files. One per model: scvi, scanvi, totalvi, peakvi, multivi, mrvi, resolvi, …

api/

API Reference

15 MD files. Per-model API signatures, parameter tables, and docstrings.

tutorials/

Tutorials

12 categories (scrna, multimodal, spatial, atac, hub, r, cytometry, …). Notebook-derived MD.

hub/

Hub Registry

Quarterly Hugging Face snapshot: 121 pretrained scvi-tools repos with class, modality, tissue, and files.

scviva_tools/

scviva-tools

8 model docs + API reference + 11 tutorials for the companion spatial toolkit (ResolVI, DestVI, scVIVA, …).

scib_metrics/

scib-metrics

15 API MD files (12 metrics + Benchmarker/BioConservation/BatchCorrection) + 2 tutorials.

skills/

Skills

20+ MD files. Step-by-step workflow recipes referenced by Claude Code skills.

user_guide/

User Guide

8 guides: training config, callbacks, multi-GPU, model saving, hyperparameter tuning, criticism.

background/

Background

5 MD files: variational inference, DE, transfer learning, counterfactual prediction.

faq/

FAQ

Discourse thread extracts. Community-sourced answers to common scvi-tools questions.

generates ↑

Build scripts

scripts/ — run offline to populate and refresh the knowledge base

scripts/convert_notebooks.py

Notebook Converter

Downloads scvi-tools Jupyter notebooks from upstream and converts them to Markdown for the tutorials/ knowledge directory.

scripts/scrape_external.py

External Scraper

Scrapes upstream documentation (ReadTheDocs, Discourse, GitHub) into background/ and faq/ knowledge.

scripts/extract_api_docs.py

API Doc Extractor

Extracts API signatures and docstrings from the installed scvi-tools package into api/ knowledge files.

scripts/scrape_huggingface_hub.py

Hub Snapshotter

Fetches public scvi-tools Hugging Face model metadata into hub/models.json and hub/summary.md.

scripts/extract_scviva_api_docs.py

scviva-tools Extractor

Extracts API signatures/docstrings from the installed scviva-tools package into scviva_tools/models/ and scviva_tools/api/, via shared _apidoc_utils.py.

scripts/extract_scib_metrics_api_docs.py

scib-metrics Extractor

Extracts API signatures/docstrings from the installed scib-metrics package into scib_metrics/api/, via shared _apidoc_utils.py.