shipper_list_issues

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.

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. 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 for single-call triage before changing workflow state, including composable status, priority, and stored pull request association filters. Supplied filters combine with AND. Use status: "held" only for external-closure decisions; a deliberate issue-scoped pause renders as [operator-paused] and remains in its next-step group. The inventory is store-backed and does not fetch pull request, attribution, or external blocker state. No-mirror local records are expected in store-only repositories; when issue mirroring is enabled, they are Mirror pending (repairable). A row for an issue with a decided route carries a trailing [simple route] or [complex route] marker so route distribution is readable from the listing alone; an undecided route omits the route suffix while retaining completed-stage context.

Behavior hints

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

Input schema

Name	Type	Required	Default	Description
status	enum: new, groomed, designed, planned, pr-open, rework, ready, held, blocked, failed	no	-	Workflow stage or control status to filter by.
priority	enum: high, normal, low	no	-	Locally stored issue priority to filter by.
has_linked_pull_request	boolean	no	-	Filter results by the locally stored pull request association: omit for no association filter, true for only issues with an association, or false for only issues without one. This filter does not enrich, attach, fetch, or modify pull-request data.
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.

Deprecated input aliases (one-release compatibility)

The following deprecated aliases are accepted for this release only:

• linkedPullRequest → has_linked_pull_request

An alias-only call succeeds and prepends this warning text for each alias:

• Deprecated input “linkedPullRequest” was accepted as “has_linked_pull_request”; it is supported for this release only and will be rejected in the next release.

The same ordered warnings are returned in _meta["shipper/deprecation-warnings"] as { alias, replacement, removal: "next-release" } entries. Supplying both an alias and its canonical input is rejected, even when their values are equal. These aliases will be rejected in the next release; use the canonical inputs now.

Example call

{
  "status": "planned",
  "priority": "high",
  "has_linked_pull_request": true,
  "repository_path": "/absolute/path/to/selected/checkout"
}

Example result

Implement (2)
  S#42 (GitHub #123) Generate MCP tool reference pages [completed stage: planned] [high] [PR #456] [operator-paused]
  S#44 Fix release workflow [completed stage: planned] [high] [PR #457] [blocked] [blocked by: GitHub #19 (unverified)]

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.
• 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.

Related tools

• shipper_get_issue
• shipper_advance