# Skore MCP server

Community MCP server for [Skore](https://docs.skore.probabl.ai/stable/) — not affiliated with Probabl. It exposes [MCP](https://modelcontextprotocol.io/) tools for projects, `evaluate` / `compare` / `train_test_split`, global `configuration`, and a **`skore_report_call` dispatcher** that covers the report surface documented in the Skore API (e.g. [`ComparisonReport.get_predictions`](https://docs.skore.probabl.ai/stable/reference/api/skore.ComparisonReport.get_predictions.html), metrics, inspection, `data.analyze`). Call **`skore_api_catalog`** for the exact allowlisted method names per accessor.

**Repository:** [github.com/fanfcorp/skore-mcp](https://github.com/fanfcorp/skore-mcp)

## Requirements

- Python **3.10+** (same as Skore 0.15)
- Dependencies: `skore`, `mcp[cli]`, `pandas` (see `pyproject.toml`)

## Install

**From PyPI** (after the package is published):

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install skore-mcp
```

**From GitHub** (any time, no PyPI needed):

```bash
pip install "skore-mcp @ git+https://github.com/fanfcorp/skore-mcp.git"
```

**From a local clone** (editable for development):

```bash
cd "/path/to/skore-mcp"
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .
```

After install, run the server as **`skore-mcp`** or **`python -m skore_mcp`** (stdio MCP).

## Cursor / Claude Desktop

Add a stdio server (use your real paths):

```json
{
  "mcpServers": {
    "skore": {
      "command": "/path/to/MCP Skore/.venv/bin/python",
      "args": ["-m", "skore_mcp"],
      "env": {
        "SKORE_WORKSPACE": "/path/to/your/skore/workspace"
      }
    }
  }
}
```

Alternatively, after `pip install` into an environment:

```json
{
  "mcpServers": {
    "skore": {
      "command": "skore-mcp"
    }
  }
}
```

## Tools

| Tool | Purpose |
|------|--------|
| `skore_info` | Skore version and mode hints |
| `skore_api_catalog` | JSON allowlists for `skore_report_call` (accessors + method names) |
| `skore_hub_login` | Hub auth for the current process (optional `api_key`) |
| `skore_project_summarize` | CSV of `Project.summarize()` |
| `skore_report_metrics` | Shortcut: metrics summary CSV for one report id |
| `skore_evaluate_csv` | `skore.evaluate` on a CSV; returns `session_report_key`; optional `put` into a project |
| `skore_project_delete` | Delete a local/hub project |
| `skore_show_versions` | `skore.show_versions()` output |
| `skore_configuration_get` / `skore_configuration_set` | Read/write `skore.configuration` |
| `skore_train_test_split_csv` | `skore.train_test_split` on a CSV → train/test CSV blobs |
| `skore_estimator_report_from_split_csv` | Build `EstimatorReport` from CSV; returns `session_report_key` |
| `skore_compare_persisted_reports` | `skore.compare` on reports from a `Project` |
| `skore_compare_session_reports` | `skore.compare` on in-memory session reports |
| `skore_report_call` | Call `get_predictions`, `cache_predictions`, `metrics.*`, `inspection.*`, `data.*`, etc. |
| `skore_session_release` | Drop a `session_report_key` from memory |

### Session keys

`skore_evaluate_csv` always registers the report in-memory and returns **`session_report_key`**. Use that with `skore_report_call` (and `skore_compare_session_reports`) without persisting to a project. Persisted reports use **`project_name` + `report_id`** (id from `summarize`) instead.

### API coverage

Skore’s Python API is large (many classes and plot objects). This server maps **one tool** (`skore_report_call`) to the methods Skore exposes on reports and accessors, with an explicit allowlist so behavior stays predictable. Plots are returned as **base64 PNG** and tables as **CSV in JSON** when serialization supports it. It is not a line-for-line duplicate of every overload in the docs, but it covers the public patterns for reports, metrics, inspection, and data analysis.

Hub projects use `project_name` like `workspace_slug/project_slug` per Skore docs. Call `skore_hub_login` (or your hub plugin’s env vars) before hub operations.

## Notes

- On **SQLite 3.41+**, the server applies a small compatibility patch for `diskcache` (used by local Skore storage) so local projects work on current macOS/Python builds.
- Logs go to **stderr**; do not print to stdout when using stdio MCP.

## License

This project is licensed under the MIT License — see [LICENSE](LICENSE). [Skore](https://github.com/probabl-ai/skore) and other dependencies remain under their own licenses.

## Publish or clone from GitHub

### PyPI via Trusted Publishing (recommended)

The repo includes [`.github/workflows/publish.yml`](.github/workflows/publish.yml). On [PyPI → skore-mcp → Publishing](https://pypi.org/manage/project/skore-mcp/settings/publishing/) (or when creating the project), add a **pending publisher**:

| Field | Value |
|--------|--------|
| **Owner** | `fanfcorp` (or your GitHub org/user) |
| **Repository** | `skore-mcp` |
| **Workflow name** | `publish.yml` |
| **Environment** | *(leave empty unless you add `environment: pypi` to the job)* |

Then merge the workflow on `main`, bump the version in `pyproject.toml` / `skore_mcp/__init__.py`, and **create a GitHub Release** (or run the workflow manually with **Actions → Publish to PyPI → Run workflow**). The release event triggers the upload; no long-lived `PYPI_API_TOKEN` is required.

### Clone

After cloning:

```bash
git clone https://github.com/fanfcorp/skore-mcp.git
cd skore-mcp
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .
```

To push updates (replace the remote URL if your fork or username differs):

```bash
git remote add origin https://github.com/fanfcorp/skore-mcp.git
git branch -M main
git push -u origin main
```

Or create the repo and push in one step (with [GitHub CLI](https://cli.github.com/) authenticated):

```bash
gh repo create fanfcorp/skore-mcp --public --source=. --remote=origin --push
```