scvi-tools-mcp 0.1.0__tar.gz

scvi_tools_mcp-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.ruff_cache/
+.pytest_cache/
+*.h5ad
+*.h5
+.ipynb_checkpoints/
+*.log
+.DS_Store
+htmlcov/
+.coverage
+.idea/
+node_modules/

scvi_tools_mcp-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Yosef Lab, Weizmann Institute of Science
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

scvi_tools_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: scvi-tools-mcp
+Version: 0.1.0
+Summary: MCP server for scvi-tools - deep probabilistic analysis of single-cell omics data
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: jupyter; extra == 'dev'
+Requires-Dist: nbconvert>=7.0; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: requests>=2.28; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2023.0; extra == 'docs'
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: scvi
+Requires-Dist: scvi-tools>=1.0; extra == 'scvi'
+Description-Content-Type: text/markdown
+
+# scvi-tools-mcp
+
+An MCP (Model Context Protocol) server that gives LLMs structured access to [scvi-tools](https://scvi-tools.org)
+knowledge: model documentation, tutorials, API reference, workflow templates, and community FAQ.
+
+No runtime model execution — pure knowledge layer. Works with Claude Desktop, Cursor, and any MCP-compatible client.
+
+______________________________________________________________________
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "scvi-tools": {
+      "command": "uvx",
+      "args": ["scvi-tools-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / other clients
+
+```json
+{ "command": "uvx", "args": ["scvi-tools-mcp"] }
+```
+
+### Local install
+
+```bash
+pip install scvi-tools-mcp
+scvi-tools-mcp
+```
+
+______________________________________________________________________
+
+## Tools
+
+| Tool                         | Description                                            |
+| ---------------------------- | ------------------------------------------------------ |
+| `recommend_model`            | Rank models by task and data type — start here         |
+| `get_model_overview`         | Full model description, use cases, inputs, outputs     |
+| `get_model_parameters`       | Key `__init__` and `train()` parameters with defaults  |
+| `get_setup_anndata_guide`    | Exact `setup_anndata()` call + required obs/var fields |
+| `validate_data_requirements` | Pass/fail checklist for your AnnData against a model   |
+| `list_tutorials`             | Browse tutorials by category                           |
+| `get_tutorial`               | Paginated tutorial content (code + prose, no outputs)  |
+| `search_tutorials`           | Keyword search across all tutorials                    |
+| `get_api_reference`          | Signature + docstring for any public class or function |
+| `search_api`                 | Search public symbols by keyword                       |
+| `get_workflow_template`      | Step-by-step code template for an analysis task        |
+| `get_downstream_guide`       | Guide for DE, clustering, embedding, label transfer    |
+| `get_faq`                    | Curated FAQ from docs, GitHub issues, and Discourse    |
+| `search_knowledge`           | Cross-search all knowledge (catch-all)                 |
+
+______________________________________________________________________
+
+## Knowledge Sources
+
+All knowledge is baked into the package as Markdown files at build time. No network calls at tool-call time.
+
+| Directory                            | Content                                                   |
+| ------------------------------------ | --------------------------------------------------------- |
+| `knowledge/models/`                  | One `.md` per model — description, use case, parameters   |
+| `knowledge/tutorials/`               | 60+ tutorials converted from `.ipynb` (code + prose only) |
+| `knowledge/api/`                     | Extracted class signatures and docstrings                 |
+| `knowledge/user_guide/`              | Narrative documentation from the scvi-tools user guide    |
+| `knowledge/faq/github_issues.md`     | Top GitHub issues snapshot                                |
+| `knowledge/faq/discourse_threads.md` | Discourse forum thread snapshot                           |
+
+______________________________________________________________________
+
+## Knowledge Refresh (CI)
+
+Three monthly GitHub Actions jobs keep knowledge current — each opens a PR if a diff is found:
+
+| Workflow                    | Schedule     | What it does                                                |
+| --------------------------- | ------------ | ----------------------------------------------------------- |
+| `refresh_knowledge.yaml`    | 1st of month | Re-scrapes GitHub issues + Discourse threads                |
+| `sync_tutorials.yaml`       | 1st of month | Fetches new `.ipynb` from scvi-tools, converts to `.md`     |
+| `sync_model_knowledge.yaml` | 1st of month | Checks CHANGELOG, regenerates model docs for changed models |
+
+All workflows also support `workflow_dispatch` for manual runs.
+
+______________________________________________________________________
+
+## Development
+
+```bash
+git clone https://github.com/ori-kron-wis/scvi-tools-mcp
+cd scvi-tools-mcp
+pip install -e ".[dev]"
+pytest
+```
+
+### Rebuild knowledge manually
+
+```bash
+# Convert tutorials from a local scvi-tools checkout
+python scripts/convert_notebooks.py /path/to/scvi-tools/docs/tutorials/notebooks \
+    src/scvi_tools_mcp/knowledge/tutorials
+
+# Extract API docs (requires scvi-tools installed)
+pip install -e ".[scvi]"
+python scripts/extract_api_docs.py
+
+# Re-scrape external knowledge
+python scripts/scrape_external.py
+```
+
+### Adding a new model
+
+1. Run `scripts/extract_api_docs.py` after updating scvi-tools.
+1. Add the model name to `MODEL_NAMES` in `src/scvi_tools_mcp/tools/_constants.py`.
+1. Add requirements to `MODEL_REQUIREMENTS` in `_data_prep.py` if needed.
+
+______________________________________________________________________
+
+## License
+
+MIT

scvi_tools_mcp-0.1.0/README.md

@@ -0,0 +1,126 @@
+# scvi-tools-mcp
+
+An MCP (Model Context Protocol) server that gives LLMs structured access to [scvi-tools](https://scvi-tools.org)
+knowledge: model documentation, tutorials, API reference, workflow templates, and community FAQ.
+
+No runtime model execution — pure knowledge layer. Works with Claude Desktop, Cursor, and any MCP-compatible client.
+
+______________________________________________________________________
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "scvi-tools": {
+      "command": "uvx",
+      "args": ["scvi-tools-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / other clients
+
+```json
+{ "command": "uvx", "args": ["scvi-tools-mcp"] }
+```
+
+### Local install
+
+```bash
+pip install scvi-tools-mcp
+scvi-tools-mcp
+```
+
+______________________________________________________________________
+
+## Tools
+
+| Tool                         | Description                                            |
+| ---------------------------- | ------------------------------------------------------ |
+| `recommend_model`            | Rank models by task and data type — start here         |
+| `get_model_overview`         | Full model description, use cases, inputs, outputs     |
+| `get_model_parameters`       | Key `__init__` and `train()` parameters with defaults  |
+| `get_setup_anndata_guide`    | Exact `setup_anndata()` call + required obs/var fields |
+| `validate_data_requirements` | Pass/fail checklist for your AnnData against a model   |
+| `list_tutorials`             | Browse tutorials by category                           |
+| `get_tutorial`               | Paginated tutorial content (code + prose, no outputs)  |
+| `search_tutorials`           | Keyword search across all tutorials                    |
+| `get_api_reference`          | Signature + docstring for any public class or function |
+| `search_api`                 | Search public symbols by keyword                       |
+| `get_workflow_template`      | Step-by-step code template for an analysis task        |
+| `get_downstream_guide`       | Guide for DE, clustering, embedding, label transfer    |
+| `get_faq`                    | Curated FAQ from docs, GitHub issues, and Discourse    |
+| `search_knowledge`           | Cross-search all knowledge (catch-all)                 |
+
+______________________________________________________________________
+
+## Knowledge Sources
+
+All knowledge is baked into the package as Markdown files at build time. No network calls at tool-call time.
+
+| Directory                            | Content                                                   |
+| ------------------------------------ | --------------------------------------------------------- |
+| `knowledge/models/`                  | One `.md` per model — description, use case, parameters   |
+| `knowledge/tutorials/`               | 60+ tutorials converted from `.ipynb` (code + prose only) |
+| `knowledge/api/`                     | Extracted class signatures and docstrings                 |
+| `knowledge/user_guide/`              | Narrative documentation from the scvi-tools user guide    |
+| `knowledge/faq/github_issues.md`     | Top GitHub issues snapshot                                |
+| `knowledge/faq/discourse_threads.md` | Discourse forum thread snapshot                           |
+
+______________________________________________________________________
+
+## Knowledge Refresh (CI)
+
+Three monthly GitHub Actions jobs keep knowledge current — each opens a PR if a diff is found:
+
+| Workflow                    | Schedule     | What it does                                                |
+| --------------------------- | ------------ | ----------------------------------------------------------- |
+| `refresh_knowledge.yaml`    | 1st of month | Re-scrapes GitHub issues + Discourse threads                |
+| `sync_tutorials.yaml`       | 1st of month | Fetches new `.ipynb` from scvi-tools, converts to `.md`     |
+| `sync_model_knowledge.yaml` | 1st of month | Checks CHANGELOG, regenerates model docs for changed models |
+
+All workflows also support `workflow_dispatch` for manual runs.
+
+______________________________________________________________________
+
+## Development
+
+```bash
+git clone https://github.com/ori-kron-wis/scvi-tools-mcp
+cd scvi-tools-mcp
+pip install -e ".[dev]"
+pytest
+```
+
+### Rebuild knowledge manually
+
+```bash
+# Convert tutorials from a local scvi-tools checkout
+python scripts/convert_notebooks.py /path/to/scvi-tools/docs/tutorials/notebooks \
+    src/scvi_tools_mcp/knowledge/tutorials
+
+# Extract API docs (requires scvi-tools installed)
+pip install -e ".[scvi]"
+python scripts/extract_api_docs.py
+
+# Re-scrape external knowledge
+python scripts/scrape_external.py
+```
+
+### Adding a new model
+
+1. Run `scripts/extract_api_docs.py` after updating scvi-tools.
+1. Add the model name to `MODEL_NAMES` in `src/scvi_tools_mcp/tools/_constants.py`.
+1. Add requirements to `MODEL_REQUIREMENTS` in `_data_prep.py` if needed.
+
+______________________________________________________________________
+
+## License
+
+MIT

scvi_tools_mcp-0.1.0/docs/conf.py

@@ -0,0 +1,19 @@
+project = "scvi-tools-mcp"
+author = "YosefLab"
+copyright = "2024, YosefLab"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+html_theme = "furo"
+html_title = "scvi-tools MCP"
+
+exclude_patterns = ["superpowers"]

scvi_tools_mcp-0.1.0/docs/faq.md

@@ -0,0 +1,42 @@
+# Frequently asked questions
+
+Don't see what you're looking for here? Check the
+[Discourse](https://discourse.scverse.org/c/help/scvi-tools/) or use `search_knowledge` in the MCP server.
+
+## Why doesn't the MCP server run my model?
+
+By design — this is a **knowledge-only** server. It returns documentation, code templates, and
+guidance. To actually train a model, install scvi-tools and run the code that the server provides.
+
+## How do I keep the knowledge base up to date?
+
+Three monthly GitHub Actions jobs handle this automatically and open PRs when diffs are found:
+
+- `refresh_knowledge.yaml` — re-scrapes GitHub issues + Discourse
+- `sync_tutorials.yaml` — syncs tutorial notebooks from scvi-tools
+- `sync_model_knowledge.yaml` — updates model docs from the scvi-tools CHANGELOG
+
+You can also trigger them manually via `workflow_dispatch` or run the scripts locally:
+
+```bash
+python scripts/scrape_external.py
+python scripts/convert_notebooks.py --src /path/to/scvi-tutorials --dst src/scvi_tools_mcp/knowledge/tutorials
+python scripts/extract_api_docs.py
+```
+
+## Which models are covered?
+
+Run `get_model_overview` or `list_tutorials` in the MCP server. The knowledge base currently covers
+scVI, scANVI, TotalVI, MultiVI, PeakVI, LinearSCVI, MrVI, Stereoscope, CellAssign, SOLO, GIMVI,
+veloVI, ContrastiveVI, SCBASSET, SysVI, DiagVI, and more.
+
+## What is the `uvx` command?
+
+`uvx` runs a package from PyPI without installing it permanently — provided by
+[uv](https://github.com/astral-sh/uv). It is the recommended way to run MCP servers because it
+always fetches the latest published version.
+
+## Can I use this server from R?
+
+Yes — any MCP-compatible client works. Configure your client to run `uvx scvi-tools-mcp` and use
+the tools from whatever language your client supports. The server itself is language-agnostic.

scvi_tools_mcp-0.1.0/docs/index.md

@@ -0,0 +1,12 @@
+# scvi-tools MCP
+
+An MCP (Model Context Protocol) server that gives LLMs structured access to [scvi-tools](https://scvi-tools.org) — a Python library for deep probabilistic analysis of single-cell omics data.
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+installation
+faq
+references
+```

scvi_tools_mcp-0.1.0/docs/installation.md

@@ -0,0 +1,67 @@
+# Installation
+
+## Quick install
+
+```bash
+pip install scvi-tools-mcp
+```
+
+or with `uvx` (no install needed, runs directly):
+
+```bash
+uvx scvi-tools-mcp
+```
+
+## MCP client configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "scvi-tools": {
+      "command": "uvx",
+      "args": ["scvi-tools-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add scvi-tools-mcp uvx scvi-tools-mcp -s user
+```
+
+### Cursor / other MCP clients
+
+```json
+{ "command": "uvx", "args": ["scvi-tools-mcp"] }
+```
+
+## Optional: scvi-tools runtime
+
+The server itself does not require `scvi-tools`. Install it only if you want to run the
+knowledge refresh scripts locally:
+
+```bash
+pip install "scvi-tools-mcp[scvi]"
+```
+
+## Development install
+
+```bash
+git clone https://github.com/ori-kron-wis/scvi-tools-mcp
+cd scvi-tools-mcp
+pip install -e ".[dev]"
+pre-commit install
+pytest
+```
+
+## Requirements
+
+- Python ≥ 3.11
+- fastmcp ≥ 3.0
+- pydantic ≥ 2.0