# verdict-mcp [Health: Active]

**Category:** 👨‍💻 Code Execution  
**Repository:** https://github.com/Dgotlieb/verdict-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/verdict-mcp

## Description
Sandboxed test runs for coding agents: compact typed verdicts with failure fingerprints and history

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "verdict-mcp": {
    "command": "uvx",
    "args": ["verdict-mcp"],
    "env": {
      "VERDICT_PROJECT": ""
    }
  }
}
```

**Requires environment variables:** `VERDICT_PROJECT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What verdict-mcp does

The verdict-mcp MCP server provides structured verification feedback for coding agents working on Python projects. It replaces direct pytest shell-outs with MCP tools that select relevant tests, execute them in an isolated environment, and return compact typed results rather than an entire test-run log.

Its main distinction is failure history. Each failure receives a stable fingerprint based on a normalized failure signature. Volatile values such as memory addresses, temporary paths, identifiers, and durations are removed before hashing, so the same logical problem can be recognized across runs and refactors. Results can indicate whether a failure is pre-existing or associated with the current change.

## How it works

The `verify` tool can inspect the working-tree diff and use a static import graph to choose affected tests. The graph is built with grimp. A full-suite mode is also available through `scope="all"`; the result includes a selection note when the server falls back from targeted selection.

Checks normally run in an ephemeral container using Podman, with Docker as a fallback. The worktree is mounted read-only at `/src` and copied to a writable `/work` directory inside the container. The check run uses `--network=none`, and the host environment is not changed by the test execution. If no container runtime is available, `prefer = "local"` can run checks against a temporary copy instead of the worktree in place.

The `explain_failure` tool retrieves the complete traceback for one check ID only when requested. `history` reports when a fingerprint was first and last seen and how often it has occurred. This keeps detailed failure output separate from the normal summary.

## Setup and configuration

The verdict-mcp MCP server can be started with `uvx verdict-mcp`, which fetches the package on first use. Permanent alternatives include `uv tool install verdict-mcp` and `pip install verdict-mcp`.

An optional `verdict.toml` file can define the project packages used for impact selection, a container image, a setup command, the local-runtime preference, and the maximum number of reported failures. Package names are guessed when the project list is omitted. A configured setup command may use the network before checks begin; the check run itself is network-disabled. A prebuilt image avoids installing dependencies during setup.

## Tools and capabilities

- `verify(scope?, base?)`: selects and runs affected tests, or runs the requested scope, and returns typed failures with fingerprints and a `preexisting` flag.
- `explain_failure(check_id)`: returns the full traceback for a selected failure.
- `history(fingerprint)`: shows first-seen, last-seen, and occurrence information for a failure fingerprint.
- `run_checks(["ruff", "mypy"])`: runs Ruff and mypy and normalizes their results into the verdict schema.

## Limitations and notes

Impact selection is intentionally approximate because it relies on static imports. Dynamic imports, fixture lookup by name, and data-driven tests may be missed, so `scope="all"` is available when broader coverage is needed.

Container setup can still fail before a check starts, including image-pull or credential-helper problems. The README specifically notes that Podman may be affected by a Docker configuration using the `gcloud` credential helper. Flake detection and coverage-based selection are described as future work rather than current capabilities.

The verdict-mcp MCP server is licensed under Apache-2.0. Its container isolation reduces host-side effects, but the documented setup step can run with network access, so repository configuration should be reviewed before enabling it.

_Full upstream README: https://allmcps.com/mcp/verdict-mcp/readme_