feat!: add Grok Build support and atomic server replacement

Merged
AN
4mo ago
+651-28

Breaking change — v2.0.0

This PR bumps add-mcp from 1.14.0 to 2.0.0.

Re-installing a server under an existing name now replaces that server's entire entry instead of deep-merging new fields into the old entry. Callers that relied on omitted fields surviving a re-install must pass the complete desired server configuration.

This fixes invalid hybrid configurations such as stale stdio command / args / env fields remaining beside a new remote url. The behavior applies to TOML, JSON, and YAML. Unrelated servers and every other section of the config file are still preserved.

What changed

  • add Grok Build as a first-class agent with grok-build and grok selectors
  • write project config to .grok/config.toml and global config to $GROK_HOME/config.toml, falling back to ~/.grok/config.toml
  • map stdio, HTTP, and SSE servers to Grok's native [mcp_servers.<name>] TOML schema
  • preserve headers and ${VAR} placeholders and map add-mcp timeouts from milliseconds to Grok's tool_timeout_sec
  • replace an existing server entry atomically when its transport or fields change
  • document the breaking replacement contract and Grok Build support in the README, docs, package metadata, changelog, and website

Why this replaces the earlier PRs

This consolidates and supersedes #78 and #83 on top of current main.

#78 established the core Grok Build integration, but its branch became conflicted and the current Grok documentation also requires $GROK_HOME support. Direct runtime testing additionally exposed stale fields when reinstalling a server under the same name with a different transport; the atomic replacement work from #83 is included here and released as a documented major-version behavior change.

Credit

Thank you to @franjorub for the original Grok Build implementation in #78. Francisco's two original commits are preserved in this branch under his GitHub author identity, and the changelog credits him directly.

Thank you to @vishk23 for the atomic replacement fix in #83. That commit is likewise preserved under its original author identity.

Validation

  • bun run registry:verify — 1,326 entries verified
  • bun run build
  • bun run typecheck
  • bun run test — 352 tests passed
  • real CLI coverage for the grok alias, project/global scope, custom $GROK_HOME, default fallback, SSE, headers, literal ${VAR} values, timeout conversion, and both stdio/remote replacement directions
  • official Grok Build CLI 0.2.111 smoke test in an isolated temporary home:
    • grok inspect --json discovered the generated server and identified its SSE transport
    • grok mcp list --json accepted the headers and tool_timeout_sec = 2
  • full repository Prettier pass in an isolated worktree; every file touched by this PR was unchanged

Implementation follows the current official Grok Build MCP and settings documentation:

Summary by CodeRabbit

  • New Features
    • Added support for Grok Build, including the grok alias and project or global installations.
    • Added support for Grok Build remote server settings, headers, and timeouts.
  • Bug Fixes
    • Reinstalling a server now replaces its existing configuration instead of retaining outdated settings.
  • Documentation
    • Updated supported-agent lists, configuration guidance, aliases, and release notes.
  • Chores
    • Released version 2.0.0 and streamlined the default test command.