# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Changed

- Rewrite the README around installation and everyday use, add a discovery/call-flow diagram, and move detailed configuration, migration, and maintainer guidance into linked docs.

## [8.0.1] - 2026-10-13

### Changed

- Refresh the MCP client, core, and server SDKs together to 2.3.1 in the adapter and interactive visualizer, and update smol-toml to 1.9.1. Keep native authentication, request lifetime, cancellation, streaming results and package discovery contracts.
- Calibrate the macOS large-history test timeout for its 10,000 real disk flushes, without reducing the workload or changing persistence assertions.

## [8.0.0] - 2026-10-01

### Changed

- Require Pi 1.0.0 and qualify the exact official SDK/CLI cohort; live installations are not changed.
- Typed MCP tools expose native schemas, complete namespace instructions, annotations, bounded structured output and result-level failures. Human content, private raw capture, output/readback artifacts, cancellation and no-replay ownership remain separate.
- Restore the selection journal backward to the first valid snapshot, preserving legacy/incomplete recovery, pins, restrictions, lazy startup and enable-first permissions. Keep this journal for the official initial SDK-resume gap.
- Save MCP App messages privately on disk. Small retrievals stay inline; large histories stream to existing paged output references. Failed persistence/delivery remains recoverable, with no new retention caps.
- Reject App messages/context updates whose authenticated upload finishes after completion, and refuse incomplete history delivery before draining accepted sessions.
- Report and document the owner-accepted failed-storage boundary: unsaved in-memory App history is lost on reload/process exit; no second recovery store is added. Normal private disk history and failed-delivery recovery remain protected.
- Remove retired fork checkpoint/metadata APIs. Preserve actual transport/OAuth/sampling/elicitation/capture shutdown ownership and move their independent lifetime tests out of the retired checkpoint suite.

## [7.1.1] - 2026-10-01

### Changed

- Update MCP Apps to 2.0.3 in the adapter and interactive visualizer, keeping their dependency graphs aligned.
- Qualify development against official Pi 0.99.2 and the current maintained fork, keeping host peers wildcard and the declared Pi/Node floors unchanged.
- Update development validation to Vitest 5.0.3 and npm 12.2.0.
- Use current public Pi tool activation and request-boundary scheduling APIs, preserving authentication, approval, and checkpoint barriers.

### Fixed

- Keep development TypeBox aligned with the official Pi baseline and block standalone updates that load a second version during source startup.
- Upgrade the split MCP client, core, and server SDKs together to 2.2.0 in the adapter and interactive visualizer. Native discovery now retains changing catalog pages that reuse an opaque cursor instead of silently dropping later tools.
- Bound native catalog walks, including automatic refreshes, to 1,024 pages and reject oversized or nonterminating catalogs without publishing partial results.

## [7.1.0] - 2026-09-27

### Changed

- Keep full MCP gateway/script schemas inactive until selected with `mcp_search({ enable: ["gateway", "script"] })`. Typed discovery still loads matches in one call. Selections persist on the current session branch; configured pins, legacy resource pins, configuration restrictions, and loader-excluded host allowlists retain their behavior.
- `npm run typecheck` now also checks the test suite under the same strict settings as the source.

## [7.0.0] - 2026-09-26

### Breaking changes

- Node.js 24 or later is required. The development baseline is Pi 0.87.1.
- Package `exports` now resolve to the compiled `dist/` modules and declarations. The npm tarball no longer ships TypeScript sources, build scripts, or tsconfig files; standalone Node consumers import the package directly without a TypeScript loader.
- `zod` is a regular dependency only, no longer a required peer.

### Changed

- Update the MCP client and core SDK to 2.1.0, `@napi-rs/keyring` to 2.1.0 (credential-store failures now surface as errors instead of empty reads), `open` to 11.0.4, and `smol-toml` to 1.9.0. Pin all runtime dependencies to exact versions.
- MCP clients report the adapter's package version instead of a stale `4.3.1`.
- Build with TypeScript 7 and test with Vitest 5. OAuth tests, conformance, and fixtures run on Node's native type stripping; `tsx` is removed. `npm test` now also runs the OAuth suite.
- Git installs copy the committed MCP Apps bridge bundle instead of rebuilding it, so they no longer need esbuild. `npm run build:bridge` regenerates it, and a test fails when it drifts.
- The MCP conformance runner is fetched on demand instead of installing a second MCP SDK into every source install.
- CI qualifies official Pi and the maintained fork with the shared Pi compatibility automation, and rejects lockfile URLs outside the public npm registry.

### Fixed

- Prevent project stdio overrides, including OpenCode working-directory and environment changes, from inheriting another config source's environment secrets.
- Refuse MCP setup writes when an existing config cannot be read, preserving the file and showing the error in the setup preview.
- Keep a shared initial MCP connection alive when one caller cancels, so other callers can continue without a false failure backoff.
- Let npm resolve explicit version ranges and tags for MCP server commands instead of launching an arbitrary cached version. Exact versions retain the direct-launch optimization.

## [6.0.0] - 2026-09-22

### Breaking changes

