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.
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).
Mirror `mcpctl config claude` for prime-agent (which talks to the same mcpctl
proxy MCP gateway over HTTP instead of stdio):
`mcpctl config prime-agent --project X`:
- registers the proxy MCP gateway in ~/.prime/agent/settings.json as
mcpServers.X = { type: "http", url: <gateway>/projects/X/mcp }, merging with
any existing servers (e.g. the bundled `sre` project) and preserving all other
settings
- writes a .mcpctl-project marker so later syncs resolve the project
- syncs the project's skills into ~/.prime/agent/skills/<name>/ as markdown
skills (prime-agent auto-discovers them at session start)
New `mcpctl skills sync --agent prime-agent` target re-syncs the tree later.
- src/cli/src/config/prime-agent.ts: settings.json read/merge/write helpers
- src/cli/src/utils/prime-agent-skills.ts: prime-agent sync (reuses
installSkillAtomic + skills-state; skips Claude-only hooks/postInstall)
- completes config.ts/skills.ts wiring; regenerated shell completions
- tests: commands/prime-agent.test.ts + utils/prime-agent-skills.test.ts
One slow call stalled every later request because the stdin loop awaited each in turn; queued requests were never sent so nothing could time them out and the client saw silence. Dispatch is now concurrent. Regression test verified to fail on the old code.
The bridge's stdin loop awaited every request before reading the next line, so
it handled exactly one at a time. A single slow call therefore stalled every
later request — and because those requests were never even sent, nothing could
time them out. The client saw silence, not an error.
Observed 2026-08-05: two gitea calls through this bridge sat completely mute
until Claude Code aborted them at its own 1800s idle limit, reporting "sent no
response or progress". The upstream was healthy the whole time — a fresh
session answered the same tools in 0.3s, and the gitea MCP server's own log
showed the calls never reached it. They died queued in the bridge.
JSON-RPC ids exist precisely so responses may return out of order, so nothing
here needed a queue. Requests now dispatch concurrently and are tracked in a
set; stdin close awaits them before the session DELETE, otherwise a concurrent
call races the teardown and dies with a 404.
We still serialise until the session id exists: it arrives on the first
response, and firing later requests without it would open a second upstream
session. A client sends `initialize` first and waits for the reply anyway, so
this costs one round trip rather than throughput.
Also makes the per-request timeout configurable via MCPCTL_MCP_TIMEOUT_MS
(default unchanged at 30s) and names it in the timeout error, so a project with
genuinely long tool calls can raise it instead of hitting a hardcoded wall.
Tests pin both halves: a fast request must overtake a slow one (this fails on
the old serial code — verified by reverting), and a failed request must still
produce a JSON-RPC error carrying the original id rather than nothing.
Even "<=8 words" was ignored — the model wrote a full-sentence reasoning, pushing
begin_session to ~7s (thin under the 8s budget). The gate only needs the names, so
request just {"selectedNames":[...]}. Validated live vs vllm-current
(glm-4.6-reap-fast): 1.5s, valid JSON. (reasoning defaults to '' in extractSelection.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
With the fast (no-think) route, gate-selection latency is now proportional to the
ANSWER length (a no-think model runs ~10-13 tok/s), not hidden thinking. A verbose
"reasoning" field pushed a selection to ~9s (over the 8s budget). Request compact
JSON with a <=8-word reasoning → ~2s (vs ~9s prose, or ~1.2s with no reasoning).
Validated live against vllm-fast (glm-4.6-reap-fast): 2.0s, valid selection JSON,
zero reasoning tokens.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Lets ops route gate prompt-selection at a fast (no-think) server Llm independent
of the project's chat llmProvider — so selection stays ~1-2s while chat keeps its
thinking model. Overrides the project llmProvider for the gate's server-selection
path; unset → prior behavior (use the project's llmProvider). Pairs with the
litellm qwen3-fast no-think alias (kubernetes-deployment) + a `vllm-fast` mcpd Llm.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Prompt selection is mechanical classification — it gains nothing from chain-of-
thought, and a reasoning model (qwen3-thinking) otherwise burns its whole budget
reasoning (~40s, 6k+ chars) and blows the gate's 8s timeout. The gate's server
selection request now includes thinking-suppression hints, forwarded verbatim by
mcpd's passthrough adapter to litellm/vLLM:
chat_template_kwargs.enable_thinking=false (Qwen3 hard-off)
reasoning_effort=low (o-series / newer vLLM)
Harmless for models that ignore them; if a backend rejects them the selector
falls back to the local provider. Override via MCPCTL_GATE_SELECT_EXTRA_BODY
(JSON), or '' to disable.
NOT yet validated live — the qwen3-thinking vLLM is crashlooping again (0/1,
HTTP 500), and whether litellm forwards chat_template_kwargs to vLLM is unconfirmed
(the /no_think prompt directive was NOT honored). Validate when the backend
recovers. mcpld gate/selector tests green (75).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cloud/server keys belong at the k8s/mcpd level; mcplocal handles only the user's
personal tokens. The gate's prompt-selection used mcplocal's LOCAL provider
registry (heavy=anthropic = the user's OAuth token, which is API-gated and 404s),
so selection always degraded.
Now LlmPromptSelector tries sources in priority order: (1) the project's server
Llm via mcpd's inference proxy (POST /api/v1/llms/:name/infer) — cloud/server
keys stay at k8s — then (2) the local personal-token provider as fallback. First
source that returns valid selection JSON wins. Extracted pickCompletionText
(content ?? reasoning_content) + extractSelection helpers.
Wiring: GatePluginConfig.llmProvider (from the project), threaded via
createDefaultPlugin; handleBeginSession builds serverInfer from ctx.postToMcpd.
Verified live: POST .../llms/vllm-current/infer returns valid selection JSON
(qwen3-thinking, 4000-token budget). + selector tests (server preferred, local
fallback on error, server-only). mcplocal suite green (755).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The local mcplocal gate resolves heavy=[anthropic]; its OAuth-gated key 404s the
configured opus-4 model, and anthropic.ts (like openai.ts before this series)
JSON.parsed the error body as a completion → empty content → the gate's
misleading "did not contain valid selection JSON". Reject on status >= 400 with
"Anthropic HTTP <status>: <body>" so the true reason (model-not-found / auth)
surfaces as the degradedReason. + parity test.
Note: this makes the error honest; it does not make the local gate SUCCEED — that
needs a working heavy provider (the anthropic OAuth token is fundamentally gated).
The qwen3-thinking gate path (k8s mcplocal) is addressed by the budget+reasoning
fix in the previous commit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The presented→canonical resolver was only built during tools/list, so a
favourite/<tool> call arriving before any list this session fell through to the
namespaced router and 404'd (all/ was fine — it prefix-strips). Real MCP clients
list first, but the smoke test's initialize→call flow exposed it. Extract
buildPresentation() and lazily rebuild the resolver in onToolCallBefore when a
favourite//all/ name isn't resolved yet. + unit test (favourite/ call with no
prior list) and realistic listTools() in the smoke routing case.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two independent, live-reproduced causes of "Smart prompt-selection unavailable
(LLM response did not contain valid selection JSON)" in the gate:
- Cause B (openai.ts request): the response handler JSON.parsed the body with no
res.statusCode check, so a LiteLLM/vLLM HTTP 500 ("Connection error") parsed as
an empty completion and surfaced as generic "bad JSON", masking backend-down.
Now reject on status >= 400 with "OpenAI HTTP <status>: <body>" so the selector
reports the true degradedReason.
- Cause A (parseResponse + selector budget): a reasoning model (qwen3-thinking)
spends its whole 1024-token budget in reasoning_content and emits content=null,
so the {selectedNames} JSON never appears. parseResponse now falls back to
reasoning_content (incl. provider_specific_fields) when content is empty, and
the selector budget is raised 1024 -> 4000 (env MCPCTL_GATE_SELECT_MAX_TOKENS)
so thinking + the JSON answer both fit.
Note: mcpd's chat path got a reasoning_content fallback in PR #67; this is the
separate mcplocal gate-selection provider, which never did. Tests: openai-provider
(500 rejects, reasoning_content capture/preference). mcplocal suite green (749).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Measured winner from the DGX-Spark bake-off (toolsim.py, 145-tool catalog): a
curated favourite/<tool> shortlist + the full all/<server>/<tool> catalog + a
load-bearing "prefer favourite/ first" instruction nearly halved wander (37→20)
and 2.5x'd first-pick (2→5/8) vs a flat catalog. The instruction is load-bearing;
enriching descriptions did not help.
- New mcplocal plugin `favourite-index.ts`: composes AFTER gate (no-ops while
gated), reshapes the ungated upstream catalog into favourite/ + all/, injects
the instruction (onInitialize), and rewrites presented names back to canonical
server/tool in onToolCallBefore so normal routing + content-pipeline still run.
Gate/agent virtual tools pass through untouched; favourites are upstream-only.
- compose.ts: onInitialize now concatenates plugin instructions (was first-non-null)
so favindex can contribute its banner alongside the gate's.
- Per-project config `Project.favouriteIndex` {enabled, tools[], maxFavourites};
surfaced to the proxy via discovery; wired at project-mcp-endpoint when enabled.
- Usage derivation: mcpd tool-usage ranking over tool_call_trace events
(normalizing presented names → canonical), GET /api/v1/audit/tool-usage, and
`mcpctl favourites suggest|list`.
- CLI: `create project` gains --favourite/--favourite-index/--max-favourites;
favouriteIndex round-trips through get -o yaml | apply -f. Completions regenerated.
- Tests: plugin unit (presentation, rewrite routing, gated no-op, collisions),
compose merge, canonicalizeToolName, buildFavouriteIndex, + a live smoke test.
- Docs: docs/tool-presentation.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Record the empirical finding: a Claude subscription OAuth token is gated by
Anthropic (404/429 as a raw API) and can't serve as the server-side fallback,
even though mcpd's adapter now sends it via Bearer. The anthropic-fallback is
wired-but-inert until mcpd Secret anthropic-key holds a real console API key.
Also note the chain is now Pulumi-owned so pulumi up won't wipe it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude subscription / Claude Code keys are OAuth tokens and authenticate with
Authorization: Bearer, not x-api-key. mcpd's server adapter only sent x-api-key,
so registering an OAuth key as a fallback Llm 401'd ("invalid x-api-key").
Mirror the mcplocal client adapter's isOAuth switch so an OAuth key works as a
server-side anthropic fallback.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Chat is LLM-essential but not model-specific — instead of failing when the
pinned model is down/drifted, it now fails over across an ordered chain and
reports which model actually answered.
- Ordered fallback: an Llm declares `extraConfig.fallbacks: string[]`; the
dispatcher builds primary-pool → fallback-pool(s) candidates and tries them
in order (resolveCandidatesWithFallbacks).
- Fail over on real failures, not just transport: runOneInference now advances
on a non-2xx status (e.g. a 400 from a drifted model) or an empty/invalid
completion, not only thrown transport errors. Streaming fails over
pre-first-chunk (already threw on 4xx).
- Transparency: ChatResult + the SSE `final` frame carry {llm, model,
failedOver}; the CLI prints `model: <llm> (<model>)` each turn and
`⚠ failed over → answered by …` when a fallback was used.
- Exhaustion names the last model + upstream body (not "no choice").
Tests: 3 failover unit tests (primary 400 → fallback answers + model reported;
primary answers → failedOver=false; all fail → clear aggregated error).
mcpd 948 + CLI 508 green; tsc + lint clean. docs/reliability.md updated.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mcpctl hung on prompt-reading whenever the LLM misbehaved (thinking model =
minutes; drifted model = silent failure). Root cause: the gate's begin_session
prompt-selection called the LLM with no timeout, its fallback only fired on
error and was silent, and it forced the project's vLLM model onto the anthropic
heavy provider (so selection failed silently every time).
- New withTimeout(run, ms, label): Promise.race + AbortSignal (fetch-based
providers cancel). CompletionOptions.signal threaded into anthropic/openai.
- Gate begin_session: LLM selection is time-bounded (MCPCTL_GATE_LLM_TIMEOUT_MS,
8s); on timeout/error it falls back to deterministic tag matching, logs
[gate] loudly, prepends a ⚠ degraded note to the response, and sets
degraded/degradedReason on the audit gate_decision.
- Gate selector no longer forces the project vLLM model — uses the heavy
provider's own model (fixes the always-silent-fail bug).
- Pagination smart-index is time-bounded too (falls back to byte-range pages).
- Chat (LLM-essential) surfaces the upstream status+body (names model+reason)
instead of "Adapter returned no choice".
- docs/reliability.md documents the principle.
Tests: with-timeout unit tests; gate degradation test (error → visible ⚠ +
deterministic prompts, no hang). mcplocal 737 + mcpd 945 green; tsc clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Chat directly with a Project (no Agent needed): its Prompts become the system
context, its MCP-server tools are callable, its llmProvider/llmModel drive the
LLM, and (opt-in) the model can read secret values. History is saved inside the
project, attributed per user, resumable, and deletable (RBAC-permitting) — "use
it like Claude, scoped to the project".
Backend (reuses the agent-chat orchestrator):
- ChatThread is now agent-XOR-project (schema + migration + CHECK constraint);
new listThreadsByProject / deleteThread on the repo.
- ChatService: prepareProjectContext (project prompt + Prompts by priority,
llm from llmProvider with llmModel override, project tools), shared
runChatLoop/runChatStreamLoop, project thread CRUD with owner enforcement
(404-not-403 on foreign threads), admin-override delete.
- Gated get_secret virtual tool: offered only with --allow-secrets AND the
caller's view:secrets; resolves via SecretService, never routes to a server.
- routes/project-chat.ts (chat SSE+non-stream, threads create/list/delete);
RBAC run:projects:<name>.
CLI:
- `mcpctl chat --project <name>` (+ --allow-secrets), one-shot/REPL/resume.
- REPL /threads, /resume <id>, /delete <id>; project-aware header + /tools.
- `mcpctl get threads --project <name>`, `mcpctl delete thread <id> --project`.
- completions regenerated (--project completes project names).
Tests: 8 new project-chat unit tests; full mcpd (945) + CLI (508) green;
schema validated against Postgres. Docs: docs/chat.md "Project chat" section.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pulumi's closure serializer reaches the dynamic provider's internal submodules
(dist/engine.js, dist/kinds.js) by subpath. An `exports` allowlist with only
"." blocks that: `pulumi preview` failed with "package.json export path for
.../dist/kinds.js not found". Removing `exports` (keeping main/types) lets the
serializer resolve them. Verified end-to-end: a real `pulumi up` from
kubernetes-deployment updated mcpd's qwen3-thinking llm and it probes 200.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New workspace package: a Pulumi dynamic provider (TypeScript, in-process) that
manages mcpctl resources declaratively from any Pulumi program. Motivated by
model drift: when the deployed vLLM/LiteLLM model changes, mcpctl's llm target
must follow, and a Pulumi resource makes that automatic on `pulumi up`.
- Generic core `McpctlResource({ kind, name, spec, mcpd })` round-trips ANY
mcpctl resource kind; typed `Llm` wrapper for ergonomics.
- Engine talks direct HTTP to mcpd's REST API (ported from cli/api-client.ts),
mirroring apply's name-keyed upsert (PUT strips immutable name/type) and
get -o json's read field-stripping. No mcpctl binary needed → CI-friendly.
- CRUD/diff/check with correct replace semantics (name/type/kind/mcpd.url force
delete-before-replace), 429 retry, secret token in state.
- Validation deferred to mcpd's Zod schemas, so new resource kinds work with no
provider release.
- CommonJS build so the serialized dynamic provider's module refs are captured.
- 18 Vitest tests (mocked mcpd + Pulumi mocks); build + lint clean; README with
auth (PAT) setup and consumer example for kubernetes-deployment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
auth.ts talked to mcpd over node:http unconditionally with port:url.port,
so an https:// mcpdUrl connected to the ingress on :80, got a 301 redirect
with an empty body (status < 400), and JSON.parse('') crashed login with
"Unexpected end of JSON input". api-client.ts already handled this; the auth
commands did not.
- All 4 auth request fns now pick https/443 and the TLS driver from the URL
protocol, mirroring api-client.ts.
- parseJsonResponse() guard turns any non-JSON <400 body into a clear
"Invalid <ctx> response from mcpd" error instead of a raw SyntaxError.
- login now suggests the previously-used email (when a session for the same
mcpd exists) so pressing Enter reuses it after a session expires.
- Regression tests drive the real default* request fns against a local
HTTP server (valid JSON, empty body, HTML redirect body, https driver
selection) and cover the email-suggestion behaviour.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Operators can now see recent mcpd error/fatal logs without kubectl:
- mcpd tees level>=error pino records into an in-memory ring buffer
(src/mcpd/src/services/error-log-buffer.ts; wired via pino.multistream in
server.ts so stdout logging is unchanged). Captures structured errors incl.
fatal kinds like BACKEND_TOKEN_DEAD.
- GET /api/v1/logs/errors?limit=N (RBAC: 'logs' operation).
- CLI: 'mcpctl errors [-n N]' renders TIME/LEVEL/DETAIL, most-recent-first.
Buffer unit tests (6); full suite 2223 passing. Needs a deploy to go live.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
scripts/provision-openbao.sh recreates the KV mount + app-mcpd ACL policy +
periodic app-mcpd-role that mcpd's secret backend needs. These were hand-made
and uncaptured, so an OpenBao re-init silently dropped the policy (root cause
of the recurring BACKEND_TOKEN_DEAD / 403-on-secret-write). Now reproducible:
run after any OpenBao (re)init; --seed also mints a token, writes bao-creds,
and restarts mcpd. Mirrors src/shared/src/vault/policy.ts. Idempotent + --dry-run.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a 'Secrets:' line to mcpctl status (and a secretBackends array to JSON
output) showing each backend healthy (✓) or, when tokenMeta.lastRotationError
is set (e.g. a dead OpenBao token), red ✗ with the error inline. Makes a
recurrence of BACKEND_TOKEN_DEAD visible at a glance instead of only in mcpd
logs. Verified live: 'Secrets: bao* ✓, default ✓'. +3 tests (28 total).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
passwd smoke read ~/.config/mcpctl/credentials and silently skipped; the CLI
stores creds at ~/.mcpctl/credentials. Now verified live against prod (4/4).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
scripts/deploy-k8s.sh replaces fulldeploy.sh's rollout-restart-:latest pattern
(which bypassed Pulumi and left no rollback target). It:
- gates on pnpm test:run
- captures the current prod images as immutable rollback tags (skopeo) + records digests
- pg_dumps the prod DB before the destructive-capable `prisma db push`
- builds/pushes mcpd+mcplocal tagged with the git short-sha
- pins the sha in ../kubernetes-deployment/Pulumi.homelab.yaml and runs
`pulumi up --target` the mcpd/mcplocal Deployments only (avoids the SOGo
docker-image resource that needs a local docker daemon)
- waits for rollout + /healthz, installs the CLI RPM, runs smoke tests
- prints an exact rollback recipe on post-cutover failure
--dry-run validated: tests/pg_dump/targeted preview run read-only.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Restores the lost `mcpctl passwd` command and builds the backend it needs.
Backend (mcpd):
- POST /api/v1/users/me/password — self-service change, requires current
password. Gated by a new `set-own-password` operation.
- PUT /api/v1/users/:id/password — admin reset of another user, gated by
edit:users (admins have edit:*). Added users name-resolver for CUID→email.
- UserService.setPassword/verifyPassword; UserRepository.update accepts
passwordHash + findByIdWithHash.
RBAC, no exceptions: self password change is a default, admin-revocable
permission. Every new user gets a `self-<id>` RbacDefinition granting
`set-own-password`, seeded on create + bootstrap, gated by the
`allowSelfPasswordChange` system setting (stored in the mcpctl-system-settings
secret, default ON; admins disable globally or revoke per-user).
CLI: src/cli/src/commands/passwd.ts (self vs admin paths) + completions.
Tests: users-password route tests (8), auth-bootstrap grant assertion,
passwd live smoke test. Full suite 2214 passing; zero new lint errors.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brings together the two unmerged feature lines onto one integration branch:
- skills/review/proposals/revisions (via fix/mcpd-instance-health-and-retry,
which contains the full skills-1..7 chain + mcpd env/retry/readiness fix)
- v7 visibility scope + ownership for Llms and Agents
Auto-merge resolved schema.prisma, mcpd main.ts, mcplocal config, CLI create,
and completions with no conflicts. Both Prisma migrations coexist.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Closes the third deferred item from PR-5: skills can declare upstream
MCP server dependencies via `metadata.mcpServers` and `mcpctl skills
sync` now attaches them to the active project. Same trust model as
postInstall/hooks: the publisher is responsible, the client just
asks mcpd to attach.
## Behaviour
- For each `{ name, fromTemplate?, project? }` entry:
- If the project already has the server attached → record as
`alreadyAttached`, no-op.
- If the server doesn't exist on mcpd → warn + skip (we don't
auto-create from template; that's a separate explicit decision
for the operator). The warning surfaces the suggested template
so the operator can decide.
- Otherwise → POST `/api/v1/projects/:id/servers { server: <name> }`.
- 409 from POST → treat as alreadyAttached (server-side idempotency).
- 404 from POST → treat as missing (race: server vanished mid-sync).
- Other errors collected per-server; sync continues.
- A dep with `project:` set to a non-active project is skipped during
this sync — keeps the active sync from making collateral changes
to other projects.
- Global skill syncs (no project context) skip mcpServers entirely
with a warning — there's no project to attach to.
## Files
### Added
- src/cli/src/utils/mcpservers-materialiser.ts (~140 LOC)
- src/cli/tests/utils/mcpservers-materialiser.test.ts (~190 LOC,
10 tests covering: parse-tolerance, fresh attach, alreadyAttached
short-circuit, missing-server warn+skip, missing-project errors-
out, 409→alreadyAttached, 404→missing, cross-project skip,
per-server error collection, empty-deps no-op)
### Edited
- src/cli/src/commands/skills.ts: applyOne calls
attachSkillMcpServers after hooks. Tracks per-skill attachments in
result.mcpServersAttached. Summary line surfaces "N mcpServers
attached".
## Verification
165 test files / 2193 tests green (up from 2182).
Real-world flow:
```yaml
# skill metadata.yaml
mcpServers:
- name: my-grafana
fromTemplate: grafana
project: monitoring
- name: my-loki
fromTemplate: loki
```
```bash
# As operator: ensure the named servers exist on mcpd first
mcpctl create server my-grafana --from-template grafana --env-from-secret grafana-creds
mcpctl create server my-loki --from-template loki
# Now publish the skill that declares them as deps. Sync will attach:
mcpctl skills sync
# → mcpctl: 1 installed, 2 mcpServers attached
mcpctl describe project monitoring # both servers now attached
```
## What's intentionally NOT in this PR
- Auto-creating servers from `fromTemplate` when they don't exist.
Provisioning infra from a skill push is a separate decision needing
explicit operator policy. v1 warns + skips; the warning includes
the suggested template name so the operator can act manually.
- Detaching a server when a skill drops it from mcpServers. Detach is
destructive (project loses access) and we can't tell whether the
detach is intentional vs. accidental drop. PR-7 can revisit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the second-biggest deferred item from PR-5: skills can declare
PreToolUse / PostToolUse / SessionStart / Stop / SubagentStop /
Notification hooks in metadata.hooks, and `mcpctl skills sync` now
registers them in ~/.claude/settings.json with proper source-tagging.
## Why this needs source-tagging
mcpctl already managed ONE entry in settings.json (the SessionStart
hook for `mcpctl skills sync --quiet`, set up by PR-5 via
`installManagedSessionHook`). That entry uses `_mcpctl_managed: true`
to identify itself for idempotent updates.
Skill-declared hooks need finer scoping: skill A and skill B could
both register PreToolUse hooks, and removing skill A must not touch
skill B's. So entries written by `applyManagedHooks` carry both:
_mcpctl_managed: true ← same flag the SessionStart hook uses
_mcpctl_source: "<skill-name>" ← differentiates per-skill
Removing a skill (orphan cleanup) drops every entry tagged with
that skill's name. User-added entries (no marker) are preserved
verbatim. The earlier session-hook installer keeps working: its
`_mcpctl_managed: true` lacks the source tag, so the hooks-materialiser
ignores it on per-skill operations.
## Behaviour
- Skill installs/updates: applyManagedHooks(skillName, metadata.hooks)
is called after files are atomically materialised. The function
reads settings.json, drops this skill's previous entries from every
declared event (and from any event it previously had entries in but
no longer declares — so a skill can shrink scope), then re-inserts
the new tagged set.
- Skill orphan removal: removeManagedHooks(skillName) drops every
entry owned by the skill. Other skills + user hooks unaffected.
- Failure handling: hooks errors are logged via the warn() callback
but do not fail the sync. Same shape as postInstall — scoped, not
fatal.
## Files
### Added
- src/cli/src/utils/hooks-materialiser.ts (~140 LOC)
- src/cli/tests/utils/hooks-materialiser.test.ts (~165 LOC, 11 tests
covering: write-from-scratch, multi-source coexistence, user-hook
preservation, update replaces (not duplicates), shrink drops events,
remove targets only the named source, multiple events independent,
idempotent, empty/JSONC settings.json tolerance)
### Edited
- src/cli/src/commands/skills.ts: applyOne calls applyManagedHooks
when metadata.hooks is set; calls removeManagedHooks(skillName) when
a previously-installed skill no longer declares hooks; orphan
removal also drops the skill's hooks. New SyncResult field
`hooksApplied`. Earlier `meta` declaration deduped (it was redeclared
in the postInstall block).
## Verification
164 test files / 2182 tests green (up from 2171).
End-to-end on a real machine after this PR ships:
```yaml
# skill metadata.yaml
hooks:
PreToolUse:
- type: command
command: "audit-pretool.sh"
SessionStart:
- type: command
command: "claude-greeting.sh"
```
```
mcpctl skills sync
# → mcpctl: 1 installed, 1 hooks applied
jq '.hooks' ~/.claude/settings.json
# → entries tagged with _mcpctl_managed + _mcpctl_source
```
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the biggest deferred item from PR-5. metadata.postInstall
scripts now actually run when their hash changes, with audit emission
back to mcpd.
Trust model unchanged from the corporate-appliance design: mcpd is
the source of truth, content is reviewed at publish time, the client
just runs. No sandbox, no signing, no consent prompts. The controls
that matter are already on the publishing side (RBAC, audit, reviewer
queue).
What we DO provide is ops hygiene:
- Hard timeout (default 60 s; per-skill override via
metadata.postInstallTimeoutSec). SIGTERM at the deadline, SIGKILL
after a 2 s grace.
- Hash pinning. The script's sha256 is recorded in
~/.mcpctl/skills-state.json. Re-syncs of an unchanged script are a
cheap no-op. A re-published "same version, fixed script" still
triggers re-execution because its hash changed.
- Curated env. PATH/HOME/USER/SHELL inherited; everything else dropped.
MCPCTL_SKILL_NAME / _VERSION / _DIR / _PROJECT injected so scripts
have stable context.
- Per-skill install log under ~/.mcpctl/skills/<name>/install.log.
Bounded at 5 × 256 KB; old entries truncated from the front.
- Audit event back to mcpd (POST /api/v1/audit-events,
eventKind=skill_postinstall) on every run, including hostname so
admins can see fleet rollout state. Best-effort — failures are
warned but never block the sync.
- Path-escape rejection. metadata.postInstall must resolve inside the
skill bundle; relative paths that try to climb out are refused.
- Auto-chmod 0755 on the script before spawn. Some upstreams ship 0644
+ a shebang and expect a shell to handle it; we always spawn the
path directly so we need +x.
Failure semantics: on timeout or non-zero exit, the recorded
postInstallHash is NOT updated. Next sync retries. Other skills in
the same sync run continue regardless — postInstall errors are
scoped, not fatal.
## Files
### Added
- src/cli/src/utils/postinstall.ts (~200 LOC)
- src/cli/tests/utils/postinstall.test.ts (~190 LOC, 10 tests covering
success, env vars, chmod, non-zero exit, timeout via exec sleep,
path-escape, missing script, log file shape + append-across-runs)
### Edited
- src/cli/src/commands/skills.ts: applyOne now invokes runPostInstall
+ emitPostInstallAudit when metadata.postInstall is set and the
script hash differs from prior state. New SyncResult fields:
postInstallsRan, postInstallsSkipped. Summary line surfaces
"N postInstall ran". --skip-postinstall flag now actually does what
it says.
## Verification
163 test files / 2171 tests green (up from 2161).
End-to-end on a real machine (after this PR ships and a skill with
metadata.postInstall is published):
```
mcpctl skills sync
# → mcpctl: 1 installed, 1 postInstall ran
cat ~/.mcpctl/skills/<name>/install.log # see stdout/stderr
mcpctl skills sync # idempotent — skipped
```
If the same skill is republished with a fixed script:
```
mcpctl skills sync
# → mcpctl: 1 updated, 1 postInstall ran (hash changed → rerun)
```
If the script fails (exit 7):
```
mcpctl skills sync
# → mcpctl: 1 updated, 1 errors
mcpctl skills sync # state.postInstallHash NOT updated → retries
```
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three connected issues with how instances came up + got reported as
healthy when their secret backend was unreachable. The motivating
case: gitea-mcp-server starts when mcpd can't read the
gitea-creds secret from OpenBao, runs with an empty
GITEA_ACCESS_TOKEN, replies fine to tools/list (so liveness passes),
but every authed call fails with "token is required" — and
`mcpctl get instances` cheerfully reports the instance as healthy.
## What changed
### 1. Env resolution failures are now fatal for the start attempt
`src/mcpd/src/services/instance.service.ts`
The previous behaviour swallowed `resolveServerEnv` failures and let
the container start anyway with whatever env survived ("non-fatal —
container may still work if env vars are optional"). That's the bug:
the gitea container started with no token, ran for weeks, and was
reported healthy.
The catch now calls `markInstanceError(instance, "secret resolution
failed: <reason>")` and returns. Optional/missing env vars should be
modelled as `value: ""` entries on the server, not as silent
secret-resolution failures.
### 2. ERROR instances retry with backoff, not blind churn
Adds Kubernetes-style escalation: 30 s × 5 attempts, then 5 min
pauses thereafter. Retry state lives on `McpInstance.metadata` (no
schema migration) — `attemptCount`, `lastAttemptAt`, `nextRetryAt`,
`error`.
The reconciler no longer tears down ERROR instances and creates
fresh replacements (which would reset attemptCount and effectively
loop at 30 s forever). Instead:
- ERROR rows whose `nextRetryAt` is in the future are LEFT ALONE
and counted against the replica budget — preventing tight create-
fail-create churn while a previous attempt is in its backoff window.
- ERROR rows whose `nextRetryAt` has elapsed are retried IN-PLACE
via a new `retryInstance` method, which preserves attemptCount on
the same row so the schedule actually escalates.
The work has been factored into `startOne` (creates + initial attempt)
+ `attemptStart` (env + container) + `retryInstance` (re-attempt the
same row) + `markInstanceError` (write retry metadata).
### 3. STDIO readiness probe goes through mcpProxyService
`src/mcpd/src/services/health-probe.service.ts`
The legacy `probeStdio` (a `docker exec node -e '... spawn(packageName)
...'` invocation) only worked for packageName-based servers. Image-
based STDIO servers like gitea-mcp-server fell through with "No
packageName or command for STDIO server" and were reported unhealthy
for the WRONG reason — they have no packageName because they are an
image, not because anything's wrong.
New `probeReadinessViaProxy`: sends `tools/call` through the live
running container via `mcpProxyService.execute`. Same code path as
production traffic, so probe failures match real failures. Picks up:
- JSON-RPC errors (e.g. "token is required" when env is empty).
- Tool-level errors expressed as `result.isError: true`.
- Connection failures wrapped as exceptions.
- Hard timeouts via the deadline race.
After this PR, configuring `gitea` with
`healthCheck: { tool: get_me, intervalSeconds: 60 }` makes
`mcpctl get instances` report it as `unhealthy` whenever the auth
token is missing or wrong — which is honest.
The dead `probeStdio` (~120 LOC) is removed; HTTP/SSE bespoke probe
paths are kept for now (they work and the diff stays minimal).
## Tests
`src/mcpd/tests/instance-service.test.ts`:
- Replaces "cleans up ERROR instances and creates replacements" with
"retries ERROR instances in-place when their backoff has elapsed".
- Adds "leaves ERROR instances alone while their nextRetryAt is in
the future" and "escalates the backoff: attemptCount + nextRetryAt
persist on retry failures".
`src/mcpd/tests/services/health-probe.test.ts`:
- Swaps STDIO probe mocks from `orchestrator.execInContainer` →
`mcpProxyService.execute`.
- Adds "marks unhealthy when proxy returns a JSON-RPC error
(e.g. broken-secret auth failure)" — explicitly the gitea case.
- Adds "marks unhealthy when proxy returns a tool-level error in
result.isError" — covers servers that report tool failures as
isError instead of as JSON-RPC errors.
- Renames "handles exec timeout" → "handles probe timeout" and
exercises the deadline race rather than an exec rejection.
Full suite: 162 test files / 2161 tests green (+4 new).
## Manual verification step (post-deploy)
```bash
mcpctl edit server gitea
# → add healthCheck:
# tool: get_me
# intervalSeconds: 60
# timeoutSeconds: 10
# failureThreshold: 3
```
If OpenBao is still down: gitea instance enters ERROR with
attemptCount + nextRetryAt visible in `mcpctl describe instance`.
Otherwise: gitea env resolves at next start, probe passes, instance
is honestly healthy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 7 of the Skills + Revisions + Proposals work — documentation
pass for the surface added in PR-1 through PR-6. Reference material
only; no code changes.
## What's added
- `docs/skills.md` — skill model, scoping rules, CLI surface, the
`mcpctl config claude --project` setup flow, metadata schema (with
the deferred-execution note for hooks/mcpServers/postInstall), the
on-disk state file shape, atomic install mechanics, failure
semantics, and what's deferred.
- `docs/revisions.md` — ResourceRevision model, semver auto-bump
rules, contentHash diff key (cross-resource sync), CLI for history
/ diff / restore, RBAC, audit emission, storage growth note.
- `docs/proposals.md` — ResourceProposal model, the reviewer flow
(CLI + web UI), atomic-approval mechanics, the propose_prompt /
propose_skill MCP tools, the propose-learnings global skill that
steers Claude toward engaging with them, and the deferred legacy
PromptRequest cutover.
## What's edited
- Top-level `CLAUDE.md` — resource cheatsheet adds `skill`, `proposal`,
`revision` with cross-references to the new docs. The legacy
`promptrequest` entry stays (still on the legacy code path) but
notes that new work should use `proposal`.
## What's NOT in this PR
- The PromptRequest → ResourceProposal cutover migration. Both run
side-by-side today; the focused cutover PR will rename + backfill +
drop. Keeping that out of PR-7 means review can stay on docs.
- Bundle-backup / `mcpctl apply -f` skill support (deferred from PR-3).
- `metadata.hooks` / `metadata.mcpServers` / `metadata.postInstall`
execution (deferred from PR-5).
- Existing-page UI migration to Tailwind (deferred from PR-6 — old
inline-styled pages coexist fine inside the new Layout).
These are tracked as future PRs; each is its own focused change.
## Verification
`pnpm test:run` whole monorepo: 162 test files / 2157 tests green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
