@pymodel/antigravity-mcp 0.0.0-stage → 0.1.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/AGENTS.md +54 -0
- package/CLAUDE.md +7 -0
- package/LICENSE +21 -0
- package/README.md +501 -2
- package/assets/banner.svg +70 -0
- package/assets/benchmarks.svg +80 -0
- package/dist/index.js +3913 -0
- package/docs/multi-client-support.md +323 -0
- package/package.json +75 -4
- package/scripts/install-skills.mjs +281 -0
- package/skills/antigravity-mcp/SKILL.md +226 -0
- package/skills/antigravity-mcp/references/dispatch-and-poll.md +229 -0
- package/skills/antigravity-mcp/references/multi-task-queues.md +77 -0
- package/skills/antigravity-mcp/references/review-and-land.md +154 -0
- package/skills/antigravity-mcp/references/writing-the-brief.md +126 -0
- package/skills/antigravity-mcp/scripts/model-selection.mjs +93 -0
- package/skills/antigravity-mcp/scripts/relay.mjs +898 -0
- package/skills/antigravity-mcp/scripts/workspace.mjs +161 -0
- package/skills/antigravity-mcp-routing/SKILL.md +94 -0
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
# Antigravity MCP: coding-agent setup
|
|
2
|
+
|
|
3
|
+
Verified against the official host documentation on **2026-11-21**.
|
|
4
|
+
|
|
5
|
+
Antigravity MCP is a third-party MCP stdio server that lets coding agents delegate
|
|
6
|
+
work to Google's Antigravity CLI (`agy`). This project is maintained independently;
|
|
7
|
+
it is not an official Google MCP server. Pi, OpenCode, Codex, and Claude Code can
|
|
8
|
+
launch it as a local process. Other hosts need an MCP stdio client or can use the
|
|
9
|
+
bundled CLI relay described in the [README](../README.md#bundled-skills).
|
|
10
|
+
|
|
11
|
+
Install `@pymodel/antigravity-mcp@0.1.0` using the [npm instructions](#npm-installation), or build locally. The GitHub repository has been renamed to
|
|
12
|
+
[PyModel/antigravity-mcp](https://github.com/PyModel/antigravity-mcp). Existing
|
|
13
|
+
checkouts can update their remote using the
|
|
14
|
+
[migration instructions](../README.md#migration-from-claude-agy-mcp).
|
|
15
|
+
|
|
16
|
+
## Start with the local build
|
|
17
|
+
|
|
18
|
+
Follow the README's [installation](../README.md#install) and
|
|
19
|
+
[build](../README.md#build) instructions. Keep the checkout and its installed
|
|
20
|
+
dependencies available: hosts will launch its built `dist/index.js`.
|
|
21
|
+
|
|
22
|
+
From that checkout, print the two absolute paths needed by the examples:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
node -p 'process.execPath'
|
|
26
|
+
node -p 'require("node:path").resolve("dist/index.js")'
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Replace `/absolute/path/to/node` and
|
|
30
|
+
`/absolute/path/to/antigravity-mcp/dist/index.js` in the configuration blocks with
|
|
31
|
+
those results. The checkout directory may still be named `claude-agy-mcp`; use its
|
|
32
|
+
actual path. Preserve other server entries when merging configuration.
|
|
33
|
+
|
|
34
|
+
Install and authenticate [Antigravity CLI](https://antigravity.google/docs/install?tab=cli)
|
|
35
|
+
for the same operating-system user that runs the host. Confirm its metadata is
|
|
36
|
+
available from that environment:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
agy --version
|
|
40
|
+
agy models
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Use an absolute `AGY_PATH` if the host's environment cannot find `agy`; the
|
|
44
|
+
[environment settings](#authentication-and-environment-settings) differ by host.
|
|
45
|
+
Select the project being delegated through the tools' `cwd` and, when needed,
|
|
46
|
+
`dirs` arguments. The bridge checkout is the server installation, not necessarily
|
|
47
|
+
the project to analyze.
|
|
48
|
+
|
|
49
|
+
## Pi
|
|
50
|
+
|
|
51
|
+
Pi added MCP support as a **built-in extension in version 0.99.0 on
|
|
52
|
+
September 29, 2026**. Use a current Pi release for the configuration below; older
|
|
53
|
+
releases require an upgrade or a separately installed adapter with its own setup.
|
|
54
|
+
See the [official changelog](https://pi.dev/changelog) and
|
|
55
|
+
[MCP guide](https://docs.pi.dev/latest/mcp).
|
|
56
|
+
|
|
57
|
+
Merge this into `~/.pi/agent/mcp.json` for user scope, or `.pi/mcp.json` for a
|
|
58
|
+
trusted project:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"antigravity": {
|
|
64
|
+
"command": "/absolute/path/to/node",
|
|
65
|
+
"args": ["/absolute/path/to/antigravity-mcp/dist/index.js"],
|
|
66
|
+
"timeout": 3660
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Pi's `timeout` is in **seconds**, defaults to 60, and resets on progress
|
|
73
|
+
notifications. Check connections with `pi mcp list` or `/mcp`. Run `/reload` after
|
|
74
|
+
changing the file during a session.
|
|
75
|
+
|
|
76
|
+
Current Pi does not require a third-party MCP adapter. An installed extension
|
|
77
|
+
that registers `/mcp`, such as `pi-mcp-adapter`, replaces the built-in integration
|
|
78
|
+
inside sessions. Follow that extension's documentation if using it. Pi SDK
|
|
79
|
+
sessions must explicitly load the built-in MCP extension; the CLI configuration
|
|
80
|
+
alone does not configure an SDK resource loader.
|
|
81
|
+
|
|
82
|
+
## OpenCode
|
|
83
|
+
|
|
84
|
+
The following is the current **native V2** format. Merge it into project
|
|
85
|
+
`opencode.jsonc` or user `~/.config/opencode/opencode.jsonc`:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"$schema": "https://opencode.ai/config.json",
|
|
90
|
+
"mcp": {
|
|
91
|
+
"servers": {
|
|
92
|
+
"antigravity": {
|
|
93
|
+
"type": "local",
|
|
94
|
+
"command": ["/absolute/path/to/node", "/absolute/path/to/antigravity-mcp/dist/index.js"],
|
|
95
|
+
"timeout": {
|
|
96
|
+
"execution": 3660000
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Run `opencode mcp list` to check the connection. V2 groups entries under
|
|
105
|
+
`mcp.servers`; a configured server connects unless `disabled` is true. The
|
|
106
|
+
`timeout` object uses **milliseconds** and separates `startup`, `catalog`, and
|
|
107
|
+
`execution`. Defaults are 30 seconds, 30 seconds, and 12 hours respectively. The
|
|
108
|
+
example deliberately bounds execution to 61 minutes.
|
|
109
|
+
|
|
110
|
+
Supported V1 configuration remains accepted by V2 and is normalized in memory.
|
|
111
|
+
V1 placed entries directly under `mcp` and used `enabled` and a numeric `timeout`.
|
|
112
|
+
Keep each server entry in one format; do not give a V1 client the native V2 block.
|
|
113
|
+
See [MCP servers](https://opencode.ai/docs/mcp-servers/),
|
|
114
|
+
[configuration locations](https://opencode.ai/docs/config/), and the
|
|
115
|
+
[V1 migration guide](https://opencode.ai/docs/migrate-v1/).
|
|
116
|
+
|
|
117
|
+
## Codex CLI and IDE
|
|
118
|
+
|
|
119
|
+
Merge this table into `~/.codex/config.toml` for user scope, or
|
|
120
|
+
`.codex/config.toml` for a trusted project:
|
|
121
|
+
|
|
122
|
+
```toml
|
|
123
|
+
[mcp_servers.antigravity]
|
|
124
|
+
command = "/absolute/path/to/node"
|
|
125
|
+
args = ["/absolute/path/to/antigravity-mcp/dist/index.js"]
|
|
126
|
+
startup_timeout_sec = 30
|
|
127
|
+
tool_timeout_sec = 3660
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Run `codex mcp list` or use `/mcp` in the CLI. Both timeout values use **seconds**;
|
|
131
|
+
the documented defaults are 10 seconds for startup and 60 seconds for a tool.
|
|
132
|
+
Use the longer tool timeout for delegation.
|
|
133
|
+
|
|
134
|
+
Codex CLI and its IDE integration share the host's MCP configuration. A hosted
|
|
135
|
+
chat does not automatically read a local `config.toml` or gain access to the local
|
|
136
|
+
process. See the [official MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
|
|
137
|
+
The documented CLI registration syntax was also checked against local
|
|
138
|
+
`codex-cli 0.172.0-alpha.2`; no server was registered during that check.
|
|
139
|
+
|
|
140
|
+
## Claude Code
|
|
141
|
+
|
|
142
|
+
For user scope, replace both absolute paths and run:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
claude mcp add-json --scope user antigravity \
|
|
146
|
+
'{"type":"stdio","command":"/absolute/path/to/node","args":["/absolute/path/to/antigravity-mcp/dist/index.js"],"timeout":3660000}'
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
For shared project scope, merge this into the project's `.mcp.json` instead:
|
|
150
|
+
|
|
151
|
+
```json
|
|
152
|
+
{
|
|
153
|
+
"mcpServers": {
|
|
154
|
+
"antigravity": {
|
|
155
|
+
"type": "stdio",
|
|
156
|
+
"command": "/absolute/path/to/node",
|
|
157
|
+
"args": ["/absolute/path/to/antigravity-mcp/dist/index.js"],
|
|
158
|
+
"timeout": 3660000
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Check with `claude mcp get antigravity` or `/mcp`. Project servers may need approval
|
|
165
|
+
inside the host. `--scope user` applies across projects; the CLI's default local
|
|
166
|
+
scope applies only to the current project for that user.
|
|
167
|
+
|
|
168
|
+
The per-server `timeout` is a hard wall-clock tool limit in **milliseconds**;
|
|
169
|
+
progress does not extend it. `MCP_TOOL_TIMEOUT` configures Claude Code's
|
|
170
|
+
cross-server tool limit, while `MCP_TIMEOUT` configures startup. These environment
|
|
171
|
+
variables are Claude Code settings, not portable MCP settings. See
|
|
172
|
+
[Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp).
|
|
173
|
+
|
|
174
|
+
## Timeout settings
|
|
175
|
+
|
|
176
|
+
The examples use 61-minute host limits. These are configuration choices, not the
|
|
177
|
+
hosts' default values:
|
|
178
|
+
|
|
179
|
+
| Host | Setting in the server entry | Example | Unit |
|
|
180
|
+
| ----------- | --------------------------- | --------- | ------------------------------------------ |
|
|
181
|
+
| Pi | `timeout` | `3660` | Seconds; progress resets the request timer |
|
|
182
|
+
| OpenCode V2 | `timeout.execution` | `3660000` | Milliseconds |
|
|
183
|
+
| Codex | `tool_timeout_sec` | `3660` | Seconds |
|
|
184
|
+
| Claude Code | `timeout` | `3660000` | Milliseconds; wall-clock limit |
|
|
185
|
+
|
|
186
|
+
The bridge's default `AGY_MAX_RUNTIME` is 3600 seconds, with a 15-second kill
|
|
187
|
+
grace. The extra host minute leaves room for cleanup and an incomplete-result
|
|
188
|
+
report. Account for tool-specific `AGY_TIMEOUT_<TOOL>` or global `AGY_TIMEOUT`
|
|
189
|
+
overrides when choosing the host limit. A queued or multi-delegation call can also
|
|
190
|
+
need more time than one individual AGY turn. Raising only a bridge timeout does
|
|
191
|
+
not extend the host's deadline. See
|
|
192
|
+
[Timeouts and cancellation](../README.md#timeouts-and-cancellation).
|
|
193
|
+
|
|
194
|
+
An interruption does not undo work already performed. Inspect partial output,
|
|
195
|
+
session metadata, and changed files before deliberately continuing. Do not
|
|
196
|
+
automatically resend a whole delegated task after a timeout or connection error.
|
|
197
|
+
|
|
198
|
+
## Authentication and environment settings
|
|
199
|
+
|
|
200
|
+
There are two separate agents: the host runs its own selected model, and this
|
|
201
|
+
server starts AGY for delegated work. Signing into Pi, OpenCode, Codex, or Claude
|
|
202
|
+
Code does not authenticate AGY. Configure AGY's account or provider separately;
|
|
203
|
+
see the README's [pricing and cost](../README.md#pricing-and-cost) discussion for
|
|
204
|
+
subscription versus API billing.
|
|
205
|
+
|
|
206
|
+
These examples use local stdio and do not require a remote MCP OAuth login.
|
|
207
|
+
AGY must be reachable and authenticated in the environment where the server
|
|
208
|
+
actually runs. A desktop app, container, or remote host can have a different
|
|
209
|
+
`PATH`, home directory, and environment from a terminal.
|
|
210
|
+
|
|
211
|
+
To set the bridge's `AGY_PATH`, use the host's documented process environment
|
|
212
|
+
field, with your actual executable path:
|
|
213
|
+
|
|
214
|
+
| Host | Environment configuration |
|
|
215
|
+
| ----------- | -------------------------------------------------------------------------------- |
|
|
216
|
+
| Pi | Add `"env": { "AGY_PATH": "/absolute/path/to/agy" }` to the server entry |
|
|
217
|
+
| OpenCode V2 | Add `"environment": { "AGY_PATH": "/absolute/path/to/agy" }` to the server entry |
|
|
218
|
+
| Codex | Add `[mcp_servers.antigravity.env]` with `AGY_PATH = "/absolute/path/to/agy"` |
|
|
219
|
+
| Claude Code | Add `"env": { "AGY_PATH": "/absolute/path/to/agy" }` to the server entry |
|
|
220
|
+
|
|
221
|
+
The same fields can hold documented bridge options such as `AGY_MAX_RUNTIME`.
|
|
222
|
+
Keep environment values as strings. Do not assume that host API credentials
|
|
223
|
+
select AGY's provider or grant access to the same models.
|
|
224
|
+
|
|
225
|
+
## First model choice
|
|
226
|
+
|
|
227
|
+
With the default `AGY_ASK_MODEL=true`, the bridge asks for the user's model choice
|
|
228
|
+
before its first delegation. An elicitation-capable host can display the model
|
|
229
|
+
form. Other hosts receive an actionable request to call `set_model`.
|
|
230
|
+
|
|
231
|
+
Have the host call `agy_status` to inspect the available inventory, ask the user
|
|
232
|
+
whether to accept the proposed default or choose a listed variant, then call
|
|
233
|
+
`set_model` with that choice. An empty object accepts the proposed default after
|
|
234
|
+
the user agrees. An explicit choice supplies the actual listed model ID; do not
|
|
235
|
+
invent an effort suffix or assume the host's own model is available in AGY.
|
|
236
|
+
`set_model` saves a preference without running a delegated model turn. See
|
|
237
|
+
[Model routing](../README.md#model-routing).
|
|
238
|
+
|
|
239
|
+
## Optional bundled skills
|
|
240
|
+
|
|
241
|
+
The MCP registration exposes tools; skill installation supplies reusable
|
|
242
|
+
delegation instructions. The bundled skill names and directories are:
|
|
243
|
+
|
|
244
|
+
| Skill | Purpose |
|
|
245
|
+
| ----------------------------------------------------------------------- | ------------------------------------------------- |
|
|
246
|
+
| [`antigravity-mcp`](../skills/antigravity-mcp/SKILL.md) | Complete delegation workflow and CLI relay |
|
|
247
|
+
| [`antigravity-mcp-routing`](../skills/antigravity-mcp-routing/SKILL.md) | Companion guidance for choosing a delegation tool |
|
|
248
|
+
|
|
249
|
+
From the checkout, preview discovery and use an explicit destination when
|
|
250
|
+
installing the new skill folders:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
node scripts/install-skills.mjs --list
|
|
254
|
+
|
|
255
|
+
# Codex: user scope.
|
|
256
|
+
node scripts/install-skills.mjs --dir "$HOME/.agents/skills"
|
|
257
|
+
|
|
258
|
+
# OpenCode: user scope.
|
|
259
|
+
node scripts/install-skills.mjs --dir "$HOME/.config/opencode/skills"
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Codex's project location is `.agents/skills`; OpenCode's is `.opencode/skills`.
|
|
263
|
+
OpenCode also discovers compatible `.agents/skills` and `.claude/skills`
|
|
264
|
+
locations, so choose one intended source instead of installing duplicate copies.
|
|
265
|
+
Keep the complete skill directory, including supporting scripts. See
|
|
266
|
+
[Codex skill locations](https://learn.chatgpt.com/docs/build-skills),
|
|
267
|
+
[OpenCode skill discovery](https://opencode.ai/docs/skills/), and the README's
|
|
268
|
+
[bundled skills](../README.md#bundled-skills).
|
|
269
|
+
|
|
270
|
+
If your destination still contains `agy-delegate` or `agy-delegation`, the
|
|
271
|
+
installer warns and leaves those copies intact. Preserve any customizations,
|
|
272
|
+
verify the new skills, then remove the old copies yourself. `--list` only
|
|
273
|
+
previews and does not write. See the
|
|
274
|
+
[installed-skill migration](../README.md#installed-skills) for the full sequence.
|
|
275
|
+
|
|
276
|
+
## npm installation
|
|
277
|
+
|
|
278
|
+
These commands register the canonical npm package. For Pi, Codex,
|
|
279
|
+
and OpenCode, keep the timeout settings from their configuration sections;
|
|
280
|
+
registration alone does not add those custom values.
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
# Pi: user scope by default; add -l for project scope.
|
|
284
|
+
pi mcp add antigravity -- npx -y @pymodel/antigravity-mcp
|
|
285
|
+
|
|
286
|
+
# OpenCode: project scope by default; add --global for user scope.
|
|
287
|
+
opencode mcp add antigravity -- npx -y @pymodel/antigravity-mcp
|
|
288
|
+
|
|
289
|
+
# Codex: configure tool_timeout_sec in config.toml after registration.
|
|
290
|
+
codex mcp add antigravity -- npx -y @pymodel/antigravity-mcp
|
|
291
|
+
|
|
292
|
+
# Claude Code: user scope, including the per-server timeout.
|
|
293
|
+
claude mcp add-json --scope user antigravity \
|
|
294
|
+
'{"type":"stdio","command":"npx","args":["-y","@pymodel/antigravity-mcp"],"timeout":3660000}'
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
For file-based configuration, replace the local launch command with `npx` and
|
|
298
|
+
arguments `-y`, `@pymodel/antigravity-mcp`. OpenCode keeps the executable and
|
|
299
|
+
arguments together in its `command` array; the other hosts have separate
|
|
300
|
+
`command` and `args` fields. Preserve the host-specific timeout and environment
|
|
301
|
+
settings. `antigravity-mcp` is the canonical executable name after installation.
|
|
302
|
+
|
|
303
|
+
## Sources and verification scope
|
|
304
|
+
|
|
305
|
+
The guide verifies documented configuration, not an end-to-end delegation run in
|
|
306
|
+
every host. No model requests or host registrations were made for this check.
|
|
307
|
+
Host versions and administrator policies can affect capability availability.
|
|
308
|
+
|
|
309
|
+
All sources below were checked on **2026-11-21**:
|
|
310
|
+
|
|
311
|
+
- Pi: [MCP servers](https://docs.pi.dev/latest/mcp),
|
|
312
|
+
[CLI commands](https://docs.pi.dev/latest/cli), and
|
|
313
|
+
[0.99.0 release notes, September 29, 2026](https://pi.dev/changelog).
|
|
314
|
+
- OpenCode: [MCP servers](https://opencode.ai/docs/mcp-servers/),
|
|
315
|
+
[configuration](https://opencode.ai/docs/config/),
|
|
316
|
+
[V1 migration](https://opencode.ai/docs/migrate-v1/), and
|
|
317
|
+
[skills](https://opencode.ai/docs/skills/).
|
|
318
|
+
- OpenAI: [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) and
|
|
319
|
+
[Codex skills](https://learn.chatgpt.com/docs/build-skills). The previous
|
|
320
|
+
`developers.openai.com/codex/mcp/` and `developers.openai.com/codex/skills/`
|
|
321
|
+
addresses redirect to these pages.
|
|
322
|
+
- Anthropic: [Claude Code MCP](https://code.claude.com/docs/en/mcp).
|
|
323
|
+
- Google: [Antigravity CLI installation](https://antigravity.google/docs/install?tab=cli).
|
package/package.json
CHANGED
|
@@ -1,6 +1,77 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pymodel/antigravity-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Connect coding agents to Antigravity models for research, code review, and implementation over MCP.",
|
|
5
|
+
"mcpName": "io.github.PyModel/antigravity-mcp",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"antigravity-mcp": "dist/index.js",
|
|
9
|
+
"antigravity-mcp-install-skills": "scripts/install-skills.mjs",
|
|
10
|
+
"claude-agy-mcp": "dist/index.js",
|
|
11
|
+
"claude-agy-mcp-install-skills": "scripts/install-skills.mjs"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"dist",
|
|
15
|
+
"skills",
|
|
16
|
+
"scripts/install-skills.mjs",
|
|
17
|
+
"AGENTS.md",
|
|
18
|
+
"CLAUDE.md",
|
|
19
|
+
"README.md",
|
|
20
|
+
"docs/multi-client-support.md",
|
|
21
|
+
"assets/*.svg",
|
|
22
|
+
"LICENSE"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=18"
|
|
26
|
+
},
|
|
27
|
+
"scripts": {
|
|
28
|
+
"build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --external:@modelcontextprotocol/sdk --external:zod --outfile=dist/index.js",
|
|
29
|
+
"test": "vitest run",
|
|
30
|
+
"typecheck": "tsc --noEmit",
|
|
31
|
+
"format": "prettier --write .",
|
|
32
|
+
"format:check": "prettier --check .",
|
|
33
|
+
"prepare": "node -e \"if(process.env.NODE_ENV!=='production'&&process.env.HUSKY!=='0')import('husky').then(m=>m.default())\"",
|
|
34
|
+
"check:release": "node scripts/check-release.mjs",
|
|
35
|
+
"test:package": "node scripts/smoke-package.mjs",
|
|
36
|
+
"install-skills": "node scripts/install-skills.mjs"
|
|
37
|
+
},
|
|
38
|
+
"keywords": [
|
|
39
|
+
"mcp",
|
|
40
|
+
"claude-code",
|
|
41
|
+
"codex",
|
|
42
|
+
"opencode",
|
|
43
|
+
"pi",
|
|
44
|
+
"antigravity",
|
|
45
|
+
"agy",
|
|
46
|
+
"gemini",
|
|
47
|
+
"delegation"
|
|
48
|
+
],
|
|
49
|
+
"author": "elkaix (https://github.com/elkaix)",
|
|
50
|
+
"repository": {
|
|
51
|
+
"type": "git",
|
|
52
|
+
"url": "git+https://github.com/PyModel/antigravity-mcp.git"
|
|
53
|
+
},
|
|
54
|
+
"license": "MIT",
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
57
|
+
"zod": "^4.6.7"
|
|
58
|
+
},
|
|
59
|
+
"devDependencies": {
|
|
60
|
+
"@commitlint/cli": "^21.2.4",
|
|
61
|
+
"@commitlint/config-conventional": "^21.2.4",
|
|
62
|
+
"@types/node": "^26.6.6",
|
|
63
|
+
"husky": "^9.1.7",
|
|
64
|
+
"lint-staged": "^17.6.1",
|
|
65
|
+
"prettier": "^3.10.1",
|
|
66
|
+
"typescript": "^7.0.2",
|
|
67
|
+
"vitest": "^5.1.1",
|
|
68
|
+
"esbuild": "^0.28.2"
|
|
69
|
+
},
|
|
70
|
+
"lint-staged": {
|
|
71
|
+
"*.{ts,js,json,md,yml,yaml}": "prettier --write"
|
|
72
|
+
},
|
|
73
|
+
"os": [
|
|
74
|
+
"darwin",
|
|
75
|
+
"linux"
|
|
76
|
+
]
|
|
77
|
+
}
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Installs the skills bundled with Antigravity MCP into an agent's skills directory.
|
|
4
|
+
*
|
|
5
|
+
* The MCP server gives an agent the *tools*; a skill tells it when and how to
|
|
6
|
+
* use them. Shipping both in one package means installing the server is enough,
|
|
7
|
+
* instead of asking every user to find and vendor the skill separately.
|
|
8
|
+
*
|
|
9
|
+
* The package exposes this as its own bin, so it is a package selection rather
|
|
10
|
+
* than a subcommand. `npx @pymodel/antigravity-mcp-install-skills` looks like a
|
|
11
|
+
* package name to npx and 404s; `npx @pymodel/antigravity-mcp install-skills`
|
|
12
|
+
* starts the stdio server with a stray argument and hangs.
|
|
13
|
+
*
|
|
14
|
+
* npx --package @pymodel/antigravity-mcp antigravity-mcp-install-skills
|
|
15
|
+
* npx --package @pymodel/antigravity-mcp antigravity-mcp-install-skills --list
|
|
16
|
+
* npx --package @pymodel/antigravity-mcp antigravity-mcp-install-skills --dir DIR
|
|
17
|
+
*
|
|
18
|
+
* Already installed, globally or in a project: `antigravity-mcp-install-skills`.
|
|
19
|
+
* The legacy claude-agy-mcp-install-skills executable remains an alias.
|
|
20
|
+
*/
|
|
21
|
+
import {
|
|
22
|
+
cp,
|
|
23
|
+
lstat,
|
|
24
|
+
mkdir,
|
|
25
|
+
mkdtemp,
|
|
26
|
+
readdir,
|
|
27
|
+
readFile,
|
|
28
|
+
realpath,
|
|
29
|
+
rename,
|
|
30
|
+
rm,
|
|
31
|
+
stat,
|
|
32
|
+
} from "node:fs/promises";
|
|
33
|
+
import { homedir } from "node:os";
|
|
34
|
+
import path from "node:path";
|
|
35
|
+
import { fileURLToPath } from "node:url";
|
|
36
|
+
|
|
37
|
+
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
|
38
|
+
const SOURCE = path.join(HERE, "..", "skills");
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Where the agents on this machine keep skills.
|
|
42
|
+
*
|
|
43
|
+
* Only directories that already exist are written to: creating `~/.claude` for
|
|
44
|
+
* someone who does not use Claude Code would be litter, not installation.
|
|
45
|
+
*/
|
|
46
|
+
const TARGETS = [
|
|
47
|
+
{ name: "Claude Code", dir: path.join(homedir(), ".claude", "skills") },
|
|
48
|
+
{ name: "Codex / shared agents", dir: path.join(homedir(), ".agents", "skills") },
|
|
49
|
+
{
|
|
50
|
+
name: "OpenCode",
|
|
51
|
+
dir: path.join(
|
|
52
|
+
process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config"),
|
|
53
|
+
"opencode",
|
|
54
|
+
"skills",
|
|
55
|
+
),
|
|
56
|
+
},
|
|
57
|
+
{ name: "Pi", dir: path.join(homedir(), ".pi", "agent", "skills") },
|
|
58
|
+
{ name: "zcode", dir: path.join(homedir(), ".zcode", "skills") },
|
|
59
|
+
];
|
|
60
|
+
|
|
61
|
+
async function isDir(p) {
|
|
62
|
+
try {
|
|
63
|
+
return (await stat(p)).isDirectory();
|
|
64
|
+
} catch {
|
|
65
|
+
return false;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** The skills this package ships, read from disk rather than hardcoded. */
|
|
70
|
+
async function bundledSkills() {
|
|
71
|
+
const names = (await readdir(SOURCE, { withFileTypes: true }))
|
|
72
|
+
.filter((e) => e.isDirectory())
|
|
73
|
+
.map((e) => e.name);
|
|
74
|
+
return Promise.all(
|
|
75
|
+
names.map(async (name) => {
|
|
76
|
+
const text = await readFile(path.join(SOURCE, name, "SKILL.md"), "utf8");
|
|
77
|
+
const described = /^description:\s*(?:>-\s*)?([\s\S]*?)(?=\n\w+:|\n---)/m.exec(text);
|
|
78
|
+
const summary = (described?.[1] ?? "").replace(/\s+/g, " ").trim();
|
|
79
|
+
return { name, summary: summary.slice(0, 100) };
|
|
80
|
+
}),
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* True when `dest` is a symlink, which means someone deliberately pointed this
|
|
86
|
+
* skill at a checkout they edit. Replacing it with a frozen copy would silently
|
|
87
|
+
* cut that source of truth loose, so it is skipped unless --force is passed.
|
|
88
|
+
*/
|
|
89
|
+
async function isSymlink(dest) {
|
|
90
|
+
try {
|
|
91
|
+
return (await lstat(dest)).isSymbolicLink();
|
|
92
|
+
} catch {
|
|
93
|
+
return false;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** Inspect legacy entries themselves; never traverse or replace a user's old copy. */
|
|
98
|
+
async function reportLegacySkills(parent) {
|
|
99
|
+
const renamed = [];
|
|
100
|
+
for (const [previous, current] of [
|
|
101
|
+
["agy-delegate", "antigravity-mcp"],
|
|
102
|
+
["agy-delegation", "antigravity-mcp-routing"],
|
|
103
|
+
]) {
|
|
104
|
+
try {
|
|
105
|
+
const entry = await lstat(path.join(parent, previous));
|
|
106
|
+
if (entry.isDirectory() || entry.isSymbolicLink()) renamed.push(`${previous} → ${current}`);
|
|
107
|
+
} catch {
|
|
108
|
+
// A missing or unreadable legacy entry must not prevent a new installation.
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
if (renamed.length) {
|
|
112
|
+
console.log(`Legacy skills in ${parent}: ${renamed.join("; ")}.`);
|
|
113
|
+
console.log(
|
|
114
|
+
"Existing copies are left untouched, including with --force. Migrate custom changes, " +
|
|
115
|
+
"then remove old copies yourself to avoid loading duplicate skills.",
|
|
116
|
+
);
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
async function install(skill, parent, force) {
|
|
121
|
+
const dest = path.join(parent, skill.name);
|
|
122
|
+
await mkdir(parent, { recursive: true });
|
|
123
|
+
const sourceRoot = await realpath(SOURCE);
|
|
124
|
+
const targetRoot = await realpath(parent);
|
|
125
|
+
if (targetRoot === sourceRoot || targetRoot.startsWith(`${sourceRoot}${path.sep}`)) {
|
|
126
|
+
throw new Error("the install directory cannot be the bundled skills source or inside it");
|
|
127
|
+
}
|
|
128
|
+
const lock = path.join(parent, `.${skill.name}.install-lock`);
|
|
129
|
+
try {
|
|
130
|
+
await mkdir(lock);
|
|
131
|
+
} catch (error) {
|
|
132
|
+
if (error.code === "EEXIST") {
|
|
133
|
+
throw new Error(`another installation owns ${lock}; inspect it before retrying`);
|
|
134
|
+
}
|
|
135
|
+
throw error;
|
|
136
|
+
}
|
|
137
|
+
let staging;
|
|
138
|
+
let previous;
|
|
139
|
+
let preserveBackup = false;
|
|
140
|
+
try {
|
|
141
|
+
if (!force && (await isSymlink(dest))) return { dest, skipped: "symlink" };
|
|
142
|
+
staging = await mkdtemp(path.join(parent, `.${skill.name}.install-`));
|
|
143
|
+
const next = path.join(staging, "next");
|
|
144
|
+
// Finish copying before touching the installed version. Staging beside the
|
|
145
|
+
// destination keeps both publication renames on the same filesystem.
|
|
146
|
+
await cp(path.join(SOURCE, skill.name), next, { recursive: true });
|
|
147
|
+
await readFile(path.join(next, "SKILL.md"), "utf8");
|
|
148
|
+
try {
|
|
149
|
+
await lstat(dest);
|
|
150
|
+
previous = path.join(staging, "previous");
|
|
151
|
+
await rename(dest, previous);
|
|
152
|
+
} catch (error) {
|
|
153
|
+
if (error.code !== "ENOENT") throw error;
|
|
154
|
+
previous = undefined;
|
|
155
|
+
}
|
|
156
|
+
try {
|
|
157
|
+
await rename(next, dest);
|
|
158
|
+
} catch (error) {
|
|
159
|
+
if (previous) {
|
|
160
|
+
try {
|
|
161
|
+
await rename(previous, dest);
|
|
162
|
+
previous = undefined;
|
|
163
|
+
} catch (rollbackError) {
|
|
164
|
+
preserveBackup = true;
|
|
165
|
+
throw new Error(
|
|
166
|
+
`publication failed (${error.message}); rollback failed (${rollbackError.message}); ` +
|
|
167
|
+
`the previous skill is preserved at ${previous}`,
|
|
168
|
+
);
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
throw error;
|
|
172
|
+
}
|
|
173
|
+
return { dest };
|
|
174
|
+
} finally {
|
|
175
|
+
// A failed rollback must retain its recovery copy. A completed publication
|
|
176
|
+
// removes stale references by replacing the directory instead of merging.
|
|
177
|
+
try {
|
|
178
|
+
if (staging && !preserveBackup) await rm(staging, { recursive: true, force: true });
|
|
179
|
+
} finally {
|
|
180
|
+
await rm(lock, { recursive: true, force: true });
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
function parseArgs(args) {
|
|
186
|
+
const options = { explicit: undefined, listOnly: false, force: false, help: false };
|
|
187
|
+
for (let i = 0; i < args.length; i++) {
|
|
188
|
+
switch (args[i]) {
|
|
189
|
+
case "--dir": {
|
|
190
|
+
if (options.explicit !== undefined) throw new Error("--dir may be supplied only once");
|
|
191
|
+
const value = args[++i];
|
|
192
|
+
if (!value?.trim() || value.startsWith("-"))
|
|
193
|
+
throw new Error("--dir requires a directory path");
|
|
194
|
+
options.explicit = value;
|
|
195
|
+
break;
|
|
196
|
+
}
|
|
197
|
+
case "--list":
|
|
198
|
+
options.listOnly = true;
|
|
199
|
+
break;
|
|
200
|
+
case "--force":
|
|
201
|
+
options.force = true;
|
|
202
|
+
break;
|
|
203
|
+
case "--help":
|
|
204
|
+
case "-h":
|
|
205
|
+
options.help = true;
|
|
206
|
+
break;
|
|
207
|
+
default:
|
|
208
|
+
throw new Error(`unknown argument: ${args[i]}`);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
return options;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
let options;
|
|
215
|
+
try {
|
|
216
|
+
options = parseArgs(process.argv.slice(2));
|
|
217
|
+
} catch (error) {
|
|
218
|
+
console.error(`install-skills: ${error.message}`);
|
|
219
|
+
process.exit(2);
|
|
220
|
+
}
|
|
221
|
+
const { explicit, listOnly, force, help } = options;
|
|
222
|
+
if (help) {
|
|
223
|
+
console.log("Usage: antigravity-mcp-install-skills [--dir <path>] [--list] [--force]");
|
|
224
|
+
console.log("--list previews without writing; --force replaces a symlinked installation.");
|
|
225
|
+
process.exit(0);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
const skills = await bundledSkills();
|
|
229
|
+
if (listOnly) {
|
|
230
|
+
console.log("Skills bundled with Antigravity MCP:\n");
|
|
231
|
+
for (const s of skills) console.log(` ${s.name}\n ${s.summary}\n`);
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
const targets = explicit
|
|
235
|
+
? [{ name: "explicit", dir: path.resolve(explicit) }]
|
|
236
|
+
: (await Promise.all(TARGETS.map(async (t) => ((await isDir(t.dir)) ? t : null)))).filter(
|
|
237
|
+
Boolean,
|
|
238
|
+
);
|
|
239
|
+
|
|
240
|
+
for (const target of targets) await reportLegacySkills(target.dir);
|
|
241
|
+
|
|
242
|
+
if (listOnly) {
|
|
243
|
+
console.log(
|
|
244
|
+
targets.length
|
|
245
|
+
? `Would install into:\n${targets.map((t) => ` ${t.dir} (${t.name})`).join("\n")}`
|
|
246
|
+
: "No agent skills directory found. Pass --dir to name one.",
|
|
247
|
+
);
|
|
248
|
+
process.exit(0);
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
if (!targets.length) {
|
|
252
|
+
console.error(
|
|
253
|
+
"No agent skills directory found on this machine.\n" +
|
|
254
|
+
"Pass --dir <path> to install somewhere explicitly, or --list to see what is bundled.",
|
|
255
|
+
);
|
|
256
|
+
process.exit(1);
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
let failed = false;
|
|
260
|
+
let skipped = 0;
|
|
261
|
+
for (const target of targets) {
|
|
262
|
+
for (const skill of skills) {
|
|
263
|
+
try {
|
|
264
|
+
const { dest, skipped: why } = await install(skill, target.dir, force);
|
|
265
|
+
if (why) {
|
|
266
|
+
skipped++;
|
|
267
|
+
console.log(`skipped ${skill.name} -> ${dest} (symlink; --force to replace)`);
|
|
268
|
+
} else {
|
|
269
|
+
console.log(`installed ${skill.name} -> ${dest}`);
|
|
270
|
+
}
|
|
271
|
+
} catch (err) {
|
|
272
|
+
failed = true;
|
|
273
|
+
console.error(`failed ${skill.name} -> ${target.dir}: ${err.message}`);
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
if (failed) process.exit(1);
|
|
278
|
+
if (skipped) {
|
|
279
|
+
console.log(`\n${skipped} skipped because they are symlinks to a checkout you maintain.`);
|
|
280
|
+
}
|
|
281
|
+
console.log("\nRestart your agent so it picks the skills up.");
|