feat(cli): npx-friendly setup — npx -y @thinkfleet/agentmark setup - #42
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>
Two small changes that turn the install subcommand into a one-line
zero-install quickstart for users who already have Node:
1. Add `agentmark` as a second bin alias next to `agentmark-mcp` in
package.json. Lets npx address the package by name:
npx -y @thinkfleet/agentmark setup
…instead of the awkward `npx -y @thinkfleet/agentmark agentmark-mcp install`.
2. Add `setup` and `quickstart` as subcommand synonyms for `install`
in the CLI router. "Install" is what package managers do, "setup"
is what users google. Both work; aliases keep the install-cmd
semantics intact and just give an extra entry point.
Help text now advertises the npx flow prominently:
QUICKSTART (Node already installed)
Run the npm package directly via npx, no global install required:
npx -y @thinkfleet/agentmark setup
Detects Claude Code / Claude Desktop / Cursor / Windsurf in one
go and wires them all up to use this MCP server.
Stacks on PR #38 (the install subcommand itself). Build + smoke
verified locally with `node dist/src/mcp/cli.js setup --dry-run`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
Two small changes that turn the `install` subcommand (PR #38) into a one-line zero-install quickstart for Node users:
Together they make this work:
```sh
npx -y @thinkfleet/agentmark setup
```
Instead of the awkward `npx -y @thinkfleet/agentmark agentmark-mcp install`.
Help text
Advertises the npx flow prominently:
```
QUICKSTART (Node already installed)
Run the npm package directly via npx, no global install required:
Detects Claude Code / Claude Desktop / Cursor / Windsurf in one
go and wires them all up to use this MCP server. Use --dry-run
first to preview.
```
Test plan
🤖 Generated with Claude Code