MCP

Shipper exposes its workflow operations to AI agents via an MCP server. Each tool below has a dedicated reference page covering schema, examples, and error modes. If you need to connect the server first, start with the MCP setup guide. For the authority model, mirror-mode boundaries, and intent-to-capability selection, use MCP agent operations.

Documentation

shipper_docs_search — Search the Shipper documentation corpus. Returns matching pages with relevance-ranked snippets so an agent can decide which page(s) to fetch in full.
shipper_docs_get — Fetch the full markdown content of a Shipper documentation page by its docs-site path.

Inspection (read-only)

shipper_status — Return a structured, repository-level Shipper overview with additive nextStepPipeline counts alongside unchanged completed-stage pipeline counts, including observation health, workflow, configuration, auto-ship posture, Ready merge waits, quota pressure, and supervision delivery health. Ready waits remain non-agent deferrals until their release condition changes. Use shipper_list_issues to drill down to individual issues. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_monitor — Return one complete, fresh snapshot of current Shipper workflow conditions without mutation. Each call independently captures the repository-wide or requested single-issue baseline; include_progress optionally adds ordinary progress. The tool does not paginate, replay, continue, or wait. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_list_issues — List shipper-managed issues grouped by route-aware next step with locally stored priority, pull request association, and outstanding blocker context. Rows are Shipper-ID-primary: mirrored issues render as S# (GitHub #) and no-mirror local records render as S# with no GitHub placeholder. Blocked issues retain their next-step group and blocker details; only unresolved stages use a blocked attention fallback. Held and Failed are separate. Status filters retain completed-stage/control meaning. Optional status, priority, and has_linked_pull_request filters combine with AND. Pull request state and external blocker state are not fetched. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_get_issue — Get detailed information about an active or closed issue, including compact locally retained review rounds and durable current or historical required-check failures. Active mirror-on issues with no local reviews retain GitHub metadata enrichment; review-bearing and closed records are read entirely from local state. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_get_issue_runtime — Poll one complete, local-only current runtime snapshot for a managed issue without consulting GitHub or changing ordinary issue detail. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_get_groom_session — List actionable paused grooming question sessions, or retrieve the complete current question batch for exactly one issue or session ID. This local-only read reports ownership and direct MCP answerability without resuming, changing, or taking over a session. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_get_review_round — Read the complete locally retained content of one review round by its stable identity, including current verification observations and pending versus delivered answers. Supports active, completed, and not-planned issues and never calls GitHub. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_get_session_logs — List every recorded agent session transcript for a Shipper issue, newest first, with its workflow stage, optional final-preparation sub-step, start time, and outcome. Supports active, completed, and not-planned issues and optional exact stage filtering. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_get_pr — Inspect a live GitHub pull request in one call. Omit mode for the comprehensive default: summary and merge state, one immediate CI-check observation without startup grace, review submissions, and bounded inline review threads. Set mode to checks for checks-only output: it makes an initial CI-check observation and, only when no checks are configured, up to three additional attempts at 10-second intervals. Provide exactly one of issue or pr. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
shipper_list_operator_pauses — List pending and durable operator pauses in the selected repository. Grooming sessions awaiting answers are intentionally excluded. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.

Issue lifecycle

