# gh_pullfrog MCP Tools

this directory contains the mcp (model context protocol) server tools for interacting with github.

## available tools

### check suite tools

#### `get_check_suite_logs`
get workflow run logs for a failed check suite with intelligent log analysis.

**parameters:**
- `check_suite_id` (number): the id from check_suite.id in the webhook payload

**replaces:** `gh run list` and `gh run view --log`

**returns:**
structured failure information for each failed job:
- `_instructions`: explains how to use each field
- `failed_jobs[]`: array of failed job results, each containing:
  - `job_id`, `job_name`, `job_url`: job identification
  - `failed_steps`: which CI steps failed (e.g., "Step 6: Run tests")
  - `log_index`: array of interesting lines (errors, warnings, failures) with line numbers
  - `excerpt`: ~80 line curated window around the last error
  - `full_log_path`: path to complete log file for deeper investigation

**log_index types:**
- `error`: lines matching `##[error]`, `Error:`, `ERR_`, `exit code N`
- `warning`: lines matching `##[warning]`, `WARN`
- `failure`: lines matching `N failed`, `FAIL`, `✕`
- `trace`: stack trace lines (deduplicated)

**workflow for using results:**
1. scan `log_index` to see where errors/warnings/failures are located in the log
2. read `excerpt` for immediate context around the main error
3. if excerpt doesn't show what you need, read specific line ranges from `full_log_path`
4. check `failed_steps` and read the workflow yml to understand what command failed

**example:**
```typescript
// when handling a check_suite_completed webhook
const result = await mcp.call("gh_pullfrog/get_check_suite_logs", {
  check_suite_id: check_suite.id
});

// result.failed_jobs[0].log_index shows:
// [
//   { line: 181, content: "WARN  Failed to create bin...", type: "warning" },
//   { line: 1079, content: "Error: expect(received).toBe(expected)", type: "error" },
//   ...
// ]
// use these line numbers to read specific sections from full_log_path
```

### review tools

#### `get_review_comments`
get all line-by-line comments for a specific pull request review, including full thread context for replies.

**parameters:**
- `pull_number` (number): the pull request number
- `review_id` (number): the id from review.id in the webhook payload
- `approved_by` (string, optional): only return comments this user gave a 👍 to

**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/comments`

**returns:**
- `commentsPath`: path to XML file with full comment details
- `reviewer`: github username of the review author
- `count`: number of comments to address

**output format (XML):**
```xml
<review_comments count="2" reviewer="colinmcd94">

<summary>
  <comment id="67890" file="src/utils/auth.ts" line="42">Actually, can you use a type guard...</comment>
  <comment id="67891" file="src/api/handler.ts" line="15">This should handle the error case</comment>
</summary>

<comment id="67890" file="src/utils/auth.ts" line="42" author="colinmcd94">
  <thread>
    <message id="12345" author="colinmcd94">Please add null checking here</message>
    <message id="23456" author="octocat">What about using optional chaining?</message>
  </thread>
  <diff>
@@ -40,7 +40,7 @@
   const user = getUser(id);
-  return user.name;
+  return user?.name;
  </diff>
  <body>Actually, can you use a type guard instead?</body>
</comment>

</review_comments>
```

- `<summary>` lists all comments to address with truncated preview
- `<thread>` shows parent comments (when replying to existing thread)
- `<diff>` contains the diff hunk around the commented line
- `<body>` is the actual comment text to address

**example:**
```typescript
// when handling a pull_request_review_submitted webhook
await mcp.call("gh_pullfrog/get_review_comments", {
  pull_number: 47,
  review_id: review.id
});
```

#### `list_pull_request_reviews`
list all reviews for a pull request.

**parameters:**
- `pull_number` (number): the pull request number

**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews`

**returns:**
array of reviews with:
- review id, body, state (approved/changes_requested/commented)
- user, commit_id, submitted_at, html_url

**example:**
```typescript
await mcp.call("gh_pullfrog/list_pull_request_reviews", {
  pull_number: 47
});
```

#### `reply_to_review_comment`
reply to a PR review comment thread explaining how the feedback was addressed.

**parameters:**
- `pull_number` (number): the pull request number
- `comment_id` (number): the ID of the review comment to reply to
- `body` (string): the reply text explaining how the feedback was addressed

**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies`

**returns:**
the created reply comment including:
- comment id, body, html_url
- in_reply_to_id showing it's a reply to the specified comment

**example:**
```typescript
// after addressing a review comment
await mcp.call("gh_pullfrog/reply_to_review_comment", {
  pull_number: 47,
  comment_id: 2567334961,
  body: "removed the function as requested"
});
```

### output tools

#### `set_output`
set the action output for consumption by subsequent workflow steps. useful when pullfrog is used as a step in a user-defined CI workflow (e.g., generating release notes).

**parameters:**
- `value` (string): the output value to expose

**returns:**
- `success`: true on success

the value will be available as the `result` output of the action, accessible via `${{ steps.<step-id>.outputs.result }}`.

**example:**
```typescript
// when generating content for downstream consumption
await mcp.call("gh_pullfrog/set_output", {
  value: "## Release Notes\n\n- Added new feature X\n- Fixed bug Y"
});
```

**usage in workflow:**
```yaml
- uses: pullfrog/pullfrog@v1
  id: notes
  with:
    prompt: "Generate release notes for v2.0.0"

- uses: softprops/action-gh-release@v1
  with:
    body: ${{ steps.notes.outputs.result }}
```

### other tools

see individual files for documentation on other tools:
- `comment.ts` - create, edit, and update comments
- `issue.ts` - create issues
- `output.ts` - set action output for workflow consumption
- `pr.ts` - create pull requests
- `prInfo.ts` - get pull request information
- `review.ts` - create pull request reviews
- `selectMode.ts` - select execution mode

## usage in agents

agents should prefer using the mcp tools provided by this server. the `gh` cli is available as a fallback if needed, but mcp tools handle authentication and provide better integration.

the agent instructions automatically include guidance on using these tools.

