KINTSUGI
Multiplex immunofluorescence image processing pipeline with an optional MCP server for AI assistants
Install / Use
claude mcp add smith6jt-cop -- npx -y github:smith6jt-cop/KINTSUGIIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Our assessment of KINTSUGI
KINTSUGI scores 81/100 on our quality scale, 2307th of 2,758 Automation skills we index.
Its MCP Server is 39 KB long, well organised into 145 sections with 44 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 25 days ago, so KINTSUGI is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.
Automated pattern scan on 2026-11-21. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
KINTSUGI compared with similar skills
All 4 of these similar skills score higher than KINTSUGI; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| KINTSUGI (this skill)by smith6jt-cop | 81 | 10 | 25d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 120.0k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
Frequently asked questions
- How do I install KINTSUGI?
- Run
claude mcp add smith6jt-cop -- npx -y github:smith6jt-cop/KINTSUGI. The install tabs above show the steps for each supported agent. - Which AI agents does KINTSUGI work with?
- It is written for Claude Code, Claude Desktop and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is KINTSUGI safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is KINTSUGI still maintained?
- The repository was last updated 25 days ago, so KINTSUGI is actively maintained.
Skill content
View source on GitHubKINTSUGI: Knowledge Integration with New Technologies for Simplified User-Guided Image processing
Multiplex image processing for challenging datasets with a focus on user integration rather than automation. This pipeline includes 2D/3D GPU/CPU illumination correction, stitching, deconvolution, extended depth of focus, registration, autofluorescence removal, segmentation, clustering, and spatial analysis.
AI-assisted signal isolation: KINTSUGI ships an optional Model Context Protocol (MCP) server that lets the AI assistant you choose (any MCP client) drive the toolbox interactively (load, inspect, suggest, apply, assess, save, learn), with enforced tool schemas, path-safe file access, a parameter-learning loop, and an evaluation gate in CI.
Citation Information:
Smith, J. A. et al. Protocol for processing and analyzing multiplexed images improves lymphatic cell identification and spatial architecture in human tissue. STAR Protocols 6, 103976 (2025). doi:10.1016/j.xpro.2025.103976
Table of Contents
- Documentation
- Installation
- Updating Existing Projects
- Verify Installation
- Usage
- Notebooks
- HPC/SLURM Job Submission
- Troubleshooting
- Development
Documentation
Full documentation with tutorials is available at kintsugi.readthedocs.io
The documentation includes:
- Installation Guide - Detailed setup instructions for all platforms
- Quick Start - Get up and running quickly
- Processing Workflows - Step-by-step workflow guides
- MCP server - The optional MCP server: connecting your client, tools, security model, evaluation
- CLI Reference - Command line interface documentation
- API Reference - Python API documentation
- Troubleshooting - Common issues and solutions
Installation
KINTSUGI uses a streamlined base installation with optional feature groups that can be added as needed. This ensures fast environment creation and avoids dependency conflicts.
Linux
# 1. Clone the repository
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI
# 2a. Create the base conda environment from the pinned lock file (x86_64, no solver run,
# about 90 s) and add the pip-only packages
conda create -n KINTSUGI --file envs/env-linux.lock.txt
conda activate KINTSUGI
pip install -e ".[workflow]"
# 2b. Or solve the environment file instead (other architectures, or to pick up newer
# packages; conda-forge-only solves took 79 s to 25+ min in testing)
conda env create -f envs/env-linux.yml
conda activate KINTSUGI
# 3. Verify
kintsugi check
./scripts/install.sh does 2a by default (--solve for 2b). Miniconda/Anaconda users: remove the
defaults channel first, see Troubleshooting.
Windows
# 1. Clone the repository
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI
# 2. Create the base conda environment
conda env create -f envs/env-windows.yml
# 3. Activate
conda activate KINTSUGI
# 4. Download and install libvips (REQUIRED for Windows)
# Download PyVips-dev from: https://zenodo.org/records/14969214
# Extract to the KINTSUGI folder
# 5. Verify installation
kintsugi check
macOS
# 1. Install libvips (required)
brew install vips
# 2. Clone the repository
git clone https://github.com/smith6jt-cop/KINTSUGI.git
cd KINTSUGI
# 3. Create the base conda environment
conda env create -f envs/env-macos.yml
# 4. Activate and verify
conda activate KINTSUGI
kintsugi check
Optional Features
After installing the base environment, add optional features as needed. Install gpu first — other groups that need PyTorch depend on it for CUDA-enabled builds.
Important: Always use
kintsugi installcommands — never runpip install torchdirectly, as it installs a CPU-only build that breaks GPU processing.
# Step 1: GPU acceleration (install this FIRST — provides CUDA torch + CuPy)
kintsugi install gpu
# Step 2 (HPC only): Snakemake workflow orchestration
kintsugi install workflow
kintsugi patch slurm # Required for SLURM >= 24.11
# Step 3: Additional features as needed
kintsugi install dl # Deep learning segmentation (InstanSeg)
kintsugi install analysis # Spatial analysis (scanpy, scimap)
kintsugi install viz # Napari interactive visualization
kintsugi install bio # Bio formats I/O (OME-TIFF, LIF)
kintsugi install mcp # MCP server for AI assistants
kintsugi install dev # Development tools (pytest, ruff, black)
# Or install everything at once (resolves all constraints together)
kintsugi install all
# Step 4: Verify everything is correct
kintsugi check --strict
All kintsugi install commands automatically enforce a constraints.txt file that prevents known-bad version combinations (e.g., numpy 2.x). See docs/DEPENDENCY_GUIDE.md for troubleshooting.
Multi-GPU Acceleration
KINTSUGI automatically detects and uses all available NVIDIA GPUs for image processing:
from kintsugi.gpu import get_gpu_manager
gpu = get_gpu_manager()
print(gpu.summary()) # Shows all detected GPUs
GPU-Accelerated Operations:
- Illumination Correction - BaSiC algorithm with CuPy FFT
- Stitching - Phase correlation on GPU
- Deconvolution - Lucy-Richardson with GPU FFT
- Extended Depth of Focus - Variance projection on GPU
# Example: GPU-accelerated illumination correction
from kintsugi.kcorrect_gpu import KCorrectGPU
corrector = KCorrectGPU(device_id=0) # Specify GPU
flatfield, darkfield = corrector.estimate(images)
# Example: Multi-GPU stitching
from notebooks.Kstitch._translation_computation import get_multi_gpu_accelerator
accelerator = get_multi_gpu_accelerator(tile_shape)
Note: For GPU-accelerated single-cell analysis (clustering, UMAP, spatial analysis), see the rapids_singlecell repository.
Feature Requirements by Notebook:
| Notebook | Required Features |
|----------|-------------------|
| 1_Single_Channel_Eval | gpu |
| 2_Cycle_Processing | gpu |
| 3_Signal_Isolation_QC | mcp (optional) |
| 4_Segmentation_Analysis | dl, viz, analysis |
Each notebook will check for required dependencies at startup and provide installation instructions if anything is missing.
Updating Existing Projects
When KINTSUGI is updated (e.g., git pull), existing project directories may contain outdated copies of notebooks, modules, workflow scripts, or Snakefiles. Use these commands to bring them up to date.
Notebooks and Python Modules
A post-commit hook runs scripts/sync_to_projects.py automatically after every git commit, syncing notebooks and Python modules (Kreg/, Kstitch/, Kview2/, Kio.py, etc.) to all discovered project directories. The sync uses MD5 checksums — only changed files are copied.
To sync manually (e.g., after git pull):
python scripts/sync_to_projects.py # Sync all projects
python scripts/sync_to_projects.py --dry-run # Preview changes
python scripts/sync_to_projects.py --force # Force overwrite all
Note: Autoreload (
%autoreload 2) is enabled in all KINTSUGI notebooks — you do not need to restart kernels after module updates. Just re-run the relevant cell.
Workflow Scripts and Snakefile
Re-run workflow config to update the Snakefile, SLURM profiles, and add any new workflow scripts:
kintsugi workflow config /path/to/project
| File | Update behavior | |------|-----------------| | Snakefile | Always overwritten (pipeline logic must stay current) | | profiles/ | Always overwritten (SLURM settings, precommand) | | scripts/*.py | Only added if missing (existing scripts are preserved) |
Updating existing workflow scripts: If a workflow script has been updated in the repo (e.g., registration.py, qc_report.py), workflow config will not overwrite the project's copy. To update, delete the stale script and re-run config:
# Update a single script
rm /path/to/project/workflow/scripts/registration.py
kintsugi workflow config /path/to/project
# Or update all scripts at once
rm /path/to/project/workflow/scripts/*.py
kintsugi workflow config /path/to/project
For bulk updates across many projects:
# Copy all current scripts to every configured project
for proj_scripts in /path/to/KINTSUGI_Projects/*/workflow/scripts/; do
[ -d "$proj_scripts" ] || continue
cp workflow/scripts/*.py "$proj_scripts/"
done
Verify Installation
After installation, verify everything is working:
# Check all dependencies
kintsugi check
# Show version info
kintsugi info
# Generate config template
kintsugi template -o my_config.json
External Dependencies
| Dependency | Purpose | Installation |
|------------|---------|--------------|
| libvips | High-performance image I/O | conda install libvips (Linux), brew install vips (macOS), or Zenodo (Windows) |
| VALIS | Image registration | Included in base install |
| CuPy | GPU acceleration (optional) | kintsugi install gpu |
| PyTorch | Deep learning (optional) | kintsugi install gpu (CUDA build) |
| RAPIDS | GPU data science (optional) | See installation docs |
Note: Java, Maven, and FIJI/CLIJ2 are no longer required. KINTSUGI now uses pure Python implementations (CuPy/NumPy) for all processing including Extended Depth of Focus (EDF).
Usage
Command Line Interface
KINTSUGI provides a CLI for common operations:
# Check dependencies and show system info
kintsugi check
kintsugi inf
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
120.0kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
