FinishUP MCP server
Commit Nov 13, 2026Verifies AI agent work by recording structured evidence, performing deterministic local checks, and issuing honest verification receipts.
Also known as orgFinishUP/finishup
- Stars
- 14
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is FinishUP MCP?
FinishUP verifies AI agent work by recording structured evidence, performing deterministic local checks, and issuing honest verification receipts.
Summary generated from the project's README
About FinishUP MCP server
Verifying that AI agents actually complete their assigned tasks is what FinishUP enables for developers and teams using agentic workflows. This local-first, open-source system allows agents to record structured evidence of their plans, actions, and results into a local ledger. Instead of simply trusting an agent's claim of completion, users can run deterministic local checks against versioned policy packs to identify gaps, such as stale evidence or unattempted requirements.
Users interact with the system through a command line interface or via MCP using six core operations: start, publish_work, check, respond, status, and receipt. The tool is designed to be private by default, running entirely offline with zero-egress unless a user explicitly approves a privacy policy for optional AI-powered review. It provides honest receipts that detail exactly what was verified and what remains open, ensuring that a clean check never falsely implies total correctness.
What you can do with it
- 1Detecting incomplete agent tasksAn AI agent can identify if it failed to verify a specific requirement like a response shape during a refactor.
- 2Auditing agent work with receiptsDevelopers can issue coverage-bounded receipts that carry findings even after an agent attempts a fix.
- 3Integrating with coding environmentsDevelopers can connect the verification layer directly to tools like Claude Code or Cursor.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableorgfinishup/finishup is public and reachablegithub.com/orgfinishup/finishup ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/orgfinishup/finishup ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub[!NOTE] FinishUP was previously called Yoetz. Existing Yoetz installations keep their data, settings and connected agents; see Upgrading from Yoetz.
FinishUP is a local-first, open-source system for recording structured work evidence, checking it with local checks, and producing honest receipts about what was and was not verified.
It is built for agent-assisted work. An agent publishes bounded facts about what it is doing — plan, claims, actions, results, evidence — into a local ledger; FinishUP checks that record with versioned local policy packs, optionally adds advisory AI-powered review inside a privacy policy you control, and issues a receipt whose wording never outruns its coverage.
The thing FinishUP refuses to do is the point. It will not tell you work is correct. It will tell you exactly what was checked, at what coverage, and what remains open.
What it looks like
$ codex
› Refactor the rate limiter. Keep the /limits response shape and make sure tests pass.
• I'll plan this first and record the obligations in finishup.
• Called finishup.start
└ task tsk_9c2e1b40 · session ses_9c2e1b40-01
• Called finishup.publish_work
└ accepted · plan + 3 obligations
• Edited src/limiter.py (+118 -74)
• Ran pytest -q
└ 41 passed
• Tests pass. Checking with finishup before I claim done.
• Called finishup.check
└ action_required · 2 findings
✗ stale_evidence_for_changed_state — "tests pass" cites a run older than the last edit
✗ requested_item_never_attempted — the /limits response shape was never verified
• Fair catch. Fixing, then re-running.
• Edited src/limiter.py (+9 -4)
• Ran pytest -q
└ 43 passed
• Called finishup.respond
└ acknowledged
• Called finishup.check
└ no_issue_detected
• Called finishup.receipt
└ unresolved_findings_remain · local · coverage-bounded
Done. The limiter is refactored, and the receipt still carries the two findings I hit on the way.
Both findings map to real rules in the shipped local policy pack, checked against the published record and FinishUP's own names-only read of what changed in the workspace — no model, no interpretation. And the receipt keeps carrying them after the fix: a later clean check never erases what was caught.
Install
# Install the latest published version from PyPI — the canonical distribution
uv tool install --managed-python --python 3.14 finishup
# Via npm — a dependency-free launcher that makes the same persistent uv install (needs uv)
npx finishup
# One-off run without installing (needs uv: https://docs.astral.sh/uv/)
uvx --python 3.14 finishup
FinishUP runs on Python 3.12, 3.13 or 3.14. You do not need to have one: uv downloads Python
3.14 on demand, whatever other Pythons are on the machine, and the install is not affected by them.
Keep --python 3.14 in the command: uv 0.13 and later otherwise pick Python 3.15, which
FinishUP's dependencies cannot install on yet. Releases are certified on CPython 3.14.6; any other interpreter (3.12, 3.13, or
another 3.14 patch) runs and is tested, but reports itself as an untested cell. The npm
package bundles no Python and no FinishUP code and never installs uv itself; it makes the same
uv tool install and launches the exact matching Python distribution. FinishUP runs on macOS and Linux (certified on
macOS arm64 and Linux x86-64 (glibc 2.28+); other Linux architectures install and report themselves as untested —
see Linux); on Windows, install it inside WSL 2 — see
Windows.
[!TIP] Let your agent set it up. Paste this into your coding agent and it walks you through installation, showing you every proposed change first:
Install FinishUP for me (https://github.com/TheGaySupreme123/finishup). Fetch its agent install guide and follow "The short version" at the top: curl -fsSL https://raw.githubusercontent.com/TheGaySupreme123/finishup/main/docs/usage/agent-start.md If your sandbox blocks that fetch, ask me to approve it or to paste the guide. Setup's questions are mine to answer, so ask me each one and wait, and show me any proposed change before it is applied. Never ask me for a key or password in chat; hand me the terminal for those.
finishup at a terminal opens a full-screen interface, and the first run walks setup inside it:
what was detected, whether you trust this project, the exact proposed change, and an explicit
approval before anything is applied. You do not need to know what MCP, hooks, policy digests, or
vaults are to finish it. A provider is never required: local verification is complete without one.
The recommended answer, FinishUP (recommended), goes on to reviewer and privacy setup so your
agent can turn on AI-powered review for a task when it helps; FinishUP, local only sets up no
reviewer, and if you stop reviewer setup partway the terminal interface offers to finish as local
only. Everything non-interactive is unchanged: pipes, redirects, CI, --help, --json, named
subcommands, and finishup mcp serve behave exactly as before, and FINISHUP_TUI=0 selects the
prompt-loop menu instead.
Full walkthrough: Install and first run and The terminal interface. A coding agent installing FinishUP for its user should follow Agent start: setup's questions appear only on the human's own terminal, and that page says what to run, what to ask, and what to recommend.
Harness observation is opt-in per project, and source files and configuration are never
activation proof. For Codex, setup offers one standing-trust preview bound to the exact selected
Codex executable and an explicitly selected, existing Codex home. Before consent, only that
executable's --version runs, with both Codex home variables redirected to a fresh owner-private
temporary home that is removed afterward; setup does not inspect the approved home's plugin
inventory. Only explicit digest-bound approval permits the scoped inventory/add commands and
disclosed marketplace, config, scratch, and versioned-cache effects in the selected home. Claude
Code and Cursor hooks are installed through finishup integrate claude ... and
finishup integrate cursor ... with the same preview-then-approve shape. What a hook keeps differs by
host: consented Codex events may retain secret-scanned, encrypted tool output and changed-file
bytes as captured evidence; Claude Code and Cursor hooks keep only structural facts — FinishUP tool
names, lifecycle events, digests — and discard prompts, transcripts, paths, and results before
storage. Under every host, even an active result proves installed inventory and cache/config
state for future sessions—not that a later session loaded a hook or delivered an observation.
What's in the box
| Six operations, two surfaces | start, publish_work, check, respond, status, receipt — identical contracts on the CLI and over MCP. Everything else is a bounded support surface, not a seventh operation. |
| Works with any MCP agent | No integration, no installed skill, no configuration. Codex, Claude Code, and Cursor have first-party integrations because each host's skill or plugin surface delivers the guidance natively — but integration buys ergonomics, never a stronger claim. |
| Honest receipts | Coverage, provenance, freshness, findings, and limitations stay separate. A clean local check is never presented as proof that work is correct. |
| Zero-egress by default | A fresh installation runs local checks only and is fully useful offline; no work is sent anywhere until first-run setup commits a privacy policy you approve. |
| Privacy-gated AI-powered review | An optional reviewer model reads a bounded, minimized packet built from the ledger and, when your privacy recipe allows repository excerpts, the task's own change, read once per check. It never browses your repository, and it sits behind explicit provider binding and reauthenticated policy authority. |
| A full-screen terminal interface | First run, status, privacy, provider, integration, service, and receipt flows in one interface; no secret ever enters it. |
| Recoverable local durability | Encrypted task bundles, generation-fenced single-writer storage, exact replay, backup/restore, and forward-only migrations. |
See The six operations for the protocol and Receipts and coverage for what a receipt does and does not say.
Private by default
A fresh installation's unconfigured seed is zero-egress and local-only: no work is sent anywhere
until first-run setup commits a policy, and FinishUP is fully useful in that state. Setup's
proposed privacy policy states whether FinishUP may check PyPI for package updates (default yes, with an
opt-out). That bounded check carries only the installation's package identity (finishup, or
yoetz for an installation still updated under its former name) and version, never task or
user content, and it never upgrades the package for you; decline it for a zero-network installation.
Rerunning setup does not suspend or revoke an existing standing policy: ordinary activity remains
governed by that policy until the user commits a replacement.
Every task starts with FinishUP's local checks. Setup's recommended answer lets your agent turn on
AI-powered review for one task when it helps, with a single recorded decision; you can instead keep
every task local or review every task, and change it later with finishup privacy conversations.
The agent's switch is a request: what may be sent is still decided by your privacy policy. The
policy you approve during setup is the privacy grant for the project folder setup connected; each
other repository needs its own grant (run finishup --privacy from it) before its tasks can use
AI-powered review, and until then its tasks run local checks only (an installation that already
sent work before 0.3 may carry its earlier permission forward when a task first starts there).
AI-powered review is a separate explicit decision. When you choose it, the CLI lists the privacy options with Assisted review as the default. It is marked recommended only for a provider route with reviewed data-use terms; otherwise, a ChatGPT subscription among them, the choice is yours. Assisted review shows and confirms a standing policy that sends the reviewer a structured packet built from the ledger — goal, obligations, claims, timeline, local findings and their bases, coverage gaps, and bounded problem-local excerpts already recorded in the case — plus the check-time change: the task's own change since the commit it started on, read from the repository once per check, and up to four unchanged files the task statement names. Expanded review allows broader in-scope excerpts. Sensitive and confidential content is off, and the never-send set is absolute. Policy loosens only through a reauthenticated decision you make: the trusted local ceremony, or your explicit current-chat approval of one exact prepared, previewed, expiring consent target that a capable agent relays for you. That relay is the agent's assertion, which FinishUP cannot independently authenticate, so the local ceremony remains the stronger path.
Provider setup distinguishes OpenAI API / compatible API from Codex with ChatGPT
subscription. The subscription route binds one exact Codex app-server and dedicated home; Codex
owns ChatGPT login and the upstream OpenAI request, while FinishUP receives no OAuth credential. It
still sends only the privacy-approved packet and records the weaker observable boundary explicitly.
A new subscription setup suggests gpt-6.1-sol at reasoning effort medium; when the Codex
FinishUP runs does not list it, setup uses gpt-6-luna and says so. A model you type is never
substituted, and an existing setup keeps its model. The suggestion is checked against Codex's model
list only; no authenticated AI-powered review with gpt-6.1-sol has been recorded yet.
Review then runs direct-to-agent: the reviewer returns a bounded challenge, the agent acts, supplies evidence, revises, disputes, or states a limitation, and rechecks. No human prompt for routine retries.
See Privacy and AI-powered review and
PRIVACY.md.
How it is put together
One trusted persistent local service owns the encryption keys, decrypted state, storage writers, privacy authority, and provider access. CLI, MCP, and the terminal interface are clients — they hold none of those things. The interface in particular is presentation only: it dispatches through the same application services the commands do, and no secret ever enters it, because credential entry suspends the interface and hands the terminal to the existing confidential ceremony. External disclosure is denied by default and must pass centralized classification, policy, minimization, secret scanning, exact destination binding, and durable structural audit.
See Architecture.
Releases you can verify
Every release is more than a tag. The tag workflow builds each distribution once, tests those exact
candidate bytes, publishes them to PyPI and npm through dedicated approval environments, and
attaches the same approved artifacts to the
GitHub release alongside SHA256SUMS, an
SBOM, the support matrix, known limitations, the release-evidence bundle, and a VERIFY.md that
walks through checking the bytes you installed. Post-publication jobs re-download the public
artifacts and compare them to the approved bytes.
Release notes are curated by hand for every release — highlights, an explicit "what this release
does not claim" section, and the full changelog — and live versioned in
docs/releases/.
Documentation
- Using FinishUP — install, the terminal interface, operations, privacy, providers, receipts.
- Architecture — topology, module map, honesty rules.
docs/adr/— architecture decisions; the top authority for public behavior.docs/INTERFACES.md— shared names, types, ports, trust boundaries.docs/OPEN_QUESTIONS.md— the decision ledger: every decision taken, each release gate's dated disposition, and what evidence a stronger claim would need.docs/— full index, including protocol pages and runbooks.
Status
FinishUP 0.3.0 is a public-alpha release and the first under the FinishUP name; Yoetz 0.2.5
was the last release before the rename. 0.3.0 lets several agents work in independent tasks within
one repository, adds a backup-first upgrade path for 0.2 task data, and carries every 0.2.x repair
through Yoetz 0.2.5; see the 0.3.0 notes for changes and validation
limits.
Every public claim in
docs/public-claims.json is bound to real checked-in evidence: a claim flagged evidenced has concrete test or fixture coverage, with its non-live
suites exercised in per-PR CI; a claim whose own wording names still-missing capability or drill
evidence stays not_yet_evidenced and is not asserted as release evidence. Every reviewed provider
preset resolves to a real runtime
factory, so a preset you can select is a preset FinishUP can dispatch — but none of the non-official
presets has recorded live evidence yet, so none is claimed as a confirmed working endpoint. That
claim stays gated by the capability evidence described in
ADR-006.
Contributing
Contributions are welcome with a high bar: search for duplicates, open an issue first, wait for
maintainer acknowledgement on design-gated areas, and disposition every review comment — including
code-review agents — before merge. See CONTRIBUTING.md and
AGENTS.md.
- Bugs and change requests: GitHub issues (use the forms; blank issues are disabled).
- Security:
SECURITY.md— private vulnerability reporting orsupport@finishup.dev. - Conduct:
CODE_OF_CONDUCT.md—support@finishup.dev.
Private strategy and architecture drafting inputs under docs/architecture/ are intentionally
gitignored. The public ADRs, docs, code, and tests must remain self-contained without them.
Licensed under the Apache License 2.0, using the official unmodified license text and the
SPDX expression Apache-2.0; FinishUP does not add a fabricated project-wide ownership notice.
FinishUP MCP questions
What does FinishUP actually do?
It records structured work evidence from agents, checks it against local policy packs, and produces receipts detailing what was and was not verified.
Does FinishUP tell me if my work is correct?
No, it refuses to claim work is correct; instead, it tells you exactly what was checked, the coverage, and what remains open.