shipper_create_issue — Create a new store-backed Shipper issue from a plain-text request. Runs the headless shipper new workflow; the agent drafts under .shipper/output/, then Shipper validates, writes the local record, and returns its local identity. When issue mirroring is enabled, Shipper also creates a GitHub issue with shipper:new and returns its GitHub number and URL. The default-false layered assignMirroredIssuesToSelf preference can additively assign the current GitHub account to that new mirror; assignment failure returns a warning, not an error, and is not retried or maintained. Store-only mode never assigns. Requires a non-empty request.
shipper_groom — Run grooming on a shipper:new issue in headless mode; the worker’s clarifying questions are surfaced to the orchestrator, which answers them via shipper_answer_question.
shipper_answer_question — Provide answers to a paused headless worker that asked questions. The worker resumes with the supplied answers and continues until it either defers again (returning another awaiting_answer payload) or completes.
shipper_advance — Advance an issue by one workflow stage (shipper next). Dispatches to the appropriate stage command based on the current label. Runs in headless mode — may take several minutes for implementation and PR review stages. For a fresh shipper:new issue, use shipper_groom first.
shipper_adopt — Adopt an existing GitHub issue or pull request into the shipper workflow. Pull requests are auto-detected and start at PR review; sources already tracked or imported by Shipper return a no-op success. In mirror-on mode, the default-false layered assignMirroredIssuesToSelf preference additively assigns the current GitHub account to each newly adopted issue or PR tracking issue while preserving existing assignees. Assignment failure returns a warning, not an error, and is not retried or maintained; store-only mode never assigns.
shipper_unadopt — Permanently remove an eligible imported GitHub issue from Shipper management while leaving the GitHub issue and its content in place. Runs immediately, has no confirmation token or force option, and reports all artifact cleanup and dependent conversions.
shipper_set_priority — Set a Shipper-managed issue’s store-authoritative scheduling priority. Returns structured applied versus already-set results; when issue mirroring is enabled, Shipper projects the matching GitHub priority label after committing the local store.
shipper_close_not_planned — Preview or apply closing one Shipper issue as not planned. The first call returns dependent-recovery impact and a confirmation token; repeat with that token to apply.
shipper_resolve_closure_hold — Resolve an operator-held external GitHub issue closure by withdrawing it as not planned, reopening it, or marking verified shipped work complete.

Issue notes

shipper_comment — Add a note to a Shipper issue. A note is an append-only, retractable annotation distinct from Shipper workflow comments. This tool cannot edit, withdraw, or otherwise touch workflow comments.
shipper_retract_comment — Withdraw a note from a Shipper issue by note ID. A note is an append-only, retractable annotation distinct from Shipper workflow comments. This tool cannot touch workflow comments, including grooming summaries, stage transitions, and blocked comments.

Recovery & cleanup

shipper_recover — Recover an eligible failed Shipper issue while preserving work and check evidence, or restore one exact live superseded-work occurrence to ordinary branches.
shipper_reset — Reset eligible packaged work to preserving Rework, including repeat Rework resets, or use existing backward targets and failed same-stage recovery. Required-check failures retain evidence and unpublished work through renewal; checks remain required. Requires an explicit stage. Supports dry-run preview mode and refuses fresh issue locks.
shipper_unblock — Attempt to unblock a blocked issue by evaluating store-owned blockers and updating local history. When issue mirroring is enabled, also repair the GitHub label/comment projections.
shipper_block — Record store-owned blocked state, typed blockers, and local history. When issue mirroring is enabled, also mirror shipper:blocked and the canonical blocked workflow comment to GitHub.
shipper_unlock — Release an issue lock. With issue: release that issue’s lock. With stale=true: sweep all stale locks across the repo. Exactly one of issue or stale must be provided.

Merge queue

shipper_merge — Run one merge pass over every eligible Ready issue captured at the start, including local changes, and report each outcome and totals. A specified issue runs only that item. Always runs —once (never polls); dry_run previews without changes.

Issue controls

shipper_pause_issue — Place the shared Desktop/MCP operator pause on one local issue. Running checkpoint-capable work is asked to stop safely and reports pending; queued automatic work is withdrawn before the durable pause is acknowledged.
shipper_resume_issue — Clear a pending or durable operator pause without changing the current worker, workflow stage, or repository Auto-ship intent.
shipper_stop_issue — Ask the current checkpoint-capable issue worker to stop after its current safe unit. This never changes operator pause or Auto-ship intent and does not wait for completion.
shipper_force_stop_issue — Preview or confirm termination of the exact reviewed issue worker and descendants. Omit confirmation_token for the non-mutating preview; confirmation is destructive and holder-bound.

Repository controls

