Metadata-Version: 2.5
Name: vmaf-mcp
Version: 1.0.0-rc.2
Summary: MCP server exposing VMAF scoring, model listing, and benchmark runs via JSON-RPC.
Project-URL: Homepage, https://github.com/VMAFx/vmafx
Project-URL: Repository, https://github.com/VMAFx/vmafx
Project-URL: Documentation, https://vmafx.github.io/vmafx/mcp/
Project-URL: Issues, https://github.com/VMAFx/vmafx/issues
Project-URL: Changelog, https://github.com/VMAFx/vmafx/blob/master/CHANGELOG.md
Author-email: Lusoris <lusoris@pm.me>
License-Expression: BSD-2-Clause-Patent
Requires-Python: >=3.10
Requires-Dist: anyio>=4.15.1
Requires-Dist: mcp>=2.2.0
Requires-Dist: pydantic>=2.13.5
Provides-Extra: dev
Requires-Dist: mypy>=2.3.1; extra == 'dev'
Requires-Dist: prometheus-client>=0.26.0; extra == 'dev'
Requires-Dist: pytest-aiohttp>=1.1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: ruff>=0.16.9; extra == 'dev'
Provides-Extra: eval
Requires-Dist: numpy>=2.5.3; extra == 'eval'
Requires-Dist: onnxruntime>=1.30.0; extra == 'eval'
Requires-Dist: pandas>=3.0.6; extra == 'eval'
Requires-Dist: pyarrow>=25.0.1; extra == 'eval'
Requires-Dist: scipy>=1.18.1; extra == 'eval'
Provides-Extra: http
Requires-Dist: aiohttp>=3.14.3; extra == 'http'
Requires-Dist: prometheus-client>=0.26.0; extra == 'http'
Provides-Extra: vlm
Requires-Dist: accelerate>=1.15.0; extra == 'vlm'
Requires-Dist: pillow>=12.3.0; extra == 'vlm'
Requires-Dist: torch>=2.14.0; extra == 'vlm'
Requires-Dist: transformers>=5.17.0; extra == 'vlm'
Description-Content-Type: text/markdown

<!-- markdownlint-disable MD060 -->
# vmaf-mcp

> **DEPRECATED (ADR-1229).** The MCP server is now the Go binary `vmafx-mcp`
> (`cmd/vmafx-mcp/`), installed at `/usr/local/bin/vmafx-mcp` in every container
> image. Attach with `docker exec -i vmaf-dev-mcp vmafx-mcp`. This Python package
> implements the same fifteen tools and is retained for one release as a
> reference implementation; it is no longer installed by `dev/Containerfile` and
> a follow-up removes it. Do not add tools here — add them to `cmd/vmafx-mcp/`.

MCP (Model Context Protocol) server that exposes the VMAFx fork's
scoring CLI to LLM tooling via JSON-RPC over stdio.

## Tools

| Tool                    | Description                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `vmaf_score`            | Score a (ref, dis) raw YUV pair. Returns the full JSON report.                     |
| `vmaf_score_encoded`    | Score encoded video (MP4/MKV/Y4M/…) — decodes via ffmpeg, then scores. (ADR-0608) |
| `list_models`           | Enumerate models under `model/` (`.json`, `.pkl`, `.onnx`).                        |
| `list_backends`         | Report which backends (`cpu`/`cuda`/`sycl`/`hip`/`metal`) are compiled in. |
| `probe_backend`         | Runtime health check: compiled-in vs driver-functional distinction. (ADR-0608)     |
| `vmaf_version`          | Return binary path, version string, and build flags. (ADR-0608)                    |
| `run_benchmark`         | Run `testdata/bench_all.sh` on the built-in fixture pairs.                         |
| `eval_model_on_split`   | Evaluate an ONNX tiny-AI model on a parquet feature split.                         |
| `compare_models`        | Rank ONNX models on the same split by PLCC.                                        |
| Tool            | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `vmaf_score`    | Score a (ref, dis) YUV pair. Returns the full JSON report.   |
| `list_models`   | Enumerate models under `model/` (`.json`, `.pkl`, `.onnx`).  |
| `list_backends` | Report which backends (`cpu`/`cuda`/`sycl`/`hip`) are live.  |
| `run_benchmark` | Run `testdata/bench_all.sh` on a pair.                       |
| `eval_model_on_split` | Evaluate an ONNX tiny-AI model on a parquet feature split. |
| `compare_models` | Rank ONNX models on the same split by PLCC. |
| `describe_worst_frames` | Extract the lowest-VMAF frames and describe visible artefacts with local VLM extras. |

## Install

```bash
cd mcp-server/vmaf-mcp
pip install -e .
```

Requires a built `libvmaf` binary at `build/tools/vmaf` (override via
`VMAF_BIN=/abs/path/to/vmaf`).

## Run

```bash
# Stdio transport (default for Claude Desktop, Cursor, etc.)
vmaf-mcp
```

## Path allowlisting

For safety, the server only reads files under `testdata/`,
`python/test/resource/`, and `model/`. Extend via colon-separated
`VMAF_MCP_ALLOW`:

```bash
VMAF_MCP_ALLOW=/data/my-corpus:/mnt/yuv vmaf-mcp
```

## Claude Desktop config

```json
{
  "mcpServers": {
    "vmaf": {
      "command": "vmaf-mcp",
      "env": {
        "VMAF_BIN": "/home/you/dev/vmaf/build/tools/vmaf",
        "VMAF_MCP_ALLOW": "/data/yuv-corpus"
      }
    }
  }
}
```
