Skip to content
Shipper

shipper_get_pr

shipper_get_pr

Section titled “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.

When to use

Section titled “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. Use this for live GitHub pull-request inspection. Omit mode for the comprehensive view: summary and merge state, one immediate checks observation, review submissions, and inline review threads. Set mode: "checks" for lightweight CI polling that fetches no pull-request summary, linked-issue snapshot, reviews, or threads. Checks mode makes an initial checks observation and, only when no checks are configured, makes up to three additional attempts at ten-second intervals before returning the informational no-checks state. Both modes return a readable checks summary and the same structured checks object; checks mode omits summary, reviews, threads, and review_data_truncated. Provide exactly one of issue or pr. Comprehensive review submissions and threads have independent 32 KiB bounds (64 KiB total) plus cursor-retrieval ceilings of 100 reviews, 100 threads, and 100 total inline comments; explicit empty arrays mean none exist, and a final notice identifies sections truncated by either pagination or byte bounds. Nullable review decisions/authors and unknown mergeability states are reported as GitHub provides them. No cached or partial fallback is returned.

Behavior hints

Section titled “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

Section titled “Input schema”
NameTypeRequiredDefaultDescription
issueinteger | stringno-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. Exactly one of issue or pr is required. An issue resolves only its currently stored pull request link, which Shipper clears on merge.
printegerno-Positive GitHub pull request number. Exactly one of issue or pr is required.
modestringno-Optional checks-only mode. Set to checks for an initial CI-check observation plus up to three additional attempts at 10-second intervals when no checks are configured. Omit it for the comprehensive default, which makes one immediate CI-check observation without retrying.
repository_pathstringno-Optional repository path to an existing local git checkout to select for this read only. Omit it to read the active repository.

Output schema

Section titled “Output schema”
NameTypeRequiredDefaultDescription
summaryobjectno--
checksobjectyes--
reviewsarrayno--
threadsarrayno--
review_data_truncatedbooleanno--

Example call

Section titled “Example call”
{
  "pr": 17,
  "mode": "checks",
  "repository_path": "/absolute/path/to/selected/checkout"
}

Example result

Section titled “Example result”
{
  "content": [
    {
      "type": "text",
      "text": "Checks for owner/repo#17: no checks configured (0 passed, 0 pending, 0 failed; total: 0)"
    }
  ],
  "structuredContent": {
    "checks": {
      "total": 0,
      "passed": 0,
      "pending": 0,
      "failed": 0,
      "pending_checks": [],
      "failed_checks": []
    }
  }
}

Error modes

Section titled “Error modes”
  • Invalid issue/PR selection: Provide exactly one of canonical inputs “issue” or “pr”. Calls that omit both or supply both are rejected before repository preparation or GitHub access.
  • Pull requests disabled: Pull requests are disabled for this repository.
  • Shipper issue not found: Could not find Shipper issue S#.
  • No currently linked pull request: S# has no currently linked pull request. Shipper clears this local link when a pull request merges; call shipper_get_pr with the pull request number in pr to inspect it.
  • GitHub pull request not found: Pull request # was not found in owner/repo.
  • Live GitHub retrieval failure: Failed to retrieve live GitHub data for pull request # in owner/repo: No cached or partial data is available.
  • 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.
Section titled “Related tools”