@craftsamo/github-tools 0.3.0 → 0.4.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 +61 -26
- package/dist/cli.js +2426 -310
- package/dist/mcp.js +2532 -484
- package/dist/opencode.js +2430 -314
- package/package.json +5 -7
- package/plugin.json +1 -1
- package/plugin.yaml +13 -1
- package/skills/github-projects/SKILL.md +172 -0
package/README.md
CHANGED
|
@@ -4,18 +4,18 @@ GitHub tools for coding agents: issues, project boards, pull requests,
|
|
|
4
4
|
repositories, releases and Actions. One implementation, delivered to each
|
|
5
5
|
agent harness in the form that suits it best.
|
|
6
6
|
|
|
7
|
-
| Harness | Delivery
|
|
8
|
-
| -------------- |
|
|
9
|
-
| OpenCode V2 | native plugin (npm package, with skills)
|
|
10
|
-
| OpenCode V1 | native plugin (npm package, no skills)
|
|
11
|
-
| Claude Code | plugin: MCP server and skills
|
|
12
|
-
| Codex | plugin: MCP server and skills
|
|
13
|
-
| Grok Build | plugin: MCP server and skills
|
|
14
|
-
| Antigravity | plugin: MCP server and skills
|
|
15
|
-
| Hermes Agent | native plugin (Python, calls the command line)
|
|
16
|
-
| other MCP host | MCP server from npm
|
|
17
|
-
|
|
18
|
-
0.3.0 moved the package from `craftsamo/agent-github` to `craft-agent/github-tools` and renamed it: npm `@craftsamo/github-tools` (was `@craftsamo/agent-github`, now
|
|
7
|
+
| Harness | Delivery | Pinned by |
|
|
8
|
+
| -------------- | ---------------------------------------------- | ------------------------------ |
|
|
9
|
+
| OpenCode V2 | native plugin (npm package, with skills) | the version in the package |
|
|
10
|
+
| OpenCode V1 | native plugin (npm package, no skills) | the version in the package |
|
|
11
|
+
| Claude Code | plugin: MCP server and skills | the release tag, as the ref |
|
|
12
|
+
| Codex | plugin: MCP server and skills | the release tag, as the ref |
|
|
13
|
+
| Grok Build | plugin: MCP server and skills | the release tag, as `@ref` |
|
|
14
|
+
| Antigravity | plugin: MCP server and skills | the release tag's tree URL |
|
|
15
|
+
| Hermes Agent | native plugin (Python, calls the command line) | the release commit, as the SHA |
|
|
16
|
+
| other MCP host | MCP server from npm | the version in the package |
|
|
17
|
+
|
|
18
|
+
0.3.0 moved the package from `craftsamo/agent-github` to `craft-agent/github-tools` and renamed it: npm `@craftsamo/github-tools` (was `@craftsamo/agent-github`, now removed from npm), plugin and MCP server `github-tools`, programs `github-tools` and `github-tools-cli`, settings `GITHUB_TOOLS_*`. Allow rules, plugin installs and MCP configurations written for 0.2.0 change; the tool IDs do not.
|
|
19
19
|
|
|
20
20
|
The tools need [Node.js](https://nodejs.org/) 24 or later and the
|
|
21
21
|
[GitHub CLI](https://cli.github.com/), authenticated as you.
|
|
@@ -98,11 +98,14 @@ fails there with a message saying so).
|
|
|
98
98
|
grok plugin install craft-agent/github-tools@v<version> --trust
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
+
Grok starts the MCP server in the session's working directory, so inside a clone
|
|
102
|
+
a bare issue number names an issue of that repository.
|
|
103
|
+
|
|
101
104
|
### Antigravity
|
|
102
105
|
|
|
103
106
|
Install from the tree of the release tag, never from the default branch, which
|
|
104
|
-
has no built `dist
|
|
105
|
-
|
|
107
|
+
has no built `dist/`; Antigravity clones the tag into
|
|
108
|
+
`~/.gemini/config/plugins/github-tools`.
|
|
106
109
|
|
|
107
110
|
```sh
|
|
108
111
|
agy plugin install https://github.com/craft-agent/github-tools/tree/v<version>
|
|
@@ -138,7 +141,8 @@ Add the server to the host's MCP configuration. Flags go in `args`:
|
|
|
138
141
|
## Tools and skills
|
|
139
142
|
|
|
140
143
|
Each toolset comes with a skill that tells an agent how to use its tools. A
|
|
141
|
-
toolset with no tools yet registers none (
|
|
144
|
+
toolset with no tools yet registers none (so far `issues` and `projects` have
|
|
145
|
+
tools).
|
|
142
146
|
|
|
143
147
|
### Issues (`issues`)
|
|
144
148
|
|
|
@@ -158,19 +162,46 @@ The skill is [`github-issues`](skills/github-issues/SKILL.md), shown as
|
|
|
158
162
|
An issue's kind is the organization's Issue Type of that name when it defines
|
|
159
163
|
one, otherwise a `type:<kind>` label.
|
|
160
164
|
|
|
165
|
+
### Project boards (`projects`)
|
|
166
|
+
|
|
167
|
+
| Tool | What it does | Class |
|
|
168
|
+
| ------------------------------- | --------------------------------------------------------------------------------------- | ---------- |
|
|
169
|
+
| `github_project_read` | `view` a board with its fields and views, `list` boards, or `item_list` a board's items | read |
|
|
170
|
+
| `github_project_create` | create a board, or reuse the one of that title, with the standard fields and views | idempotent |
|
|
171
|
+
| `github_project_field_ensure` | add a field, or the missing options of a single select | idempotent |
|
|
172
|
+
| `github_project_view_ensure` | add a saved view with its fields, columns, grouping and sort | idempotent |
|
|
173
|
+
| `github_project_link` | link a board to a repository of the same owner | idempotent |
|
|
174
|
+
| `github_project_unlink` | unlink a board from a repository | idempotent |
|
|
175
|
+
| `github_project_item_add` | put an issue or pull request on a board, or return its item, with field values | idempotent |
|
|
176
|
+
| `github_project_item_create` | create a draft item with field values | add |
|
|
177
|
+
| `github_project_item_edit` | set or clear field values, and change a draft's title and body | overwrite |
|
|
178
|
+
| `github_project_item_archive` | archive an item | overwrite |
|
|
179
|
+
| `github_project_item_unarchive` | bring an archived item back | overwrite |
|
|
180
|
+
| `github_project_item_convert` | turn a draft into an issue, with its kind, labels and milestone | add |
|
|
181
|
+
|
|
182
|
+
The toolset is off by default: add `projects` to `toolsets`. The skill is
|
|
183
|
+
[`github-projects`](skills/github-projects/SKILL.md), shown as
|
|
184
|
+
`github-tools:github-projects` in Claude Code and `github-tools:projects` in
|
|
185
|
+
Hermes. A board is named by its number, `owner/N`, URL or title (`Roadmap` when
|
|
186
|
+
none is given), and found among the boards linked to the repository, then its
|
|
187
|
+
organization's, then the viewer's. The token needs the `project` scope
|
|
188
|
+
(`gh auth refresh -s project`). No API sets a roadmap view's date fields, so
|
|
189
|
+
after `github_project_create` set the Roadmap view's "Date fields" to Start and
|
|
190
|
+
Target in the web UI.
|
|
191
|
+
|
|
161
192
|
## Reads and writes
|
|
162
193
|
|
|
163
194
|
Every read tool is named `github_<domain>_read`. Reads can run unasked; writes
|
|
164
195
|
are confirmed by the harness.
|
|
165
196
|
|
|
166
|
-
| Harness | Reads without asking
|
|
167
|
-
| ----------- |
|
|
168
|
-
| OpenCode | always; the plugin asks only before a write
|
|
169
|
-
| Claude Code | the rule `mcp__plugin_github-tools_github-tools__*_read` in `permissions.allow` of `~/.claude/settings.json` or a project
|
|
170
|
-
| Codex | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do
|
|
171
|
-
| Grok Build | `grok --allow 'MCPTool(github-tools__*_read)'`
|
|
172
|
-
| Antigravity |
|
|
173
|
-
| Hermes | always; the plugin asks only before a write
|
|
197
|
+
| Harness | Reads without asking |
|
|
198
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
199
|
+
| OpenCode | always; the plugin asks only before a write |
|
|
200
|
+
| Claude Code | the rule `mcp__plugin_github-tools_github-tools__*_read` in `permissions.allow` of `~/.claude/settings.json` or a project |
|
|
201
|
+
| Codex | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do |
|
|
202
|
+
| Grok Build | `grok --allow 'MCPTool(github-tools__*_read)'` |
|
|
203
|
+
| 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
|
+
| Hermes | always; the plugin asks only before a write |
|
|
174
205
|
|
|
175
206
|
Where a write is asked about, and where it is not:
|
|
176
207
|
|
|
@@ -178,6 +209,10 @@ Where a write is asked about, and where it is not:
|
|
|
178
209
|
a rule asks for it: add the `github_*` rule shown under [OpenCode](#opencode).
|
|
179
210
|
- **Codex** under `codex exec`, and **Grok Build** under `grok -p`, refuse a
|
|
180
211
|
write they cannot ask about, unless it is allowed beforehand.
|
|
212
|
+
- **Antigravity** asks before any MCP tool no rule allows, reads included, and
|
|
213
|
+
names the plugin's server `github-tools_github-tools` (plugin, then server).
|
|
214
|
+
`agy -p` refuses a tool it cannot ask about; `--dangerously-skip-permissions`
|
|
215
|
+
runs every tool unasked.
|
|
181
216
|
- **Hermes** `hermes chat -q` refuses a write it cannot ask about; `hermes -z`
|
|
182
217
|
and `--yolo` skip approval, so writes then run unasked.
|
|
183
218
|
|
|
@@ -214,9 +249,9 @@ environment variable in `env:` is allowed). Where each harness reads them:
|
|
|
214
249
|
exclude_tools: [github_pr_merge]
|
|
215
250
|
```
|
|
216
251
|
|
|
217
|
-
- **Claude Code and Antigravity** start the plugin's server without flags
|
|
218
|
-
|
|
219
|
-
|
|
252
|
+
- **Claude Code and Antigravity** start the plugin's server without flags and
|
|
253
|
+
pass it the client's environment, so set the variables in the environment the
|
|
254
|
+
harness runs in.
|
|
220
255
|
- **Codex and Grok Build** pass no environment to a plugin's MCP server, so the
|
|
221
256
|
`GITHUB_TOOLS_*` variables have no effect there. To change settings in Codex,
|
|
222
257
|
add the server under `[mcp_servers]` in Codex's config with flags in `args` (as
|