feat(mcp): agentmark-mcp install — auto-wire detected AI clients - #38
Merged
Conversation
The friction-killer that pairs with the new .pkg / .msi installers.
After someone double-clicks the installer, the next thing they have
to do today is figure out which JSON config file to edit and where.
This subcommand does it for them: detects what's installed on the
box, writes the right config blocks, supports dry-run + rollback.
CLI surface:
agentmark-mcp start the MCP server (default)
agentmark-mcp serve same, explicit
agentmark-mcp install auto-wire detected clients
agentmark-mcp install --client=cursor target specific clients
agentmark-mcp install --dry-run show what would change
agentmark-mcp uninstall remove our entry
agentmark-mcp doctor diagnose what's installed
agentmark-mcp --help
Supported clients (config path on macOS shown; mirrored on other OS):
claude-code ~/.claude.json
claude-desktop ~/Library/Application Support/Claude/claude_desktop_config.json
cursor ~/.cursor/mcp.json
windsurf ~/.codeium/windsurf/mcp_config.json
codex ~/.codex/config.toml (TOML — surfaces a "not yet
supported, edit manually"
error pending a TOML writer)
All four supported clients use the same `mcpServers` JSON shape, so
one writer covers them; only the file path differs per descriptor.
Safety:
- Every write creates a `<path>.bak` copy first; rollback is one
`mv` away.
- Refuses to overwrite malformed JSON (would silently lose user
config otherwise).
- Writes go through temp file + atomic rename.
- Auto-detection of the launcher command walks the bundled-installer
layout first (relocatable), then PATH, then falls back to
process.execPath.
The install / uninstall results are reported per-client with one of:
added | updated | already_present | removed | not_present | skipped | error
Plus a per-row message (backup path on writes; error detail on errors).
Tests (13 new, 504 total):
- readJson + writeJson atomic round-trips
- .bak created on overwrite
- parent-dir auto-create
- refuses malformed JSON
- applyEntry adds + updates + preserves siblings
- removeEntry returns removed=false when no entry
- installToClients rejects unknown client ids
- dry-run doesn't touch disk
Smoke-tested end-to-end against this developer's actual ~/.claude.json
via `--dry-run` (file was correctly left alone).
Pairs with PR #37 (.pkg / .msi installer): after a one-click install,
`agentmark-mcp install` is the one-command setup that gets every
AI tool on the box talking to the agentmark MCP server.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
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
2 participants
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
CLI surface
```
agentmark-mcp start the MCP server (default)
agentmark-mcp serve same, explicit
agentmark-mcp install auto-wire detected clients
agentmark-mcp install --client=cursor target specific clients
agentmark-mcp install --dry-run show what would change
agentmark-mcp uninstall remove our entry
agentmark-mcp doctor diagnose what's installed
agentmark-mcp --help
```
Supported clients
All four use the same `mcpServers` JSON shape, so one writer covers them; only the file path differs per descriptor.
Safety
Result reporting
Per-client action tag: `added` / `updated` / `already_present` / `removed` / `not_present` / `skipped` / `error`, plus a per-row message (backup path on writes; error detail on errors).
```
$ agentmark-mcp install
agentmark-mcp install — results:
✓ Claude Code [added] /Users/me/.claude.json
backup: /Users/me/.claude.json.bak
✓ Cursor [added] /Users/me/.cursor/mcp.json
· Windsurf [already_present] /Users/me/.codeium/windsurf/mcp_config.json
```
Test plan
🤖 Generated with Claude Code