304 Commits

Author	SHA1	Message	Date
Michal	0eca4148e3	fix(mcplocal): recreate a stale session instead of 404ing outside the envelope ... Second of the two faults that both presented as a 1800s hang. mcplocal keeps MCP sessions in memory only, so any restart -- a deploy, an RPM install, scripts/release.sh -- invalidates every connected client's session id. The response was a bare 404 {"error":"Session not found"}: 3.5ms server-side, but it lands OUTSIDE the JSON-RPC envelope with no id, so the client cannot correlate it to its request and simply waits out its own timeout. Every mcpctl tool call in that session became a 30-minute stall while the server was perfectly healthy and answering other traffic in milliseconds. Now the session is recreated, keeping the id the client already holds -- a re-handshake would change it and invalidate everything the client has cached. The SDK assigns sessionId/_initialized only while handling an `initialize` (webStandardStreamableHttp.js:419-420), so adoptSession() replays exactly those two assignments. It reaches into SDK internals, so it fails LOUDLY: the guard throws with a pointer to itself, and session-adopt.test.ts is the canary that goes red at `pnpm test` rather than in production on the next SDK bump. Recreation is not silent. Doing it quietly would hand an agent an ungated tool list with no signal that its gate state had vanished, so the first tools/call result carries the established "⚠ Session state unavailable (...)" notice telling it to call begin_session again. onsessioninitialized does NOT fire on the adopt path, so its body is factored into registerSession() and called explicitly. That is the subtle part: skipping it would have produced recreated sessions with null userName on every audit event, silently. Also fixed, and it is the CAUSE rather than the symptom: MCP clients close a session with DELETE + Content-Type: application/json and an empty body, which Fastify's default parser rejected with FST_ERR_CTP_EMPTY_JSON_BODY before the route handler ran. sessions.delete() therefore never happened and every "closed" session leaked -- manufacturing the stale-session condition this commit handles. Fixing recreation without fixing teardown would have shipped the workaround and kept the cause. project-mcp-endpoint.test.ts's "returns 404 for unknown session ID" inverts to "recreates an unknown session instead of 404ing it", and asserts the id comes back unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GqMidYEGUJG5fxeoTELBu2	2026-08-25 23:36:27 +01:00
Michal	c06c34f0a2	feat(mcplocal): a trace code that actually reaches the audit trail ... The plumbing for request tracing was all present and almost entirely inert. correlationId was generated at the endpoint and threaded into traffic events, but: - emitTrace() dropped it, so every durable tool_call_trace row had correlationId = null and could not be joined to anything; - ExecuteOptions.correlationId existed but its only production caller never passed it, making every stage_execution and pipeline_execution row unjoinable too -- dead code that looked like a feature; - plugin events (all three gate emits) had no access to it at all; - and the value itself was `<session-uuid>:<jsonrpc-id>`, which nobody can retype from a screenshot. Also fixed: onToolCallBefore intercepts returned without emitTrace, so every tool call made while a session was gated produced no trace whatsoever. The trace code now IS the correlationId. Nothing parses the old format -- checked across mcpd's audit repository and route, mcplocal's router and traffic capture, and the CLI console -- sessionId is its own audit column and the JSON-RPC id is in the traffic body, so nothing is lost. AuditEvent.correlationId is already an indexed Postgres column, so lookup works with no migration. 8 chars of Crockford base32 without I/L/O/U: readable aloud, typeable from a screenshot, 40 bits (a collision shows two traces, it corrupts nothing). Getting it to the plugins and the executor needed AsyncLocalStorage, not a parameter. Both are constructed per SESSION, not per request -- processContent is a closure with no RouteContext -- so threading an argument would have touched PluginSessionContext, every plugin, ExecuteOptions and StageContext. ALS also stays correct with two requests in flight on one session, which a mutable field on the session-scoped context would not; there is a test for exactly that. PluginContextImpl.emitAuditEvent auto-fills it the way it already auto-fills sessionId, so this covers every gate event and every plugin written later without a per-callsite edit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GqMidYEGUJG5fxeoTELBu2	2026-08-25 23:32:10 +01:00
Michal	c2a419b4f7	fix(mcplocal): one LLM budget per stage, so a loop cannot multiply it ... A per-call timeout bounds one call. It does not bound a stage that calls the LLM in a loop -- and summarize-tree does worse than loop: buildTree recurses to maxDepth (3 by default) and iterates per section at every level, then groupSections iterates again. Hundreds of sequential calls are reachable, so a 10s per-call cap is a multiplier, not a bound. StageBudget is one wall-clock budget shared across everything a single stage invocation does. Once it is gone the stage takes its deterministic path -- first-line excerpts, numbered pages -- and says so. The executor builds one per stage from config.budgetMs ?? MCPCTL_STAGE_LLM_BUDGET_MS (30s) and disposes it in a finally, so a long-lived mcplocal never accumulates timers. Two details that matter more than they look: - A warm cache is never budget-gated. cachedSummarize and generatePageTitles used ctx.cache.getOrCompute, which makes the budget check impossible to place correctly; split into get/set so a cached summary -- which costs nothing -- is still returned when the budget is spent. - "No LLM configured" is NOT a degradation. It is a deliberate choice, and numbered pages are the expected output there, so it gets no warning. Only failures, timeouts and exhausted budgets do. Crying wolf on a working configuration would train people to ignore the notice. summarize-tree's single-block path previously had no try/catch at all, so a failure escaped the stage entirely and executor.ts discarded the whole stage's work. It now degrades like the others. Degradation is reported three ways, all from util/degrade.ts: the reason in the content behind the established "⚠ <feature> unavailable (<reason>)" prefix, the count of affected sections (the recursion can hit one exhausted budget dozens of times, so the user needs the reason once plus what it cost), and degraded/degradedReason on the stage_execution audit event -- previously a degradation was invisible in the trace. docs/reliability.md now names ONE helper rather than a list of compliant call sites. That list is exactly how this drifted: the doc named the gate and llm/pagination.ts, and the newer stages never joined it. Tests: the 20-section recursion completes in ~300ms against a 300ms budget; a warm cache still serves real titles with the budget exhausted. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GqMidYEGUJG5fxeoTELBu2	2026-08-25 23:29:45 +01:00
Michal	2c90f5971d	fix(mcplocal): no LLM call can hang a tool call forever ... docs/reliability.md has stated the rule since it was written: "LLM-optional operations must be time-bounded, fall back deterministically, and report the degradation". The gate and llm/pagination.ts obey it. The newer proxymodel stages never adopted it -- stages/paginate.ts:72 awaited ctx.llm.complete() with no timeout and no signal, and its try/catch caught errors, not hangs. So when a provider hung rather than erroring, the promise never settled, the tool call never returned, mcplocal never wrote to the already-hijacked socket, and the client waited out its own 1800s timeout. In the journal that is three POST /projects/docmost/mcp requests accepted and never answered -- the only three such requests in 9,600 across every project, each followed immediately by [llm-adapter] "trying next" and [paginate] "Smart page titles failed". It read as a Docmost transport fault for two sessions. It was neither: Docmost answers /search in 203ms, and through mcplocal on a fresh session in 461ms. docmost_search returns ~14KB and crosses the pagination threshold; update_page returns a small ack and does not. One tool paginated, one did not, and only the paginating one could hang. Bound it centrally in the adapter rather than at each call site, so a stage that passes no options is still bounded and a stage written next year inherits the guarantee: - LLMCompleteOptions gains optional budgetMs/perCallTimeoutMs/signal. Optional matters -- seven inline stubs implement LLMProvider structurally and a required member would break every one. - LLMProviderAdapter.complete() runs one budget with a deadline across the whole failover chain, each attempt capped at min(perCall, remaining). A per-provider timeout would have made the worst case N x timeout; wrapping the method would have killed failover mid-chain. - Every attempt now gets a real AbortSignal. anthropic and openai (which back vllm) honour it; deepseek/ollama/gemini ignore it, and withTimeout's race unblocks the caller anyway -- exactly what its doc comment anticipated. - A caller abort stops failover: if nobody is waiting, don't burn the chain. util/degrade.ts generalises the gate's bounded -> fallback -> loud log -> degradedReason pattern into bounded(), which cannot throw, so the deterministic fallback is unconditional rather than something a catch block must remember. gate.ts is refactored onto it; plugin-gate and router-gate pass UNMODIFIED (61 tests), which is the proof the generalisation is faithful. anySignal() rather than AbortSignal.any: that landed in Node 20.3 and package.json declares >=20.0.0. proxymodel-llm-adapter.test.ts now asserts signal: expect.any(AbortSignal) -- every provider attempt being cancellable is the guarantee, so it is pinned. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GqMidYEGUJG5fxeoTELBu2	2026-08-25 23:23:16 +01:00
Michal	b4ad95ca66	test(mcplocal): smoke asserts the wire-form tool-name contract ... The smoke suite talks to the live mcplocal through the HTTP boundary, which serves wire names since #124 — assertions expecting `favourite/`, `all/` and `smoke-aws-docs/` prefixes now check the underscore wire form (config pins stay canonical). These two files were the release-gate failures after the bbd3188 rollout; 166/166 green against the live fleet after the update. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-25 22:06:18 +01:00
Michal	c014fcdd82	fix(mcplocal): name tools in wire form in gate and favourite-index prose ... Follow-up to #124: the boundary WireNameCodec serves underscore-joined names, but the gate plugin's tool inventories (initialize instructions and begin_session response) still listed canonical `server/tool`, and the favourite-index instruction told the model to prefer `favourite/<tool>` — prose naming functions the model cannot call. Inventories now run through sanitizeWireName and the instruction describes the favourite_/all_ prefixes. Cosmetic for routing (slash names still pass through the codec) but load-bearing for tool selection: models copy names out of prose. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-25 21:58:52 +01:00
michal	7fbb827aa5	Merge pull request 'fix(mcplocal): serve OpenAI-safe tool names on the wire' (#124) from fix/wire-safe-tool-names into main	2026-08-25 19:23:19 +00:00
Michal	eb0e97e76e	test(mcplocal): end-to-end wire-name coverage on the project endpoint ... Drives /projects/:name/mcp over the real Streamable HTTP transport with a fake websearch upstream: tools/list must serve `websearch_fetch_content` (every name matching the OpenAI function-name charset), calling that wire name must reach the upstream as bare `fetch_content`, and a legacy client echoing the canonical `websearch/fetch_content` must still route. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-25 20:23:09 +01:00
Michal	065ce02a60	fix(mcplocal): serve OpenAI-safe tool names on the wire ... The proxy namespaces tools as `server/tool` (and favourite-index presents `favourite/<tool>` / `all/<server>/<tool>`). A `/` is not a valid character in an OpenAI-style function name, so hosts that forward MCP tool names verbatim as LLM function names depend on the model faithfully echoing an illegal name. LibreChat did exactly that: deepseek-v4-flash intermittently dropped the `websearch/` prefix, LibreChat's registry lookup failed, and it reported "This tool's MCP server is temporarily unavailable" while nothing was down — the calls never reached mcplocal at all (confirmed against the AuditEvent table, 2026-08-25). Claude Code and the pi extension only dodge this because they sanitize names client-side. Fix at the HTTP boundary only: a WireNameCodec rewrites tools/list responses to wire-safe names (`/` -> `_`, exact-match reverse map, deterministic suffix on collision) and maps tools/call names back before routing. Wired into both /mcp and /projects/:name/mcp. Everything inside the proxy — routing maps, plugins, favourites config, audit events — keeps canonical names, and unknown inbound names (legacy clients echoing slash names, virtual tools) pass through unchanged, so existing clients keep working. Codecs are keyed per project and outlive the router cache TTL so a client can call a tool it listed minutes earlier; after a restart the client's initialize-time tools/list repopulates the map. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-25 20:17:33 +01:00
Michal	913c0fbdc6	fix(secrets): wrap an image server's own command, not just entrypoint ... Migrating docmost and my-home-assistant, both rendered their secret and neither picked it up. The pod spec showed why: command: (empty) args: ["node","build/index.js"] server.entrypoint: (unset) wrapCommand consulted only `server.entrypoint` for non-package servers, so with `entrypoint` unset it returned undefined, the wrapper was skipped entirely, and the container ran its normal command — which never sourced /vault/secrets/<name>. The failure is silent by construction: the agent init container succeeds, the file is there, and the server simply starts with empty credentials. An explicit `command` on an image server is already a complete command line — mcpd's exec mode would run exactly it — so it should be wrapped verbatim. `entrypoint` is only needed when there is no command at all and the image's own ENTRYPOINT would take over. Now branches on the three real shapes: package server (prepend the runner entrypoint mcpd owns), image + command (use verbatim), image only (require the declared entrypoint). Seven tests, one per shape plus the two undefined cases. Reintroducing the old logic fails two of them — checked before keeping. Both servers were rolled back to secretDelivery: env and are healthy; they can migrate once this ships. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-21 11:14:39 +01:00
Michal	0a83f71648	fix(secrets): injector-delivered servers must attach, not exec ... With injected delivery the credentials exist ONLY in PID 1's environment: the container command is a shell that sources /vault/secrets/<name> and execs the real server, so the values live in that process and nowhere else — not in the pod spec, which is the whole point. mcpd picks its STDIO mode from the server's shape: an explicit command or a packageName selects `exec`, a bare dockerImage selects `attach`. `exec` spawns a NEW process inside the container, which never sourced the file and therefore starts with empty credentials. The server comes up, answers tools/list, and fails every authenticated call — precisely the silent empty-token failure this feature exists to prevent. Seen as `Readiness check (list_datasources) failed: process exited 1` on a pod whose PID 1 demonstrably held the token (verified via /proc/1/environ: GRAFANA_URL set, token 46 chars, nothing in the pod spec). So secretDelivery: injector now forces attach regardless of server shape. Safe because wrapCommandForInjector execs rather than forks, so PID 1 IS the server. It also means no bouncer or HTTP shim is needed — mcpd's PersistentStdio already holds one long-lived connection; it was simply pointed at the wrong process. Note this inverts an assumption I had earlier: image-entrypoint servers were already on the attach path and would have worked; it is the package-based ones that were broken. gitea remains the sole exception, and for the unrelated reason that it is distroless and has no shell to source the file. Extracts the decision as a pure `chooseStdioMode()` so it can be tested — it is subtle and fails silently. Six cases pinned, including that env delivery still execs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-21 02:05:51 +01:00
Michal	ec35e1cc36	fix(secrets): the injector wrapper must replace the entrypoint, not extend it ... Caught migrating a real server: the pod crashlooped with `.: cannot open /vault/secrets/grafana-creds`, and the reason was in the generated spec: args: ["/bin/sh","-c",". /vault/secrets/grafana-creds; exec \"$0\" \"$@\"", "@leval/mcp-grafana"] mcpd deliberately maps ContainerSpec.command -> k8s `args` so a package server keeps its runner image's ENTRYPOINT (`npx -y`, `uvx`). Putting the sourcing wrapper there meant the pod actually ran `npx -y /bin/sh -c '...'` — npx trying to resolve a package called /bin/sh. The agent had rendered the file correctly; nothing ever sourced it. Adds `ContainerSpec.entrypoint`, which maps to k8s `command` and so REPLACES the image entrypoint, and has wrapCommand fold that entrypoint into the argv it returns (`npx -y` / `uvx` for package servers, the server's own `entrypoint` field for dockerImage servers — already required at validation for exactly this reason). Two tests pin it: a wrapped server emits `command` and no `args`; an unwrapped one still emits `args` and no `command`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-21 01:28:21 +01:00
Michal	ef9ba6fb8d	fix(servers): persist secretDelivery and entrypoint ... `mcpctl patch server my-grafana secretDelivery=injector` printed "patched server 'my-grafana'" and changed nothing. The repository maps update/create fields explicitly, one by one, so a new column silently does nothing until it is added there — and the silence is total: the API returns 200, the CLI reports success, and `get -o yaml` still shows the old value. Caught by trying to migrate a real server, not by any test. Adds the two fields to both create and update, plus tests that assert the mapping directly. Those tests fail against the unfixed repository (3 of 4) — verified before keeping them. This class of bug will recur: the mapping is manual and nothing links a schema column to it. The tests at least make the next omission loud for these two fields. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 23:40:59 +01:00
Michal	370fd0a034	feat(secrets): opt-in injected secret delivery, scoped per server ... Completes the path that stops mcpd writing secret VALUES into MCP server pod specs. With `secretDelivery: injector`, the pod fetches its own secrets from OpenBao through the agent injector, under a ServiceAccount and role scoped to just that server's secrets — so the value never enters etcd, and gitea-mcp cannot read the Grafana token. Opt-in per server, defaulting to `env`. Every existing server is bit-for-bit unchanged, and migrating is one reversible decision at a time rather than a flag day. The two invariants under most risk, both tested: - **Opted-out servers produce an identical manifest.** No annotations, no serviceAccountName, automountServiceAccountToken still false. - **Opted-in servers still fail LOUDLY on a bad ref.** Once mcpd stops reading a server's secrets, the check e6cd735 added no longer fires for it, and a typo'd secretRef would degrade into a vault-agent-init crashloop that mcpd reports as a generic pod failure — the same class of bug that had gitea-mcp running for weeks on an empty token while reporting healthy. `validateServerEnvRefs` resolves every ref and throws the value away, purely to keep that error. After the value cache it is a cache hit and costs nothing. Shell quoting is the other silent-failure trap and is treated as part of the contract: the agent renders `export NAME='value'` and the container command sources it, so a value containing a space, `$`, a quote or a newline would truncate and yield an empty token. `shellSingleQuote` is tested by executing a real /bin/sh over nine adversarial values including `'; export PWNED=1; '` — and those tests fail against naive quoting, confirmed before keeping them. `sh -c <script> arg0 arg1 …` preserves argv via $0/$@, and `exec` keeps PID 1 as the real process, which matters because mcpd attaches to PID 1's stdin/stdout for STDIO servers. Docker/Podman declare `capabilities.secretRefs: false` and fall back to inline resolution, so local development is untouched. Deleting a server revokes its identity, after its pods are gone and best-effort — a role no pod can authenticate as grants nothing, and failing the delete over it would strand the row. Per the CLI rules, `secretDelivery`/`entrypoint` are `create` flags, round-trip through apply -f, and show in `describe server` — which now also flags servers still inlining secrets into their pod spec. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 23:33:20 +01:00
Michal	f8427959e5	test(secrets): cover per-server identity containment ... ServerIdentityService shipped without tests. Containment is the whole point of the design, so it needs assertions rather than trust: a shared role would let third-party MCP images (gitea-mcp, ha-mcp) read every secret under secret/mcpctl/*, which is worse than the pod-spec exposure it replaces. Eight cases, all about what a server must NOT get: the grant covers only the secrets that server declares; a secret referenced twice is one grant, not two; inline env values never widen it; another server's secrets never appear. Plus the ordering invariant (ServiceAccount before the role that binds it — the reverse lets a pod start, fail to log in and crashloop while the role is still being written), and that a backend which cannot scope identities REFUSES rather than silently succeeding, which would leave a pod believing it held access it never got. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 23:13:49 +01:00
Michal	7b5136491f	fix(secrets): list via GET ?list=true — the LIST verb dies at the proxy ... Found by the readiness probe added in the previous commit, on its first run against production: `mcpctl status` reported Secrets: bao-k8s* ✗ auth failed: OpenBao list: HTTP 400 Bad Request That is a real bug, not a probe artifact. `bao-k8s` is configured with the public ingress URL, and Cilium's ingress Envoy rejects the non-standard LIST HTTP method outright. Verified live from the mcpd pod: LIST https://bao.ad.itaz.eu/v1/secret/metadata/mcpctl/ -> 400 Bad Request GET https://bao.ad.itaz.eu/v1/secret/metadata/mcpctl/?list=true -> 403 permission denied (bogus token, i.e. reached bao) LIST http://openbao.openbao.svc:8200/... (ClusterIP, no Envoy) -> 403 permission denied So the verb was fine against bao and fatal through the ingress. OpenBao accepts both forms and documents the GET form for exactly this reason. This was never noticed because nothing called list() in production — it backs `mcpctl migrate secrets`, which would have failed with an opaque HTTP 400 against any ingress-fronted backend. Also adds the per-server scoping primitives Phase 2 needs, with tests: buildServerSecretPolicyHcl (no wildcards, read-only, stable under reordering), buildServerProvisioningPolicyHcl (prefix-confined so mcpd cannot grant itself more than it holds), ensureKubernetesAuthRole / delete helpers, the driver-level ensureServerIdentity/removeServerIdentity capability, and ServerIdentityService. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 22:54:42 +01:00
michal	eb3e558a44	Merge pull request 'feat(secrets): survive OpenBao outages and report real backend health' (#115) from feat/openbao-resilience into main	2026-08-20 21:37:57 +00:00
Michal	545e7745da	test(secrets): cover the rotator loop's boot-time dead-token detection ... SecretBackendRotatorLoop had zero tests, despite being the detector added in e51b924 specifically so a re-initialised OpenBao surfaces the moment mcpd boots rather than 24h later when the scheduled rotation finally fires. The class already injects setTimeout/clearTimeout and a logger, so this needed no production change. Nine cases, weighted to what actually breaks: the boot health check runs per rotatable backend; a dead token emits kind BACKEND_TOKEN_DEAD through the injected logger (the point of the earlier console.error removal — a bare console call never reaches ErrorLogBuffer, so `mcpctl errors` could not see it); a throwing health check does not abort start(); overdue backends rotate immediately and still get scheduled; the 60s floor holds across 50 adversarial-jitter draws; and stop() both clears timers and trips the `stopped` guard against rescheduling, which had never been exercised. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 22:17:24 +01:00
Michal	fe9987cefd	test(secrets): smoke-cover backend health honesty + cache correctness ... Two of these four assertions currently FAIL against the live cluster, which is the point: mcpd there still renders `Secrets: bao-k8s* ✓` from the rotation field, and its JSON status carries no live/ready pair. Per the project rule the fix is to deploy, not to relax the assertion. The status check specifically rejects a bare "name ✓" with no qualifier — that string is the old rendering and proves the probe was never consulted. Deliberately does not take the real OpenBao down. Simulating an outage against shared infrastructure to satisfy a test would be worse than the bug it covers; the outage paths are unit-tested with an injected clock. Docs: adds a Reliability section (request hardening, the stale-while-error table, the cold-cache gap and why persisting values is not the answer, live-vs-ready) and replaces the stale "Kubernetes ServiceAccount auth is not shipped yet" note — it shipped in 5152066, and it is what the live backend has used since June. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 22:16:04 +01:00
Michal	0fbfc72d68	feat(secrets): report real backend health instead of a hard-coded tick ... `mcpctl status` derived its Secrets verdict entirely from `tokenMeta.lastRotationError`. The rotator writes that field only for `auth: 'token'` backends (SecretBackendRotator.isRotatable), so a `kubernetes`-auth backend never wrote it and the line rendered a green tick unconditionally — including with OpenBao sealed, unreachable, or answering 403 to every read. The one signal we had was structurally incapable of going red for the backend we actually run. New `GET /api/v1/secretbackends/:id/health` reports two signals, kept separate on purpose: live — reachable at all? (unauthenticated sys/health) ready — can we read through it? (uses our credentials) live-but-not-ready is the exact shape of a re-initialised OpenBao handing back valid-looking tokens that grant nothing; collapsing both into one boolean is what hid that for four days. Needs no RBAC mapping — it falls through to the generic `secretbackends` resource, so a GET is `view:secretbackends`. `mcpctl status` now renders four states — reachable / degraded (serving N cached secrets) / unreachable / auth failed — with rotation error demoted to a trailing clause rather than the verdict. A failed probe renders "? unknown", never green: not knowing is not health. JSON output carries the same probe, so scripts stop being told every k8s-auth backend is fine. Also adds a boot-time cache warm. The stale-while-error cache can only absorb an outage for secrets it has already seen, so a cold mcpd during a backend outage still fails; resolving each running server's refs once at startup closes that for the common case. Best-effort and deliberately partial — if the backend is also down at boot this is a no-op and instances fail loudly, which is correct. Persisting last-known-good to Postgres or disk would just be plaintext-at-rest again. Tests: 15 new. The five status assertions were confirmed to fail against the old rotation-only logic before being kept. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 22:14:12 +01:00
Michal	bd3e1134c9	feat(secrets): survive OpenBao outages instead of cascading them ... mcpd re-read the secret backend on every use — server env resolution, LLM api keys, chat, git providers, code repos, webhooks — with no value cache, no request timeout, and a retry that only fired on HTTP 403. A few seconds of OpenBao unavailability therefore turned into minutes of degraded service: instances that restarted during the blip failed env resolution, got marked ERROR, and entered the 30s x5 then 5min backoff. Three changes, in dependency order: 1. Typed errors. `SecretNotFoundError` (definitive) vs `SecretBackendUnavailableError` (transport). The distinction has to be typed rather than string-matched — a mis-classified "not found" would resurrect deleted secrets, and a mis-classified auth failure would paper over revoked grants, which is how an upstream re-init once broke every secret write for four days (e51b924). 2. Driver resilience. Every request now carries an AbortSignal timeout (there was none, so an unreachable backend hung its caller) and retries 5xx/429/network with full-jitter backoff — 503 is what a sealed OpenBao returns and used to be an immediate hard failure. The 403 purge-and-retry stays single-shot and outside the retry budget: it is a credential refresh, not a backend-unavailable condition, and looping on it would hide a genuinely revoked grant. `healthCheck()` no longer routes through the authenticated path, so an expired role stops reporting as "OpenBao is down"; it maps OpenBao's status codes (sealed/standby/uninitialised) instead. New `authCheck()` covers the readiness half via list(), which exercises the capability we actually depend on — unlike lookup-self, which only proves the token exists. 3. CachingSecretBackendDriver. Fresh reads inside the TTL never touch the network; past it we always try the backend, and on a transport failure serve the last known-good value instead of throwing. That is what stops the ERROR storm. Deleted secrets evict and rethrow — serving those stale would resurrect a revoked credential, strictly worse than an outage — and non-transport errors rethrow untouched. plaintext is not wrapped: its read() is an identity function over the row handed in. A cold cache during an outage still fails, loudly and by design (e6cd735). Also routes BACKEND_TOKEN_DEAD / BACKEND_ROTATION_FAILED through pino rather than bare console.error. They bypassed the multistream feeding ErrorLogBuffer, so the one failure `mcpctl errors` exists to surface was the one it never showed. Tests: 20 new. The two load-bearing guards (never serve a deleted secret stale; never serve stale for a non-transport error) were confirmed to fail against deliberately broken code before being kept. The 403 purge-retry path had no coverage at all until now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018vybEitX4FykeMatKe5Xki	2026-08-20 22:08:10 +01:00
Michal	5fb1154190	Merge remote-tracking branch 'origin/main' into fix/stdio-restart-recovery	2026-08-15 23:32:46 +01:00
Michal	b022f322f0	fix(mcpd): recover k8s STDIO instances after in-place container restarts ... A container restart (OOMKill, crash, transient npx failure) used to strand the instance in ERROR forever while its pod sat 1/1 Running, because five gaps lined up (#114): - the exec/attach websocket died without ending the stdout PassThrough (client-node installs no onclose), so PersistentStdioClient — whose only death signal was stdout 'end' — kept believing it was connected and every request rode the 120s timeout into a dead pipe; - the stdioClients cache is keyed by pod name, which survives a restart, so nothing ever evicted the corpse; - syncStatus never re-inspected ERROR rows and never read restartCount, so neither the recovery nor the in-place restart was visible; - its ERROR writes clobbered retry metadata, making the row instantly dueForRetry, and the retry recreated the pod under the SAME name — an uncaught 409 that looped ERROR against a healthy pod; - the stuck row consumed the whole replica budget, blocking a fresh-id replacement. The fix, layer by layer: - ws 'close'/'error' now end stdout in both k8s interactive paths (and the docker interactive path mirrors its own one-shot handlers), funneling into an identity-guarded teardown in PersistentStdioClient that also listens for stream 'close'/'error' — a late event from a previous session cannot clobber a reconnected one; - syncStatus re-inspects ERROR rows (pod running again → back to RUNNING with retry metadata cleared), tracks restartCount in instance metadata to catch restarts between polls, MERGES retry metadata instead of clobbering it, and evicts the cached stdio client through a setter-injected hook whenever the pipe is known-dead; - createContainer adopts an alive pod on 409 instead of throwing (and only replaces a genuinely dead one, waiting out the deletion grace period); - attach mode retries once through a fresh client before surfacing an error, so the first call after a detected death succeeds; - the health probe evicts the cached client when failures cross the threshold, and shutdown finally calls closeAll(). Closes #114 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-15 23:32:23 +01:00
Michal	c66502e590	fix(mcplocal): fetch project instructions with the caller's token (#113) ... The instructions fetch was the one downstream call in getOrCreateRouter still using mcpdClient — whose token is an empty string in HTTP mode — so mcpd answered 401, the catch swallowed it, and every session initialized with no instructions while nothing looked broken. requestClient exists precisely for this; use it. Closes #113 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-15 21:43:00 +01:00
Michal	740ce31469	fix(mcplocal): give proxied tools/call a 120s budget, not the 30s default ... McpdUpstream.send routed every non-list method through the default-timeout client, so any tool that legitimately runs past 30s — web_url_read through a browser solver, a large PDF extraction, a slow retail site — died as "mcpd proxy error: mcpd did not respond within 30000ms" while mcpd was still working on it. LibreChat agents hit this constantly on real pages. New TOOLCALL_TIMEOUT_MS (default 120s, env MCPLOCAL_TOOLCALL_TIMEOUT_MS) sits between DISCOVERY_TIMEOUT_MS (list calls must stay short so a dead upstream can't stall session init) and LONG_RUNNING_TIMEOUT_MS (chat and inference, minutes). withTimeout preserves the caller token and headers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JaFvfHrQyUKCGv6o3N2Wir	2026-08-15 21:43:00 +01:00
Michal	03350856ea	fix(mcplocal): make the paginated-result contract usable by any MCP client ... UniFi tools were unusable from non-Claude agents. A tool result over 2000 chars is replaced with a table of contents and re-read by calling the tool again with _resultId/_section, but those params were never declared on the tool's inputSchema — and unifi-network and my-grafana ship `additionalProperties: false`, so for a client that validates arguments the drill-down call was illegal and the data unreachable. The stub's own wording made it worse: "Use section parameter" names a param that does not exist; sending it fell through to the upstream, re-paginated, and minted a fresh _resultId. An unbounded loop. UniFi took the blame because it is the one server whose results always trip the threshold: get_devices was 11,718 chars, get_clients 136,696 across 19 pages with a 92-char page-1. Grafana and Gitea return compact results. - content-pipeline gains onToolsList, declaring _resultId/_section on every tool it can paginate (gate tools excluded — they are intercepted before the pipeline runs). additionalProperties stays false: a property listed in `properties` is already legal under it, so declaring is enough and the upstream keeps its typo protection. - createDefaultPlugin wired only the gate's onToolsList, so the pipeline's would have been dropped on the floor. Both now chain, gate first. - _resultId without _section re-shows the table of contents instead of forwarding an unknown argument to a strict upstream. - The stub names the tool, the live _resultId and a real section id. - Nested MCP envelopes are collapsed. A server fronting another MCP server returns the inner result wrapped in its own content/structuredContent pair, so the payload arrives two or three times over. A layer is peeled only when it carries nothing the inner value lacks, which keeps it lossless. Live against the sre project: get_devices 11,718 -> 5,210 chars and no longer paginates at all; get_clients 136,696 -> 62,358 across 8 pages instead of 19. - deploy/mcplocal.service shipped MCPLOCAL_MCPD_URL=http://10.0.0.194:3100, which is dead — every working machine had a hand-written drop-in. Points at the k8s ingress now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JNXFvxanvM6uiFcb4Mp3xU	2026-08-14 23:27:36 +01:00
Michal	8a31121e30	Merge remote-tracking branch 'origin/main' into feat/web-search-templates ... # Conflicts: # completions/mcpctl.bash # completions/mcpctl.fish # src/cli/src/commands/create.ts # src/db/src/seed/index.ts	2026-08-12 23:11:54 +01:00
Michal	ac5dee906e	fix(cli): don't brick the chat REPL when the first turn fails upstream ... Observed live: turn 1 died with an anthropic 429 before the stream's `final` frame, streamOnce resolved '' as the thread id, the REPL stored it, and every later message sent `threadId: ""` — rejected by mcpd's z.string().min(1) with HTTP 400. Permanently stuck: no turn could succeed again, so no `final` frame could ever repair the id. Two independent layers: - streamOnce now resolves `string | undefined` — undefined when no `final` frame arrived — and the REPL keeps its previous thread state on undefined instead of overwriting it. One-shot mode skips the `(thread: ...)` footer when there is none to report. - chatBody refuses to serialize an empty threadId at all, so even a leaked '' can never reach the wire. Regression cover in chat-thread-brick.test.ts (7 tests), including the full REPL chain: failed turn 1 → turn 2 body carries no threadId key. The assertions are the direct inverse of the old behavior, so they fail pre-fix by construction. CLI suite 726 passed, lint clean, tsc clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016dNpnBqyyz9GxfznVcX2sP	2026-08-10 22:54:53 +01:00
Michal	bbd2195c64	test(mcplocal): prove chat SSE streams live through the proxy, not buffered ... `mcpctl chat reviewer` showed nothing until the turn finished, then dumped the whole answer at once. mcpd streams token deltas and the CLI renders them incrementally — the sole buffering point was mcplocal's catch-all /api/v1/* proxy reading the whole SSE body via res.text() before replying. The previous commit (cherry-picked from feat/agentic-teams) pipes the body through instead; this one adds the cover that was missing: - proxy-long-running.test.ts: a progressive-delivery test in which the stand-in mcpd withholds its final frame until the client has observed the first delta through the proxy. A buffering proxy cannot satisfy that ordering — verified: the test fails in 3s (no hang) against a res.text() proxy and passes against the piped one. The existing SSE test used inject(), which collects the whole body and so passes either way. - agent-chat.smoke.test.ts: a live smoke that posts through mcplocal on localhost:3200 (the path `mcpctl chat` actually takes — every other chat smoke uses --direct and bypasses the proxy entirely) and asserts delta frames arrive spread across the generation window, not in one burst at stream end. Uses its own agent: the shared smoke agent pins replies to a single token, too short to tell live streaming from a buffer dump. Also settles the strict-boolean-expressions lint on the auth-header check the streaming split touched. Local: workspace 2546 passed, proxy suite 10/10, smoke file loads + self-skips. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016dNpnBqyyz9GxfznVcX2sP	2026-08-10 22:27:21 +01:00
Michal	5a8185d7c9	fix(mcplocal): stop the 30s proxy timeout killing agent turns ... `mcpctl chat <agent>` failed with HTTP 503 {"error":"service_unavailable","message":"Cannot reach mcpd daemon. Is it running?"} while mcpd was answering /healthz in 32ms. The message was wrong in a way that cost real debugging time: mcplocal was reaching mcpd fine and giving up after 30s. journalctl shows the signature plainly — statusCode 503 with responseTime 30003.87 on POST /api/v1/agents/reviewer/chat. This blocks the agentic-teams epic outright. An agent turn is a multi-turn tool-use loop that runs for minutes by design, so a 30s ceiling on the chat path is not a safety net, it is a guaranteed failure for every non-trivial turn. Three defects, all in the same path: 1. One blanket budget for every forwarded route. DEFAULT_TIMEOUT_MS = 30_000 is right for CRUD and wrong for chat. Chat, project chat, llm infer and inference-task streams now get LONG_RUNNING_TIMEOUT_MS (600_000, override with MCPLOCAL_LONG_TIMEOUT_MS) — matching STREAM_TIMEOUT_MS, which the CLI already allowed. mcplocal in the middle was the binding constraint. 2. Timeouts were reported as connection failures. Split UpstreamTimeoutError out of ConnectionError and map it to 504 with an accurate message that says the daemon IS reachable. ConnectionError still means unreachable and still returns 503. Verified nothing else branches on ConnectionError. 3. SSE was buffered. `forward()` reads the whole body through res.text(), so even turns that finished in time arrived as one blob and the CLI's live token output never appeared. Streaming routes now use forwardStream() and pipe the body straight through, preserving content-type and x-accel-buffering (dropping the latter lets intermediaries re-buffer and reintroduces the stall). Also closes the escape that produced the sibling `500 code:23` failure: the body read in forward() was outside the try, so when mcpd had already written SSE headers the raw DOMException reached Fastify unhandled. Tests: 9 new proxy tests. The two that matter — "does not abort an agent chat that outlives the CRUD budget" and "streams SSE through instead of buffering" — were confirmed to FAIL against the pre-fix behaviour and pass after. Three existing mcpd-client tests asserted the old taxonomy and were updated to assert the new one deliberately. Local: build clean, workspace 2375 passed, lint unchanged at 869. NOT YET LIVE: mcplocal runs from the installed RPM, so this needs a package rebuild + `systemctl --user restart mcplocal` to take effect. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N4wNHWf7xSwnZCWpJcyv9p	2026-08-10 22:19:56 +01:00
Michal	822c1bb047	build: fail the release when smoke tests fail, and fix the SSE test that hung ... release.sh printed `WARNING: Smoke tests failed!` and exited 0. That is how four broken readiness probes shipped unnoticed on 2026-08-10 — the warning scrolled past in the build log and the release reported success. It now exits 1, with `MCPCTL_ALLOW_SMOKE_FAILURE=1` as the escape hatch. The message is explicit that smoke runs LAST, against the installed binary: the package is already published and installed, so the failure reports fleet breakage rather than preventing a bad artifact. Turning the gate on required fixing a latent hang first, or every release would have blocked on it. `security.test.ts > /inspect SSE endpoint …` waited for a response body that by design never ends, so it could only settle via the socket's *inactivity* timeout — and /inspect relays every project's MCP traffic, so during a full smoke run it is never idle. Run alone it passed and looked flaky; run with the suite it failed every time. httpRequest gains `headersOnly`, which resolves on the response headers and hangs up. The assertion only ever needed the status line. Verified: full smoke suite 158/158 (was 157/158 with this test timing out); the gate block lifted verbatim from release.sh exits 1 with a stubbed failing smoke run, and exits 0 reaching subsequent code under MCPCTL_ALLOW_SMOKE_FAILURE=1. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wUmrfkVQR6CKcYKxENq7k	2026-08-10 17:15:40 +01:00
Michal	b8cedd6262	test(smoke): give the smoke-aws-docs fixture a readiness probe ... health-readiness.smoke.test.ts asserts no RUNNING server lacks a healthCheck.tool. The smoke suite's own shared fixture had none, so the suite reported its own scaffolding as a fleet regression — and because the fixture is in the PROTECTED set of clean-smoke-resources.ts, it is long-lived and failed that assertion on every run. Mirrors the production aws-docs probe (same package): search_documentation with a phrase, 300s interval since the call leaves the cluster. Verified live: with this applied, "every RUNNING server has a readiness probe configured" passes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wUmrfkVQR6CKcYKxENq7k	2026-08-10 16:59:41 +01:00
Michal	b07287baf2	fix(k8s): set fsGroup on pods with volumes ... A freshly provisioned PVC mounts root:root, so any image that drops privileges cannot write to it. docs-mcp-server runs as uid 1000 and died on first start with SQLITE_CANTOPEN; its own Dockerfile says to chown the volume 1000:1000. Pods with volumes now carry securityContext.fsGroup, defaulting to 1000 and overridable per volume. fsGroupChangePolicy is OnRootMismatch so Kubernetes does not walk and re-chown the whole volume on every start. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB	2026-08-10 12:31:31 +01:00
Michal	bb4b0b910f	fix(k8s): read ApiException.code when classifying client-node errors ... @kubernetes/client-node v1 raises ApiException, which carries the HTTP status on `.code`. Every check in the orchestrator read only `.statusCode` — the pre-1.0 HttpError field — so `status` came back undefined and each "expected" 404/409 was rethrown instead of handled. Found in production: the first start of a server with a volume read a not-yet-existing PVC, got a 404 that should have meant "create it", and failed the instance instead. The same latent bug sat in removeContainer, where a missing pod failed the delete rather than being treated as already gone. httpStatusOf() checks .code, .statusCode and .response.statusCode, and falls back to parsing the rendered "HTTP-Code: NNN" message for wrappers that keep none of them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB	2026-08-10 12:20:56 +01:00
Michal	2a7bba11ea	fix(claude): stop pre-migration .mcp.json residue outranking a project switch ... `mcpctl config claude --project X` writes user scope and never rewrites a checkout's `.mcp.json`. The status line, however, preferred that file unconditionally — so a legacy project-named entry an older mcpctl left behind (`homeautomation` -> `mcpctl mcp -p homeautomation`) kept naming the old project for good, and every switch looked like it had done nothing. Reproduced live: with user scope on `sre`, `mcpctl statusline --directory ~/developer/michalzxc/claude/debug` printed `mcpctl:homeautomation` — a project Claude Code also had in `disabledMcpServers` for that directory, so the line named a server that was not even mounted. Rank the sources by how deliberate each one is instead: a canonical `mcpctl` pin, then user scope, then legacy residue, then the marker. A pin is a decision and still wins; residue is not and no longer does. At every step, skip a server Claude Code has switched off for that directory. `config claude` now also warns when the working directory's `.mcp.json` contradicts the switch, naming the file — the two scopes are merged rather than chosen between, so nothing else would tell you. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wUmrfkVQR6CKcYKxENq7k	2026-08-10 12:15:46 +01:00
Michal	be7fabd467	fix(pi-ext): stop importing @earendil-works/pi-ai at runtime ... The extension failed to load outright on older pi installs: Failed to load extension ".../mcpctl-pi.ts": Cannot find module '@earendil-works/pi-ai' pi doesn't resolve an extension's bare specifiers the ordinary way — it hands jiti a hard-coded alias table built from its own dependencies, and that table differs between pi distributions. `@earendil-works/pi-coding- agent` (0.84.1) aliases both the `@earendil-works/*` and legacy `@mariozechner/*` names; `@mariozechner/pi-coding-agent` (0.73.1) aliases only the old ones. Neither resolves the other's namespace, so a single import outside the intersection takes the whole extension down: every tool, the /mcpctl command, and the status line, all gone. The only thing we used from pi-ai was `StringEnum`, a six-line wrapper over `Type.Unsafe`. Inlined as a local `stringEnum` with byte-identical output, so `typebox` — aliased by every published pi — is now the sole bare runtime import. The call site also passes `description` through, which the pi-ai version was silently dropping. Guarded in tests/config/pi-extension-embed.test.ts: any runtime import in the embedded sources that isn't `node:`, relative, or typebox now fails. Verified against both installs with the same active project: 0.73.1 reproduced the error verbatim before the change and loads cleanly after, and 0.84.1 keeps registering the gate tool exactly as before. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014tsRTqhEC7YYYYaP3cBqo8	2026-08-10 00:15:04 +01:00
Michal	a158e49ec2	fix(templates): make the shipped templates match reality ... The templates are what `create server --from-template` builds from and what mcpd seeds on start, so drift there ships broken servers. Nothing ever read these files in a test, and they had rotted badly. - grafana: GRAFANA_URL now defaults to the in-cluster ClusterIP and the description spells out why the public hostname is wrong — reaching a co-located Grafana over its ingress hairpins through the per-host Envoy L7 policy, which drops the caller's identity and returns a bare `Access denied` 403 with a perfectly valid token. That cost a day of looking at the token. - unifi-network: was wrong on every field that mattered. `runtime: python` for an npm package, an env contract (UNIFI_HOST/USERNAME/PASSWORD) the package doesn't read, and no probe. Now UNIFI_TARGETS with the classic-vs-unifi_os distinction and the :8443 egress caveat written down. - docmost, gitea: both carried "health check disabled" comments citing a limitation of the old docker-exec probe, which readiness-via-proxy removed. Both probes verified against the live servers. gitea uses search_repos, not get_me, because get_me needs a `read:user` scope a repo-scoped token lacks. - filesystem: packageName was `@anthropic/filesystem-mcp`, which 404s on npm — the template could never have installed. Points at the real package. - terraform: deleted. `@anthropic/terraform-mcp` 404s too and there is no npm-published replacement to point it at. - node-red: deleted, the service is gone. Two supporting fixes: - The seeder declared no `runtime` field and never wrote the column, so a template asking for the python runner silently seeded as null and got node. - A new templates test reads every shipped file: schema-valid, a runner the orchestrator knows, some way to actually start, unique env names, and a readiness probe (without one an instance can only ever report `live`). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0114dg56YmVacyqhp5fitcTb	2026-08-09 23:53:22 +01:00
Michal	b2547429ca	fix(health): a passing tools/list is live, not healthy ... `mcpctl get instances` showed all eight servers healthy while the UniFi one had never once reached its controller. The default probe is `tools/list`, which MCP servers answer from a static in-process table — no credentials, no upstream, ~3ms. It cannot fail for any reason the user cares about, so it was reporting `healthy` for every process that managed to start. Split the two passes: healthy — readiness: `tools/call` on `healthCheck.tool`. The upstream answered, so the server can actually do its job. live — liveness: `tools/list` only. Process up, upstream unverified. `live` is now the default for any server without a `healthCheck.tool`. It is not a warning; it is an admission that nothing is watching that server. Probe events name which probe ran and which tool ("Readiness check (list_sites) passed"), so the events log distinguishes the two after the fact. Also: - `healthCheck.tool` is optional now, so the timings can be tuned without inventing a readiness probe. - `create server --health-check-tool/-args/-interval/-timeout/ -failure-threshold`, per the rule that everything applyable is a create flag. Merges over a `--from-template` healthCheck rather than replacing it. - `describe instance` explains a `live` verdict instead of leaving it cryptic. - create.ts held a raw NUL byte in a string literal, which made grep treat the whole file as binary and silently skip it. Escaped as `\0`. Verified against the live fleet: with readiness probes configured, my-grafana went unhealthy (Grafana API 403) and my-node-red degraded (connect timeout to a Tailscale address) — both had read healthy for months. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0114dg56YmVacyqhp5fitcTb	2026-08-09 21:23:33 +01:00
Michal	cbd3b95d97	fix(opencode): guard state parsing, lint the .tsx, correct an overstated doc claim ... Three findings from a cross-branch review of the competing opencode implementations, all of which are fair. 1. `readState` type-guards the parsed JSON now. A bare try/catch does not cover it: `JSON.parse('null')` succeeds and returns null, so the catch never fires and the next `state.project` throws a TypeError that takes the plugin down. Verified the crash before fixing; a test pins the guard in the embedded copies. Credit to the competing 'opencode-mine' branch, which had this right. 2. eslint now covers `src/opencode-ext/*.tsx`. The glob was `*.ts` only, so the 300-line TUI plugin — the largest file in the addon — was linted by nothing. It was typechecked, which is why this went unnoticed. Confirmed the rules actually fire on it rather than the file being silently skipped. The 'abhishek' branch was the only entry that got this right. 3. docs/opencode-extension.md overstated the security argument. "The token would sit in a 0644 opencode.json" is not a point against a `type: local` stdio bridge, which needs no token at all because it reads your own credentials. That reason is a consequence of having picked the HTTP gateway, not a justification for it. The docs now lead with the real reason — live re-pointing without a restart — and state the trade honestly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-09 20:47:45 +01:00
Michal	b7c0de2bf0	feat(claude): register the MCP server in user scope by default ... `config claude` wrote a per-directory `.mcp.json`, so you had to re-run it in every checkout you opened — and in a repo that commits `.mcp.json` (this one does) it dirtied the working tree. Every other integration is already global: pi, prime-agent and opencode each have one active project, wired once. Claude Code's user scope is `mcpServers` in `.claude.json`, which applies in every directory and window. That is now the default. `--scope project`, or an explicit `-o/--output`, keeps the old per-directory file for a repo that wants its own pinned project. `--inspect` stays project-scope — it is a debugging server you turn on for one checkout. Details worth knowing: - The file path is asymmetric: `$CLAUDE_CONFIG_DIR/.claude.json` when that is set, but `$HOME/.claude.json` by default — beside `~/.claude/`, not inside it. Verified against a live Claude Code run with an isolated config dir. - `.claude.json` also holds onboarding state, caches and a per-project map that Claude Code rewrites while running, so this merges into the document and writes through a temp file + rename. - User scope writes no `.mcpctl-project` marker: it scopes nothing to a directory, and a marker beside `.claude.json` would sit in $HOME and scope every repo under it. - `statusline` now resolves directory-scoped `.mcp.json` first (a repo that pinned itself wins), then user scope, then the marker. Scope selection reads Commander's option source rather than process.argv — argv is the test runner's command line when the command is driven in-process, which the suite caught immediately. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-09 19:59:48 +01:00
Michal	a9fcd83ed8	refactor(prime-agent): extract the /mcpctl switcher to typechecked source; pi --dry-run; docs ... The prime-agent switcher existed only as a 275-line string literal inside prime-agent-extension.ts, so nothing typechecked or linted it — the exact gap that let a wrong ctx.ui.select() option shape ship in the pi extension. It now lives at src/prime-agent-ext/mcpctl-switch.ts with a generator, a tsconfig checking it against the real @earendil-works/pi-coding-agent types, eslint coverage and an embed-freshness test, matching pi and opencode. The extraction was verified byte-identical before any edit, so the behaviour shipped today is exactly what was captured. Linting it then found six problems in code nothing had ever checked: object-truthiness null guards, a nullable string conditional and a missing return type. All behaviour-preserving to fix, but exactly the class of thing that ships silently when nothing is looking. Also: - `config pi` gains --dry-run, the last agent without it. - The SessionStart hook installer now drops untagged duplicates of its own exact command — rows left behind before the marker existed, or by a suite that used to write into a real ~/.claude. Invisible in the UI; they just run the sync twice per session. A hook the user wrote is never touched, even one calling `mcpctl skills sync` with different flags. - docs/claude-integration.md and docs/prime-agent-extension.md, the two integrations that had no page. prime-agent deliberately keeps its per-project MCP entry name rather than the constant `mcpctl` claude and opencode now use: its switcher already unmounts the previous project, so it never accumulates entries, and re-keying auth.json from mcp:<project> to mcp:mcpctl would give up per-project token caching and needs a migration. Documented as its own change rather than folded in here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-09 19:20:36 +01:00
Michal	b3a062ce28	feat(claude): active-project status line + /mcpctl switcher, and stop tests writing to ~/.claude ... Claude Code had neither of the things opencode, pi and prime-agent all have: a visible active project, and a way to change it from inside a session. It has no plugin API that can draw a widget or open a picker, but it does run a command for its status line and it does load slash commands — which is enough for both. - `mcpctl statusline` prints the active project (from .mcp.json, falling back to a .mcpctl-project marker) and is wired into settings.json. It reads the directory out of the JSON Claude Code pipes in, so it follows /cwd rather than reporting wherever the binary was launched. Prints nothing when no project is active: an empty line beats "none" on every unrelated repo. - `/mcpctl [project]` switches and reminds you to reconnect from /mcp. allowed-tools is scoped to the four exact mcpctl invocations it needs. Three things found by running it rather than reasoning about it: - Claude Code REWRITES settings.json against its own schema and strips unknown keys from `statusLine` — our `_mcpctl_managed` marker came back gone, so ownership is now determined by the command string. (Hooks keep their marker; statusLine does not.) A composed line like `my-prompt && mcpctl statusline` is deliberately not claimed. - Every `!`-prefixed block in a slash command is permission-checked against allowed-tools. Omitting `statusline` failed the whole command before the model saw anything. A test now asserts every pre-executed command is covered. - Setting ANTHROPIC_AUTH_TOKEN *and* ANTHROPIC_API_KEY makes Claude Code warn that auth may not work; claude-vllm now sets only the former and clears an inherited API key. Also fixes a pre-existing test-isolation bug this work would have made worse: `config claude` wrote into the developer's real ~/.claude when the suite ran, which is how an untagged duplicate of the skills-sync SessionStart hook got there. Both the hook installer and the new UI installers now honour CLAUDE_CONFIG_DIR (Claude Code's own override — correct behaviour first, isolation second), `config claude` gains --claude-dir for parity with --pi-dir and --opencode-dir, and the suite is verified to leave ~/.claude byte-identical. Verified live: status line renders `mcpctl:homeautomation`, `/mcpctl docmost` switches and the line updates to `mcpctl:docmost` in the same session. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-09 19:06:06 +01:00
Michal	d7055a0953	fix(claude): one constant mcpctl MCP entry instead of one per project ... `config claude` named the `.mcp.json` entry after the project, and the file is merged rather than rewritten — so configuring a second project left the first one mounted alongside it. Every project you had ever configured stayed connected, with duplicate tool names and nothing saying which was active. The entry is now always `mcpctl`, and switching rewrites what sits behind that name. Claude Code can reconnect an existing MCP server from inside a session, so a switch lands without restarting the app, and the tool prefix stays stable across switches. Entries an older CLI wrote are retired on the next run — recognised by the pairing that makes retiring them safe: our command, named after the very project it bridges to. A hand-configured server is never touched. The shaping lives in config/claude-mcp.ts as pure functions so the merge, migration and active-project detection are unit-tested rather than inferred from a command's side effects. Also brings two parity gaps in line with `config opencode` / `config prime-agent`: --dry-run, and --skip-marker for when the caller must not re-scope the directory it runs in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-09 18:51:31 +01:00
Michal	b0233918ff	feat(servers): persistent volumes + self-hosted web search and docs templates ... Instances are immutable and get recreated on any server edit, so anything an MCP server wrote to its container filesystem was lost at exactly that point. That ruled out every stateful MCP server, docs-mcp among them: its index is a SQLite file (better-sqlite3 + sqlite-vec) and it has no external-database mode, so no amount of Postgres helps. A server or template can now declare volumes. The backing store is keyed on the server, not the instance — `mcpctl-<server>-<name>` — which is the whole point: an instance-scoped claim would be destroyed precisely when the data needs to survive. On Kubernetes that is a PVC ensured in the servers namespace before the pod is created and never deleted with it; on Docker, a named volume (named, not anonymous, so `removeContainer`'s `v: true` leaves it alone). Claims are ReadWriteOnce, so volumes and replicas > 1 are mutually exclusive; validation rejects that pair instead of leaving the extra replicas unschedulable. storageClassName is omitted rather than sent empty when no class is configured — to Kubernetes those mean different things. Also fixes a pre-existing bug in the same path: seedTemplates dropped `runtime`, so every PyPI-backed template seeded from YAML silently defaulted to node and would run `npx` against a package that only exists on PyPI. `unifi-network` declares `runtime: python` and had been seeding with runtime unset. Templates added, all self-hosted and none needing an API key: - duckduckgo — no backing service at all - searxng — needs a SearXNG engine (compose profile in stack/) - docs-mcp — open-source Context7/Ref alternative, uses the new volume Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB	2026-08-09 18:17:32 +01:00
Michal	99f881dd67	feat(opencode): leader keybind, explicit unmount on switch, non-wrapping indicator ... Three improvements taken from reading the sibling opencode branches (feat/opencode-extension-abhishek in particular): - `<leader>m` opens the project picker. Switching is the repeated action and typing `/mcpctl` every time is friction; the other two commands stay palette-only. - A switch disconnects before re-adding. `mcp.add` under the same name does re-point the tools on its own, but leaves it to opencode whether the previous client is closed — and an abandoned one keeps its `mcp-session-id` alive on mcplocal, which is exactly what holds a gated project open. Best-effort, so a first mount still works. - The footer label renders `wrapMode="none" truncate`. The home prompt row is narrow enough that the default wrap broke `mcpctl:homeautomation` across two lines mid-word; clipping the tail of a long name reads far better. Verified against opencode 1.18.15: ctrl-x m opens the picker, the home footer is now one line, and a disconnect-then-add switch still lands — the model called `mcpctl_begin_session` and listed the new project's tools. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-09 18:02:52 +01:00
Michal	be2a5cb189	feat(opencode): native opencode integration — /mcpctl switcher, live project switching, footer indicator ... Adds `mcpctl config opencode`, two opencode plugins and an `opencode` skills sync target, so an mcpctl project can be switched from inside opencode's TUI and the active one is visible at a glance. Unlike `config claude` / `config prime-agent`, this writes NO MCP entry into the host's config. opencode exposes an HTTP API for its own MCP registry (`POST /mcp`), so the project is mounted through the running app: - the token stays in ~/.mcpctl/opencode-state.json (0600) instead of a mode-0644 opencode.json users paste into bug reports; - switching projects takes effect on the next turn, with no restart. Inside opencode: /mcpctl filterable project picker; switches live /mcpctl-status active project, mount state, gateway URL /mcpctl-skills re-sync this project's skills plus a `mcpctl:<project>` indicator in the prompt footer, next to the model name and one line above the token counter. Design notes: - the MCP server is registered under a constant name, so tools keep a stable `mcpctl_*` prefix and opencode's per-request tool resolution shows the new project's tools by itself — no "your old tool names are dead" message to the model, unlike the pi extension; - an unchanged mount is never re-registered: mcp.add rebuilds the connection and mcplocal binds a gated project's unlocked state to that connection's mcp-session-id, so re-adding would re-lock a project begin_session had just opened; - the server plugin does not mount during setup — setup runs before the server accepts connections and mcp.add calls back into it, which hangs opencode on a blank screen before the TUI draws; - the switcher shells out to this CLI (--skip-plugin --skip-marker) so token minting, state and skills stay in one place; - no usable credential aborts non-zero with the state file untouched, so a failed switch leaves the previous project working rather than swapping it for a mount that 401s. `skills sync --agent opencode` installs into ~/.config/opencode/skill (XDG aware) with the same shared-tree semantics as pi and prime-agent. The credential plumbing shared with `config prime-agent` is lifted to one place and parameterised by agent rather than copied. The plugin sources are embedded in the CLI (generated, freshness-tested) so an installed binary with no source tree can provision them, and are typechecked against the real @opencode-ai/plugin types. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP	2026-08-08 21:03:53 +01:00
Michal	a8a1045824	Merge 'fix(smoke): actually clean up smoke-test resources' into feat/pi-extension	2026-08-08 20:16:21 +01:00
Michal	3fa41e4d46	Merge main into feat/pi-extension	2026-08-08 19:59:25 +01:00
Michal	90c49bcb22	refactor(prime-agent): drop the widget fallback, keep the tray status ... With prime-agent-extension-status.patch in place the tray renders ctx.ui.setStatus() next to the model name, which is what a status line should be. The widget was a workaround for its absence and was never a substitute: widgetContainerBelow sits in the fullscreen *scroll* list, not the dock, so it scrolled away with the transcript, and with both set the project name appeared twice. The startup retries stay: resetExtensionUI() clears extension statuses just as it cleared widgets, so the value set during session_start is still wiped before it can be seen. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB	2026-08-08 19:59:24 +01:00
Michal	0a29c2fd7f	fix(prime-agent): re-publish the indicator after prime-agent clears extension widgets ... Verified with a probe extension rather than by reading the bundle: session_start fires with hasUI=true, ctx.ui.setWidget exists and the call returns without throwing — and the widget still never appeared. Cause is prime-agent wiping it immediately afterwards. resetExtensionUI() -> clearExtensionWidgets() runs from onBeforeSessionInvalidate and from the connection-state-snapshot handler, both of which land after session_start, so the indicator was set and cleared before it could be seen. Nothing re-set it until a turn, which is why a fresh session with no messages showed nothing. Re-publishes at 1s/3s/6s after session_start to land past that reset. setWidget is idempotent, so a redundant retry costs one re-render. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017BMXdb2qZbPSh8Q7XpTyjB	2026-08-08 19:52:07 +01:00