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.

When to use

Omit repository_path to use the active repository, or supply a local checkout path in repository_path to select that repository for this call only. Explicit targets remain usable when active startup is degraded, do not count as active-repository work, and never change ambient server state. The successful response shape is identical for active and targeted calls. New automatic check stops apply only to independently acquired hosted checks. Hosted-check external obstruction and unchanged-revision stalled remediation enter Failed over Rework while retaining useful fixes, package/branch/PR identity, answers, evidence and delivery debt. Obstruction requires concrete evidence, cause, external remedy and final-HEAD applicability after same-pass fixes; red status, main-branch match or missing tools alone are insufficient. The mechanical backstop requires a completed current V4 check-only review with retained answers and identical fresh failures on unchanged HEAD after refresh/rerun/flake opportunities. Nits are neutral; changed/passed/new/material/pending/unavailable evidence and request-changes bodies veto it. Sandbox limitations remain ordinary investigation. A skipped review consumes no allowance and each stop counts once toward terminal safety. No report, answer, resolution or retry waives required checks or permits red ship/merge. Remedy/restart alone stays Failed. Preserving shipper reset S#123 --to rework and eligible shipper recover S#123 renew allowance on unchanged HEAD, preserve unpublished work and history, and require fresh normal verification. Existing eligibility, locks, closure holds and confirmation rules apply. Missing/divergent retained refs refuse retry. Read current or historical diagnosis, local procedures and pending delivery with issue view/get-issue, including roundless failures. Local verification uses existing prose summaries and relevant comments, without a structured local evidence report. Every attempted non-permission local failure, including apparently unrelated or pre-existing failures, requires an anchored 🔴 must-fix: comment on the most relevant changed line and REQUEST_CHANGES, then ordinary Rework fixes or prose replies. Permission-denied and unattempted checks are limitations, never passes or waivers; all previously required checks stay required. Local-only workflows have no local-evidence automatic stop; the ordinary review-round cap still applies. Historical local observations and failure records remain readable without migration. Outstanding historical local findings receive ordinary prose replies and never authorize a new automatic stop. Upgrade alone does not clear findings, renew allowance, or recover Failed. Publication and hook diagnostics and required hook execution remain unchanged. Design, Plan, Implement, Review, Rework, and Ready name next work. Designed simple issues next Implement; complex or undecided issues next Plan. Packaged work next Review in either PR mode. Ready means ready for final integration, not shipped. New stays separate; held and failed are excluded (hold wins), while blocked, locked, paused, and running retain membership. CLI/MCP retain six next-step groups; desktop has five columns, with Implement combining Implement and Rework for the same population and attention exclusions. Current nextStep and nextStepPipeline are additive; completed-stage pipeline fields, labels, filters, commands, reset arguments, and historical records retain their meanings. Maintained label descriptions automatically refresh during next normal setup or maintenance, without separate initialization; successful cache skips repeats and force refresh reads again. Read-only status makes no label writes. Use this when an agent needs store-authoritative issue detail and compact Reviews before deciding whether to advance, reset, inspect checks, or answer a paused worker. Reviews lists every locally retained review round oldest first with stable identity, revision, disposition, finding count, optional handling state, and an optional pull request reference. Use shipper_get_review_round with a listed round identity for full feedback, findings, replies, and partial coverage. Active and closed records are supported. Empty Reviews is explicit; an unreadable review record degrades only that section. Review-bearing reads are local-only and unbounded; active mirror-on issues with empty Reviews retain GitHub metadata enrichment. GitHub-sourced inline PR review threads are not shown here; locally retained Shipper review rounds are shown under Reviews.

Behavior hints

readOnlyHint: true — The tool only reads state and does not intentionally modify the repository.
openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	integer \| string	yes	-	Shipper issue reference. S# (GitHub #) accepts ordinary surrounding whitespace and requires the current mirror. Bare numbers are Shipper local IDs first; S# is accepted; gh: and # explicitly target a mapped GitHub issue; GitHub issue URLs are accepted. Responses return S# first with GitHub # second when mapped.
repository_path	string	no	-	Optional repository path to an existing local git checkout to select for this read only. Omit it to read the active repository.

Example call

{
  "issue": 42,
  "repository_path": "/absolute/path/to/selected/checkout"
}

Example result

Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages
<issue shipper-id="S#42" github-number="123" title="Generate MCP tool reference pages" state="open">
<body>Generate reference pages from MCP tool metadata.</body>
<lifecycle>
<stage>shipper:planned</stage>
<next-step>implement</next-step>
<priority>normal</priority>
<blocked>false</blocked>
<failed>false</failed>
<locked>false</locked>
<ownership kind="operator-pause" paused-at="2026-08-03T20:00:00.000Z"/>
</lifecycle>
<comments>
<comment author="shipper-local" date="2026-07-01T14:00:00Z" source="local-workflow-event-log" kind="stage_comment" event="event-1" mirror-group="group-1" projection="mirrored" superseded="false">Implementation plan approved.</comment>
<comment author="design_adversary" date="2026-07-01T14:05:00Z" source="local-workflow-event-log" kind="note" stage="design" event="note-1" mirror-group="note-group-1" projection="mirrored" superseded="false">The retry boundary needs an idempotency assertion.</comment>
</comments>
<reviews>
<review-round number="1" round-id="round-1" reviewed-revision="abc123" disposition="REQUEST_CHANGES" finding-count="2" addressed="true" superseded="false"/>
</reviews>
</issue>

<linked-pr number="17"/>

Error modes

Local issue-state replica not initialized: Local issue-state replica is not initialized for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
Local issue-state replica present but not fully reconciled: Local issue-state replica is present but not fully reconciled for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
Local issue-state replica schema unsupported: Local issue-state replica has an unsupported schema for owner/repo. Locally reconstructable older replicas migrate automatically on first issue-state access. Run shipper issue reconcile --repair for supported local-ID V3 blocker imports requiring GitHub data or ordinary current-store repair. Numeric snapshots in issues/<GitHub-number>.json or _pending-blocker-imports/legacy/<GitHub-number>.json refuse the entire store, listing all affected records and leaving existing local issue state unchanged. This Shipper version no longer migrates GitHub-number issue snapshots. Use a Shipper release from before this change to migrate the store before retrying this version. Fresh or recreated stores retain initial blocked-state imports and interrupted-import retries after metadata becomes reconciled; local-ID V3 stored blocker lists can complete locally in store-only mode.
Local issue-state replica malformed: Local issue-state replica is malformed for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
Running issue-state reader stale: The running Shipper issue-state reader is stale for owner/repo: observed store schema v10 is newer than supported schema v9. Restart or reconnect the MCP client and server. If a freshly launched server remains incompatible, update the installed Shipper release or rebuild the source checkout before reconnecting. Preserve the issue-state store unchanged.
GitHub command failure: Command failed: gh
Invalid or unready repository target: Repository identity could not be established for . The repository has no commits. Create an initial commit. Correct this condition and retry the repository read with repository_path.

shipper_get_issue

shipper_get_issue

When to use

Behavior hints

Input schema

Example call

Example result

Error modes

Related tools