@fitchmultz/pi-mcp-adapter 8.0.0 → 8.0.2

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [8.0.2] - 2026-10-31
+
+### Changed
+
+- Link the READMEs to the exact runtime requirements and conformance referee details without pinning release versions in installation guidance.
+- Batch metadata-cache writes across connected servers at startup and shutdown, reducing repeated disk work while preserving on-demand updates.
+- Reuse search indexes after calls when live tool metadata is unchanged; rebuild them when descriptors change.
+- Load the native MCP client SDK on first connection instead of at startup; cached discovery remains available without it.
+- Index saved plain-text output once, then read only the requested page's sparse file window. Native UI history appends, including large events, index only the new text without rescanning the prefix. Keep exact UTF-16 totals, Unicode boundaries and private-directory checks; external edits and incomplete UTF-8 fall back to a fresh scan. The bounded in-memory index retains checkpoints, not output text.
+- Reuse unchanged metadata-cache snapshots and derived tool descriptors across session tool synchronization. Each session and branch still restores its own selections and validates configuration, trust, and server identity.
+- Load Zod and the command, panel, gateway, script and resource modules on first MCP use instead of at extension startup, so sessions that never use MCP skip them. Server initialization modules now load during session start, after cached tools and prompt commands register. Cached tool registration, schemas, commands and first-call behavior are unchanged. Internal types no longer load Zod; the published `./types` entry still exports the same values and types, including the Zod-backed UI stream schemas.
+- Update Zod to 4.6.7 in the adapter and interactive visualizer, and rebuild the bundled MCP Apps bridge with it. Zod 4.6.6 rejects arrays, sets and maps over their declared size limit before checking each element ([GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5)).
+
+### Fixed
+
+- Stop browser-host heartbeats when MCP App sessions complete, and tear down the app once on server or user completion.
+- Mark `mcp_search` schema alternatives as objects so providers requiring explicit object types accept them.
+- Bind cached plain-output page indexes to a SHA-256 digest of the actual file content, verified on every reuse, so a same-size in-place rewrite inside one filesystem timestamp grain can no longer serve stale checkpoints or UTF-16 totals. Verified native appends keep advancing the digest, preserving warm paging after appends; warm reads now cost one raw verification pass plus the sparse page window instead of the window alone.
+- Stream large `mcp_script` output to its spill file while the script runs instead of holding every emitted value in the Pi process, and pause the script worker while the host catches up. Previously, large finite output could exhaust the host heap and abort Pi. The returned preview, saved file, ordering and images are unchanged. Pi processes already running when the adapter updates keep returning `mcp_script` output; one that ran `mcp_script` before the update keeps the earlier in-memory handling until it restarts.
+- Prune recognized expired and future-dated metadata entries during cache saves while preserving configured servers, explicitly supplied entries, and unknown records. Keep fresh disk merges and atomic cache replacement.
+
+## [8.0.1] - 2026-10-13
+
+### 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.
+- 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
@@ -74,7 +103,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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](README.md#upgrading-from-v5).
+- 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
 
@@ -95,7 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **BREAKING:** Independently maintained package identity is now `@fitchmultz/pi-mcp-adapter`, with CLI `fitch-mcp-adapter` and repository `fitchmultz/pi-mcp-adapter`. Original Nico MIT attribution is retained.
+- **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.
@@ -104,9 +133,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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](README.md#upgrading-from-v4).
+- 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. Separate sign-ins are required for independent grants across distributions. Normal runtime never falls back to the old namespace after logout.
+- 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
 
@@ -173,7 +202,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Known issues
 
-- Pi 0.84.0's development dependency shrinkwrap still installs `undici` 8.9.0, affected by upstream 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.
+- 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
 
@@ -350,7 +379,7 @@ The ranked search scoring, did-you-mean suggestions, approval patterns, endpoint
 
 ### 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 pi-subagents issue #638 and issue #219.
+- 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
 
@@ -401,7 +430,7 @@ The ranked search scoring, did-you-mean suggestions, approval patterns, endpoint
 - 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. Thanks @NicoAvanzDev for PR #25.
+- 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.

package/LICENSE

@@ -1,5 +1,6 @@
 MIT License
 
+Copyright (c) 2026 Mitch Fultz
 Copyright (c) 2026 Nico Bailon
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/OAUTH.md

@@ -333,17 +333,17 @@ On Linux, if credential access fails because Pi inherited a revoked session keyr
 
 Normal runtime uses `<Pi agent dir>/fitch-mcp-adapter/mcp-oauth/sha256-<server-hash>/tokens.json` only for legacy plaintext imports. With `settings.oauthDir`, runtime uses a `fitch-mcp-adapter/` child of that directory, so a migrated v4 setting cannot consume or delete its old token files. Explicit migration reads the original directory. `FITCH_MCP_OAUTH_DIR` overrides the final runtime import path. A valid entry in these locations is imported on first read and its plaintext file removed. These directories do not change the OS credential namespace.
 
-Version 5 never automatically reads v4's `pi-mcp-adapter.oauth` service, old default `~/.pi/agent/mcp-oauth/` directory, or `MCP_OAUTH_DIR`. After installation and before restarting Pi, run `fitch-mcp-adapter migrate --dry-run`, then `fitch-mcp-adapter migrate` from each project with an old override. See [upgrade instructions](README.md#upgrading-from-v4).
+Version 5 never automatically reads v4's `pi-mcp-adapter.oauth` service, old default `~/.pi/agent/mcp-oauth/` directory, or `MCP_OAUTH_DIR`. After installation and before restarting Pi, run `fitch-mcp-adapter migrate --dry-run`, then `fitch-mcp-adapter migrate` from each project with an old override. See [upgrade instructions](docs/migration.md#upgrading-from-v4).
 
 Explicit migration copies configured HTTP servers' old OS entries or legacy token files into the new service only when no destination credential exists. It preserves URL/issuer bindings, client registration and tokens, verifies each copy, prints no plaintext secrets, and leaves all old sources untouched. Dry-run lists file actions without reading the keychain or writing. Existing destinations are never overwritten or merged; repeated migration skips them. The old `MCP_OAUTH_DIR` is honored only for this explicit migration.
 
-Logging out removes the new namespace's entry; normal runtime cannot restore it from the old namespace. Migration preserves the existing provider grant rather than creating a second grant. Using both distributions with independent provider grants requires separate sign-ins.
+Logging out removes the new namespace's entry; normal runtime cannot restore it from the old namespace. Migration preserves the existing provider grant rather than creating a second grant. Sign in again if you need a separate provider grant.
 
 The stored `serverUrl` field ensures credentials are invalidated if the server URL changes. Client and token issuer bindings also remain strict: a changed authorization-server issuer requires explicitly clearing credentials before authenticating again, including for CIMD. Normal authentication never silently changes stored-login or issuer bindings.
 
 ### Android / Termux
 
-Persistent OAuth is unsupported out of the box on Android/Termux: the published `@napi-rs/keyring` 1.3.0 package has no Android native binding. When native loading fails, authentication and credential status explain this limitation rather than suggesting that unlocking a Linux keyring will fix it. Use a supported platform with a working OS credential store for persistent OAuth; there is no plaintext fallback. Unauthenticated servers, header-token authentication, and stdio servers remain available. Public HTTP servers still defer credential-store access until an OAuth challenge.
+Persistent OAuth is unsupported out of the box on Android/Termux: the published `@napi-rs/keyring` 2.1.0 package has no Android native binding. When native loading fails, authentication and credential status explain this limitation rather than suggesting that unlocking a Linux keyring will fix it. Use a supported platform with a working OS credential store for persistent OAuth; there is no plaintext fallback. Unauthenticated servers, header-token authentication, and stdio servers remain available. Public HTTP servers still defer credential-store access until an OAuth challenge.
 
 ## Security Considerations