feat(cli): burrow mcp agent onboarding and install progress#150
Merged
Conversation
Add `burrow mcp` to connect Burrow's MCP server to a coding agent without
hand-editing a config file. It previews by default and mutates only when the
user appends `install`, so it never surprises them: `burrow mcp <tool>` shows
exactly what will change, and `burrow mcp <tool> install` applies it.
Per-tool adapters, each seam-isolated for unit testing:
- claude: runs `claude mcp add --scope user burrow -- burrow-mcp` via its CLI,
with a `claude mcp get burrow` pre-check so a repeat run no-ops instead of
surfacing the CLI's duplicate error, and a manual-command hint when the CLI
is not on PATH.
- cursor: merges `burrow` into ~/.cursor/mcp.json, preserving other servers,
backing the file up first, idempotent on a second run.
- codex: appends an [mcp_servers.burrow] table to ~/.codex/config.toml with a
plain-text, backed-up, idempotent edit (no TOML parser dependency).
Add a TTY-aware install progress indicator: the apply loop animates a single
rewriting `Applying resources... i/total` line on a real terminal and stays
silent (only the existing summary) when stdout is not a terminal, so captured
and piped output remain clean.
Point the post-install tail at connecting an agent over MCP rather than at a
`burrow app deploy` command, since Burrow is agent-driven.
Signed-off-by: Nicholas Phillips <nsphilli@gmail.com>
Codex and GitHub Copilot both ship a native `mcp` subcommand of the same shape as Claude Code, so connect them through their CLIs rather than hand-editing a config file, and add Copilot as a fourth supported tool. Factor claude, codex, and copilot into one generic CLI-backed adapter parameterized by binary, display name, and the exact `add` args (claude alone needs `--scope user`); all three share the `<bin> mcp get burrow` idempotency check and the `<bin> mcp add ... burrow -- burrow-mcp` invocation. Cursor stays the separate JSON file-merge adapter, since it has no CLI, with its backup and idempotency intact. Drop the codex config.toml text-append path (and its path seam) entirely. The `burrow mcp` overview, the post-install guidance, and arg validation now list all four tools. Signed-off-by: Nicholas Phillips <nsphilli@gmail.com>
Expand `burrow mcp` to the wider agent set and document onboarding end to end.
- opencode: a file-config adapter for ~/.config/opencode/opencode.json, since
OpenCode's `mcp add` wires only remote (URL) servers. It merges a local stdio
server (`mcp.burrow = {type: local, command: [burrow-mcp], enabled: true}`),
preserving $schema and any other servers, backing the file up first, and is
idempotent. The written config is accepted by the opencode CLI (verified with
`opencode mcp list`).
- aider: recognized but reported as unsupported (Aider has no MCP support), with
a pointer to burrow-mcp for anyone running an MCP bridge. It mutates nothing.
- unknown tools no longer error: `burrow mcp <x>` for an agent with no built-in
adapter prints how to add burrow-mcp by hand, the built-in list, and a support
link, since burrow-mcp is a plain stdio server any MCP-capable tool can use.
- the bare `burrow mcp` overview lists opencode and closes with the same
burrow-mcp pointer and support link.
Add docs/getting-started.md: a two-part walkthrough (set up Burrow on your
cluster, then connect your agent) with a per-agent support table, and refactor
the README quickstart to three commands plus a link to the full guide.
Signed-off-by: Nicholas Phillips <nsphilli@gmail.com>
incognick
force-pushed
the
install-onboarding-ux
branch
from
3851021 to
d261f31
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an install-UX and agent-onboarding surface to the Burrow CLI, plus a live install progress indicator, plus a getting-started guide. Three parts:
burrow mcp(new command)Connects Burrow's MCP server (
burrow-mcp) to a coding agent without hand-editing a config file. It previews by default and mutates only when the user appendsinstall:burrow mcpprints an overview: what it does, the supported tools, and how to preview then apply, closing with a pointer thatburrow-mcpis a plain stdio server any MCP-capable tool can use.burrow mcp <tool>previews exactly what will be added and mutates nothing (and reports when a tool is already configured).burrow mcp <tool> installapplies it, idempotently, backing up any file it edits.Built-in setup: claude, cursor, codex, copilot, opencode.
addargs (claude alone needs--scope user). Each uses<bin> mcp get burrowas an idempotency pre-check and<bin> mcp add ... burrow -- burrow-mcpto add the server. A missing binary prints the manual command instead of failing hard.~/.cursor/mcp.json, opencode into~/.config/opencode/opencode.json(a local stdio server under themcpkey). Both preserve other servers and top-level keys, back the file up first, and are idempotent. The opencode config Burrow writes was verified against the realopencode mcp list.burrow-mcpfor anyone running an MCP bridge; it mutates nothing.burrow mcp <unknown>does not error. It explains how to addburrow-mcpby hand, lists the built-in tools, and links a support request.TTY-aware install progress
The apply loop animates a single rewriting
Applying resources... i/totalline on a real terminal, and stays silent (only the existingApplied N resource(s): ...summary) when stdout is not a terminal, so CI, piped, and e2e-captured output stay clean. Terminal detection is via a smallisTerminalhelper overgolang.org/x/term(already in the module graph).Post-install guidance
The post-install tail now points at connecting an agent over MCP (
burrow mcp claude (or: cursor, codex, copilot)) rather than at aburrow app deploycommand, since Burrow is agent-driven.Docs
docs/getting-started.md: a two-part walkthrough (set up Burrow on your cluster, then connect your agent) with a per-agent support table and a "do not see your agent?" pointer.burrow install <context>;burrow mcp <tool> install) plus a prominent link to the full guide.Tests
mcp_test.go: preview mutates nothing for every tool; the CLI-backed tools (claude/codex/copilot) are exercised through a shared table that asserts the exactaddinvocation when absent, the already-configured no-op when<bin> mcp getsucceeds, and the manual-command hint on a LookPath miss; cursor and opencode install create+merge, preserve other servers/keys, back up a pre-existing file, and are idempotent; aider prints the unsupported message with no side effects; the unknown-tool fallback prints the pointer and support link; arg validation.apply_test.go: non-TTY apply emits the summary and no carriage return.install_test.go: the post-install guidance points atburrow mcp.burrow mcp.task checkis green,gofmt -lis clean,go test ./...passes.Note
This branch is based on
cli-help-kubectl-style(#149), so it inherits that PR's help template. GitHub will show it stacked on #149's changes until #149 merges; that is expected.