- New gateway calls require an explicit `action` (`status`, `search`, `list`, `describe`, `call`, `connect`, `instructions`, `resources`, `read-resource`, `read-result`, `auth-start`, `auth-complete`, or `ui-messages`) and object arguments. Stored v5 optional-mode calls and JSON-string arguments are normalized only at ingress.
- `mcp_search` discovers and loads full typed tool schemas for the next request, without executing a hit. `directTools` pins the initial active set; other eligible tools remain available for later discovery. Host tool allowlists and `MCP_DIRECT_TOOLS=__none__` remain binding.
- Resources are listed and read explicitly by server and URI, not registered as synthetic functions. The panel shows separate resource counts and only real-tool pin choices. Legacy resource aliases remain gateway/script-callable; old resource pins keep the gateway available even with `disableProxyTool` enabled.
- Script `tools.describe` preserves complete JSON Schema and raw descriptor fields rather than returning `inputTypeScript`. Update consumers to use `inputSchema` and optional `outputSchema`.
- Cold caches no longer trigger connections to every lazy server. Global search reports partial catalog coverage; selected server discovery, configured pins, and eager/keep-alive startup remain intentional connection paths.
- Metadata cache format 2 preserves raw tool/resource descriptors and reads legacy format 1. Downgrading to v5 ignores format 2 and requires rediscovery. Config paths and the OAuth namespace are unchanged from v5; see [migration](docs/migration.md#upgrading-from-v5).

### Added

- Branch-scoped typed-tool selection in native Pi session entries, restored on resume, reload, tree navigation, and working-directory changes. Optional native tool-search hosts use exact namespaced lazy references; official Pi 0.87.0 uses the ordinary loader with the same discover-then-call workflow. Existing pins keep flat names.
- Conditional native asynchronous execution for typed tools when the host and selected model route both support it, excluding configured approval, MCP App UI, and sequential checkpoint flows.
- Gateway `resources`, `read-resource`, and `read-result` actions; script `tools.resources`, `tools.readResource`, and `tools.readResult` methods. Resource access retains exposure, filtering, authentication, and approval policy.
- Model-visible references to retained raw results for structured, media, resource, oversized, and extra-field payloads. Saved-result readback selects JSON Pointers/fields before bounded character paging and never repeats a server call. Artifacts respect the SDK host's `outputDirectory`.

### Changed

- Search uses MiniSearch over tool names, descriptions, and parameter guidance. Discovery and descriptions retain canonical descriptors, including output schemas, annotations, and `_meta`; app-only tools stay hidden from the model and panel.
- Typed, gateway, and script calls share dispatch, authentication, approvals, and call capture. Scripts receive raw MCP results, including error-result data, without rendering unused text artifacts. Tiny plain-text results remain inline.
- Render `structuredContent` alongside content blocks instead of suppressing it when text or images are present. Existing output byte/line limits still bound model-facing text.
- MCP Apps uses 2.0.0 alongside the split MCP SDK 2.0.0 runtime, removing the runtime SDK 1 dependency.
- Panel and command status distinguish real tools, resources, startup pins, and undiscovered catalogs while retaining authentication, reconnect, and error controls.

## [5.0.0] - 2026-09-19

### Changed

- **BREAKING:** Package identity is now `@fitchmultz/pi-mcp-adapter`, with CLI `fitch-mcp-adapter` and repository `fitchmultz/pi-mcp-adapter`.
- **BREAKING:** Adapter-owned config, metadata/onboarding/npx caches and legacy OAuth imports now live under `<Pi agent dir>/fitch-mcp-adapter/`. The project override is `.pi/fitch-mcp-adapter/mcp.json`; default traces use `.pi/fitch-mcp-adapter/traces/`. Shared standard MCP files and explicit config paths/imports remain supported unchanged.
- **BREAKING:** OAuth uses service `fitch-mcp-adapter.oauth` and normal legacy imports use `FITCH_MCP_OAUTH_DIR`. Old adapter-owned defaults and credentials are never imported implicitly; `MCP_OAUTH_DIR` is read only by explicit migration. Other operational `MCP_*` and `PI_MCP_ADAPTER_*` controls remain compatible.
- The private runtime registry and exported status channel use the `fitch-mcp-adapter` prefix (`MCP_STATUS_EVENT` is `fitch-mcp-adapter/status/v1`). Public `mcp`, `mcp_script`, slash commands and wire-stream metadata remain unchanged.
- Default DCR homepage points to the Fitch repository; the public client metadata document is named `Fitch MCP Adapter` at its existing URL. Existing client registrations retain priority.

### Migration

- Replace the previous package entry with `pi install npm:@fitchmultz/pi-mcp-adapter` (or the Fitch Git source). Load only one adapter in a Pi host.
- After installation, before restarting Pi, run `fitch-mcp-adapter migrate --dry-run`, then `fitch-mcp-adapter migrate`. Repeat from each project with a v4 `.pi/mcp.json` override. See [full upgrade instructions](docs/migration.md#upgrading-from-v4).
- Migration copies global owned files, the current project override, and configured HTTP servers' OAuth entries only when destinations are absent. It preserves URL/issuer/client/token data, verifies credential copies, reports existing destinations without merging, prints no plaintext secrets, and leaves old sources untouched. Dry-run never reads the keychain or writes; repeated migration skips existing destinations.
- The copied OAuth grant remains the same provider grant. Sign in again for a separate provider grant. Normal runtime never falls back to the old namespace after logout.

## [4.4.0] - 2026-09-18

### Fixed

- Publish generated TypeScript declarations so installed SDK consumers do not compile adapter implementation files or require its development-only types.
- Update `smol-toml` to 1.8.0 and the locked `hono` dependency to 4.13.8, including fixes for the published malformed-TOML denial of service and Hono parsing/static-generation advisories.
- Return the original input schema from `mcp_script` discovery when its TypeScript shape cannot be represented, so tool parameters and constraints remain available. Representable schemas keep the compact TypeScript description.
- Honor `limit` and `offset` when listing tools after an explicit `mcp({ connect })` request.
- Keep the `mcp` gateway description stable across metadata refreshes and credential changes. Configured server names and usage guidance stay visible; catalog counts and server instructions remain available through tool results without rewriting the prompt prefix. Direct-tool refresh and connection behavior are unchanged.
- Restrict opted-in modern transport retries to explicit read-only or idempotent tool annotations. Unknown write outcomes request provider readback instead of redispatch; confirmed pre-dispatch session/auth recovery remains available.
- Let cancelled MCP tools stop waiting for initialization immediately without cancelling shared startup or other callers. Proxy and script tools keep their existing 30-second initialization timeout.

### Added

- Complete a manual OAuth flow with `auth-complete` after the authenticated browser reaches this Pi session's callback, without copying the authorization code into a tool call. Existing pasted URLs/codes, callback validation, cancellation and expiry remain supported; receiving the callback alone does not exchange tokens.
- Optional `createMcpAdapter({ transformConfig })` to extend a freshly resolved configuration with session context before initialization and tool registration, preserving ambient configuration and project trust boundaries.
- Optional `createMcpAdapter({ defaultScriptTimeoutMs })` to change or disable the host's overall script deadline. Explicit per-script deadlines take precedence; individual service deadlines, cancellation and owner shutdown remain unchanged.
- Optional resolved `McpOperationContext` in the existing `beforeExecute` callback for direct, proxy, script and resource calls. It exposes live annotations and the existing annotation-trust opt-in before the individual service deadline, without changing native before/after events or requiring new configuration. Two-argument callbacks and conservative non-call proxy checkpoints remain supported.
- Optional `createMcpAdapter({ outputDirectory })` for host-managed oversized tool/resource text, raw MCP JSON, and final script output. Unconfigured adapters keep the system temp directory; limits, live results, random file names, and private file permissions are unchanged.
- An awaited `createMcpAdapter({ onToolCall })` callback before dispatch and after raw outcomes, including each script call's resolved arguments and native outer/inner identity. Hosts can checkpoint native Pi history without replaying completed calls.
- Optional `createMcpAdapter({ beforeExecute })` for awaited host checkpoints before direct/proxy execution and each resolved script call. Supplying it selects Pi's native sequential sibling scheduling; Stop, output directories, and default request/script limits remain unchanged.

## [4.3.1] - 2026-09-07

### Fixed

- Settle modern HTTP tool requests after an SSE response body disconnects instead of waiting for the deadline. Retry only the affected request, once with a fresh ID, when `retryOnTransportFailure` is enabled. Preserve the original deadline, cancellation, sibling calls, native resumption, and transport shutdown tracing.

## [4.3.0] - 2026-09-05

### Added

- Native `oauth.crossAppAccess` enterprise OIDC ID-token exchange with separate IdP/MCP identities, lazy token sources, public custom-document and private-key MCP authentication, headless operation and native enterprise capabilities. IdP failures preserve the MCP login; HTTP cancellation follows the connection and individual request without interrupting siblings.
- Native `oauth.privateKeyJwt` client authentication with lazy PEM/JWK environment and command sources, configured or custom-document identities, and browser code/refresh support. Configured client-credentials clients advertise the native OAuth extension. Local signing failures preserve credentials and do not trigger browser consent.
- Native Client ID Metadata Documents (CIMD) with an automatic shared Pi MCP Adapter identity for eligible public browser clients and `oauth.clientMetadataUrl` custom URL / `false` overrides. Configured and usable stored clients keep priority; unsupported servers retain native dynamic registration.

### Fixed

- Reject reuse of a saved shared browser CIMD registration for machine or private-key authentication without erasing that login. Explicit pre-registration and opaque DCR client IDs retain priority.
- Preserve saved CIMD registrations and refresh tokens when only the native loopback callback port changes, including after changing the metadata URL setting. DCR, exact callback and issuer checks remain unchanged.
- Retain newly registered noninteractive public clients as registrations rather than legacy config stubs, so custom CIMD token requests include their actual client ID.

## [4.2.3] - 2026-09-05

### Fixed

- Carry newly required OAuth scopes into the next permitted authorization flow without changing issued token scopes, automatic-auth limits, or native refresh and machine-to-machine behavior.
- Activate implicit OAuth for protected catalogs and first tool calls after public startup, including when valid tokens are already stored.
- Validate callback state and issuer before displaying OAuth errors on both pasted redirects and the HTTP listener.
- Preserve accepted work during manual, automatic, command, and panel auth handoffs while keeping ordinary reconnect/reset behavior.
- Explain missing or unloadable Android/Termux native keyring bindings in OAuth failures and credential status. Persistent OAuth still requires a supported secure store; no plaintext fallback is added.

## [4.2.2] - 2026-09-04

### Fixed

- Save direct-tool selections without copying inherited server connection details or credentials into Pi config.
- Recover expired sessions without interrupting or replaying accepted work on the old connection; concurrent callers share a replacement while keeping their own cancellation and deadlines.

### Changed

- Refresh development dependencies `nanoid` to 3.3.18, `postcss` to 8.5.28, `protobufjs` to 7.6.6, and the root `undici` to 7.29.1. Update checkout/setup-node Actions to v7.0.1/v7.0.0 while keeping Node 22 tests and the Pi 0.84.0 development baseline.

### Known issues

- Pi 0.84.0's development dependency shrinkwrap still installs `undici` 8.9.0, affected by dependency advisories fixed in 8.10.2. This remains unresolved even when npm audit reports zero vulnerabilities. Source installs temporarily include these development dependencies to build, then prune them.

## [4.2.1] - 2026-09-04

### Fixed

- Update transitive dependencies `fast-uri` to 3.1.7 and `qs` to 6.16.0 to address URI normalization and query-string parsing security advisories.

## [4.2.0] - 2026-09-04

### Added

- Native HTTP automatic negotiation for MCP 2026-07-28 using official split SDK 2.0.0, with a per-server `protocolVersion: "legacy"` override. Stdio and Unix sockets keep their legacy default.
- Opt-in `retryOnTransportFailure` makes one fresh modern tool request after a lost pre-response connection or HTTP 5xx without a JSON-RPC error. It is disabled by default because retrying may duplicate side effects. Direct tools, `mcp`, and `mcp_script` share the same policy and absolute call deadline.
- Per-server `oauth.skipIssuerMetadataValidation`, disabled by default, for providers with mismatched authorization-server metadata. Stored issuer bindings and callback issuer/state validation remain enforced.

### Changed

- Let the SDK own negotiation, protocol and parameter headers, schema refresh, multi-round-trip input handling, pagination, and JSON Schema dialect validation. Remove the duplicate HTTP initialization probe and raw endpoint-shape probe. Retain SDK v1 only for MCP Apps.
- Preserve native transport identity during tracing so modern POST-stream cancellation and native stdio probing work correctly.
- Pass OAuth callback `iss` to the SDK and retain implicit OAuth credential-store deferral until a real challenge.
- Render valid primitive structured results, including `null`, without dropping non-empty content or images.

### Compatibility

- SDK 2.0.0 still rejects HTTP 200 discovery errors with a null response ID. Set `protocolVersion: "legacy"` for affected servers; the adapter does not patch native negotiation.
- Ambiguous failures while reading JSON/SSE response bodies are not automatically replayed. Deprecated SSE fallback is limited to unsupported HTTP endpoint responses during connection.

## [4.1.5] - 2026-08-14

### Fixed

- Load MCP status, setup, and authentication panels through the extension's static module graph so Pi can resolve their `@earendil-works/pi-tui` and `@earendil-works/pi-coding-agent` host peers after install-time dev-dependency pruning.

## [4.1.4] - 2026-08-14

### Changed

- Build cleanup is uniformly best-effort, so a locked staging tree cannot turn a successful concurrent race loss into failure or mask the compiler/publish error that matters.
- `scripts/build.mjs` now separates stranded-tree reaping, compilation plus runtime-asset staging, and publication behind named retry/cleanup constants and helpers while preserving the cross-repo build contract.
- `scripts/prepare.mjs` structurally preserves the original build error when the final dev-dependency prune also fails; the prune warns and may leave the dev toolchain for manual cleanup.
- An empty `dist/` is no longer accepted as a concurrent winner; this build retains and retries its staged emit instead.
- Deterministic tests now cover an unreapable strand, failed old-output removal, concurrent-winner discard, empty-directory rejection, vanished staging, and retry-cap exhaustion. The real-process smoke narrows from three twelve-wide rounds to one four-way round while deterministic faults cover each publication branch without destabilizing unrelated process-heavy suites. A publish failure after old-output removal fails loudly and may leave `dist/` absent.

## [4.1.3] - 2026-08-14

### Changed

- `dist/` is now published by retrying this build's own `rename` instead of waiting on another build. A rename failure yields only when `dist/` already exists (an existence check, not an errno check, so platforms that report a different code for rename-onto-existing-directory still behave correctly); otherwise the staging tree is retained and the rename retried, so this build can publish its own output rather than wait on a concurrent winner's scheduling. This replaces the bounded poll shipped in 4.1.2, which could still fail a build whose concurrent winner was descheduled past the poll window.
- Staging-reaper documentation now states its precise guarantee: only pids already gone at probe time are eligible; pid reuse between probe and removal remains inherent to pid-based reaping.
- Swap coverage now includes the deterministic slow-winner regression, and concurrent-storm failures surface the build's stderr instead of only its exit code.

## [4.1.2] - 2026-08-14

### Changed

- `scripts/build.mjs` now reaps `dist.staging.<pid>` directories stranded by dead builds (SIGKILL or crash mid-emit) at the start of every build, using a signal-0 liveness probe so live concurrent builds are never touched. Reaping is best-effort: an unreapable strand warns instead of failing the build.
- The race-loss check now polls briefly for a mid-swap concurrent winner before declaring failure, closing the window identified in the v4.1.1 review where a losing build could spuriously exit 1 while the winner was between its own `rm` and `rename`.
- `scripts/prepare.mjs` prunes the dev toolchain in a `finally` (even when the build fails) and forwards build output on success, so install-time diagnostics such as the concurrent-swap race-loss warning are no longer swallowed.
- New automated coverage for the staging swap: failed builds preserve the previous `dist/`, successful builds purge stale files and copy the runtime assets, dead-pid staging dirs are reaped while live ones survive, and concurrent builds all succeed.

## [4.1.1] - 2026-08-14

### Changed

- `scripts/build.mjs` now emits into a pid-scoped `dist.staging.<pid>` directory, so concurrent builds (pack-triggered `prepare`, parallel lanes) cannot clobber each other's staging tree or swap a partial emit into `dist/`. A build that loses the swap race to a concurrent winner normally exits 0 (the winner's tree is an equivalent fresh emit; a narrow timing window can still surface the loss as a loud failure); `rm(dist)` failures always fail loudly. Ports the build hardening reviewed in pi-cursor-sdk v0.3.0.

## [4.1.0] - 2026-08-13

### Changed

- The Pi extension manifest now loads precompiled `dist/index.js` instead of transpiling the ~19kloc TypeScript graph through jiti. This removes the transpile cost on cold starts and after cache invalidation (fresh installs, `pi update`, cache eviction); warm starts with a hot jiti cache were already at parity. A `prepare` lifecycle script builds `dist/` on install and update, including Pi's `npm install --omit=dev` git-install flow, prunes the dev toolchain back out afterwards, and copies the runtime sibling assets (`mcp-keyring-helper.cjs`, `mcp-script-worker.mjs`, `app-bridge.bundle.js`) into `dist/`.

## [4.0.2] - 2026-08-09

### Fixed
- Preserved compact search settings across pagination and clarified recovery when an explicit server does not own a requested tool.

## [4.0.1] - 2026-08-08

### Fixed
- Paginated server tool catalogs with bounded ranges, explicit continuation calls, a 100-item page cap, and out-of-range recovery instead of dumping every tool.
- Ranked typo suggestions by same-server edit distance, rejected oversized guessed names before ranking, avoided connecting on cached-name misses, and removed full-catalog error dumps.
- Let `mcp_script` process full raw MCP results before model-facing output guards, and kept overflow summaries distinct from real `structuredContent`.
- Omitted stale catalog counts from tool guidance and emitted the large direct-tool advisory only once per resolved tool set.

## [4.0.0] - 2026-08-08

### Changed
- **BREAKING:** Removed regex tool search and the `regex: true` input. Ranked substring and token search remains available.
- **BREAKING:** Removed the legacy `settings.hostConfigDiscovery: "prompt"` value. Existing `"prompt"` settings are treated as `"off"`; use `"on"` to load detected host configs.
- Proxy and direct tool calls now share one execution path, keeping output guarding, recovery, UI handling, and raw MCP result details consistent.
- Removed unused internal APIs, compatibility modules, and dependencies, reducing non-test source by about 805 lines and the installed footprint by about 56 MB.

## [3.0.1] - 2026-08-07

### Changed
- The MCP footer status now defaults to compact `MCP connected/enabled`. Set `settings.mcpFooterStatus` to `"full"` to restore the previous detailed text.

## [3.0.0] - 2026-08-06

### Changed
- **BREAKING:** Pi 0.84.0 or later and Node.js 22.19.0 or later are now required. Pi host development dependencies and TypeBox are pinned to the released 0.84.0 contract, while core runtime packages remain optional wildcard peers per Pi package conventions.
- MCP sampling now dispatches through Pi's `ModelRegistry.complete()` so resolved endpoints, custom providers, authentication, and `null` header-deletion markers are preserved by the 0.84 request pipeline.
- Direct-tool schemas now use Pi 0.84's bundled TypeBox APIs directly, stale tools use the supported active-tool deactivation flow instead of compatibility probes for non-contract host APIs, and renderer hints honor configured Pi keybindings.
- Project MCP configuration and project-local host imports now respect Pi 0.84's project trust decision. They are not read and cannot start servers unless the project is trusted.
- Custom MCP panels now open only in TUI mode; non-TUI UI clients receive text status or command guidance.

### Fixed
- Stopped tokenless discovery requests, sandboxed MCP app documents, unrelated child windows, and app-opened popups from gaining session authority; discovery now serves a non-sensitive landing page, app HTML loads with a separate resource-only token, host messages accept only the app frame as their source, and the app response enforces sandboxing even when opened as a top-level page.

## [2.19.0] - 2026-08-03

### Added
- `mcp_script` now records each search, describe, and call with its input, outcome, and duration in result details; emitted, returned, and console values retain readable Maps, Sets, cycles, functions, symbols, and BigInts. Its docs now lead with the plain JavaScript agents write and position it as the primary MCP multi-call workflow surface.
- Documented how to hide the bundled `mcp-scripting` Pi skill while keeping the adapter extension installed. Thanks @aryzing for issue #267.
- Documented Linux revoked-keyring recovery in the OAuth guide and `_meta.ui.visibility` behavior in the MCP UI guide.

### Changed
- `mcp_script` is now registered by default for trusted JavaScript MCP multi-call workflows, while `mcp` remains the right tool for status, discovery, auth, and single calls. Set `settings.scriptMode` to `false` to hide the tool.

### Fixed
- `mcp_script` traces now include missing describe attempts, and shared acyclic values no longer render as circular in script output formatting.

## [2.18.0] - 2026-08-02

### Added
- Added `settings.freezeDirectTools` to keep direct MCP tool registration stable after initial sync while preserving explicit reconnect refreshes. Thanks @ddfourtwo for PR #254.
- Added best-effort Linux OAuth credential recovery when Pi inherits a revoked session keyring, allowing explicit re-authentication through a fresh `keyctl` session helper. Thanks @anthod0 for issue #248 and the validation prototype.
- Ranked, paginated MCP tool search: best matches come first in a short page of 12 instead of an unranked dump of every match with full schemas, so the model stops guessing and each search costs a fraction of the tokens. Misses on describe/call now return top-5 "Did you mean" suggestions, letting the model self-correct a typo or missing prefix in the same turn instead of burning a round trip.
- Optional `approveTools` patterns (global and per-server) add the missing middle tier between "tool runs instantly" and "tool hidden entirely": flag risky tools and Pi asks before running them — Allow once / Allow for session / Deny — across proxy, direct, resource, and iframe-originated calls. Safe tools keep full speed; a deny is a normal result the model adapts to, not a crash.
- Opt-in `mcp_script` trusted JavaScript MCP scripting turns N-step jobs into one call: loop, filter, and chain tools for tool-restricted subagents where every round trip costs child context. Scripts discover tools with `await tools.search({ query })`, inspect exact shapes with `await tools.describe({ path })`, and call them with `tools.call(path, args)` — no more guessing names from outside the script. A runaway script can never freeze Pi itself: scripts run isolated from the main process and are force-stopped at their time limit, even if stuck in an infinite loop. Result details include a `calls` trace of every invoked path and outcome, and a bundled `mcp-scripting` skill teaches the full workflow on demand. Every scripted call still goes through auth, output guarding, and the approval gate.
- HTTP connection failures are now probe-classified into a plain-language diagnosis (for example "endpoint returned HTML (200) — this URL does not appear to speak MCP") instead of an opaque "fetch failed", so setup mistakes are fixed in seconds. Healthy connections are never probed.
- Tool parameters render as compact TypeScript shapes (`{ query: string; limit?: number }`) in describe and search, replacing multi-line schema dumps — the model reads less and acts sooner, with the previous formatting kept as a fallback for exotic schemas.
- `/mcp setup` gained curated one-click presets (DeepWiki, Context7, Notion, GitHub, Chrome DevTools): pick, preview the exact config write, confirm — new servers in under a minute with no hand-typed setup.

The ranked search scoring, did-you-mean suggestions, approval patterns, endpoint shape probe, TypeScript-shaped schemas, and codemode design in this release are adapted from [Executor](https://github.com/UsefulSoftwareCo/executor) by Rhys Sullivan (@RhysSullivan). Thanks Rhys.

### Fixed
- Brought MCP Apps UI hosting in line with the current spec: provider HTML now runs in a real sandbox, gets a restrictive default CSP even when the resource omits one, and `_meta.ui.visibility` is honored so app-only tools stay out of the model tool list while model-only tools cannot be called from the UI.
- MCP Apps UI sessions are now easier to open from Moshi and remote terminals: the local UI server uses Moshi-discoverable low ports, answers preview discovery probes, serves a loopback-only landing shell, prints Moshi/SSH access hints for remote sessions, and fits the host shell better in narrow in-app browsers. UI-submitted model context is now captured as a bounded handoff, wakes the agent like prompts and intents, and remains available through `mcp({ action: "ui-messages" })` after the UI closes.

## [2.17.0] - 2026-07-31

### Added
- Added `settings.mcpFooterStatus` to compact or hide the persistent MCP footer status. Thanks @jwintz for issue #5.
- Added per-server OAuth `authorizationParams` for provider-specific authorization URL parameters such as Google's `access_type=offline`, while rejecting OAuth flow-owned parameter overrides. Thanks @hank-warren for issue #238.

### Fixed
- Added a best-effort absolute-path fallback for loading the `@napi-rs/keyring` native binding when compiled Pi/Bun cannot resolve the package loader. Thanks @sgiath for issue #230.
- Bound collapsed MCP tool result rendering by character count as well as line count, preventing huge single-line results from slowing long TUI sessions. Thanks @Whisperfall for issue #249.
- Let configured `oauth.scope` override OAuth discovery scopes during authorization flows. Thanks @viggy28 for issue #225 and @adity982 for PR #226.

## [2.16.0] - 2026-07-30

### Added
- Added an optional per-server `toolPrefix` override for direct MCP tools, prompts, and proxy summaries, falling back to the global prefix when unset. Thanks @FurryWolfX for issue #229.
- Added an advisory warning when resolved direct tools pass the documented 75-tool threshold, with no cap or enforcement. Thanks @JasonLandbridge for issue #240.

### Changed
- Restored the MCP SDK v1 client for compatibility with deployed MCP servers and OAuth providers. This rollback temporarily removes SDK v2-only protocol negotiation while retaining OAuth issuer binding and callback issuer validation. Thanks @hyknerf for PR #237 and issue #236, @leonfox28 for issue #227, and @JorelLatraille for issue #241.

### Fixed
- Avoided a double-close race when disconnecting MCP connections by letting the SDK client own transport shutdown. Thanks Szymon Wiszczuk (@golota60) for PR #235.
- Prevented `/mcp` and `/mcp-auth` from crashing when the OS OAuth credential store is unavailable.
- Stored oversized OAuth credential payloads as secure-store manifests plus chunks, so Windows Credential Manager value limits no longer block OAuth completion for large token records. Thanks @LysanderdeJong for issue #223.
- Stored OAuth credential payloads as compact JSON, so multiline secrets no longer corrupt gnome-keyring plaintext keyrings. Thanks @hank-warren for issue #239.
- Kept collapsed MCP tool results from re-wrapping full multi-10KB payloads on repeated TUI renders, avoiding composer keystroke lag after large MCP dumps. Thanks @hyknerf for PR #233 and @chapmanb for the held-Text follow-up fix.

## [2.15.0] - 2026-07-25

### Added
- Added native `rmcp-mux` Unix-socket connections for explicitly sharing external MCP server processes across Pi sessions. Thanks j0e1 (@pWoLiAn) for issue #76.
- Added connection-time command resolution for HTTP bearer tokens and headers, OAuth client secrets, and stdio environment values, with `!!` escaping and fail-closed execution. Thanks @estrizhok for issue #221.

### Fixed
- Treated null optional server URLs as absent and cleaned unpublished runtimes after initialization failures, preventing `not_initialized` sessions with surviving MCP children. Thanks @autopeasant for the diagnosis in issue #222.
- Registered env-selected direct MCP tools before child `agent_start` when their metadata cache must be populated first. Thanks @peedrr for the original report in issue #219.

## [2.14.0] - 2026-07-25

### Added
- Added the global `settings.showStatusIcon` opt-out for plain `MCP: ...` status and connection text while keeping the plug icon enabled by default. Thanks @vaultboy001 for issue #216.

### Fixed
- Deferred implicit OAuth credential-store access until an HTTP server actually challenges for authentication, so unauthenticated remote Streamable HTTP servers work in headless environments. Thanks @vdom-1 for issue #218.
- Accepted draft-07 tool output schemas alongside JSON Schema 2020-12 while preserving structured-content validation. Thanks Daniel Marbach (@danielmarbach) for issue #217.

## [2.13.0] - 2026-07-25

### Added
- Added a versioned, sanitized MCP runtime status snapshot on Pi's shared event bus for extensions, without connecting lazy servers or exposing SDK internals. Thanks Ludev (@ludevdot) for issue #110.
- Added opt-in host-specific MCP config discovery with source/provenance and conflict reporting. Standard shared and Pi-owned config precedence remains unchanged, and external host files are never written or silently executed. Thanks @lsmir2 for issue #169.
- Added opt-in metadata-only JSONL MCP protocol tracing with bounded per-session files and redaction. Thanks @66-firebat for issue #45.
- Added per-server `includeTools` allowlists with exact-name and glob matching for proxy, direct-tool, and `/mcp` panel surfaces. Thanks Finn (@finnvyrn) for issue #136.
- Made `mcp({ connect: "server" })` refresh an already connected server instead of reusing stale tool metadata. Thanks Sebastiano Poggi (@rock3r) for issue #28 and @theflysurfer for the refresh analysis.
- Added a plug icon prefix to MCP footer status text. Thanks Felipe Cadal (@cadal-cw) for issue #145.
- Discovered user-global MCP configs from `~/.agents/mcp.json` and `~/.agents/mcp/mcp.json`. Thanks David Jadczyk (@davidjadczyk) for issue #117.
- Accepted JSONC-style comments and trailing commas in MCP JSON config files. Thanks @GoCoder7 for issue #124.

### Changed
- Measured and spilled oversized raw MCP result details as compact JSON instead of pretty-printed JSON, reducing hot-path allocation and event-loop work. Thanks José Maia (@glitch-ux) for issue #214 and PR #215.
- Renamed generated MCP resource tools from `get_<resource>` to `read_<resource>` to match the MCP `resources/read` operation. Thanks @vdom-1 for issue #185.

### Security
- Moved persistent OAuth credentials from plaintext `tokens.json` files into the operating system credential store, with one-way legacy import and fail-closed behavior when secure storage is unavailable. Thanks Sam Atkins (@atkinsam) for issue #180.

### Fixed
- Skipped `resources/list` for MCP servers that do not advertise the `resources` capability, matching the existing prompt discovery gate and silencing the SDK v2 debug line that tools-only servers printed on every connect. Thanks Aleksandr Davydenko (@kotuke) for PR #213.
- Made the MCP footer show enabled configured servers as the primary count, with active connections as secondary state, so lazy servers no longer look broken before first use or after idle shutdown. Thanks blumlaut (@Blumlaut) for issue #93.
- Show the actual proxied MCP server/tool name in `mcp` tool results. Thanks Finn (@finnvyrn) and @dillontkh for issue #68.
- Removed the remaining TypeScript import cycles reported by `madge`. Thanks @av1155 for issue #101.

## [2.12.1] - 2026-07-24

### Fixed
- Restored the SDK v1 dependency required by the MCP Apps bridge during Pi managed installs, where peer dependencies are intentionally not auto-installed. Thanks Nikolai Ugelvik (@NikolaiUgelvik), @warmwaffles, and @max-miller1204 for issue #212.

## [2.12.0] - 2026-07-24

### Added
- Added MCP prompts support as Pi slash commands under the `mcp__<server>__<prompt>` namespace, with capability-gated discovery, cache-backed startup registration, argument validation, lazy dispatch, and `/mcp prompts` listing. Thanks to Egor Egorov (@ee92) for PR #203.
- Hot-loaded refreshed direct MCP tools after metadata reconnects, lazy connects, direct-tool panel changes, and MCP list-change notifications. Thanks Devin Bost (@devinbost) for PR #72.
- Migrated the MCP client and interactive visualizer to the exact-pinned MCP SDK v2 beta.5 packages, with automatic protocol negotiation and client conformance coverage. Thanks Matt Carey (@mattzcarey) for PR #210.
- Added disabled MCP server definitions plus `/mcp disable` and `/mcp enable` project-local overrides that preserve visibility while preventing execution. Thanks Ömer Ulusoy (@ulusoyomer) for PR #61.
- Added argument completions for `/mcp` subcommands and reconnect/logout server names. Thanks @sting8k for PR #8.
- Surfaced MCP connection failure reasons from bounded stdio diagnostics in status output and the `/mcp` panel, with a shortcut to copy the selected failure. Thanks @parkuman for PR #197.
- Added Codex MCP imports from `.codex/config.toml`, with fallback to the existing JSON config. Thanks @npo-mmenke for PR #31.
- Added explicit OpenCode V1 MCP imports from global and project `opencode.json` files, including nested config merging and environment interpolation. See PR #25.
- Added environment-variable interpolation for HTTP MCP server URLs, with missing URL variables failing closed before requests are sent. Thanks @ozeias for PR #206.
- Added `settings.oauthDir` to store MCP OAuth credentials in a project-specific directory, with `MCP_OAUTH_DIR` still taking precedence. Thanks @Termina1 for PR #105.
- Added `lazy-keep-alive` lifecycle mode for MCP servers that should start on first use and then stay resident with health-check reconnects. Thanks @ricardoraposo for PR #143.
- Added `MCP_UI_VIEWER=none` / `off` / `disabled` to suppress MCP UI browser or Glimpse windows while keeping inline tool results available. Thanks @stevekrouse for PR #172.
- Surfaced MCP server `instructions` from the initialize handshake: captured at connect time, cached alongside tool metadata, shown as a truncated head in the `mcp` proxy tool description, previewed in `mcp({ server: "name" })` listings, and available in full via the new `mcp({ instructions: "name" })` mode. Thanks @JeongJuhyeon for issue #188 and PR #189.
- Added `createMcpAdapter({ config, configPath })` for isolated SDK configuration and file-path overrides. Thanks @Cansiny0320 for PR #86.

### Changed
- Removed stale hot-loaded direct tools from Pi's registry when `pi.unregisterTool()` is available, while preserving active-tool deactivation fallback for older Pi hosts.
- Deferred loading the regex safety checker until regex search is used, improving startup time. Thanks @kaushikgopal for PR #175.
- Declared Pi host packages as optional peer dependencies with exact development pins, reducing extension install footprint and avoiding host version conflicts. Thanks @t0dorakis for PR #200.

### Fixed
- Started MCP initialization at extension load when any server is configured with `lifecycle: "eager"` or `"keep-alive"`, so hosts that drive Pi programmatically without `session_start` still connect startup servers. Thanks Brian Gebel (@ductiletoaster) for PR #170.
- Enforced normalized standard `_meta.ui.csp` and OpenAI-compatible `_meta["openai/widgetCSP"]` metadata with response headers while preserving provider HTML. Thanks @IdoHadar for PR #195.
- Avoided MCP renderer crashes without a TUI theme and preserved status-bar updates with plain fallback text. Thanks @fankangsong for PR #183.
- Abandoned MCP initialization quietly when a session is disposed during eager or keep-alive connection setup. Thanks @luisfontes for PR #192.
- Fenced MCP runtime ownership across Pi reloads so stale callbacks and late connections cannot outlive their session. Thanks @uuunk (Paul Lorsbach) for PR #202.
- Added `toolPrefix: "mcp"` support for `mcp__<server>_<tool>` names across direct and proxy MCP tool paths. Thanks @riicodespretty for PR #99.
- Sanitized dotted MCP tool names before registering them with Pi. Thanks @benjaminrickels for PR #190.
- Reconnected OAuth MCP servers automatically after successful panel or `/mcp-auth` authorization, and made panel reconnect force a fresh connection like `/mcp reconnect`. Thanks @mightymatth for issue #171.
- Recovered stale Streamable HTTP MCP sessions that report `-32000 Server not initialized` after a server restart. Thanks @vicary for issue #184.
- Kept npm cache lookups working on Windows by resolving `npm` through `cross-spawn`. Thanks @zeyadhost for PR #201.
- Kept direct MCP tool registration working when a host TypeBox shim does not expose `Type.Unsafe`. Thanks @RaviTharuma for PR #198.
- Kept exact `npx` package specs from reusing a different same-name package version from npm's `_npx` cache. Thanks @danhrahal for issue #178.
- Kept POST-only Streamable HTTP servers on the Streamable HTTP transport when the optional GET stream returns 405. Thanks @ramhaidar for issue #204.
- Kept manual OAuth `auth-start` / `auth-complete` flows from being invalidated by keep-alive health checks, and made reserved manual callback states show a manual completion page instead of a CSRF error. Thanks @oozle for issue #207.
- Accepted object-valued `mcp.args` in addition to JSON strings, avoiding double-encoded tool arguments while preserving provider-compatible string calls. Thanks @johnny-smitherson for issue #205.
- Collapsed long single-line MCP results according to terminal-wrapped visual lines. Thanks @xz-dev for PR #181 and @maxpaulus43 for PR #177.
- Recovered Streamable HTTP MCP sessions after a server restart invalidates the previous session ID. Thanks @damselem for PR #194.
- Used server-advertised OAuth protected-resource metadata during authorization so resource servers can point Pi at the correct authorization server. Thanks @jameswarren for issue #173 and PR #174.
- Dropped inherited HTTP auth when a higher-precedence MCP config repoints a server URL, while preserving explicit OAuth disable flags. Thanks @ductiletoaster for PR #182.

## [2.11.0] - 2026-07-03

### Changed
- Restored the tracked npm lockfile for reproducible installs and downstream packaging. Thanks @fmoda3 for issue #71.

### Added
- Added default-on MCP output guarding with temp-file spillover for oversized text results, compact summaries for large proxy result details, and `settings.outputGuard` tuning. Thanks @tmustier for PR #160.

### Fixed
- Defaulted stdio MCP servers without an explicit `cwd` to the Pi session cwd so relative server output lands in the workspace. Thanks @TimoFreiberg for PR #152.
- Kept multiline/control MCP panel metadata from corrupting rows and made Keep & Close save dirty changes. Thanks @gpmarques for issue/PR #14, @Vahor for issue #115, and @markokocic for issue #134/PR #135.
- Preserved `--` separators when resolving `npx` wrapper commands so subcommand flags are not consumed by tools like `dotenv-cli`. Thanks @sherif-fanous for issue #15.
- Merged partial per-server Pi overrides into imported MCP server definitions instead of replacing the full server entry. Thanks @cfbraun for issue #94.
- Fixed the `pi-mcp-adapter` bin entrypoint when invoked through installed symlinks, so `init` runs instead of silently exiting. Thanks @cfbraun for issue #95.
- Normalized direct MCP tool schemas so draft metadata and strict top-level additional properties do not break Pi registration. Thanks @marchellodev for issue #2/PR #3 and @comtihon for PR #144.
- Routed interactive `/mcp-auth` OAuth URLs through Pi UI notifications so long authorization links remain intact instead of being truncated by raw terminal output. Thanks @feoh for issue #147/PR #148.
- Respected configured HTTP headers before implicit OAuth auto-detection so API-key/custom-header MCP servers do not trigger OAuth DCR. Thanks @OnlyXianzo for issue #158.
- Propagated Pi abort signals into MCP connect, resource, and tool requests so cancelled calls settle promptly. Thanks @xz-dev for PR #159 and @murrayju for PR #149.
- Re-flagged failed MCP tool calls (`tool_error`/`call_failed`) as errors so they are recorded as failures (`isError: true`) instead of successes. Thanks @ishinder for PR #157.
- Honored configured `requestTimeoutMs` during MCP connection, discovery, tool, resource, and UI proxy requests. Thanks @mizuikki for PR #155 and @danecando for PR #62.
- Rendered successful MCP `structuredContent` when servers return it without `content`. Thanks @dovixman for PR #146.

## [2.10.0] - 2026-06-13

### Added
- Added manual remote/headless OAuth proxy actions for copying authorization URLs and completing pasted redirect URLs or codes. Thanks @Gabrielgvl for PR #120.

### Fixed
- Honored user `tui.select.*` keybindings in MCP management, setup, and auth panels. Thanks @owenniles for PR #138.
- Included configured OAuth scopes in authorization-code flows while preserving token endpoint authentication method selection. Thanks @carlosdagos for PR #140.
- Fixed MCP elicitation on stock Pi, including form dialogs with validation and review, consent-based URL handling, URL-required errors, completion notifications, and TUI-only browser navigation. Thanks @dmmulroy for PR #139.
- Expanded MCP schema formatting for nested `anyOf`/`oneOf` variants, `const` discriminators, nested object properties, and array items.

## [2.9.0] - 2026-06-04

### Added
- Added MCP elicitation support with Pi form prompts and browser-opening URL requests.

### Fixed
- Rejected non-http/https MCP URL elicitations before prompting or opening a browser.
- Preserved empty string form values for MCP string elicitations unless schema constraints reject them.

## [2.8.0] - 2026-05-25

### Added
- Added per-server OAuth `redirectUri`, `clientName`, and `clientUri` overrides for pre-registered callbacks and dynamic client metadata.

### Fixed
- Avoided OAuth callback port exhaustion by starting the callback server lazily and using OS-assigned ports for dynamic OAuth flows.
- Re-register dynamic OAuth clients before browser auth when cached redirect URI metadata is missing or no longer matches the active callback URI.

## [2.7.0] - 2026-05-22

### Added
- Added TUI call rendering for MCP proxy and direct tool inputs. Thanks @dmmulroy for PR #102.

### Fixed
- Hardened OAuth credential storage paths against server-name path traversal without rejecting valid configured server names.
- Rejected unsafe regex-mode MCP search patterns before executing them.

## [2.6.1] - 2026-05-13

### Added
- Added `/mcp logout <server>` to clear stored OAuth credentials and disconnect the server. Thanks @mattzcarey for PR #96.

### Fixed
- Cancel pending OAuth callbacks when logging out of an MCP server.

## [2.6.0] - 2026-05-10

### Added
- Added a no-argument `/mcp-auth` OAuth picker and in-panel auth shortcut for OAuth-capable MCP servers.
- Added compact collapsed rendering for MCP proxy and direct-tool result rows while keeping full tool results available when expanded.

### Changed
- Migrated Pi runtime dependencies and imports from deprecated `@mariozechner/*` packages to `@earendil-works/*` packages.

### Fixed
- Re-register dynamic OAuth clients during fresh auth when cached DCR client info exists without tokens, avoiding dead authorization URLs after server-side client invalidation.
- Kept OAuth tokens, dynamic client info, PKCE verifiers, and OAuth state bound to the server URL so stale credentials cannot be reused after a server URL changes.
- Kept the `/mcp-auth` OAuth picker search focused on OAuth server rows and prevented hidden panel shortcuts from unexpectedly launching auth.
- Kept long MCP error results expanded in compact tool result rendering.

## [2.5.4] - 2026-05-04

### Changed
- Ignored npm lockfiles and removed checked-in `package-lock.json` files.

### Fixed
- Resolved `${VAR}` and `$env:VAR` placeholders in HTTP bearer tokens.
- Honored MCP sampling `modelPreferences.hints` before falling back to the current/default model.

## [2.5.3] - 2026-05-01

### Added
- Added environment variable and `~` expansion for stdio server `cwd` values.

## [2.5.2] - 2026-04-29

### Fixed
- Respected `PI_CODING_AGENT_DIR` for Pi-owned MCP config and state files, including metadata cache, npx cache, onboarding state, OAuth credentials, and `pi-mcp-adapter init` writes.

## [2.5.1] - 2026-04-24

### Fixed
- Changed OAuth browser callbacks to `http://localhost:<port>/callback` for pre-registered clients such as Slack MCP. Thanks @shenal for PR #53.

## [2.5.0] - 2026-04-24

### Added
- Added MCP `sampling/createMessage` support with conservative human approval by default and opt-in `settings.samplingAutoApprove` for non-interactive flows.
- Added configured Vitest coverage for OAuth provider authorization fallback behavior.
- Added `test:oauth-provider` for running the root OAuth provider node test with the required TypeScript loader.

### Fixed
- Applied `settings.authRequiredMessage` to proxy and direct-tool auth-required paths, including non-UI `autoAuth` failures.
- Fixed `/mcp-auth <server>` reporting success for expired stored OAuth tokens without forcing the SDK refresh/re-auth flow.
- Kept `mcp` search focused on MCP tools and added a direct-call hint when native Pi tools are accidentally routed through the proxy.

## [2.4.2] - 2026-04-22

### Fixed
- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x so packaged installs follow Pi's current extension runtime contract.

### Changed
- Replaced the legacy `@sinclair/typebox` runtime dependency with `typebox`.

## [2.4.1] - 2026-04-22

### Added
- Added standard-MCP-first config discovery: `~/.config/mcp/mcp.json` and project `.mcp.json` now load automatically, with Pi-owned files preserved as override layers.
- Added `pi-mcp-adapter init` as a native post-install helper that detects host-specific MCP configs and scaffolds Pi compatibility imports without using the old raw GitHub downloader flow.
- Added first-run onboarding inside the extension: `/mcp` now shows shared-config hints or actionable empty states, and `/mcp setup` opens a guided setup flow for compatibility imports, minimal `.mcp.json` scaffolding, detected config paths, RepoPrompt quick-add, and exact before/after write previews.
- Added automatic Pi-core reload after setup or direct-tool config changes, using the same flow as `/reload` so freshly configured direct tools can appear without a manual restart.
- Added a dedicated Pi-owned onboarding state file so shared-config hints behave as one-time guidance instead of repeating every session.

### Changed
- Updated config precedence to prefer shared MCP files first, then Pi overrides, with `.pi/mcp.json` acting as the final Pi-specific project override.
- Updated Claude Code compatibility probing to prefer modern Claude MCP config locations before legacy paths.
- Updated project scaffolding so generated `.mcp.json` files are safe minimal shells instead of fake placeholder servers that fail on first reload.
- Updated the setup panel and README for clearer first-run guidance, improved spacing, and a more digestible shared-MCP-first setup story.

## [2.4.0] - 2026-04-13

### Added
- `settings.disableProxyTool` to hide the `mcp` proxy tool once configured direct tools are fully available from cache. Thanks @tanavamsikrishna for PR #41.
- Per-server `excludeTools` to hide specific MCP tools/resources by original or prefixed name across direct tools, proxy discovery, and the `/mcp` panel. Thanks @ahmadaccino for issue #36.
- `settings.autoAuth` to optionally trigger OAuth automatically from proxy/direct tool usage, then rerun the original blocked connect/tool operation once after authentication succeeds. Thanks @unimonkiez for issue #34.

### Fixed
- Regenerated `package-lock.json` so the root lockfile metadata matches `package.json` again, including the declared `open`, `@types/bun`, `@types/open`, and `tsx` entries.
- Kept the `mcp` proxy tool available as a first-session fallback when configured direct tools are still missing cache metadata, avoiding no-tool startup gaps.

## [2.3.5] - 2026-04-13

### Fixed
- Session lifecycle now always tears down OAuth callback state on restart and shutdown, preventing callback-server leaks across session transitions.
- OAuth callback server now calls `unref()` after successful bind so it no longer keeps sub-agent processes alive by itself.
- Strict OAuth port mode now rebinds to the configured callback port when safe, while refusing to switch ports when authorizations are still pending.
- Added focused lifecycle/callback-server regression coverage for teardown, `unref()`, strict rebinding, and pending-auth guardrails.
- Thanks @blai for the investigation and PR #43 that surfaced the sub-agent hang/root lifecycle issues.

## [2.3.4] - 2026-04-12

### Fixed
- OAuth callback handling now allows dynamic-registration flows to fall back to a free local port when the preferred callback port is busy, while keeping pre-registered clients on their exact configured redirect port.
- Documented the new callback-port behavior and added focused auth-flow regression coverage.

## [2.3.3] - 2026-04-12

### Fixed
- Remove the blank footer status line when no MCP servers are configured by clearing the MCP status entry instead of setting it to an empty string. Thanks @HazAT for PR #27.

## [2.3.2] - 2026-04-11

### Added
- Optional `oauth.grantType: "client_credentials"` for non-interactive machine-to-machine OAuth on HTTP MCP servers.

### Fixed
- `/mcp-auth <server>` now handles `client_credentials` without browser/callback flow.
- MCP panel status no longer marks `client_credentials` servers as auth-blocked solely because no stored user tokens exist yet.
- OAuth auth flow now closes temporary transports consistently on success, refresh, and auth removal paths.
- Init paths now preserve debug-level context for previously silent direct-tool bootstrap and lazy-connect failures.

## [2.3.1] - 2026-04-11

### Fixed
- Removed `/mcp-auth-callback`. OAuth auth now hard-cuts to `/mcp-auth <server>` only.

## [2.3.0] - 2026-04-11

### Added
- OAuth callback server initialization on session start and a deprecated `/mcp-auth-callback` command that now points users to `/mcp-auth <server>`.

### Fixed
- OAuth `needs-auth` handling across `/mcp` status/panel, `mcp({ connect })`, `mcp({ tool })`, reconnect flow, lazy/direct tool execution, and startup bootstrap.
- OAuth callback cleanup now cancels by stored OAuth state and closes pending transports on failure/cancel paths.
- Callback server now fails fast when the OAuth callback port is occupied by another process.
- Package manifest test now ignores root `*.test.ts` files.

## [2.2.2] - 2026-04-03

### Fixed
- Session lifecycle teardown now handles repeated `session_start` transitions safely and prevents stale async init results from replacing newer state.
- Shutdown now still runs `gracefulShutdown()` even if metadata cache flushing throws, avoiding leaked MCP processes.
- Proxy/direct tool init error paths now preserve and surface underlying error messages instead of returning generic failures.
- Invalid `mcp` tool `args` now fail by throwing with parse/type context instead of returning non-failing tool payloads.
- Added focused lifecycle regressions tests for stale init cleanup and init-error visibility.

## [2.2.1] - 2026-03-23

### Fixed
- Added `promptSnippet` to MCP proxy tool and direct MCP tools so they appear in the system prompt's Available tools section (required since pi 0.59.0)

## [2.2.0] - 2026-03-16

### Added
- **MCP UI Integration** - Support for the [MCP UI](https://github.com/MCP-UI-Org/mcp-ui) standard. Tools with `_meta.ui.resourceUri` open interactive UIs:
  - Bidirectional AppBridge communication (tool calls, messages, context updates)
  - Works with both stdio and HTTP MCP servers
  - User consent management for tool calls from UI (configurable: never/once-per-server/always)
  - Keyboard shortcuts: Cmd/Ctrl+Enter to complete, Escape to cancel
  - UI prompts/intents trigger agent turns via `pi.sendMessage({ triggerTurn: true })`
  - `mcp({ action: "ui-messages" })` retrieves accumulated messages from UI sessions

- **Session reuse** - When the agent calls the same tool while its UI is already open, results push to the existing window instead of replacing it. Per-call stream IDs with independent sequences. Error results scoped to the individual call.

- **Glimpse integration** - MCP UI opens in a native macOS WKWebView window instead of a browser tab when [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`). Falls back to browser on non-macOS or when unavailable. Override with `MCP_UI_VIEWER=browser` or `MCP_UI_VIEWER=glimpse`.

- **Logger module** (`logger.ts`) - Centralized logging with levels (debug/info/warn/error), contextual child loggers, and `MCP_UI_DEBUG=1` env var.

- **Error types** (`errors.ts`) - Structured errors with recovery hints: `ResourceFetchError`, `ResourceParseError`, `BridgeConnectionError`, `ConsentError`, `SessionError`, `ServerError`, and `wrapError()` helper.

- **Test suite** - 178 tests covering consent manager, UI resource handler, host HTML template, logger, and error types.

- **Interactive visualizer example** (`examples/interactive-visualizer`) - Minimal MCP server demonstrating charts (bar/line/pie/doughnut via Chart.js), bidirectional messaging, and streaming.

### Fixed
- Host-iframe timing: bridge now connects before loading iframe, fixing `ui/initialize` timeout on first load
- All internal `log.info` calls demoted to `log.debug` to eliminate stdout noise during normal use

### Technical Notes
- Uses local minified AppBridge bundle (408KB) to avoid CDN Zod bundling issues
- Serves app HTML from `/ui-app` endpoint instead of blob URLs to avoid iframe issues
- SSE for real-time tool result streaming to browser

## [2.1.2] - 2026-02-03

### Changed
- Added demo video and `pi.video` field to package.json for pi package browser.

## [2.1.0] - 2026-02-02

### Added
- **Direct tool registration** - Promote specific MCP tools to first-class Pi tools via `directTools` config (per-server or global). Direct tools appear in the agent's tool list alongside builtins, so the LLM uses them without needing to search through the proxy first. Registers from cached metadata at startup — no server connections needed.
- **`/mcp` interactive panel** - New TUI overlay replacing the text-based status dump. Shows server connection status, tool lists with direct/proxy toggles, token cost estimates, inline reconnect, and auth notices. Changes written to config on save.
- **Auto-enriched proxy description** - The `mcp` proxy tool description now includes server names and tool counts from the metadata cache, so the LLM knows what's available without a search call (~30 extra tokens).
- **`MCP_DIRECT_TOOLS` env var** - Subagent processes receive their direct tool configuration via environment variable, keeping subagents lean by default.
- **First-run bootstrap** - Servers with `directTools` configured but no cache entry are connected during `session_start` to populate the cache. Direct tools become available after restart.
- Config provenance tracking for correct write-back to user/project/import sources
- Builtin name collision guard (skips direct tools that would shadow `read`, `write`, etc.)
- Cross-server name deduplication for `prefix: "none"` and `prefix: "short"` modes

## [2.0.1] - 2026-02-01

### Fixed
- Adapt execute signature to pi v0.51.0: add signal, onUpdate, ctx parameters

## [2.0.0] - 2026-01-29

### Changed
- **BREAKING: Lazy startup by default** - All servers now default to `lifecycle: "lazy"` and only connect when a tool call needs them. Previously all servers connected eagerly on session start. Set `lifecycle: "keep-alive"` or `lifecycle: "eager"` to restore the old behavior per-server.
- **Idle timeout** - Connected servers are automatically disconnected after 10 minutes of inactivity (configurable via `settings.idleTimeout` or per-server `idleTimeout`). Cached metadata keeps search/list working after disconnect. Set `idleTimeout: 0` to disable.
- `/mcp reconnect` accepts an optional server name to connect or reconnect a single server

### Added
- **Metadata cache** - Tool and resource metadata persisted to `~/.pi/agent/mcp-cache.json`. Enables search/list/describe without live connections. Per-server config hashing with 7-day staleness. Multi-session safe via read-merge-write with per-process tmp files.
- **npx binary resolution** - Resolves npx package binaries to direct paths, eliminating the ~143 MB npm parent process per server. Persistent cache at `~/.pi/agent/mcp-npx-cache.json` with 24h TTL.
- **`mcp({ connect: "server-name" })` mode** - Explicitly trigger connection and metadata refresh for a named server
- **Failure backoff** - Servers that fail to connect are skipped for 60 seconds to avoid repeated connection storms
- **In-flight tracking** - Active tool calls prevent idle timeout from shutting down a server mid-request
- **Prefix-match fallback** - Tool calls with unrecognized names try to match a server prefix and lazy-connect the matching server
- Lifecycle options: `lazy` (default), `eager` (connect at startup, no auto-reconnect), `keep-alive` (unchanged)
- Per-server `idleTimeout` override and global `settings.idleTimeout`
- First-run bootstrap: connects all servers on first session to populate the cache

### Fixed
- Connection close race condition: concurrent close + connect no longer orphans server processes
- **Fuzzy tool name matching** - Hyphens and underscores are treated as equivalent during tool lookup. MCP tools like `resolve-library-id` are now found when called as `resolve_library_id`, which LLMs naturally guess since the prefix separator is `_`.
- **Better "tool not found" errors** - When a server is identified (via prefix match or override) but the tool isn't found, the error now lists that server's available tools so the LLM can self-correct immediately instead of needing a separate list call

## [1.6.0] - 2026-01-29

### Added
- **Unified pi tool search** - `mcp({ search: "..." })` now searches both MCP tools and Pi tools (from installed extensions)
- Pi tools appear first in results with `[pi tool]` prefix
- Details object includes `server: "pi"` for pi tools
- Banner image for README

## [1.5.1] - 2026-01-26

### Changed
- Added `pi-package` keyword for npm discoverability (pi v0.50.0 package system)

## [1.5.0] - 2026-01-22

### Changed
- **BREAKING: `args` parameter is now a JSON string** - The `args` parameter which previously accepted an object now accepts a JSON string. This change was required for compatibility with Claude's Vertex AI API (`google-antigravity` provider) which rejects `patternProperties` in JSON schemas (generated by `Type.Record()`).

### Added
- **Type validation for args** - Parsed args are now validated to ensure they're a JSON object (not null, array, or primitive). Clear error messages for invalid input.
- **`isError: true` on error responses** - JSON parse errors and type validation errors now properly set `isError: true` to indicate failure to the LLM.

### Migration
```typescript
// Before (1.4.x)
mcp({ tool: "my_tool", args: { key: "value" } })

// After (1.5.0)
mcp({ tool: "my_tool", args: '{"key": "value"}' })
```

## [1.4.1] - 2026-01-19

### Changed

- Status bar shows server count instead of tool count ("MCP: 5 servers")

## [1.4.0] - 2026-01-19

### Changed

- **Non-blocking startup** - Pi starts immediately, MCP servers connect in background. First MCP call waits only if init isn't done yet.

### Fixed

- Tool metadata now includes `inputSchema` after `/mcp reconnect` (was missing, breaking describe and error hints)

## [1.3.0] - 2026-01-19

### Changed

- **Parallel server connections** - All MCP servers now connect in parallel on startup instead of sequentially, significantly faster with many servers

## [1.2.2] - 2026-01-19

### Fixed

- Installer now downloads from `main` branch (renamed from `master`)

## [1.2.1] - 2026-01-19

### Added

- **npx installer** - Run `npx pi-mcp-adapter` to install (downloads files, installs deps, configures settings.json)

## [1.1.0] - 2026-01-19

### Changed

- **Search includes schemas by default** - Search results now include parameter schemas, reducing tool calls needed (search + call instead of search + describe + call)
- **Space-separated search terms match as OR** - `"navigate screenshot"` finds tools matching either word (like most search engines)
- **Suppress server stderr by default** - MCP server logs no longer clutter terminal on startup
- Use `includeSchemas: false` for compact output without schemas
- Use `debug: true` per-server to show stderr when troubleshooting

## [1.0.0] - 2026-01-19

### Added

- **Single unified `mcp` tool** with token-efficient architecture (~200 tokens vs ~15,000 for individual tools)
- **Five operation modes:**
  - `mcp({})` - Show server status
  - `mcp({ server: "name" })` - List tools from a server
  - `mcp({ search: "query" })` - Search tools by name/description
  - `mcp({ describe: "tool_name" })` - Show tool details and parameter schema
  - `mcp({ tool: "name", args: {...} })` - Call a tool
- **Stdio transport** for local MCP servers (command + args)
- **HTTP transport** with automatic fallback (StreamableHTTP → SSE)
- **Config imports** from Cursor, Claude Code, Claude Desktop, VS Code, Windsurf, Codex
- **Resource tools** - MCP resources exposed as callable tools
- **OAuth support** - Token file-based authentication
- **Bearer token auth** - Static or environment variable tokens
- **Keep-alive connections** with automatic health checks and reconnection
- **Schema on-demand** - Parameter schemas shown in `describe` mode and error responses
- **Commands:**
  - `/mcp` or `/mcp status` - Show server status
  - `/mcp tools` - List all tools
  - `/mcp reconnect` - Force reconnect all servers
  - `/mcp-auth <server>` - Show OAuth setup instructions

### Architecture

- Tools stored in metadata map, not registered individually with Pi
- MCP server validates arguments (no client-side schema conversion)
- Reconnect callback updates metadata after auto-reconnect
- Human-readable schema formatting for LLM consumption