# SHAP MCP Server (`shap-mcp`)

[![CI](https://github.com/manas/shap-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/manas/shap-mcp/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/shap-mcp.svg)](https://pypi.org/project/shap-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A lightweight, focused **Model Context Protocol (MCP)** server that exposes SHAP (SHapley Additive exPlanations) model explainability as agent-callable tools.

Designed for AI assistants (like Claude Desktop) and human data scientists to collaborate seamlessly across a **shared in-memory session**.

---

## Key Features

- **Dual Simultaneous Transports**: Standard `stdio` transport for Claude Desktop alongside a Starlette `HTTP` transport on port `8765` serving the Web GUI and generated visualisations.
- **Unified In-Memory Session**: Run analysis via the Web GUI and ask questions in Claude, or have Claude trigger analysis and view generated plots instantly in the GUI gallery.
- **Universal Model Support**:
  - `tree`: Exact TreeExplainer for XGBoost, LightGBM, CatBoost, RandomForest, ExtraTrees.
  - `linear`: Fast closed-form LinearExplainer for Logistic Regression, Ridge, Lasso.
  - `deep`: DeepExplainer for PyTorch neural networks.
  - `kernel`: Model-agnostic KernelExplainer with automatic kmeans clustering.
- **Publication-Ready Visualisations**: Generate and save 6 plot types (`summary`, `bar`, `waterfall`, `force`, `dependence`, `heatmap`) with pre-formatted clickable browser and local file links.
- **URL & File Ingestion**: Ingest models and CSV datasets from local paths or public HTTP/HTTPS URLs with streaming downloads, automatic size caps (`SHAP_MCP_MAX_DOWNLOAD_MB`), and temp-file cleanup.
- **Security**: Optional API key authentication via `SHAP_MCP_API_KEY` for HTTP endpoints.

---

## Installation

```bash
# Standard installation
pip install shap-mcp

# Optional extra for PyTorch DeepExplainer support
pip install shap-mcp[deep]
```

---

## Claude Desktop Configuration

Add `shap-mcp` to your `claude_desktop_config.json`:

### Universal Recommended Setup (via `uvx`)

```json
{
  "mcpServers": {
    "shap-mcp": {
      "command": "uvx",
      "args": ["shap-mcp", "--no-ui"]
    }
  }
}
```

### Direct Pip / Pipx Setup

```json
{
  "mcpServers": {
    "shap-mcp": {
      "command": "shap-mcp",
      "args": ["--no-ui"]
    }
  }
}
```

---

## Tool Reference

| Tool | Purpose | Key Inputs |
|------|---------|------------|
| `load_model` | Load `.joblib`/`.pkl` model and configure explainer | `model_path` or `model_url`, `model_type`, `background_path` |
| `run_analysis` | Compute SHAP values over dataset | `data_path` or `data_url` or inline `data`, `sample_size` |
| `get_feature_importance` | Global ranking of top features | `top_n` (default 10) |
| `explain_prediction` | Local attribution breakdown for single instance | `index` or arbitrary `data` record |
| `get_interaction` | Pairwise feature interaction strength (Tree models) | `feature_a`, `feature_b` |
| `get_plot` | Render & save PNG visualisation with clickable URL | `plot_type`, `index`, `feature_name`, `color_feature`, `top_n` |

---

## Runtime Configuration

All runtime configuration is managed via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `SHAP_MCP_PORT` | `8765` | HTTP server port (auto-increments if busy; `--port` flag overrides) |
| `SHAP_MCP_API_KEY` | *(unset)* | Bearer token for HTTP auth; unset = no auth required on localhost |
| `SHAP_MCP_OUTPUT_DIR` | `./outputs/` | Root directory for saving generated plot PNGs |
| `SHAP_MCP_MAX_DOWNLOAD_MB` | `500` | Maximum allowed size cap for URL-based model/dataset downloads |
| `SHAP_MCP_LOG_LEVEL` | `INFO` | Structured JSON log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

---

## Web GUI

When started directly via `shap-mcp`, the server automatically opens the Web GUI at `http://localhost:8765/ui/`:

- **Configuration Form**: Input local paths or URLs, pick model architecture, and run analysis.
- **Real-Time Badges**: Live model loaded status, rows analyzed count, and active explainer type.
- **Dynamic Plot Gallery**: Thumbnails appear automatically as Claude or the GUI generates visualisations.
- **Instance Explainer**: Interactive table of individual feature contributions.

---

## Upcoming Features & Roadmap

The following capabilities are planned for upcoming releases:

- **`save_analysis` / `load_analysis`**: Serialize computed SHAP values to `.npz` files to skip re-computation on reload and share results across teams.
- **Auth-Protected Remote Ingestion**: Support for Hugging Face tokens, private S3/GCS buckets, and presigned URLs.
- **Tabbed GUI & Progressive Disclosure**: Redesign the Web GUI into clean, focused tabs with progressive unlocking as analysis completes.
- **Interactive Visualisations**: Pan, zoom, and tooltip hover support on matplotlib charts via `mpld3`.
- **Plot-Specific Guided Prompts**: Dedicated MCP prompts tailored for each of the 6 visualization types.
- **Multi-Tenant Session Isolation**: Connection-isolated session states for shared multi-user server deployments.
- **Additional Model Formats**: Native support for ONNX runtime, MLflow models, and Weights & Biases model registries.
- **Fairness & Bias Disaggregation**: Per-subgroup demographic parity and slice-based SHAP analysis.
- **MCP-UI Inline Canvas & Local Drag-and-Drop**: Direct in-chat canvas rendering via the MCP-UI / MCP Apps specification with local drag-and-drop file ingestion, eliminating external browser tabs and cloud attachment friction.

---

## License

MIT License. See [LICENSE](LICENSE) for details.