Epic: Replace MCP with an agent-native CLI

[nicksenap]

Problem

Grove's built-in MCP server adds a second interface and runtime path for a small set of local-agent features:

• JSON-RPC server lifecycle and protocol handling;
• automatic .mcp.json generation and cleanup;
• an SQLite-backed announcements database;
• MCP-specific dependencies, tests, documentation, and failure modes.

The target users are local developers and coding agents such as Claude Code, Codex, and Cursor that already have shell access. Requiring a separate protocol server makes Grove harder to maintain without providing a necessary trust or authentication boundary.

Decision

Make the Grove CLI the only first-party agent interface and remove MCP from Grove core.

Human or coding agent
        ↓
       gw CLI
        ↓
shared workspace service

Grove will not ship or maintain an MCP adapter as part of this work. If future demand appears, an external adapter can wrap the stable CLI contract without changing core.

Goal

A coding agent should be able to discover, inspect, plan, execute, and recover Grove operations safely through ordinary shell commands with stable machine-readable contracts.

This should also improve CI, scripts, and plugins rather than creating an agent-only implementation.

Agent-native CLI contract

Consistent machine mode

Standardize on a global output selector:

gw list --format json
gw status feature-x --format json
gw create ... --format json
gw doctor --format json

In machine mode:

• stdout contains exactly one structured response;
• progress, diagnostics, and debug logs use stderr;
• no colors, spinners, prompts, or version-update notices;
• commands never require a TTY;
• failures return structured errors and meaningful exit codes.

Response envelope

Every machine response should use one versioned envelope:

{
  "ok": true,
  "schemaVersion": 1,
  "result": {},
  "next_actions": []
}

Errors use the same envelope:

{
  "ok": false,
  "schemaVersion": 1,
  "error": {
    "code": "WORKTREE_DIRTY",
    "message": "api has uncommitted changes"
  },
  "fix": "Commit, stash, or explicitly force deletion",
  "next_actions": []
}

Requirements:

• stable machine-readable error codes;
• schema-version policy and compatibility documentation;
• semantic exit codes for usage, permission, conflict, and transient failures;
• filled-in next_actions where a safe/relevant next command exists.

Discovery/context command

Add one cheap composite command for agents:

gw context --format json

It should report, as available:

• current workspace and path;
• source/task provenance;
• repository paths, remotes, live branches, and dirty/ahead/behind state;
• blueprint identity;
• preparation/Oven status;
• safe next actions.

This is a read-only convenience over existing service methods, not a separate state model.

Plan before mutation

Mutating agent workflows should support a structured preview produced by the same validation path as execution:

gw plan create -f workspace.toml -b feat/refunds --format json > plan.json
gw apply plan.json --format json

Destructive plans should identify every repository/path/branch mutation. Applying a saved plan must either execute exactly the reviewed plan or fail when relevant state has changed.

The transactional implementation belongs with #59; this issue owns the public machine contract.

MCP removal

• Stop creating and deleting .mcp.json from workspace lifecycle code.
• Remove the built-in MCP command and command registration.
• Remove internal/mcp/ and its tests.
• Remove the announcements SQLite database and modernc.org/sqlite dependency tree.
• Remove MCP setup from the wizard, diagnostics, e2e suite, and documentation.
• Do not automatically reimplement announce/get_announcements; restore coordination later only if there is demonstrated usage.
• Clean up stale .mcp.json files from existing workspaces safely or document a migration command.

Delivery slices

• Specify the versioned CLI envelope, error codes, stdout/stderr rules, and compatibility policy.
• Add a global machine-output mode while preserving current human-oriented tables.
• Bring create/delete/sync/add/remove/run to structured output parity.
• Add gw context --format json.
• Add shared plan/apply primitives with Epic: Make workspace operations transactional and recoverable #59.
• Update AGENTS.md and public docs with agent usage examples.
• Remove MCP/SQLite and publish migration notes.
• Measure release binary size before and after removal.

Acceptance criteria

• A local coding agent can complete the create → inspect → sync → delete lifecycle without parsing human-formatted output.
• Machine-mode stdout remains valid JSON even during warnings, progress, hooks, and errors.
• Every mutating command supports non-interactive use and returns per-repository results.
• Destructive agent operations have a structured plan/dry-run path.
• No MCP server, .mcp.json lifecycle, announcements database, or SQLite dependency remains in Grove core.
• Unit and e2e tests cover the machine contract and common recovery paths.
• Existing human CLI workflows remain ergonomic and backwards compatible except for the documented MCP removal.

Non-goals

• Supporting agent clients without shell access.
• Maintaining an official MCP compatibility plugin.
• Building an agent runtime, chat UI, or session supervisor.
• Adding an agent-specific parallel implementation of workspace logic.
• Preserving unused announcement behavior solely for feature parity.

Dependencies and sequencing

• Epic: Make workspace operations transactional and recoverable #59 establishes the trustworthy result, rollback, and plan/apply semantics beneath this interface.
• This issue should land before Epic: Turn a task or PR URL into a ready workspace with gw grab #60 so gw grab and future plugins compose the stable CLI rather than private state or duplicated orchestration.