shipper_comment

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.

When to use

Use this to add an append-only, retractable note to a Shipper issue. Notes are distinct from Shipper workflow comments and are authoritative in local workflow history. The optional author label supplements the MCP origin marker: without it the author is MCP, and with it the author is MCP: <label>. Store-only issues need no GitHub number. When mirroring is enabled, a GitHub projection failure does not undo local success; shipper issue reconcile --repair can repair the pending mirror. If the authoritative local append fails, the tool returns the underlying error and no note_id.

Behavior hints

• 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.
body	string	yes	-	Required non-blank note body. Shipper preserves the supplied body instead of trimming or rewriting it.
author	string	no	-	Optional non-blank free-text author label. MCP provenance is always recorded, whether or not this label is supplied.

Example call

{
  "issue": "S#42",
  "body": "The retry boundary needs an idempotency assertion.",
  "author": "design critic"
}

Example result

Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages
Note recorded locally for S#42 (GitHub #123).
note_id: 550e8400-e29b-41d4-a716-446655440000

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.
• Local issue not found: Cannot append note: active local issue S# was not found

Related tools

• shipper_retract_comment
• shipper_get_issue