michal/mcpctl
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity

feat(cli): config prime-agent — proxy MCP + skills + /mcpctl switcher (hardened across 2 reviews) #95

Open
michal wants to merge 0 commits from feat/config-prime-agent into main
pull from: feat/config-prime-agent
merge into: michal:main
Conversation 0 Commits - Files Changed -
michal commented 2026-08-08 10:30:29 +00:00
Owner
Copy Link

Complete mcpctl config prime-agent feature, hardened across two review rounds. Includes the /mcpctl in-app project switcher.

What it does

mcpctl config prime-agent --project X:

  1. Registers the proxy MCP gateway as the single active mcpctl project in ~/.prime/agent/settings.json (merging, preserving non-mcpServers settings, keeping untagged servers like hand-configured sre).
  2. Provisions the project bearer credential in ~/.prime/agent/auth.json (mcp:X; via --token, existing entry, or auto-mint that first revokes prior prime-agent tokens).
  3. Syncs skills into ~/.prime/agent/skills/ (per-project ownership; never deletes another project's skills or untracked hand-authored dirs).
  4. Installs the /mcpctl project-switcher extension into ~/.prime/agent/extensions/ (skip with --skip-extension) so you can switch projects from the prime-agent TUI.
  5. Writes the .mcpctl-project marker (explicit -p is authoritative, never scopes $HOME).

Also adds mcpctl skills sync --agent prime-agent for re-syncing.

Review hardening (round 1 + round 2)

  • settings.json / auth.json — both fail loudly on corrupt JSON (refuse to overwrite) instead of swallow-and-rewrite destroying every other setting/credential; auth.json is written 0600.
  • skills ownership — canonical scope (project name, or null for globals; legacy undefined adopted); orphan removal can fire for global-only syncs; a same-named skill owned by a different project is preserved, not clobbered.
  • switching — one active mcpctl project via a mcpctlManaged tag; the extension reads that tag (no false short-circuit); an explicit -p updates a differing marker.
  • credentials — a project left with no usable credential exits non-zero (the extension checks child exit status); mint revokes stale never-expiring tokens.
  • DRY — the prime-agent sync is unified into runSkillsSync via target; mcpServers auto-attach is gated + warned for prime-agent (no silent mcpd project mutation).
  • --agent validation — unknown target errors.

Validation

  • tsc --build clean; full CLI suite 544 tests green.
  • Live end-to-end against the deployed gateway; hand-authored sre skill preserved; 544 tests include corrupt-input, 0600-mode, mint-failure-exit, cross-project preservation, and single-active dedup.
Complete `mcpctl config prime-agent` feature, hardened across two review rounds. Includes the `/mcpctl` in-app project switcher. ## What it does `mcpctl config prime-agent --project X`: 1. Registers the proxy MCP gateway as the single *active* mcpctl project in `~/.prime/agent/settings.json` (merging, preserving non-mcpServers settings, keeping untagged servers like hand-configured `sre`). 2. Provisions the project bearer credential in `~/.prime/agent/auth.json` (`mcp:X`; via `--token`, existing entry, or auto-mint that first revokes prior `prime-agent` tokens). 3. Syncs skills into `~/.prime/agent/skills/` (per-project ownership; never deletes another project's skills or untracked hand-authored dirs). 4. Installs the `/mcpctl` project-switcher extension into `~/.prime/agent/extensions/` (skip with `--skip-extension`) so you can switch projects from the prime-agent TUI. 5. Writes the `.mcpctl-project` marker (explicit `-p` is authoritative, never scopes `$HOME`). Also adds `mcpctl skills sync --agent prime-agent` for re-syncing. ## Review hardening (round 1 + round 2) - **settings.json / auth.json** — both fail loudly on corrupt JSON (refuse to overwrite) instead of swallow-and-rewrite destroying every other setting/credential; auth.json is written `0600`. - **skills ownership** — canonical scope (project name, or null for globals; legacy undefined adopted); orphan removal can fire for global-only syncs; a same-named skill owned by a different project is preserved, not clobbered. - **switching** — one active mcpctl project via a `mcpctlManaged` tag; the extension reads that tag (no false short-circuit); an explicit `-p` updates a differing marker. - **credentials** — a project left with no usable credential exits non-zero (the extension checks child exit status); mint revokes stale never-expiring tokens. - **DRY** — the prime-agent sync is unified into `runSkillsSync` via `target`; mcpServers auto-attach is gated + warned for prime-agent (no silent mcpd project mutation). - **`--agent` validation** — unknown target errors. ## Validation - `tsc --build` clean; full CLI suite **544 tests green**. - Live end-to-end against the deployed gateway; hand-authored `sre` skill preserved; 544 tests include corrupt-input, 0600-mode, mint-failure-exit, cross-project preservation, and single-active dedup.
michal added 2 commits 2026-08-08 10:30:30 +00:00
fix(cli): harden config prime-agent sync + install /mcpctl switcher extension
Some checks failed
CI/CD / lint (pull_request) Successful in 1m4s
Details
CI/CD / typecheck (pull_request) Successful in 1m6s
Details
CI/CD / test (pull_request) Successful in 3m9s
Details
CI/CD / build (pull_request) Successful in 2m16s
Details
CI/CD / smoke (pull_request) Failing after 3m27s
Details
CI/CD / publish (pull_request) Has been skipped
Details
eb1642ab1a 
Addresses a review of the `config prime-agent` feature and adds the in-app
project switcher.

Safety/correctness fixes (prime-agent's shared, hand-editable ~/.prime/agent
tree must never suffer silent data loss):
- config/prime-agent.ts: loadPrimeAgentSettings now fails loudly on corrupt
  JSON instead of swallowing it and rewriting the file (which destroyed every
  non-mcpServers setting). A project's mcpServers entry is merged (keeping
  user-added fields) rather than replaced wholesale. Added writePrimeAgentAuth
  / hasPrimeAgentAuth helpers for auth provisioning.
