David Blass
207 lines
6.5 KiB
Markdown
207 lines
6.5 KiB
Markdown
# 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
|
|
- `delegate.ts` - delegate task to a subagent with a specific mode and effort level
|
|
|
|
## 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.
|
|
|