vmaf-mcp 1.0.0rc1__tar.gz

vmaf_mcp-1.0.0rc1/.gitignore

@@ -0,0 +1,233 @@
+# Caches, build artifacts
+.DS_Store
+.cache/
+# Rust build artifacts
+target/
+# Editor / refactor scratch backups — never in tree (ADR-0546 audit cleanup
+# bundle surfaced a 142 KB `tools/vmaf-tune/src/vmaftune/cli.py.bak` that
+# had been polluting greps for weeks).
+*.bak
+*.orig
+*.egg*
+.idea/
+*.py[cod]
+.tox/
+.*version
+# Virtual environments. No trailing slash on the second pattern: `.venv*/`
+# matches only DIRECTORIES, so a symlink named `.venv` sailed past it and was
+# committed by #1231. That symlink pointed at the maintainer's own absolute
+# venv path, so every fresh checkout materialised a self-referential loop and
+# `git pull` replaced anyone's real (ignored, hence disposable) venv with it.
+.venv*/
+.venv*
+__pycache__/
+build/
+build-golden/
+core/build-golden/
+dist/
+vmaf_output.xml
+compile_commands.json
+
+# tiny-AI training artifacts (re-generated by ai/scripts/train_konvid.py).
+# The contents of ai/data/ are gitignored EXCEPT the ADR-0203 Python
+# modules. We use the "ignore everything inside the dir, then re-allow
+# .py" pattern so the dir itself stays tracked for the modules below.
+ai/data/*
+!ai/data/__init__.py
+!ai/data/netflix_loader.py
+!ai/data/feature_extractor.py
+!ai/data/scores.py
+# Phase F.5 calibrated recipe overrides (ADR-0325).
+# Tracked as a tiny JSON snapshot — regenerated by
+# ai/scripts/calibrate_phase_f_recipes.py against a real corpus.
+!ai/data/phase_f_recipes_calibrated.json
+# ADR-0335 — hardware-capability prior table is small, hand-curated,
+# and committed in-tree (not a generated artifact).
+!ai/data/hardware_caps.csv
+runs/
+
+# Large test data (generated via testdata/generate.sh)
+testdata/*_1280x720_*.yuv
+testdata/*_1920x1080_*.yuv
+testdata/*_3840x2160_*.yuv
+testdata/bbb/*.yuv
+
+# Large binary files
+*.mp4
+*.mkv
+
+# Upstream MATLAB MEX compiled artefacts (platform-specific binaries).
+# Rebuild locally via `mex file.c` if you need the MATLAB reference path.
+# Paths follow ADR-0700 rename (python/vmaf/ → compat/python-vmaf/).
+# See Scorecard Binary-Artifacts / D38.
+compat/python-vmaf/matlab/**/*.mex
+compat/python-vmaf/matlab/**/*.mex[0-9]*
+compat/python-vmaf/matlab/**/*.mexa64
+compat/python-vmaf/matlab/**/*.mexglx
+compat/python-vmaf/matlab/**/*.mexlx
+compat/python-vmaf/matlab/**/*.mexmac
+compat/python-vmaf/matlab/**/*.mexmaci64
+compat/python-vmaf/matlab/**/*.mexsol
+compat/python-vmaf/matlab/**/*.mexw32
+compat/python-vmaf/matlab/**/*.mexw64
+compat/python-vmaf/matlab/**/*.dll
+compat/python-vmaf/matlab/**/*.exp
+compat/python-vmaf/matlab/**/*.lib
+compat/python-vmaf/matlab/**/*.o
+
+# Cython-generated C from compat/python-vmaf/core/adm_dwt2_cy.pyx
+# (produced by `python setup.py build_ext`; never tracked).
+compat/python-vmaf/core/adm_dwt2_cy.c
+compat/python-vmaf/core/adm_dwt2_cy.cpp
+
+# Local corpus data — large YUV/MP4 fixtures, never committed.
+# Was only in .git/info/exclude; now visible to all contributors.
+.corpus/
+
+# Working/scratch directories
+.workingdir/
+# Also match it as a symlink. A trailing slash only matches a real
+# directory, so an agent worktree that symlinks this shared state dir
+# in (the praetor flavor audit wants them present) leaves an untracked
+# entry that `git add -A` happily commits -- an absolute path to one
+# machine, landing in a PR. Caught exactly that way; see bug ledger L-78.
+.workingdir
+
+# vmaf-tune Phase A scratch outputs (ADR-0237)
+corpus.jsonl
+# ...but never a committed test fixture. The bare pattern above matches at any
+# depth, which silently excluded pkg/benchmark/testdata/corpus.jsonl from its
+# own PR and left the package's tests failing on a missing file.
+!**/testdata/corpus.jsonl
+tools/vmaf-tune/build/
+tools/vmaf-tune/dist/
+tools/vmaf-tune/*.egg-info/
+
+# external-bench harness scratch / binary downloads (ADR-0332)
+tools/external-bench/**/build/
+tools/external-bench/**/dist/
+tools/external-bench/**/*.bin
+tools/external-bench/**/output*.json
+tools/external-bench/**/__pycache__/
+
+# Zed per-user local settings (auth tokens, window state — machine-specific).
+# .zed/ itself IS tracked (shared project config); only the local/ subdir is not.
+.zed/local/
+
+# Claude Code local (machine-specific) settings
+.claude/settings.local.json
+.claude/scheduled_tasks.lock
+# Agent isolation worktrees (created by parallel-agent harness; machine-local).
+.claude/worktrees/
+# Local merge-train nudger + its log (machine-local operator tooling).
+.claude/mergetrain/
+
+# Generated benchmark results
+testdata/bbb/results/
+build-docs/
+preprints202604.0035.v1.pdf
+
+# Meson wrap-fetched subprojects (downloaded at meson setup time).
+# Only the .wrap files + packagefiles/ are tracked; the unpacked
+# upstream trees are gitignored.
+core/subprojects/*/
+!core/subprojects/packagefiles/
+core/subprojects/packagecache/
+core/subprojects/.wraplock
+
+# Per-run training output (per-epoch ONNX checkpoints)
+model/tiny/training_runs/
+
+# u2netp fork-local mirror (ADR-0325). Binary lives only in GitHub
+# Releases; the scaffold (license, model card, operator doc, release
+# workflow guard) is tracked, the binary itself is not.
+model/u2netp_mirror.onnx
+model/u2netp_mirror.pth
+
+# Go build artifacts (ADR-0702)
+# Compiled binaries at the repo root (from `go build ./cmd/...`).
+# Anchored with a leading "/" so the patterns match only files at the repo
+# root, not directories named "vmafx-tune" anywhere in the tree (e.g.
+# cmd/vmafx-tune/). Leading slash also prevents hiding new test files.
+/vmafx-server
+/vmafx-mcp
+/vmafx-tune
+/vmafx-controller
+/vmafx-node
+/vmafx-operator
+/vmafx-ort-runner
+# Per-package test binaries
+*.test
+# Go build cache is stored in $GOPATH/pkg, not the repo; go.sum is tracked.
+# Dist directories from per-cmd Makefile targets
+/cmd/*/dist/
+
+# Rust build artifacts (ADR-0702)
+# Workspace target directory (cargo output)
+/target/
+# Rust source backup files (rustfmt temp)
+**/*.rs.bk
+# Cargo.lock: kept for workspace binaries (this workspace's root Cargo.lock
+# is tracked); per-crate library Cargo.lock files are gitignored below.
+# Library crates inside bindings/ produce their own Cargo.lock which we
+# do NOT track (libraries let consumers pin).
+bindings/rust/**/Cargo.lock
+
+# Nsight Compute profiling artifacts
+*.ncu-rep
+
+# Generated upscaled perf benchmark fixtures (reproducible from 576x324 native)
+testdata/ref_1920x1080_48f.yuv
+testdata/dis_1920x1080_48f.yuv
+testdata/ref_2560x1440_48f.yuv
+testdata/dis_2560x1440_48f.yuv
+testdata/bbb/ref_3840x2160_30f.yuv
+testdata/bbb/dis_3840x2160_30f.yuv
+
+# Geometry-bearing wrappers generated from committed Kubernetes E2E raw clips.
+test/e2e/fixtures/ref.y4m
+test/e2e/fixtures/dist.y4m
+# kuttl may materialize a credential-bearing kubeconfig in its working
+# directory; the harness uses only the dedicated file below RUNNER_TEMP.
+/kubeconfig
+
+# Pyright strict-audit config (ADR-0888). Intentionally local-only —
+# shipping it would surface ~1,600 stub-cascade errors as a CI gate
+# before the long-tail cleanup is done. Operators re-run with
+# `pyright -p pyrightconfig.audit.json --outputjson <pkg>/`.
+pyrightconfig.audit.json
+
+# Fuzzer-generated corpus growth (seed entries are not tracked)
+core/test/fuzz/*_corpus/
+
+# Netflix golden-data YUV fixtures (CLAUDE.md section 8). Downloaded by
+# scripts/test/fetch-test-yuvs.sh, deliberately untracked because of their size
+# -- but they are the numerical ground truth, so they must never be reachable by
+# `git clean -xfd`. Ignoring them makes clean skip them and keeps them out of
+# `git status` noise.
+python/test/resource/yuv/
+python/test/resource/test_image_yuv/
+
+# Cython extension built in-place by compat/python-vmaf (setup.py build_ext).
+compat/python-vmaf/core/*.so
+
+# Per-host sidecar identity cache, written at runtime by vmafx-tune sidecar.
+# Machine-local state, never a build input (ADR-0237-style scratch).
+relcache/
+
+# Test artifact: vmaftune.encode probes ffmpeg with `[ffmpeg_bin, "-version"]`,
+# and a stubbed binary in the test suite leaves a file literally named
+# `-version` behind. A leading dash also makes `pre-commit run --files` parse
+# the path as an option, so the large-file hook never sees it.
+/tools/vmaf-tune/-version
+build-upstream-ab/
+
+# local-only agent scratch (bench fixtures, fan-out logs, tmp scratch)
+.claude/bench-data/
+.claude/fanout/
+.claude/tmpsp/
+
+# Vendor skill mirrors. `.claude/skills/` is canonical and tracked; the
+# per-vendor copies drift and are regenerated from it.
+.agents/skills/
+/.standards/worktrees/

vmaf_mcp-1.0.0rc1/Dockerfile

@@ -0,0 +1,58 @@
+# syntax=docker/dockerfile:1.27@sha256:bde3983e9c939224420ddaf6b784cc30e09b035a4dea01f581230c50809f372e
+#
+# Sandboxed vmaf-mcp server — MCP over stdio + pre-built libvmaf binary.
+#
+# Build from the repo root so the build context has libvmaf and mcp-server/:
+#   docker build -f mcp-server/vmaf-mcp/Dockerfile -t vmaf-mcp .
+#
+# Run (mount your YUV corpus read-only, keep stdio open for MCP):
+#   docker run --rm -i \
+#       -v /path/to/yuv-corpus:/data:ro \
+#       -e VMAF_MCP_ALLOW=/data \
+#       vmaf-mcp
+
+FROM ubuntu:26.04@sha256:61ebaa5cc23ca45450db85eac015435199ec569e28ec222ea13f2aed2110b8a6 AS build
+
+ENV DEBIAN_FRONTEND=noninteractive
+# hadolint ignore=DL3008
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential meson ninja-build pkg-config nasm \
+        python3 python3-pip python3-venv \
+        ca-certificates git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src
+COPY . /src
+WORKDIR /src/libvmaf
+RUN meson setup ../build -Denable_cuda=false -Denable_sycl=false --buildtype=release \
+    && ninja -C ../build
+WORKDIR /src
+RUN python3 -m pip install --no-cache-dir --break-system-packages --require-hashes \
+        -r requirements/locks/package-build.txt \
+    && python3 -m build --no-isolation --wheel --outdir /wheels mcp-server/vmaf-mcp
+
+FROM ubuntu:26.04@sha256:61ebaa5cc23ca45450db85eac015435199ec569e28ec222ea13f2aed2110b8a6
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    VMAF_BIN=/opt/vmaf/vmaf \
+    PATH=/opt/vmaf:$PATH
+
+# hadolint ignore=DL3008
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip python3-venv \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /src/build/tools/vmaf /opt/vmaf/vmaf
+COPY --from=build /wheels/vmaf_mcp-*.whl /tmp/
+COPY --from=build /src/mcp-server/vmaf-mcp/requirements-runtime-lock.txt /tmp/
+COPY --from=build /src/model /opt/vmaf/model
+COPY --from=build /src/testdata /opt/vmaf/testdata
+
+RUN pip install --no-cache-dir --break-system-packages --require-hashes \
+        -r /tmp/requirements-runtime-lock.txt \
+    && pip install --no-cache-dir --break-system-packages --no-deps \
+        /tmp/vmaf_mcp-*.whl
+
+WORKDIR /opt/vmaf
+ENTRYPOINT ["vmaf-mcp"]

vmaf_mcp-1.0.0rc1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: vmaf-mcp
+Version: 1.0.0-rc.1
+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.8; 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"
+      }
+    }
+  }
+}
+```

vmaf_mcp-1.0.0rc1/README.md

@@ -0,0 +1,78 @@
+<!-- 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"
+      }
+    }
+  }
+}
+```

vmaf_mcp-1.0.0rc1/claude-desktop-config-example.json

@@ -0,0 +1,21 @@
+{
+  "//": "Drop this into Claude Desktop's mcpServers config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%/Claude/claude_desktop_config.json on Windows). Adjust paths for your machine.",
+  "mcpServers": {
+    "vmaf-local": {
+      "command": "vmaf-mcp",
+      "env": {
+        "VMAF_BIN": "/home/you/dev/vmaf/build/tools/vmaf",
+        "VMAF_MCP_ALLOW": "/home/you/yuv-corpus:/home/you/renders"
+      }
+    },
+    "vmaf-docker": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "/home/you/yuv-corpus:/data:ro",
+        "-e", "VMAF_MCP_ALLOW=/data",
+        "ghcr.io/VMAFx/vmafx-mcp:latest"
+      ]
+    }
+  }
+}

vmaf_mcp-1.0.0rc1/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "vmaf-mcp"
+version = "1.0.0-rc.1" # x-release-please-version
+description = "MCP server exposing VMAF scoring, model listing, and benchmark runs via JSON-RPC."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-2-Clause-Patent"
+authors = [
+  { name = "Lusoris", email = "lusoris@pm.me" },
+]
+dependencies = [
+  "mcp>=2.2.0",
+  "pydantic>=2.13.5",
+  "anyio>=4.15.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=9.1.1",
+  "pytest-asyncio>=1.4.0",
+  "pytest-aiohttp>=1.1.1",
+  "prometheus-client>=0.26.0",
+  "ruff>=0.16.8",
+  "mypy>=2.3.1",
+]
+# Optional HTTP operator surface (--transport http). Kept separate so stdio
+# clients do not need aiohttp or Prometheus at runtime (ADR-0701).
+http = [
+  "aiohttp>=3.14.3",
+  "prometheus-client>=0.26.0",
+]
+# Optional: enables `eval_model_on_split` + `compare_models`. Pulls in the
+# ONNX / pandas / scipy stack, so it's off by default to keep the base MCP
+# install light for callers that only want `vmaf_score`.
+eval = [
+  "numpy>=2.5.3",
+  "pandas>=3.0.6",
+  "pyarrow>=25.0.1",
+  "onnxruntime>=1.30.0",
+  "scipy>=1.18.1",
+]
+# Optional: enables `describe_worst_frames` with vision-language fallback
+# (SmolVLM → Moondream2 → metadata-only). Pulls in transformers + torch.
+# Heavy install; off by default so the base MCP keeps a light footprint
+# (ADR-0172 / T6-6).
+vlm = [
+  "transformers>=5.17.0",
+  "torch>=2.14.0",
+  "Pillow>=12.3.0",
+  "accelerate>=1.15.0",
+]
+
+[project.scripts]
+vmaf-mcp = "vmaf_mcp.server:main"
+vmafx-mcp = "vmaf_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/VMAFx/vmafx"
+Repository = "https://github.com/VMAFx/vmafx"
+Documentation = "https://vmafx.github.io/vmafx/mcp/"
+Issues = "https://github.com/VMAFx/vmafx/issues"
+Changelog = "https://github.com/VMAFx/vmafx/blob/master/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.32.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vmaf_mcp"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    # Tests >30 s wall (or that exercise real GPUs / containers and may grow
+    # past 30 s). Exclude with `pytest -m 'not slow'` for fast iteration.
+    # See docs/adr/0908-slow-test-audit-2026-05-30.md.
+    "slow: marks tests as slow (deselect with -m 'not slow')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "SIM", "RUF"]
+ignore = [
+  "E501",   # line length handled by black
+  "B008",   # typer.Option / FastAPI Depends pattern — idiomatic
+  "RUF001", # ambiguous unicode — em-dashes in strings are intentional
+  "RUF002", # ambiguous unicode in docstrings
+  "RUF003", # ambiguous unicode in comments
+]