@craftsamo/github-tools 0.4.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.antigravity-plugin/plugin.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +50 -14
- package/dist/cli.js +6623 -3509
- package/dist/mcp.js +5956 -2851
- package/dist/opencode.js +6732 -3618
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/plugin.yaml +13 -1
- package/skills/github-issues/SKILL.md +56 -23
- package/skills/github-projects/SKILL.md +3 -1
- package/skills/github-pull-requests/SKILL.md +221 -0
package/README.md
CHANGED
|
@@ -141,26 +141,56 @@ Add the server to the host's MCP configuration. Flags go in `args`:
|
|
|
141
141
|
## Tools and skills
|
|
142
142
|
|
|
143
143
|
Each toolset comes with a skill that tells an agent how to use its tools. A
|
|
144
|
-
toolset with no tools yet registers none (so far `issues
|
|
145
|
-
tools).
|
|
144
|
+
toolset with no tools yet registers none (so far `issues`, `pull_requests` and
|
|
145
|
+
`projects` have tools).
|
|
146
146
|
|
|
147
147
|
### Issues (`issues`)
|
|
148
148
|
|
|
149
|
-
| Tool | What it does
|
|
150
|
-
| ---------------------- |
|
|
151
|
-
| `github_issue_read` | `view` one issue in full, or `list` a repository's issues or a parent's sub-issues
|
|
152
|
-
| `github_issue_create` | create an issue with its kind, labels, assignees, milestone, parent and blocked-by issues | add |
|
|
153
|
-
| `github_issue_edit` | change the title, body (or append to it), kind, labels, assignees or
|
|
154
|
-
| `github_issue_comment` | comment on an issue
|
|
155
|
-
| `github_issue_close` | close with a reason (`completed`, `not_planned`, `duplicate`)
|
|
156
|
-
| `github_issue_reopen` | reopen a closed issue
|
|
157
|
-
| `github_issue_relate` | set the parent, sub-issues, blocked-by and blocking issues, sending only what differs
|
|
158
|
-
| `github_issue_develop` | create a branch on GitHub linked to the issue, or return the one already linked
|
|
149
|
+
| Tool | What it does | Class |
|
|
150
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- |
|
|
151
|
+
| `github_issue_read` | `view` one issue in full, or `list` a repository's issues or a parent's sub-issues, with their issue fields | read |
|
|
152
|
+
| `github_issue_create` | create an issue with its kind, labels, assignees, milestone, parent and blocked-by issues, issue fields and a board | add |
|
|
153
|
+
| `github_issue_edit` | change the title, body (or append to it), kind, labels, assignees, milestone or issue fields | overwrite |
|
|
154
|
+
| `github_issue_comment` | comment on an issue | add |
|
|
155
|
+
| `github_issue_close` | close with a reason (`completed`, `not_planned`, `duplicate`) | overwrite |
|
|
156
|
+
| `github_issue_reopen` | reopen a closed issue | overwrite |
|
|
157
|
+
| `github_issue_relate` | set the parent, sub-issues, blocked-by and blocking issues, sending only what differs | idempotent |
|
|
158
|
+
| `github_issue_develop` | create a branch on GitHub linked to the issue, or return the one already linked | idempotent |
|
|
159
159
|
|
|
160
160
|
The skill is [`github-issues`](skills/github-issues/SKILL.md), shown as
|
|
161
161
|
`github-tools:github-issues` in Claude Code and `github-tools:issues` in Hermes.
|
|
162
162
|
An issue's kind is the organization's Issue Type of that name when it defines
|
|
163
|
-
one, otherwise a `type:<kind>` label.
|
|
163
|
+
one, otherwise a `type:<kind>` label. Issue fields (Priority, Effort, Start
|
|
164
|
+
date, Target date and any others) are the organization's own, so only an
|
|
165
|
+
organization's repositories have them; `list` filters by one with
|
|
166
|
+
`field.<name>:<value>` in `query`.
|
|
167
|
+
|
|
168
|
+
### Pull requests and stacks (`pull_requests`)
|
|
169
|
+
|
|
170
|
+
| Tool | What it does | Class |
|
|
171
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
|
|
172
|
+
| `github_pr_read` | `view` one pull request in full, `list` a repository's pull requests, read its `checks` (waiting up to 45 seconds, with failed job logs) or its `diff` | read |
|
|
173
|
+
| `github_pr_create` | open a pull request from a pushed branch, with labels, assignees, reviewers, milestone, closing issues, a board and attachments | add |
|
|
174
|
+
| `github_pr_edit` | change the title, body (or append to it), base, labels, assignees, reviewers, milestone or closing issues | overwrite |
|
|
175
|
+
| `github_pr_comment` | comment, with attachments | add |
|
|
176
|
+
| `github_pr_review` | approve, request changes or comment, with line comments | add |
|
|
177
|
+
| `github_pr_ready` | mark ready for review, or turn back into a draft | idempotent |
|
|
178
|
+
| `github_pr_close` | close | overwrite |
|
|
179
|
+
| `github_pr_reopen` | reopen a closed pull request | overwrite |
|
|
180
|
+
| `github_pr_merge` | merge, with the open layers below it in a stack when asked | administrative |
|
|
181
|
+
| `github_stack_read` | `view` a native stack by its number or a pull request in it, or `list` a repository's stacks | read |
|
|
182
|
+
| `github_stack_link` | join pull requests into a stack, or add them on top of one | idempotent |
|
|
183
|
+
| `github_stack_unlink` | dissolve a stack, leaving its pull requests open | overwrite |
|
|
184
|
+
|
|
185
|
+
The skill is
|
|
186
|
+
[`github-pull-requests`](skills/github-pull-requests/SKILL.md), shown as
|
|
187
|
+
`github-tools:github-pull-requests` in Claude Code and
|
|
188
|
+
`github-tools:pull-requests` in Hermes. The tools do not push: push the branch
|
|
189
|
+
first and pass the commit it pushed as `head_sha`, so a pull request opens, is
|
|
190
|
+
reviewed or merges on exactly that commit. Closing issues are kept as `Closes
|
|
191
|
+
#N` lines in the body, since GitHub has no other way to link them. Stacks use
|
|
192
|
+
GitHub's REST stack endpoints, so the `gh stack` extension is not needed.
|
|
193
|
+
Attachments need gh 2.99 or newer.
|
|
164
194
|
|
|
165
195
|
### Project boards (`projects`)
|
|
166
196
|
|
|
@@ -199,7 +229,7 @@ are confirmed by the harness.
|
|
|
199
229
|
| OpenCode | always; the plugin asks only before a write |
|
|
200
230
|
| Claude Code | the rule `mcp__plugin_github-tools_github-tools__*_read` in `permissions.allow` of `~/.claude/settings.json` or a project |
|
|
201
231
|
| Codex | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do |
|
|
202
|
-
| Grok Build | `grok --allow 'MCPTool(github-tools__*_read)'`
|
|
232
|
+
| Grok Build | `grok --allow 'MCPTool(github-tools__*_read)' --allow 'MCPTool(github_*_read)'` (both rules; see below) |
|
|
203
233
|
| Antigravity | the rule `mcp(github-tools_github-tools/github_issue_read)` in `permissions.allow` of `~/.gemini/antigravity-cli/settings.json`, one for each read tool |
|
|
204
234
|
| Hermes | always; the plugin asks only before a write |
|
|
205
235
|
|
|
@@ -209,6 +239,12 @@ Where a write is asked about, and where it is not:
|
|
|
209
239
|
a rule asks for it: add the `github_*` rule shown under [OpenCode](#opencode).
|
|
210
240
|
- **Codex** under `codex exec`, and **Grok Build** under `grok -p`, refuse a
|
|
211
241
|
write they cannot ask about, unless it is allowed beforehand.
|
|
242
|
+
- **Grok Build** calls the plugin's tools through its `use_tool` tool, and the
|
|
243
|
+
agent often names a tool without its server first (`github_project_read`).
|
|
244
|
+
Grok checks the rules against the name as given, so the server-qualified rule
|
|
245
|
+
alone does not match that first call, and `grok -p` refuses it and stops
|
|
246
|
+
instead of letting the agent retry with `github-tools__github_project_read`.
|
|
247
|
+
The second rule matches the short name; a write still matches neither.
|
|
212
248
|
- **Antigravity** asks before any MCP tool no rule allows, reads included, and
|
|
213
249
|
names the plugin's server `github-tools_github-tools` (plugin, then server).
|
|
214
250
|
`agy -p` refuses a tool it cannot ask about; `--dangerously-skip-permissions`
|