> offline, rule-based repository verifier
Easy Verifier
An offline, rule-based repository verifier, available as an MCP server and a CLI. It rates a repository, or a change, from declared rules over measured facts, and says so when it cannot rate something.
What it is
Easy Verifier gathers evidence about a repository (file excerpts, citations, and lists of what it looked for and did not find) and computes inspectable ratings from declared rules. A calling agent can optionally submit its own findings for a separate assessment.
- No inferred verdict. Ratings are deterministic arithmetic over cited metrics.
- No guessing. A source it did not find is reported as missing; a rating without enough evidence is withheld.
- Read-only and local. It never executes the repository's code and makes no outbound network request.
Terms used below: a dimension is one independently rated aspect (for example security); an evaluation area is one of 32 cited review topics a rule can measure; an abstention is "no number, with a reason code".
Run it
Two lines with Docker: download the start script, then run it with the absolute parent directory of the repositories you want to score in place of /home/you/code.
curl -fsSLO https://raw.githubusercontent.com/thunderkds/easy-verifier-mcp/main/scripts/run_mcp.sh
bash run_mcp.sh /home/you/codeThe script does the manual steps under Other ways for you: it pulls temvar/easy-verifier-mcp:0.2.0, starts one read-only container with the same flags, and runs claude mcp add when Claude Code is installed. Read the script first if you like.
Then ask your agent to score a repository, passing its absolute path as repo.
Other ways to run it
The script, from a clone
git clone https://github.com/thunderkds/easy-verifier-mcp.git
cd easy-verifier-mcp
bash scripts/run_mcp.sh /home/you/codeIf a container named easy-verifier already exists, the script stops without changing anything; add --replace to remove that container first.
Step by step, without the script
Three steps with Docker: pull the image, run it, register it. Nothing is built.
Replace both /home/you/code with the absolute parent directory of the repositories you want to score.
1. Pull
docker pull temvar/easy-verifier-mcp:0.2.02. Run
mkdir -p ~/.easy-verifier-reports ~/.easy-verifier-sot
sudo chown 10001:10001 ~/.easy-verifier-reports ~/.easy-verifier-sot
docker run -d --name easy-verifier --restart unless-stopped --init \
--read-only --network host --cap-drop ALL \
--security-opt no-new-privileges:true \
--tmpfs /tmp:rw,noexec,nosuid,nodev,size=16m \
-e EASY_VERIFIER_REPORTS_DIR=$HOME/.easy-verifier-reports \
-e EASY_VERIFIER_SOT=/sot \
-v /home/you/code:/home/you/code:ro \
-v $HOME/.easy-verifier-reports:$HOME/.easy-verifier-reports \
-v $HOME/.easy-verifier-sot:/sot \
temvar/easy-verifier-mcp:0.2.0 --transport streamable-http3. Register
claude mcp add --transport http easy-verifier http://127.0.0.1:8766/mcpBuild from source (Compose)
From a clone of the repository, build the same image yourself and start it with the absolute parent directory of the repositories you want to score:
docker compose build scorer
mkdir -p ~/.easy-verifier-reports && sudo chown 10001:10001 ~/.easy-verifier-reports
EASY_VERIFIER_WORKSPACE=/home/you/code docker compose up -d scorerWithout a container (stdio)
Install the package into a Python 3.11+ environment and register the stdio server:
python -m pip install .
claude mcp add easy-verifier -- easy-verifier-mcpCLI
python -m easy_verifier.adapters.cli score --repo . --scope projectFull guides are in the repository: README.md, docs/DOCKER_MCP_GUIDE.md and docs/LOCAL_MCP_GUIDE.md.
What it measures: dimensions
Thirteen dimensions are rated for the repository, plus change-risk, which rates a change. Each dimension is independently callable.
Design and intent
architectureStructural fit against the project's declared designsolution-fitWhether the change addresses the stated problemrequirement-fidelityWhether the work matches its requirement or spec
Code and tests
code-qualityStyle, readability and maintainability signalstest-strategyWhat is and is not covered by testsblast-radiusWhat else depends on, or is touched by, the code
Security and supply chain
securityInjection, secret handling and other security evidencesupply-chainDependency pinning and licences, CI reproducibility, provenance, SBOM, signing
Interfaces and data
apiAPI specification, request validation, versioning, removed endpointsdataMigrations beside a schema, rollbacks, constraints, DROP/RENAME operations
Running systems
reliabilityError handling, deadlines, retry backoff, business-continuity documentoperationsLogging and tracing, audit logs, CODEOWNERS, agent guardrails, setupinfrastructureIAM and RBAC wildcards, open ingress, unencrypted storage, state and backups in Terraform, Kubernetes, CloudFormation
Rates a change, not the repository
change-riskRates a change, not the repository: only atchangesorworktreescope, and reported as its own headline, never averaged into the overall
All dimensions as a table
| Dimension | What it looks at |
|---|---|
architecture | Structural fit against the project's declared design |
solution-fit | Whether the change addresses the stated problem |
requirement-fidelity | Whether the work matches its requirement or spec |
code-quality | Style, readability and maintainability signals |
security | Injection, secret handling and other security evidence |
test-strategy | What is and is not covered by tests |
blast-radius | What else depends on, or is touched by, the code |
reliability | Error handling, deadlines, retry backoff, business-continuity document |
supply-chain | Dependency pinning and licences, CI reproducibility, provenance, SBOM, signing |
api | API specification, request validation, versioning, removed endpoints |
data | Migrations beside a schema, rollbacks, constraints, DROP/RENAME operations |
operations | Logging and tracing, audit logs, CODEOWNERS, agent guardrails, setup |
infrastructure | IAM and RBAC wildcards, open ingress, unencrypted storage, state and backups in Terraform, Kubernetes, CloudFormation |
change-risk | Rates a change, not the repository: only at changes or worktree scope, and reported as its own headline, never averaged into the overall |
What it measures: 32 evaluation areas
Every rule names exactly one of these areas. The marker shows whether any rule measures the area today: core rule a core rule exists; optional pack only an optional pack measures it, and that pack runs only when the repository opts in or shows that domain; no rule yet nothing measures it yet, and the scorecard says so instead of implying coverage.
- 28 core rule
- 4 optional pack only
- 0 no rule yet
Grouped by the dimension whose rules measure each area. An area two dimensions measure is shown once, under the first of them.
architecture
- Architecture & dependency direction
requirement-fidelity
- Business-rule correctness
- Documentation source-of-truth governance
code-quality
- Type safety & code quality
- Maintainability, reuse, library judgment, patterns
- Technical-debt lifecycle & closure evidence
security
- AuthN/Z, sessions, offboarding
- Threat modeling, abuse cases, appsec
- Dependencies, vulns, licenses, obsolescence
test-strategy
- Test strategy, coverage, false confidence, isolation
blast-radius
- Backward compatibility & upgrade safety
reliability
- Transactions, concurrency, idempotency
- Error handling & safe degradation
- Retries, deadlines, unknown outcomes, vendor outages
- Performance, scalability, capacity, cost
- Business continuity & degraded modes
supply-chain
- CI quality & reproducibility
- Artifact provenance, SBOM, signing, promotion, rollback
api
- API contracts, validation, versioning
data
- Data model, constraints, migrations
operations
- Observability, auditing, SLOs, error budgets
- Incident response, change mgmt, access review
- Configuration ownership & operational readiness
- AI-assisted-development safety
- Developer experience & deterministic local setup
infrastructure
- Infra security: IAM, networking, KMS, secrets
- Terraform state, environment, account, drift
- Database HA, backups, restore, DR
Optional packs
- Financial integrity & historical reconstruction finance
- PHI minimization, retention, test-data safety healthcare
- Accessibility, responsive UX, browser compat frontend-a11y
- Vendor, BAA, data classification, residency healthcare
All 32 areas as a table
| # | Area | Status |
|---|---|---|
| 1 | Architecture & dependency direction | core rule |
| 2 | Business-rule correctness | core rule |
| 3 | Financial integrity & historical reconstruction | optional pack: finance |
| 4 | Data model, constraints, migrations | core rule |
| 5 | Backward compatibility & upgrade safety | core rule |
| 6 | Transactions, concurrency, idempotency | core rule |
| 7 | API contracts, validation, versioning | core rule |
| 8 | AuthN/Z, sessions, offboarding | core rule |
| 9 | PHI minimization, retention, test-data safety | optional pack: healthcare |
| 10 | Threat modeling, abuse cases, appsec | core rule |
| 11 | Infra security: IAM, networking, KMS, secrets | core rule |
| 12 | Error handling & safe degradation | core rule |
| 13 | Retries, deadlines, unknown outcomes, vendor outages | core rule |
| 14 | Observability, auditing, SLOs, error budgets | core rule |
| 15 | Performance, scalability, capacity, cost | core rule |
| 16 | Test strategy, coverage, false confidence, isolation | core rule |
| 17 | Type safety & code quality | core rule |
| 18 | Maintainability, reuse, library judgment, patterns | core rule |
| 19 | Accessibility, responsive UX, browser compat | optional pack: frontend-a11y |
| 20 | Dependencies, vulns, licenses, obsolescence | core rule |
| 21 | CI quality & reproducibility | core rule |
| 22 | Artifact provenance, SBOM, signing, promotion, rollback | core rule |
| 23 | Terraform state, environment, account, drift | core rule |
| 24 | Database HA, backups, restore, DR | core rule |
| 25 | Incident response, change mgmt, access review | core rule |
| 26 | Configuration ownership & operational readiness | core rule |
| 27 | Documentation source-of-truth governance | core rule |
| 28 | Vendor, BAA, data classification, residency | optional pack: healthcare |
| 29 | AI-assisted-development safety | core rule |
| 30 | Developer experience & deterministic local setup | core rule |
| 31 | Technical-debt lifecycle & closure evidence | core rule |
| 32 | Business continuity & degraded modes | core rule |
How scoring works
One repository goes in at the top. Each dimension follows the same path: it ends either in a number from 0 to 100 or in an abstention, never a guess.
- 00Repository
- 01Evidence
- 02Rules
- 03Coverage check
- 04Rating or abstention
A worked example
Taken from the sample scorecard below: three of its rated dimensions and one abstention.
| Dimension | Outcome |
|---|---|
architecture | rated 100 |
test-strategy | rated 75 |
security | rated 50 |
supply-chain | abstains, too little measured: insufficient_measured_weight |
The overall is 47: the mean of all 10 rated dimensions in that run. The abstained dimensions are left out, not counted as zero.
The rules in detail
- Each dimension has declared rules over measured metrics. A rule compares one metric with a threshold; a met rule earns its weight and an unmet rule earns zero. The weights of the rules that apply at one scope add up to 100;
solution-fithas no static rule. - Each rule cites its metric and its threshold separately. A threshold tagged
project-defaultmeans the standard names the measure but publishes no number. - A coverage floor guards every dimension: if too little of the evidence it needs was found, it abstains with a reason code rather than showing a number. A metric that cannot be measured is left out of both the earned and the total weight.
- The overall is the mean of the dimensions that could be rated, and the scorecard names which dimensions contributed and which abstained.
- The improvement plan lists unmet rules ordered by their declared gain, recomputed from the same arithmetic, so fixing the top item is worth exactly the points shown.
- The engine makes no model call and no network request. The same repository state gives the same score.
change-riskis rated only atchangesorworktreescope, and is not averaged into the overall.
Sample scorecard
Easy Verifier scoring itself at project scope, commit 8062b35, taken . This is a static snapshot, not a live result.
sample scorecard · 8062b35
47 / 100
overall, out of 100
22 of 32 areas measured
Mean of the dimensions that could be rated. Dimensions shown as abstained are left out of it.
| Dimension | Rating |
|---|---|
api | 0 |
architecture | 100 |
blast-radius | 50 |
code-quality | 31 |
data | 40 |
infrastructure | — abstained: all_metrics_abstained |
operations | 50 |
reliability | 50 |
requirement-fidelity | 20 |
security | 50 |
solution-fit | — abstained: no_static_rule |
supply-chain | — abstained: insufficient_measured_weight |
test-strategy | 75 |
This run measured 22 of 32 evaluation areas. No rule that ran in it covers these: four belong to optional packs that did not run, and one has no rule yet:
- Financial integrity & historical reconstruction
- Transactions, concurrency, idempotency
- PHI minimization, retention, test-data safety
- Accessibility, responsive UX, browser compat
- Vendor, BAA, data classification, residency