17aa35fba7
Fold augment's runtime-literal conversion branches onto descriptor-driven
hostBehaviors and delete dead code:
- Site A (_applyRuntimeRewrites case 'augment'): the 4 ~/.augment dot-dir
regexes now derive from getDirName('augment') via escapeRegExp (byte-
identical; getDirName('augment')==='.augment') — no runtime literal.
- Site B (applyRuntimeContentRewritesForCommandsInPlace): the
`if (runtime==='augment')` markdown-converter branch now reads
runtime.hostBehaviors.commandBodyConverter and dispatches through a local
COMMAND_BODY_CONVERTERS map (degrade-closed on unknown/absent name).
- Deleted dead `claudeToAugmentTools` map (zero refs; orphaned by ADR-1508
single-sourcing) and the unreachable `else if (isAugment)` agent-conversion
branch (augment ∈ _DESCRIPTOR_AGENTS_RUNTIMES → gated out upstream).
- Incidental orphan cleanup (no-defer): removed the equally-unreachable
`else if (isTrae)` agent-conversion arm left behind by trae's already-merged
migration #2094 (trae ∈ _DESCRIPTOR_AGENTS_RUNTIMES, same upstream gate).
copilot/windsurf/codebuddy arms are removed by their own pending migrations.
UPGRADE 3 (transport:mcp): register the GSD companion MCP server in Augment's
settings.json under mcpServers.gsd (Augment hosts MCP in settings.json, not a
standalone file). mergeGsdMcpServerIntoSettings mutates the in-memory settings
object finishInstall already writes (gated on hostBehaviors.mcpCompanion===
'settings-json'); non-destructive + idempotent; symmetric uninstall removal.
settings.json is golden-excluded, so no golden change. UPGRADE 1 (named/
background dispatch) + UPGRADE 2 (settings-json hook bus, Claude dialect)
were already live in production — this adds tests exercising both.
Golden: byte-identical for all 16 runtimes (folds preserve regex behavior;
MCP lives in golden-excluded settings.json) — verified by a real double-install
tree diff. Tests: declarative-reference-augment (adapter/axes/fail-closed/
undocumented-sub-axes + source-grep guard scoped to conversion-logic branches)
+ augment-upgrades (dispatch negotiation, hook-bus live install, MCP add/
idempotent/preserve/uninstall). Matrix + connect-gsd-mcp-server + a stale
install-on-your-runtime hook-ownership claim corrected; changeset (Changed).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
111 lines
4.4 KiB
Markdown
111 lines
4.4 KiB
Markdown
# How to connect a host to the GSD companion MCP server
|
|
|
|
This guide shows you how to make a MCP-capable host (Claude Code, Codex,
|
|
OpenCode, VS Code, Antigravity CLI, Cursor, Cline, Hermes, Augment Code) drive
|
|
GSD — run GSD
|
|
commands and read/write `.planning/` state — through the companion MCP server,
|
|
with no bespoke plugin.
|
|
|
|
Once connected, three tools appear in the host alongside its others:
|
|
`gsd_invoke_command`, `gsd_read_state`, `gsd_write_state`. (For the tool
|
|
contracts, see the reference section below; for *why* this server exists and
|
|
its trust model, see [ADR-1239](../adr/1239-gsd-embeddable-orchestration-engine.md)
|
|
and the [capability trust model](../explanation/capability-trust-model.md).)
|
|
|
|
## 1. Add the server to your host's MCP config
|
|
|
|
The entry shape is the same everywhere; only the config file and key differ by
|
|
host.
|
|
|
|
```jsonc
|
|
{
|
|
"gsd": {
|
|
"command": "npx",
|
|
"args": ["-y", "@opengsd/gsd-core", "gsd-mcp-server"],
|
|
"cwd": "/abs/path/to/your/project"
|
|
}
|
|
}
|
|
```
|
|
|
|
- **Claude Code / Codex / Cursor / Cline / Hermes** — under the host's
|
|
`mcpServers` object (project or user config).
|
|
- **Augment Code** — under the `mcpServers` block of its own
|
|
`settings.json` (not a standalone MCP config file, unlike Antigravity)
|
|
— global at `~/.augment/settings.json`, project-local at
|
|
`.augment/settings.json`. GSD's installer configures this entry
|
|
automatically (`--augment` installs).
|
|
- **VS Code** — in the workspace MCP servers list.
|
|
- **Antigravity** — under the `mcpServers` block of its standalone
|
|
`mcp_config.json` profile (not embedded in `settings.json`) — global at
|
|
`~/.gemini/antigravity/mcp_config.json` (or the sibling
|
|
`antigravity-ide`/`antigravity-cli` dir GSD resolved into), project-local at
|
|
`.agents/mcp_config.json`. GSD's installer configures this entry
|
|
automatically (`--antigravity` installs).
|
|
- **OpenCode** — under the `mcp` key (**not** `mcpServers`), in
|
|
`~/.config/opencode/opencode.jsonc` (global) or `./opencode.json`
|
|
(project). The entry shape also differs — see below.
|
|
- **Kilo Code** — an OpenCode fork; also under the `mcp` key (**not**
|
|
`mcpServers`), in `~/.config/kilo/opencode.jsonc` (global) or
|
|
`./opencode.json` (project). Same entry shape as OpenCode.
|
|
|
|
Set `cwd` to the project whose `.planning/` you want GSD to manage — the server
|
|
resolves state paths against it.
|
|
|
|
### OpenCode / Kilo entry shape
|
|
|
|
OpenCode (and Kilo, which shares OpenCode's config schema) use a
|
|
`type`/`command`/`timeout` entry under the `mcp` key instead of the generic
|
|
`command`/`args`/`cwd` form above:
|
|
|
|
```jsonc
|
|
{
|
|
"mcp": {
|
|
"gsd": {
|
|
"type": "local",
|
|
"command": ["npx", "-y", "@opengsd/gsd-core", "gsd-mcp-server"],
|
|
"timeout": 10000
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 2. Restart the host
|
|
|
|
On startup the host performs the MCP `initialize` handshake, lists tools, and
|
|
the three GSD tools become callable.
|
|
|
|
## 3. Verify
|
|
|
|
Ask the host to read an existing planning file:
|
|
|
|
```jsonc
|
|
{ "name": "gsd_read_state", "arguments": { "path": "/abs/path/to/your/project/.planning/STATE.md" } }
|
|
```
|
|
|
|
It returns the file's contents. `gsd_invoke_command` takes
|
|
`{family, subcommand, args}` and returns the command-routing hub's structured
|
|
result (the same shape `gsd-tools` produces).
|
|
|
|
## If something does not work
|
|
|
|
- **`command not found: gsd-mcp-server`** — invoke via `npx` as shown above, or
|
|
install the package globally first (`npm i -g @opengsd/gsd-core`).
|
|
- **`gsd_read_state` fails with ENOENT** — the path is resolved literally; pass
|
|
an absolute path under the project's `.planning/`.
|
|
- **The host lists no GSD tools** — confirm the server starts in isolation:
|
|
`npx @opengsd/gsd-core gsd-mcp-server` then send an `initialize` request on
|
|
stdin; it writes a `protocolVersion` response and exits on EOF.
|
|
- **You manage multiple projects** — register one `gsd` entry per project with a
|
|
distinct name and `cwd`; the server is stateless across projects.
|
|
|
|
## Reference — the three tools
|
|
|
|
| Tool | Arguments | Returns |
|
|
|------|-----------|---------|
|
|
| `gsd_invoke_command` | `{family: string, subcommand: string, args?: unknown[]}` | the command-routing hub result (`{ok, …}`) as JSON text |
|
|
| `gsd_read_state` | `{path: string}` | the file contents as text |
|
|
| `gsd_write_state` | `{path: string, content: string}` | `{ok: true, path}` as JSON text |
|
|
|
|
Errors from a tool are returned as MCP tool errors (`isError: true`), not as
|
|
JSON-RPC protocol errors — the host surfaces them in its normal tool-failure UX.
|