**English** | [한국어](README.ko.md)

# DoneProof MCP

[![CI](https://github.com/efficjump/doneproof-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/efficjump/doneproof-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-2ea44f.svg)](LICENSE)

Convert an implementation objective into explicit acceptance criteria and a fresh, traceable evidence
matrix. Completion is derived from active policies, current workspace fingerprints, and an intact
hash-linked ledger—not from model confidence.

```mermaid
flowchart LR
    A[Implementation objective] --> B[Reviewable criteria draft]
    B --> C[Activated evidence policy]
    C --> D[Discovered verifiers]
    D --> E[Approved verification]
    E --> F[Hash-linked evidence]
    F --> G{Fresh and sufficient?}
    G -->|Yes| H[Complete]
    G -->|No| I[Failed or insufficient]
```

## Highlights

- Host-model criterion proposals that remain drafts until explicitly activated
- Evidence policies with required kinds and minimum pass counts
- Dynamic verifier discovery from current project manifests
- One-time approvals for direct argv verification commands
- Workspace fingerprints that make old evidence visibly stale
- Separate `observed` and `attested` provenance
- Append-only SHA-256-linked evidence ledger with tamper detection
- Deterministic completion assessment and Markdown proof reports

## Install

```bash
uv tool install "git+https://github.com/efficjump/doneproof-mcp.git"
doneproof-mcp --transport stdio
```

For source development:

```bash
git clone https://github.com/efficjump/doneproof-mcp.git
cd doneproof-mcp
uv sync --all-extras --locked
uv run doneproof-mcp --transport stdio
```

## Generic MCP client configuration

```json
{
  "mcpServers": {
    "doneproof": {
      "command": "doneproof-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}
```

No local checkout path is required after tool installation.

## Tool workflow

| Stage | Tools |
| --- | --- |
| Task state | `create_task`, `list_tasks`, `get_task` |
| Criteria | `derive_criteria`, `set_criteria` |
| Verification | `discover_verifiers`, `prepare_verification`, `execute_verification` |
| Evidence | `record_file_evidence`, `record_attestation` |
| Decision | `assess_completion`, `build_proof_report` |

`record_file_evidence` returns `unknown` unless an expected SHA-256 is supplied. File existence alone
does not prove semantic correctness. Manual review remains explicitly labelled as attestation.

## Safety model

- Project roots are constrained by `DONEPROOF_ALLOWED_ROOTS`.
- Verifier commands must come from current project discovery.
- Commands use argv execution, output limits, timeouts, and one-time plan tokens.
- Workspace-writing commands need separate approval.
- User text and command output are redacted before persistence.
- Invalid or tampered evidence ledgers reject further appends.

This server is not an operating-system sandbox. Use an isolated environment for untrusted projects.

## Streamable HTTP

```bash
doneproof-mcp --transport streamable-http --host 127.0.0.1 --port 8767
```

The default endpoint is `http://127.0.0.1:8767/mcp`.

## Development

```bash
uv sync --all-extras --locked
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest --cov --cov-report=term-missing
uv build
```

See [architecture](docs/architecture.md), [security policy](SECURITY.md), and
[contribution guide](CONTRIBUTING.md).

## License

[MIT](LICENSE)