- skills sync: unified the near-verbatim prime-agent copy into runSkillsSync
  via a `target: 'claude' | 'prime-agent'` option (prime-agent-skills.ts is now
  a thin wrapper). Under the prime-agent target it: preserves untracked
  pre-existing skill dirs on first sync (no more rm -rf of hand-authored `sre`),
  records per-project ownership so configuring a second project never deletes
  the first project's skills, skips Claude-only hooks/postInstall, and keeps
  the mcpServers auto-attach step.
- config.ts: `config prime-agent` now (a) provisions the bearer credential in
  auth.json (--token, existing entry, or auto-mint via POST /api/v1/mcptokens),
  (b) writes the .mcpctl-project marker only when none exists up-tree and never
  from $HOME, and (c) propagates the skills sync exit code so auth failures are
  reported instead of swallowing them.
- skills.ts: `--agent` is validated; an unknown value errors instead of
  silently running the Claude sync.

New feature: `config prime-agent` installs a `/mcpctl` project-switcher
extension into ~/.prime/agent/extensions/ (skip with --skip-extension). It lists
mcpctl projects via `mcpctl get projects -o json`, lets you pick one from the
prime-agent TUI, applies the switch through the CLI, and reloads the session.

Regenerated shell completions. Tests: 538 pass (new coverage for settings
corruption, entry merge, auth provisioning, extension install/skip, marker
$HOME handling, untracked/cross-project skill preservation, --agent validation).
fix(cli): close second review on prime-agent sync + switcher (auth, ownership, switching)
Some checks failed
CI/CD / lint (pull_request) Successful in 1m4s
Details
CI/CD / typecheck (pull_request) Successful in 1m5s
Details
CI/CD / test (pull_request) Successful in 3m7s
Details
CI/CD / smoke (pull_request) Failing after 3m13s
Details
CI/CD / build (pull_request) Successful in 2m12s
Details
CI/CD / publish (pull_request) Has been skipped
Details
fa7055ac5e 
Addresses the second round of `config prime-agent` review (10 findings).

auth.json (config/prime-agent.ts) — the settings.json data-loss fix had a twin:
- loadPrimeAgentAuth now fails loudly on corrupt JSON instead of swallow-and-
  rewrite, so one syntax error can no longer destroy the provider API key and
  every other project's credential. hasPrimeAgentAuth shares that guarantee.
