agy-mcp-plugins

# agy-mcp-plugins

Wire MCP servers and package/install plugins into Google's **Antigravity (AGY)**
image so an AGY worker can reach the flywheel substrate (Agent-Mail, the br/beads
bridge) and run the AgentOps corpus in its own harness. Sibling of `agy-native`,
which drives the loop; this skill supplies the tool surface that loop runs against.

## Overview / When to Use

AGY's extension surface is **plugins** — a plugin tree (`plugin.json` + `skills/`,
`subagents/`, `hooks.json`, and a `mcpServers` declaration) imported, validated,
and enabled through `agy plugin {import,validate,install,enable,disable,uninstall,link,list}`.
MCP servers reach AGY *through* that plugin model (declared in a plugin's
`mcpServers`, or via the AGY settings at `~/.gemini/settings.json`), not through a
standalone gemini-cli `mcp` subcommand. A bare `SKILL.md` under `~/.gemini/skills/`
is portable and needs no `plugin.json` just to expose a skill — but a *tool server*
must be declared, enabled, and reachable before any skill that depends on it runs.

Use this skill when standing up the AGY lane in the flywheel, when a freshly built
MCP server must become reachable to an AGY worker, or when distributing the
AgentOps bundle to AGY as a plugin.

This is **operator-side**: it drives the flywheel harness. Never surface these
commands or this framing in client-facing AI Partner content.

**AGY ≠ gemini-cli.** Do not reach for `gemini mcp`, `gemini extensions`, or
`gemini -p` — those belong to the retired gemini-cli image. AGY's runtime is
`agy` / `agy -p`, and its extension unit is the **plugin**.

## ⚠️ Critical Constraints

- **Rule 1 — Verify the live surface first.** Run `agy plugin help` (and
  `agy plugin <sub> --help`) before acting. **Why:** the subcommand shape shifts
  between Antigravity releases; acting on a remembered shape silently writes a
  malformed plugin or settings entry that breaks later `agy` runs.
- **Rule 2 — List before and after every mutation.** Run `agy plugin list` before
  and after import/install/enable/disable. **Why:** the effective tool surface is
  the list output, not the command you believed you ran.
- **Rule 3 — Declare only scoped MCP servers.** Register only the servers the AGY
  task actually needs (Agent-Mail, the br bridge, a specific connector). **Why:**
  every registered server widens the tool blast radius an AGY worker can call.
- **Rule 4 — Disable before uninstall when uncertain.** Prefer
  `agy plugin disable <name>` as the reversible first step over `uninstall`.
  **Why:** uninstalling a working plugin destroys config that may belong to
  another lane; disable is recoverable.
- **Rule 5 — Never inline secrets.** Declare MCP tokens by env-var reference in
  the plugin's `mcpServers` / settings, never as a literal in a tracked file.
  **Why:** `plugin.json` and `~/.gemini/settings.json` are plaintext and often
  synced across the fleet — an inlined token leaks everywhere.
- **Rule 6 — Keep the `dcg` guard wired.** `~/.gemini/settings.json` carries a
  `BeforeTool` → `dcg` hook on `run_shell_command`; do not remove or shadow it
  when adding plugins/servers. **Why:** it blocks destructive commands that an
  auto-approved AGY worker would otherwise run.
- **Rule 7 — Operator-side; invoke-never-rebuild.** Drive `agy`; do not re-author
  AGY, do not write under `~/dev/agentops`, do not push agentops. **Why:** AGY is
  Emanuel's substrate — own a thin adapter, not the tool.

## Workflow / Methodology

### Phase 1: Inventory the current surface
```bash
agy plugin help               # confirm the live subcommand shape (Rule 1)
agy plugin list               # installed plugins + enabled state (the BEFORE list)
```
Record installed plugins, their enabled state, and any MCP servers already declared
in `~/.gemini/settings.json` / enabled plugins.
**Checkpoint:** the target plugin/server name is NOT already present, OR you have
decided repair vs. leave-as-is. Do not blind-add over an existing name.

### Phase 2: Declare an MCP server (the tool-reach path)
AGY reaches an MCP server through a plugin's `mcpServers` declaration (or the AGY
settings). A minimal plugin tree exposing one server:
```
agy-tools/
  plugin.json     # { "name":"agy-tools", "version":"0.1.0",
                  #   "mcpServers": { "agent-mail": { "command":"mcp-agent-mail" },
                  #     "beads-br": { "command":"br", "args":["mcp"],
                  #                   "env": { "BR_DB": "$BR_DB" } } } }
```
For a remote/HTTP MCP, declare its `url` and a `*_ENV_VAR` token reference (never
the literal token — Rule 5). Validate, then install + enable:
```bash
agy plugin validate ./agy-tools
agy plugin install ./agy-tools     # reads plugin.json (or name@marketplace)
agy plugin enable agy-tools
agy plugin list                    # the AFTER list — server-bearing plugin enabled
```
**Checkpoint:** `agy plugin list` shows the plugin enabled; the declared server
appears in the effective surface with the expected scope.

### Phase 3: Ship a plugin bundle (the distribution path)
Distribute the AgentOps bundle the AGY-native way — import an existing tree or
install from a `plugin.json` / marketplace reference:
```bash
agy plugin import claude            # pull an existing Claude plugin tree into AGY
agy plugin import gemini            # or an existing gemini plugin tree
agy plugin validate ./agentops-bundle
agy plugin install ./agentops-bundle        # local tree
agy plugin install agentops@<marketplace>   # or a marketplace reference
agy plugin enable agentops
```
Portable-skill note: the corpus already lives at `~/.gemini/skills/<name>/SKILL.md`
and AGY reads `SKILL.md` directly — no `plugin.json` is needed *just* to expose a
skill; the plugin path is for servers, subagents, hooks, and bundled distribution.
**Checkpoint:** `agy plugin list` shows the bundle installed and enabled from the
expected source.

### Phase 4: Smoke-test the tool surface
Run a read-only AGY worker that exercises the wiring; captur