@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.
@@ -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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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.");