@fitchmultz/pi-mcp-adapter 7.1.1 → 8.0.1

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
@@ -62,7 +85,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
 
@@ -83,7 +106,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.
@@ -92,9 +115,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
 
@@ -161,7 +184,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
 
@@ -338,7 +361,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
 
@@ -389,7 +412,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

@@ -327,23 +327,23 @@ Persistent OAuth entries are stored in service `fitch-mcp-adapter.oauth`, with t
 
 The adapter fails closed when the OS credential store is unavailable. On headless Linux, configure an unlocked Secret Service-compatible keyring before using persistent OAuth; the adapter does not silently fall back to plaintext token files.
 
-The optional native working-session checkpoint barrier acknowledges completed refresh persistence only after owned SDK operations finish, including background GET/reconnect provider work and cancellation tails. Active browser flows (including captured callbacks awaiting `auth-complete`) and authentication operations keep sleep readiness false; PKCE/callback memory is not serialized. The server-challenge cache alone is reconstructible through normal re-challenge; granted scopes and issuer bindings persist in the native credential store. Per-server cancellation stays prompt, but final shutdown joins actual provider promises rather than just the cancelled public request. Hosts must preserve and unlock the actual private OS credential store on replacement compute, not merely copy the legacy import directory. The Linux binding may select a kernel keyring when Secret Service is unavailable, so successful credential access alone does not prove durable storage. Verify the persistent unlocked Secret Service collection before launching a durable Linux workspace. See [native working-session checkpoints](README.md#native-working-session-checkpoints) for the supported HTTP boundary.
+Final runtime shutdown joins owned SDK operations, including background GET/reconnect provider work and cancellation tails. Per-server cancellation stays prompt; closing the runtime waits for actual provider promises, not just the cancelled public request. Granted scopes and issuer bindings remain in the native OS credential store. Active browser flows and callback memory are not serialized, and no operation is replayed to recover them. Hosts must preserve and unlock the actual private credential store on replacement compute; a Linux kernel keyring alone does not prove persistent Secret Service storage.
 
 On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter makes one best-effort retry through `keyctl session - node <packaged helper>`. This lets explicit re-authentication write fresh credentials from a new session keyring without restarting a long-lived tmux or server process. The recovery path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 
 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