- writePrimeAgentAuth writes 0600 (preserving an existing file's mode) instead
  of the default umask — bearer tokens are no longer world-readable on first
  creation.

state ownership (commands/skills.ts) — the ownership model edge cases:
- orphan-removal guard now normalises a canonical scope (project name, or null
  for globals; legacy undefined adopted to current scope) instead of comparing
  null against undefined, so global-only syncs and pre-PR state can no longer
  leave stale skills on disk forever.
- a same-named skill *tracked* to a different project is preserved (with a
  warning) rather than silently overwritten in the shared flat tree.
- mcpServers auto-attach is gated behind !isPrimeAgent with an explicit warning
  (prime-agent's HTTP gateway must not mutate shared mcpd project attachments);
  this also makes the earlier dropped-attach concern explicit rather than silent.

single-active project + switcher (config/prime-agent.ts, prime-agent-extension.ts):
- registerPrimeAgentMcp tags the project's entry mcpctlManaged:true and removes
  other mcpctl-managed entries, so prime-agent has one *active* mcpctl project
  while preserving untagged servers (hand-configured sre, websearch, etc).
- the /mcpctl extension now reads that tag as the single source of truth for the
  active project, fixing the false short-circuit / no-op switch.

config.ts command:
- an explicit -p now updates a differing up-tree .mcpctl-project marker (scope
  no longer silently reverts on the next sync), no-ops when it matches, and
  still never scopes $HOME.
- a project left with no usable credential now exits non-zero (the /mcpctl
  extension checks child exit status, so it no longer reports a successful
  switch after provisioning failed).
- skills sync is treated as best-effort: settings+auth determine switch success,
  so a skills error no longer falsely fails the switch.
- token minting now revokes prior active `prime-agent` tokens before creating a
  fresh one (no more never-expiring token litter / lost-credential duplication).

Tests (544 green): corrupt auth.json refusal, 0600 mode, mint-failure exit
code, single-active dedup preserving untagged sre, cross-project overwrite
preservation, and global-orphan removal on global-only sync.
michal added 1 commit 2026-08-08 11:01:57 +00:00
fix(cli): close third review — token collision, migration, ownership
Some checks failed
CI/CD / typecheck (pull_request) Successful in 1m5s
Details
CI/CD / lint (pull_request) Successful in 2m13s
Details
CI/CD / test (pull_request) Successful in 1m20s
Details
CI/CD / build (pull_request) Successful in 2m9s
Details
CI/CD / smoke (pull_request) Failing after 2m44s
Details
CI/CD / publish (pull_request) Has been skipped
Details
170dc06496 
Round 2 fixed the first review but introduced regressions of its own, all
of which only bite against state written by the previously installed build.

`config prime-agent`:
- Mint each credential under a unique `prime-agent-<stamp>` name again.
  `McpToken` is unique on (name, projectId) and revoke is a soft delete, so
  round 2's fixed `prime-agent` name could only ever be minted once per
  project — and the revoke-first ordering destroyed the working credential
  before discovering the mint would fail.
- Provision the credential BEFORE touching settings.json. Registering the
  new project unmounts the previously active one, so a failed mint must not
  be able to leave prime-agent with no working project at all. The command
  now aborts with settings.json untouched.
- Retire only the token this auth.json actually held, once its replacement
  is stored. Sweeping every `prime-agent*` token for the project would
  revoke the credential another install (or a custom --output run) is
  using; anything else that looks orphaned is reported, not deleted.
- Validate a pre-existing credential instead of trusting its presence: a
  revoked or expired token used to short-circuit provisioning and leave
  prime-agent broken while the command reported success. Matched by
  tokenPrefix against the project's active tokens, so the secret is never
  sent. Fails open when the API can't be consulted.
- Actually write auth.json 0600. `writeFile`'s mode is ignored for an
  existing file and prime-agent creates auth.json itself at 0644, so chmod
  after writing.
- Recognise the untagged mcpServers entries older CLIs wrote (canonical
  proxy URL + an `mcp:<name>` mcpctl PAT in auth.json) so a switch unmounts
  them instead of leaving two gateways live. Hand-configured servers have
  no such credential and are still preserved. Same rule in the `/mcpctl`
  switcher's active-project lookup.
- Add `--skip-marker`, and pass it from the `/mcpctl` switcher: the
  extension runs from whatever directory prime-agent was started in, and
  was silently re-scoping that repo's `.mcpctl-project`.

`skills sync --agent prime-agent`:
- Record ownership from the skill's own scope, not the syncing project's.
  Globals were being pinned to whichever project happened to sync them,
  after which every other project refused to update them forever.
- Never adopt legacy, ownership-less state into the current scope. Round 2
  did, which deleted the other project's skills on the first sync after
  upgrading. Such entries are attributed to the project that last wrote the
  state file, and left alone when that isn't the project syncing now.
- Close the overwrite-guard bypass: a sync with no project, or a global
  landing on a project-owned name, could still clobber and re-own a
  tracked skill.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB
Some checks failed
CI/CD / typecheck (pull_request) Successful in 1m5s
Details
CI/CD / lint (pull_request) Successful in 2m13s
Details
CI/CD / test (pull_request) Successful in 1m20s
Details
CI/CD / build (pull_request) Successful in 2m9s
Details
CI/CD / smoke (pull_request) Failing after 2m44s
Details
CI/CD / publish (pull_request) Has been skipped
Details
This branch is already included in the target branch. There is nothing to merge.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/config-prime-agent:feat/config-prime-agent
git checkout feat/config-prime-agent
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
michal
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: michal/mcpctl#95
Delete Branch "feat/config-prime-agent"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?