shipper_switch_repo — Switch this running MCP server to another already-existing local Shipper-ready git checkout for subsequent Shipper MCP operations. Runtime-only; does not clone, initialize, or persist configuration.
shipper_set_auto_merge — Set the persistent Auto-merge choice for the active registered repository. This does not change Auto-ship enablement or start a daemon. An unregistered or unreadable repository registry refuses the change.
shipper_set_auto_ship — Change the active repository’s machine-global auto-ship desired state in one atomic write. Supply at least one of enabled, worker_count, or halt_requested. Fields not supplied are preserved exactly, so enabling never clears a halt; supply halt_requested: false in the same call for an atomic combined enable-and-clear. This local machine state mutation requires successful checkout registration before recording the entire requested enable patch. Registration failure means enablement did not complete and preserves the prior enabled setting and every other supplied field. Unreadable registrations are preserved unchanged; use a build able to read them or restore the damaged file. An explicit enable then makes a bounded attempt to provide a supervisor, and reports exactly one availability outcome: available, not-started, incompatible, or indeterminate. Host availability is separate from repository supervision/pickup and automaticWork. Successful recording can have Pickup unconfirmed; check shipper_status after roughly five seconds. Switch to the repository checkout and explicitly enable Auto-ship to recover missing registration. Other mutations do not start or attach to a supervisor; a running supervisor normally observes them within roughly five seconds. Every durable record write returns status recorded or refused. Recorded results use the core applied/unchanged outcomes and disclose any lossless version 1 or 2 migration to version 3. A future schema is retained unchanged and refused with a request for a human operator to re-run Shipper installation or reconnect with a current Shipper client; a valid foreign repository identity is retained unchanged and refused with a request to resolve the file outside Shipper. Refusals contain only status, repository, and conflict—never previous, resulting, outcomes, migration, supervisor, or dispatch facts—and neither conflict has a Shipper repair, reset, or discard gesture. Corrupt replaceable records remain recoverable. Halt, disable, and the automatic safety stop are three distinct states. A halt is a persistent operator-requested repository hold: it preserves enablement and worker settings, survives idle periods, safe-checkpoint wind-down, and process or machine restarts, and ends only through an explicit clear with shipper_clear_auto_ship_halt or a halt_requested false patch. Disable sets enabled false, drains current automatic work, and prevents dispatch until auto-ship is enabled again; neither disabling nor enabling clears a halt, and enabling preserves every field the patch does not supply. The safety stop is an automatic failure safeguard with its own durable latch, its own status, and shipper_resume_auto_ship as its only recovery gesture; safety recovery never clears a halt. Automatic pre-start launch failures use a separate durable launchFailureRetries ledger: attempts one through four wait 30, 60, 120, and 240 seconds, the fifth enters recovery-only quiescence, and cooled-scope changes or the ordinary heartbeat authorize sparse probes without a manual recovery action. A successful automatic or manual start clears the repository episode and that issue episode, issue ineligibility retires issue scope, and disable followed by re-enable clears the enablement ledger. A halt or disabled state requests repository-control Stops for running automatic Ships at safe checkpoints and withdraws queued automatic work. Once enabled and unhalted is observed, unconsumed repository-control requests are retracted while explicit per-run Pause and Stop gestures remain intact. Consumed stops and withdrawn queue entries are not revived; only ordinary future dispatch may make their issues eligible again. Setting halt_requested false records cancellation intent only: there may be no live supervisor, and this response reports no retraction count or observed runtime outcome. Explicit manual work stays available under a repository halt, including hand-driven workflow advances and per-run Pause and Stop actions. Non-enable changes to untracked repositories persist, but no supervisor acts on them and there is no board surface to observe or stop anything. Enabled means requested, not dispatching: an availability outcome, a persistent halt, a launch-retry posture, or a durable safety stop can show that dispatch is not active without changing the recorded enablement value. Inspect shipper_status.autoShip.launchFailureRetries and suppression before concluding dispatch is occurring. Auto-merge is separate and must be enabled by the operator before anything merges. This machine-global operator state follows the machine, is not committed repository configuration, and is not shared with collaborators.
shipper_clear_auto_ship_halt — Clear the active repository’s persistent auto-ship halt in one atomic write. A halt is an operator-requested repository hold that survives idle periods, safe-checkpoint wind-down, restarts, and disabling or enabling auto-ship; only an explicit clear ends it. This does not enable auto-ship, change worker count, resume an engaged safety stop, restart stopped runs, restore withdrawn queue entries, or start or attach to a daemon. Use shipper_resume_auto_ship for the separate automatic safety stop.
shipper_resume_auto_ship — Clear the active repository’s durable auto-ship safety stop in one atomic operation. Safety recovery does not clear an operator-requested repository halt; use shipper_clear_auto_ship_halt for that. This does not change enablement, worker count, halt state, or daemon availability.
shipper_clear_dispatch_ownership — Inspect and deliberately clear the active repository’s dispatch ownership. A tokenless call never mutates state: when ownership is held it returns the full holder facts, a concurrent-schedulers warning, and an opaque confirmation token. Echo that exact token in a second call to clear only the ownership that was shown. This does not change desired state, contact GitHub, or start or attach to a daemon.