DoneState docs / Reference

MCP tool index

All 20 tools currently exposed by the hosted DoneState MCP service. This is a lookup reference: each entry describes the public purpose, effect class, and accepted inputs.

20 tools documented

Find a tool

Showing 20 of 20 tools.

Credentials

3 matching tools.

get_openai_credential_status

Check whether the authenticated user has connected their own OpenAI API key for DoneState execution. The key is never returned.

Read

Inputs

No tool arguments.

create_openai_credential_setup

Create a single-use HTTPS setup link for connecting or replacing the authenticated user's OpenAI API key outside MCP tool arguments.

Setup

Inputs

No tool arguments.

The setup link is short-lived and the secret is entered in the DoneState HTTPS settings flow.

delete_openai_credential

Delete the authenticated user's encrypted OpenAI execution credential. Active work must be cancelled first.

Delete

Inputs

confirm: true · required; Explicit confirmation of permanent credential deletion.

GitHub & maintenance

8 matching tools.

get_github_app_status

Check whether the least-privilege DoneState GitHub App is configured without returning private keys, webhook secrets, or installation tokens.

Read

Inputs

No tool arguments.

create_github_app_setup

Create a single-use setup link for the Proof & State owner to create and encrypt the private DoneState GitHub App, then install it on selected repositories.

Setup

Inputs

No tool arguments.

This is an owner-administration surface, not a normal end-user setup step.

select_maintenance_repository

Register one explicit repository for maintenance and define its observation, scheduling, PR-only, and required-check policy.

Write

Inputs

repository: owner/name · required; Exact GitHub repository.
defaultBranch: string · default main; Branch used as the maintenance base.
mode: observe | pr_only · default observe; Whether DoneState may only observe or may prepare PR-only repairs.
scheduleEnabled: boolean · default false; Enable scheduled maintenance discovery for this repository.
autoRepair: boolean · default false; Allow eligible labeled issues to queue bounded PR-only repair.
requiredCheckNames: string[] · default []; Exact CI check names required for automatic-repair verification; maximum 20.

Automatic repair requires pr_only mode, scheduling, a selected GitHub App installation, and at least one exact required check.

list_maintenance_repositories

List the authenticated user's selected maintenance repositories and their PR-only, scheduling, and check policies.

Read

Inputs

No tool arguments.

remove_maintenance_repository

Remove one repository and its maintenance findings from the authenticated user's DoneState registry. This does not uninstall the GitHub App.

Delete

Inputs

repository: owner/name · required; Repository to remove from DoneState maintenance.
confirm: true · required; Explicit confirmation of removal.

discover_maintenance_work

Read selected-repository issues labeled donestate:repair and recent failing GitHub Actions runs, recording bounded internal findings without changing repository state.

Write

Inputs

repository: owner/name · required; Selected repository to inspect.

A failing workflow is evidence only. Explicitly labeled issues are the repair-eligible source.

list_maintenance_findings

List bounded maintenance findings for the authenticated user, optionally filtered to one repository.

Read

Inputs

repository: owner/name; Optional selected repository filter.

start_maintenance_repair

Start a bounded PR-only Codex repair for one eligible maintenance finding. Protected authority files remain blocked and OpsTruth verification is mandatory.

Write

Inputs

findingId: 64-char hex digest · required; Exact finding identifier returned by maintenance discovery.

Objectives

5 matching tools.

create_objective

Create a bounded repository objective, pin the exact base commit, and optionally queue isolated execution with explicit consequence authorities.

Write

Inputs

repository: owner/name · required; GitHub repository to work on.
baseRef: string · default main; Exact branch or ref to pin before execution.
goal: string · required; Repository outcome to achieve; maximum 20,000 characters.
acceptanceCriteria: string[] · required; One to 20 observable criteria, each up to 2,000 characters.
authorities: AuthorityClass[] · required; Explicit consequence classes granted to this objective.
publication: branch | pull_request · default pull_request; How the remote result should be surfaced.
validationProfile: auto | node | python | rust | go | none · default auto; Validation strategy used after implementation.
trustedVerifierFingerprints: sha256[] · default []; Pinned independent verifier identities.
verificationRequirements: VerificationRequirement[] · default []; Machine-checkable requirements sealed into the verification handoff.
maxChangedFiles: integer · default 100; Maximum changed files, bounded from 1 to 500.
maxDurationMs: integer · default 1800000; Execution budget from 60 seconds to 2 hours.
autoStart: boolean · default true; Start execution immediately after durable objective creation.

start_objective

Queue a previously created DoneState objective for durable isolated execution.

Write

Inputs

runId: UUID · required; Objective run identifier.

get_objective

Get durable state, bounded action results, publication references, verifier summary, and hash-chained event history for an objective.

Read

Inputs

runId: UUID · required; Objective run identifier.

cancel_objective

Cancel a queued or active objective. Completed, blocked, and verification states are not rewritten as if cancellation had happened earlier.

Write

Inputs

runId: UUID · required; Objective run identifier.

delete_objective

Delete a terminal or cancelled objective, including its encrypted run credential, action records, and event history.

Delete

Inputs

runId: UUID · required; Terminal or cancelled objective to delete.

Verification

4 matching tools.

create_verification_handoff

Create the exact sealed handoff that an independent verifier such as OpsTruth must inspect and sign.

Verify

Inputs

runId: UUID · required; Run currently awaiting independent verification.

submit_verifier_attestation

Historical compatibility adapter for pre-contract objectives. New hosted objectives use submit_verifier_response.

Verify

Inputs

attestation: VerificationAttestation · required; Signed legacy verifier attestation.

Do not choose this path for a new v2 hosted objective.

submit_verifier_response

Submit the complete versioned OpsTruth verification response for a new hosted objective. Signed report and attestation are validated together and replayed nonces are rejected.

Verify

Inputs

response: donestate.verification-contract.v2 response · required; Complete report plus signed v2 attestation.

request_opstruth_verification

Ask the configured independent OpsTruth service to re-observe one sealed run and return the complete versioned verification response. DoneState never signs the result.

Verify

Inputs

runId: UUID · required; Sealed run to re-observe.

How to read the effect badges

Read

Returns state or evidence without changing DoneState or repository state.

Setup

Creates a short-lived setup path or configuration workflow.

Write

Changes DoneState service state and may perform an authorised open-world operation.

Delete

Destructively removes eligible service state and requires explicit confirmation where the tool schema provides it.

Verify

Creates or processes independent-verification material; it does not grant DoneState self-verification authority.