pi-mcp-adapter 2.37.0 → 2.38.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.38.0] - 2026-09-26
+
+### Highlights
+
+- Search-mode tools become full direct tools after a successful proxy call, without requiring a separate search first.
+- Runtime-registered keep-alive servers now publish their tools even when Pi starts with no enabled MCP servers.
+- Compact `mcpScript` results show which tools ran, how often they ran, and how many calls failed.
+- Stdio configurations support home-relative paths, and MCP UI windows can open in Orca.
+- OpenCode v2 imports, OAuth credential access, and Rust MCP schemas are more reliable.
+
+### Added
+
+- A successful `mcp({ tool })` call now activates a held `directTools: "search"` tool, so later calls use its full schema even if the model skipped search. Thanks to [@chiptoe-svg](https://github.com/chiptoe-svg) for [PR #670](https://github.com/nicobailon/pi-mcp-adapter/pull/670).
+- MCP stdio server commands, arguments, and working directories now support home-relative paths. Thanks to [@FRFlo](https://github.com/FRFlo) for [PR #655](https://github.com/nicobailon/pi-mcp-adapter/pull/655).
+- Set `MCP_UI_VIEWER=orca` to open MCP UI windows in Orca. Thanks to [@jaesimio](https://github.com/jaesimio) for [PR #654](https://github.com/nicobailon/pi-mcp-adapter/pull/654).
+
+### Fixed
+
+- Keep-alive servers registered at runtime now connect and publish their tools even when no configured servers are enabled at startup. Thanks to [@ahodges22](https://github.com/ahodges22) for [issue #671](https://github.com/nicobailon/pi-mcp-adapter/issues/671).
+- Valid `ancestorConfigRoots` entries that do not contain the current working directory are ignored without warnings. Invalid entries still warn. Thanks to [@TheEdgeOfRage](https://github.com/TheEdgeOfRage) for [issue #668](https://github.com/nicobailon/pi-mcp-adapter/issues/668) and [PR #669](https://github.com/nicobailon/pi-mcp-adapter/pull/669).
+- Collapsed `mcpScript` results now show the tools called, repeat counts, and a visible failure count instead of only the first output line. Unsafe or ambiguous tool names are quoted and escaped, and script code remains hidden. Thanks to [@sargismarkosyan](https://github.com/sargismarkosyan) for [PR #666](https://github.com/nicobailon/pi-mcp-adapter/pull/666).
+- Metadata refreshes no longer reactivate an `mcp` gateway tool removed by the host. On hosts without `unregisterTool`, the adapter can still hide the gateway when direct tools cover the server and restore it when needed. Thanks to [@xulongwu4](https://github.com/xulongwu4) for [PR #665](https://github.com/nicobailon/pi-mcp-adapter/pull/665).
+- `mcpScript` no longer asks models to load its intentionally hidden manual skill. Thanks to [@k03mad](https://github.com/k03mad) for [#659](https://github.com/nicobailon/pi-mcp-adapter/issues/659).
+- OAuth credential reads now reuse a healthy keyring Entry without retaining secret values, avoiding repeated native sessions while still observing external updates. Thanks to [@mmarabel](https://github.com/mmarabel) for [#657](https://github.com/nicobailon/pi-mcp-adapter/issues/657).
+- Suppressing MCP UI windows with `MCP_UI_VIEWER=none` / `off` / `disabled` no longer prints raw output into the TUI. Thanks to [@andreafspeziale](https://github.com/andreafspeziale) for [#656](https://github.com/nicobailon/pi-mcp-adapter/issues/656).
+- The published package now includes the OAuth guide linked from the README. Thanks to [@dajiaohuang](https://github.com/dajiaohuang) for [PR #653](https://github.com/nicobailon/pi-mcp-adapter/pull/653).
+- OpenCode v2 configs now import. Servers under `mcp.servers` are picked up, `disabled: true` servers are skipped, and the snake_case OAuth fields `client_id`, `client_secret`, and `auth_server_metadata_url` are mapped. OpenCode v1 configs keep working. Thanks to [@sleroq](https://github.com/sleroq) for [PR #650](https://github.com/nicobailon/pi-mcp-adapter/pull/650).
+- Tools from Rust MCP servers, such as DBX, no longer print Ajv `unknown format "uint64" ignored` warnings on every call. Number formats like `uint64`, `uint32`, `uint`, and `uint8` are now recognized, and `type`/`minimum` still validate the values. Thanks to [@nightlitten](https://github.com/nightlitten) for [#649](https://github.com/nicobailon/pi-mcp-adapter/issues/649).
+
 ## [2.37.0] - 2026-09-23
 
 ### Highlights

package/OAUTH.md

@@ -0,0 +1,369 @@
+# OAuth 2.1 Authentication for MCP
+
+This document describes the OAuth 2.1 + PKCE authentication implementation for the Pi MCP Adapter using the official MCP SDK.
+
+## Overview
+
+The Pi MCP Adapter uses the official MCP SDK's built-in OAuth implementation, which provides:
+
+- **Automatic OAuth endpoint discovery** (RFC 9728) - No manual configuration needed
+- **Dynamic Client Registration** (RFC 7591) - The default for URL-only servers when no pre-registered `clientId` is configured and the server supports registration
+- **Client ID Metadata Documents** (SEP-991) - An advanced opt-in that uses an operator-supplied public HTTPS metadata URL as `client_id` when the authorization server opts in
+- **Automatic callback handling** - Built-in HTTP server handles callbacks automatically
+- **Automatic token refresh** - SDK handles token refresh transparently
+
+## Features
+
+- **PKCE (S256)** - Mandatory code challenge method for OAuth 2.1
+- **Automatic Callback Server** - Local browser redirects automatically when available
+- **Manual Remote Flow** - Copy auth URLs and pasted redirect URLs/codes for headless SSH sessions
+- **Dynamic Client Registration** - Registers by default when no pre-registered client is configured and the server supports registration
+- **Client ID Metadata Documents** - Opts into a configured, operator-hosted URL-based client ID when the authorization server advertises support
+- **Auto-Discovery** - Discovers OAuth endpoints from server metadata
+- **Automatic Token Refresh** - SDK handles expired tokens automatically
+- **State Parameter Validation** - CSRF protection
+- **Secure Token Storage** - Persistent OAuth entries are stored in the operating system credential store
+
+## Configuration
+
+### Minimal Configuration (Recommended)
+
+For most MCP servers, you only need the URL:
+
+```json
+{
+  "mcpServers": {
+    "my-oauth-server": {
+      "url": "https://api.example.com/mcp"
+    }
+  }
+}
+```
+
+OAuth is automatically enabled for HTTP servers. The SDK will:
+- Auto-detect if the server requires OAuth
+- Discover OAuth endpoints from the server
+- Use Dynamic Client Registration when no pre-registered client is configured and the server supports it
+- Handle the entire OAuth flow including callback
+
+Pi does not configure or host a Client ID Metadata Document by default. URL-only configurations continue to use Dynamic Client Registration. CIMD is available only through the advanced, operator-supplied `oauth.clientMetadataUrl` option below.
+
+### Optional Configuration
+
+You can optionally provide a pre-registered client:
+
+```json
+{
+  "mcpServers": {
+    "my-oauth-server": {
+      "url": "https://api.example.com/mcp",
+      "auth": "oauth",
+      "oauth": {
+        "clientId": "your-client-id",
+        "clientSecret": "your-client-secret",
+        "scope": "read write",
+        "authorizationParams": { "access_type": "offline", "prompt": "consent" },
+        "redirectUri": "http://localhost:3118/callback"
+      }
+    }
+  }
+}
+```
+
+
+
+### Configuration Options
+
+- `url` - The MCP server URL (required)
+- `auth` - Set to `"oauth"` to force OAuth, `false` to disable, or omit to auto-detect
+- `oauth.grantType` - `"authorization_code"` (default, browser flow) or `"client_credentials"` (non-interactive)
+- `oauth.clientId` - Pre-registered client ID. Takes precedence over `oauth.clientMetadataUrl` when both are configured.
+- `oauth.clientSecret` - Client secret for confidential clients (optional). When `oauth.clientMetadataUrl` is also set, an explicit `oauth.clientId` is required; the explicit client takes precedence.
+- `oauth.clientMetadataUrl` - Advanced opt-in for an operator-supplied public HTTPS Client ID Metadata Document URL with a non-root path. The URL is used as `client_id` when the authorization server advertises `client_id_metadata_document_supported: true`; otherwise Dynamic Client Registration remains the fallback. The document must be publicly fetchable and match this client's metadata, especially `redirect_uris`. The adapter does not provide a default URL or host this document.
+- `oauth.scope` - Requested OAuth scopes (optional)
+- `oauth.authorizationParams` - Extra authorization URL parameters for provider-specific extensions, such as Google's `{ "access_type": "offline", "prompt": "consent" }`. Flow-owned parameters like `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden.
+- `oauth.redirectUri` - Browser callback URI to advertise and bind, such as `http://localhost:3118/callback`. Use `{port}` in a loopback URI when the provider permits an OS-assigned RFC 8252 port, for example `http://127.0.0.1:{port}/callback` (optional)
+- `oauth.clientName` - Client display name used for Dynamic Client Registration fallback (optional, defaults to `Pi Coding Agent`)
+- `oauth.clientUri` - Client homepage URI used for Dynamic Client Registration fallback (optional)
+- `oauth.authServerMetadataUrl` - HTTPS OAuth/OIDC authorization-server metadata document to use authoritatively when MCP protected-resource discovery is unavailable (optional; issuer validation remains enabled)
+- `oauth.skipIssuerMetadataValidation` - Set `true` only for a known-misconfigured authorization server whose metadata issuer cannot be fixed immediately. This weakens OAuth issuer validation.
+
+Dynamic fallback clients normally omit `oauth.redirectUri`; the adapter starts the callback server lazily on the default loopback host (`localhost`) and asks the OS for an available local port when auth begins. Use `oauth.redirectUri` when the provider requires a pre-registered callback, such as Slack MCP's Claude-compatible `http://localhost:3118/callback`. A loopback URI must use `http://` with `localhost`, `127.0.0.1`, or `[::1]`. It may contain an explicit port, which is bound exactly, or `{port}`, which is replaced with the OS-assigned port in the authorization and token requests.
+
+### Non-Interactive `client_credentials`
+
+For machine-to-machine OAuth, configure `grantType: "client_credentials"`.
+
+```json
+{
+  "mcpServers": {
+    "my-service": {
+      "url": "https://api.example.com/mcp",
+      "auth": "oauth",
+      "oauth": {
+        "grantType": "client_credentials",
+        "clientId": "service-client-id",
+        "clientSecret": "service-client-secret",
+        "scope": "read write"
+      }
+    }
+  }
+}
+```
+
+This flow does not open a browser or use callback handling. `oauth.redirectUri` is ignored for `client_credentials`; `oauth.clientName` and `oauth.clientUri` still apply to dynamic client registration metadata.
+
+## Usage
+
+### Step 1: Authenticate
+
+Run the `/mcp-auth` command with the server name:
+
+```
+/mcp-auth my-oauth-server
+```
+
+Manual `/mcp-auth` is the default flow. If you set `settings.autoAuth: true`, proxy/direct tool execution will trigger OAuth automatically when a server returns `needs-auth`, then retry the original operation once.
+
+This will:
+1. Start the callback server lazily on an OS-assigned local port, on an OS-assigned host-specific `{port}` callback, or on the exact `oauth.redirectUri` port for fixed callbacks
+2. Discover OAuth endpoints automatically
+3. Use Dynamic Client Registration by default, or the explicitly configured Client ID Metadata Document when supported
+4. Open your browser for authentication
+5. Wait for the automatic callback
+6. Complete the OAuth flow
+7. Store tokens securely
+
+### Remote/headless authentication
+
+When Pi runs over SSH or in a headless environment, use the proxy tool to retrieve the authorization URL instead of relying on OS browser launch:
+
+```
+mcp({ action: "auth-start", server: "my-oauth-server" })
+```
+
+Open the returned URL in your local browser. After approval, copy the full redirected localhost URL from the browser address bar (the page may fail to load locally) and complete the same pending auth flow:
+
+```
+mcp({
+  action: "auth-complete",
+  server: "my-oauth-server",
+  args: { redirectUrl: "http://localhost:19876/callback?code=...&state=..." }
+})
+```
+
+You can also pass only the `code` query parameter with `args: { code: "..." }`. JSON-string args remain supported. Redirect URL completion validates the saved OAuth state; raw code completion is available for providers that display a code directly.
+
+### Step 2: Use the Server
+
+Once authenticated, use the server normally:
+
+```
+mcp({ server: "my-oauth-server" })
+mcp({ tool: "my-tool", args: { key: "value" } })
+```
+
+The SDK automatically:
+- Adds the access token to requests
+- Refreshes expired tokens automatically
+- Re-authenticates if tokens are invalid
+
+To clear stored OAuth credentials and force a fresh authorization:
+
+```
+/mcp logout my-oauth-server
+```
+
+Within one Pi process, logout is a linearizable boundary: OAuth work that began
+before logout cannot recreate credentials after they are cleared, and new OAuth
+work is admitted after logout finishes. Explicit token updates made through the
+public API retain last-writer semantics. Separate Pi processes are intentionally
+not coordinated, so concurrent cross-process credential operations can still race.
+
+## How It Works
+
+### Authentication Flow
+
+```
+┌─────────┐     ┌──────────────┐     ┌─────────────────┐
+│   Pi    │────▶│  MCP Server  │────▶│  OAuth Server   │
+│         │     │              │     │                 │
+│ 1. Init │     │ 2. Discovery │     │ 3. Register     │
+│         │     │              │     │                 │
+│         │◀────│              │◀────│ 4. Auth URL     │
+│         │     │              │     │                 │
+│         │────▶│  Callback    │◀────│ 5. Browser      │
+│         │     │  Server      │     │    Redirect     │
+│         │     │              │     │                 │
+│         │◀────│              │◀────│ 6. Code         │
+│         │     │              │     │                 │
+│         │────▶│              │────▶│ 7. Exchange     │
+│         │     │              │     │                 │
+│         │◀────│              │◀────│ 8. Tokens       │
+└─────────┘     └──────────────┘     └─────────────────┘
+```
+
+### Auto-Discovery
+
+The SDK attempts to discover OAuth endpoints using:
+
+1. **RFC 9728 Metadata** - Fetches `/.well-known/oauth-protected-resource`
+2. **WWW-Authenticate Header** - Parses `resource_metadata` from 401 responses
+
+### Client ID Metadata Documents and Dynamic Registration
+
+CIMD is an advanced, explicit opt-in. Set `oauth.clientMetadataUrl` to a stable, operator-supplied public HTTPS URL that serves this client's OAuth metadata. When authorization-server discovery advertises `client_id_metadata_document_supported: true`, the adapter and SDK use that URL directly as `client_id` and skip Dynamic Client Registration. The URL must have a non-root path. An explicit `oauth.clientId` takes precedence. Combining `oauth.clientMetadataUrl` with `oauth.clientSecret` without an explicit `oauth.clientId` is rejected.
+
+The adapter does not provide a default URL or host the public document: operators must publish it and keep fields such as `redirect_uris`, `grant_types`, `response_types`, and `token_endpoint_auth_method` consistent with the configured flow. URL-only/default Pi configurations therefore continue to use Dynamic Client Registration. When the server does not advertise CIMD support, or no metadata URL is configured, the SDK uses Dynamic Client Registration if the server supports it:
+
+1. Discovers the registration endpoint from OAuth metadata
+2. Registers a new client with:
+   - `client_name`: configured `oauth.clientName` or "Pi Coding Agent"
+   - `client_uri`: configured `oauth.clientUri` or the adapter repository URL
+   - `redirect_uris`: `["http://localhost:<active-callback-port>/callback"]`, or the configured `oauth.redirectUri`
+   - `grant_types`: `["authorization_code", "refresh_token"]`
+3. Stores the registered client credentials and the redirect URIs returned by the authorization server
+
+When a fresh browser auth starts, cached dynamic fallback client info with tokens is re-registered if its stored redirect URIs are missing or do not include the current redirect URI. Token refresh does not perform this redirect check, so existing refresh-token grants keep working even after a callback setting changes.
+
+### Callback Server
+
+A Node.js HTTP server runs on a loopback callback endpoint and handles the active callback path:
+
+- Dynamic registration starts the callback server only when auth begins, binds the default host `localhost`, and asks the OS for an available local port
+- Pre-registered clients (`oauth.clientId`) without `oauth.redirectUri` require the exact configured callback port from `MCP_OAUTH_CALLBACK_PORT` or the default `19876` on `localhost`
+- `oauth.redirectUri` binds the exact loopback host and path. An explicit port is bound exactly; `{port}` asks the OS for a port and is replaced with that assigned value before the URI is advertised to the provider
+
+- Handles `code`, `state`, and `error` parameters
+- Displays success/error HTML pages
+- Validates state parameter for CSRF protection
+- Has a 5-minute timeout for pending authorizations
+
+## Token Storage
+
+Persistent OAuth entries are stored per configured server name in the operating system credential store, using macOS Keychain, Windows Credential Manager, or Linux Secret Service/libsecret through `@napi-rs/keyring`. The stored entry contains tokens, dynamic client information, legacy verifier/state fields when present, and the server URL binding.
+
+Windows Credential Manager cannot hold a typical large OAuth JSON blob in one value, so payloads over 1,000 UTF-16 code units are stored as a manifest plus chunks; the size-limited test store uses the same representation. macOS Keychain and Linux Secret Service keep each record in one item, including ordinary 8–10 KiB records; if an unusually large record exceeds the native store's actual limit, that store error is surfaced. This avoids separate prompts for digest-addressed Keychain chunks. On macOS and Linux, the first ordinary read of a previously chunked record validates and rewrites it as one item before cleaning up its old chunks. Windows and the size-limited test store retain the chunked representation. Status inspection reads the existing representation but does not compact it; existing secure-record and legacy-plaintext cleanup semantics still apply.
+
+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. Windows OpenSSH network logons may report `ERROR_NO_SUCH_LOGON_SESSION` (1312) because Credential Manager has no credential set for that logon.
+
+For Windows OpenSSH/headless use, `settings.oauthCredentialStore: "encrypted-file"` explicitly selects an AES-256-GCM file store. It requires `PI_MCP_ADAPTER_OAUTH_FILE_KEY` to contain canonical base64 for exactly 32 random bytes; generate one with `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"` and inject it through an external secret mechanism. Never place the key in config or beside the ciphertext. One authenticated, versioned envelope is stored per hashed server account at `<Pi agent directory>/mcp-oauth-encrypted/sha256-<server-hash>/credentials.json`. The server URL and secrets appear only inside ciphertext, and account-bound authenticated data prevents copying an envelope to another account.
+
+Encrypted-file writes use private directory/file modes where supported and same-directory atomic replacement. POSIX modes are checked on reads, but they do not establish a Windows ACL; encryption with the external key is the confidentiality boundary. This backend never falls back to the OS store, reads `oauthDir` / `MCP_OAUTH_DIR`, or imports legacy plaintext. Reauthenticate after opting in. Key loss or rotation makes existing envelopes unreadable; remove them and reauthenticate with the new key.
+
+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.
+
+Complete credential entries are held in memory for the lifetime of the Pi process on every supported credential-store platform. The MCP SDK reads the access token before every outbound request, so caching avoids a credential-store lookup on each tool call; on Linux this specifically avoids overloading the Secret Service daemon. The cache is filled on the first read for a server and covers both present and absent entries. Authenticating, refreshing, and logging out all update it immediately, so credential changes made through Pi take effect at once. Status-panel inspection deliberately bypasses it and still reads the store directly.
+
+A credential changed or deleted by another process while Pi is running is not observed immediately. The affected server picks it up after the first credential-backed authentication failure in that `needs-auth` episode: Pi discards the cached entry, and the following read reloads from the credential store. Restarting Pi also clears the cache. Set `PI_MCP_ADAPTER_DISABLE_AUTH_CACHE=1` to turn the cache off entirely and restore a credential-store read per request.
+
+Older versions stored plaintext entries at `~/.pi/agent/mcp-oauth/sha256-<server-hash>/tokens.json`, or under `settings.oauthDir` / `MCP_OAUTH_DIR`. With the default OS backend, the first read after upgrade imports a valid legacy entry and removes the plaintext `tokens.json`. The encrypted-file backend leaves legacy files untouched. These directories are legacy import locations, not persistent credential stores or isolation namespaces.
+
+The stored `serverUrl` field ensures credentials are invalidated if the server URL changes.
+
+## Security Considerations
+
+### PKCE
+
+All OAuth flows use PKCE with the S256 method, preventing authorization code interception attacks.
+
+### State Parameter
+
+A cryptographically secure random state parameter is generated for each flow and validated on callback.
+
+### Issuer Metadata Validation
+
+OAuth authorization-server metadata normally must echo the expected issuer. This protects against authorization-server mix-up. The adapter keeps this check on by default.
+
+For private servers with known-broken metadata, `oauth.skipIssuerMetadataValidation: true` forwards the SDK's issuer-validation opt-out for that server only. Use it only as a temporary workaround while the server metadata is fixed. Do not use it for public or untrusted servers.
+
+When an MCP server does not publish usable protected-resource metadata, configure `oauth.authServerMetadataUrl` with the HTTPS URL of its OAuth/OIDC authorization-server metadata document. That document is authoritative instead of MCP protected-resource discovery, and its issuer is still checked by default. Treat this as trusted configuration and point it only at a metadata endpoint you explicitly trust.
+
+### Credential Stores
+
+Persistent OAuth credentials are written to the OS credential store by default, or only to the encrypted file store when explicitly selected. Legacy plaintext files are read only for one-way migration to the default OS store and are removed after successful import. On Linux, revoked session-keyring errors can be retried once through a fresh `keyctl session` helper during explicit re-authentication.
+
+Credential entries reside in process memory for the lifetime of the Pi process rather than being re-read per request, and the process-memory copy is discarded on exit.
+
+### URL Validation
+
+Credentials are tied to a specific server URL. If the URL changes, the credentials are invalidated and re-authentication is required.
+
+## Troubleshooting
+
+### "No OAuth tokens found"
+
+Run `/mcp-auth <server>` to authenticate.
+
+### "Failed to discover OAuth endpoints"
+
+The SDK automatically discovers OAuth endpoints from the MCP server. If discovery fails, the server may require a pre-registered client ID:
+
+```json
+{
+  "mcpServers": {
+    "server": {
+      "url": "https://api.example.com/mcp",
+      "auth": "oauth",
+      "oauth": {
+        "clientId": "your-client-id",
+        "scope": "read"
+      }
+    }
+  }
+}
+```
+
+### "Dynamic client registration not supported"
+
+Some servers require pre-registered clients. Obtain a client ID from your OAuth provider and add it to the config.
+
+### Callback server already in use
+
+Dynamic fallback browser OAuth uses a lazy OS-assigned port on the default loopback host (`localhost`), so the configured default port being busy should not block fallback registration.
+
+For pre-registered OAuth clients (`oauth.clientId`), the callback redirect URI must match the provider registration policy. Set `oauth.redirectUri` to the full fixed callback, such as Slack MCP's Claude-compatible `http://localhost:3118/callback`, use a loopback `{port}` URI when the provider explicitly permits dynamic RFC 8252 ports, or free/set `MCP_OAUTH_CALLBACK_PORT` when you rely on the default `/callback` path without an explicit redirect URI.
+
+### Browser doesn't open
+
+If the browser fails to open (e.g., in SSH sessions), the authorization URL will be displayed. Copy it manually to your browser.
+
+## Architecture
+
+The OAuth implementation uses the following modules:
+
+- `mcp-auth.ts` - Auth storage and retrieval through the OS credential store, with one-way legacy `tokens.json` import
+- `mcp-oauth-provider.ts` - SDK OAuthClientProvider implementation
+- `mcp-callback-server.ts` - Node.js HTTP callback server
+- `mcp-auth-flow.ts` - High-level auth flow using SDK transport
+
+## SDK Integration
+
+The implementation uses the stable modular MCP client and OAuth APIs:
+
+```typescript
+import {
+  auth,
+  StreamableHTTPClientTransport,
+  UnauthorizedError,
+  type OAuthClientProvider,
+} from "@modelcontextprotocol/client"
+```
+
+The `McpOAuthProvider` class implements `OAuthClientProvider` and is passed to `StreamableHTTPClientTransport`:
+
+```typescript
+const transport = new StreamableHTTPClientTransport(url, {
+  authProvider: new McpOAuthProvider(serverName, serverUrl, config, callbacks),
+})
+```
+
+## References
+
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Authorization Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
+- [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11)
+- [PKCE (RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636)
+- [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)
+- [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591)
+- [OAuth Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728)

package/README.md

@@ -71,7 +71,7 @@ Precedence is (later entries win):
 5. `.mcp.json`
 6. `.pi/mcp.json`
 
-Ancestor discovery is off by default. To opt in, set `settings.ancestorConfigRoots` in a user-global config above, or in the explicitly selected `--mcp-config`/`configPath` file, for example `"ancestorConfigRoots": ["~/work/team"]`. Each root must be an explicit absolute path or `~/...`, resolve to an existing directory under `$HOME`, and contain the canonical cwd. If several roots match, only the nearest (deepest) is used. Project `.mcp.json` and `.pi/mcp.json` files cannot enable discovery or extend the boundary.
+Ancestor discovery is off by default. To opt in, set `settings.ancestorConfigRoots` in a user-global config above, or in the explicitly selected `--mcp-config`/`configPath` file, for example `"ancestorConfigRoots": ["~/work/team"]`. Each root must be an explicit absolute path or `~/...` and resolve to an existing directory under `$HOME`. Roots that do not contain the canonical cwd are ignored. If several roots match, only the nearest (deepest) is used. Project `.mcp.json` and `.pi/mcp.json` files cannot enable discovery or extend the boundary.
 
 Within the selected root, existing `.mcp.json` and `<configDir>/mcp.json` (normally `.pi/mcp.json`) files load between steps 4 and 5, from the root through parent(cwd), farthest first. Nearer directories override farther ones, Pi overrides shared config within each directory, and cwd files win over ancestors. Search never goes above the configured root or `$HOME`; the boundary limits discovery but is not a file-ownership or symlink-target sandbox. Only configure roots whose project files you trust. `/mcp setup` write targets and project-local `/mcp disable` and `/mcp enable` overrides are unchanged.
 
@@ -113,6 +113,13 @@ Use the shared MCP files when you want one setup to work across hosts, and Pi-ow
 | `<Pi agent dir>/mcp.json` | Pi global override and compatibility imports (`~/.pi/agent/mcp.json` by default) |
 | `.pi/mcp.json` | Pi project override |
 
+For local stdio servers, a leading `~/` is expanded to the current user's home
+directory in `command`, `args`, and `cwd`. On Windows, the equivalent `~\\`
+form is supported too; on POSIX, backslashes remain literal filename
+characters. Bare commands such as
+`node`, `bunx`, or `git` continue to resolve through `PATH`.
+Built-in Agent Plugin arguments remain literal; this path expansion applies to native and shared MCP configuration.
+
 Pi-specific files are the write targets for imported or shared global servers when Pi needs to persist adapter-only settings such as `directTools`.
 
 ### Agent Plugins
@@ -508,7 +515,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `collapsedResultLines` | Number of result text lines to show before expansion: `1`, `2`, or `3`. Defaults to `1` in compact mode and `3` in boxed mode. |
 | `notifyOnStartupConnect` | Show successful startup connection notices (default: `true`). Set to `false` to suppress routine `MCP: N servers connected (M tools)` notices. Connection errors and authentication warnings remain visible. |
 | `hostConfigDiscovery` | Host-specific config policy: `"off"` (default), `"prompt"` (detect/report only), or `"on"` (explicitly load detected host configs as the lowest-precedence fallback) |
-| `ancestorConfigRoots` | Trusted absolute or `~/...` roots for opt-in ancestor config discovery. Only user-global or explicitly selected config may set it; the deepest root containing cwd is used. |
+| `ancestorConfigRoots` | Trusted absolute or `~/...` roots for opt-in ancestor config discovery. Only user-global or explicitly selected config may set it; roots outside cwd are ignored and the deepest matching root is used. |
 | `agentPluginPaths` | Agent Plugins package directories to load MCP servers from. Relative paths resolve from the active project cwd. |
 | `approveTools` | `true` to require approval before every MCP tool call, or an array of glob patterns such as `["github_delete_*", "notion_update_*"]`. Per-server `approveTools` overrides this. |
 | `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
@@ -523,7 +530,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `scriptMode` | Register the MCP-only `mcpScript` plain-JavaScript tool (default: true). Set to `false` to hide it. |
 | `exposeResources` | Expose MCP resources as tools (default: `true`). Set to `false` to disable globally across all servers. Per-server `exposeResources` overrides this. |
 | `jev` | Optional System One Jev settings. A valid System One key enables semantic search across every enabled MCP server by default; `semanticSearch: false` disables it. `scriptEvaluation` remains disabled by default and requires an `allowedServers` source allowlist when enabled. `jev: false` disables both. Run `/mcp jev setup` for guided configuration. |
-| `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. Ignored while any server uses `directTools: "search"`, whose tools are registered inactive and can only be activated through `mcp({ search })`. |
+| `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. Ignored while any server uses `directTools: "search"`, whose tools are registered inactive and can only be activated through the gateway (`mcp({ search })` or a successful `mcp({ tool })` call). |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 | `sampling` | Allow MCP servers to sample through Pi models, honoring `modelPreferences.hints` before current/default fallback (default: true when UI approval is available). |
 | `samplingAutoApprove` | Skip sampling confirmation prompts. Required for sampling in non-UI sessions (default: false). |
@@ -784,7 +791,7 @@ Per-server `directTools` overrides the global setting. The example above registe
 }
 ```
 
-A successful `mcp({ search })` activates matching search-mode tools additively for the process lifetime and reports newly activated names in `addedToolNames`; no other operation activates them. A restart or resumed session starts with them inactive again. Selecting `directTools: true` activates held tools, while switching back to `"search"` holds them again. Search-mode tools do not count toward the 75-tool advisory.
+A successful `mcp({ search })` activates matching search-mode tools additively for the rest of the session and reports newly activated names in `addedToolNames`. A successful `mcp({ tool })` call for a held search-mode tool activates it the same way, so the next call uses its real schema; a failed call (lookup, approval, or tool error) activates nothing. A restart or resumed session starts with them inactive again. Selecting `directTools: true` activates held tools, while switching back to `"search"` holds them again. Search-mode tools do not count toward the 75-tool advisory.
 
 To expose only a subset of a noisy server, add `includeTools` on the server. Values can be exact original names, generated resource names such as `read_<resource>`, prefixed names, or simple glob patterns:
 
@@ -847,7 +854,7 @@ MCP servers can ship interactive UIs via the [MCP UI](https://github.com/MCP-UI-
 3. pi-mcp-adapter fetches the UI HTML and opens it in an iframe
 4. The UI can call MCP tools and send messages back to the agent
 
-**Native rendering:** On macOS, if [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`), UIs open in a native WKWebView window instead of a browser tab. Set `MCP_UI_VIEWER=browser` to force the browser, `MCP_UI_VIEWER=glimpse` to require native rendering, or `MCP_UI_VIEWER=none` (also accepts `off` / `disabled`) to suppress the window entirely — the tool still runs and its inline result is returned to the agent, but no browser or native window opens. This is useful for headless setups, CI, or users who want the tool output delivered inline as text only. When suppressed, a one-line info notification shows the UI URL so it can still be opened manually if needed.
+**Native rendering:** On macOS, if [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`), UIs open in a native WKWebView window instead of a browser tab. Set `MCP_UI_VIEWER=browser` to force the browser, `MCP_UI_VIEWER=glimpse` to require native rendering, `MCP_UI_VIEWER=orca` to open in the [Orca](https://github.com/orca) built-in browser (falls back to the system browser if Orca is unavailable), or `MCP_UI_VIEWER=none` (also accepts `off` / `disabled`) to suppress the window entirely — the tool still runs and its inline result is returned to the agent, but no browser or native window opens. This is useful for headless setups, CI, or users who want the tool output delivered inline as text only. When suppressed, a one-line info notification shows the UI URL so it can still be opened manually if needed.
 
 **Bidirectional communication:** The UI talks back. When it sends a prompt or intent, the message is stored and `triggerTurn()` wakes the agent. The agent retrieves messages via `mcp({ action: "ui-messages" })` and responds, enabling conversational UIs where the app and agent collaborate in real-time.
 

package/config.ts

@@ -621,10 +621,10 @@ function getConfiguredAncestorRoot(globalSources: ConfigSourceSpec[], cwd: strin
     }
     try {
       const root = realpathSync(expanded);
-      if (!statSync(root).isDirectory() || !isWithin(home, root) || !isWithin(root, canonicalCwd)) throw new Error();
-      valid.push(root);
+      if (!statSync(root).isDirectory() || !isWithin(home, root)) throw new Error();
+      if (isWithin(root, canonicalCwd)) valid.push(root);
     } catch {
-      console.warn(`Invalid settings.ancestorConfigRoots entry ${JSON.stringify(entry)}: expected an existing directory under HOME containing cwd`);
+      console.warn(`Invalid settings.ancestorConfigRoots entry ${JSON.stringify(entry)}: expected an existing directory under HOME`);
     }
   }
   return valid.sort((left, right) => right.length - left.length)[0];
@@ -806,7 +806,27 @@ function loadImportedConfig(
       try {
         const value = readImportedConfig(path);
         if (value && typeof value === "object" && !Array.isArray(value)) {
-          merged = mergeOpenCodeConfigs(merged, value as Record<string, unknown>);
+          const imported = value as Record<string, unknown>;
+          const mcp = isRecord(imported.mcp) ? imported.mcp : {};
+          // OpenCode v2 nests definitions under mcp.servers; normalize before
+          // merging so project overrides retain the existing merge semantics.
+          const entries = isRecord(mcp.servers)
+            ? { ...Object.fromEntries(Object.entries(mcp).filter(([name]) => name !== "servers" && name !== "timeout")), ...mcp.servers }
+            : mcp;
+          const normalized = Object.fromEntries(Object.entries(entries).map(([name, entry]) => {
+            if (!isRecord(entry) || !isRecord(entry.oauth)) return [name, entry];
+            const { client_id, client_secret, auth_server_metadata_url, ...oauth } = entry.oauth;
+            return [name, {
+              ...entry,
+              oauth: {
+                ...oauth,
+                ...(client_id !== undefined ? { clientId: client_id } : {}),
+                ...(client_secret !== undefined ? { clientSecret: client_secret } : {}),
+                ...(auth_server_metadata_url !== undefined ? { authServerMetadataUrl: auth_server_metadata_url } : {}),
+              },
+            }];
+          }));
+          merged = mergeOpenCodeConfigs(merged, { ...imported, mcp: normalized });
           highestPrecedencePath = path;
         }
       } catch (error) {
@@ -1006,7 +1026,7 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
     if (kind === "opencode") {
       if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
       const raw = entry as Record<string, unknown>;
-      if (raw.enabled === false) continue;
+      if (raw.enabled === false || raw.disabled === true) continue;
 
       if (raw.type === "local" && Array.isArray(raw.command) && raw.command.length > 0 && raw.command.every((value): value is string => typeof value === "string")) {
         const env = toStringRecord(raw.environment);
@@ -1033,12 +1053,15 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
         } else if (raw.oauth && typeof raw.oauth === "object" && !Array.isArray(raw.oauth)) {
           const oauth = raw.oauth as Record<string, unknown>;
           mapped.auth = "oauth";
+          const clientId = oauth.clientId;
+          const clientSecret = oauth.clientSecret;
+          const authServerMetadataUrl = oauth.authServerMetadataUrl;
           mapped.oauth = {
-            ...(typeof oauth.clientId === "string" ? { clientId: oauth.clientId } : {}),
-            ...(typeof oauth.clientSecret === "string" ? { clientSecret: oauth.clientSecret } : {}),
+            ...(typeof clientId === "string" ? { clientId } : {}),
+            ...(typeof clientSecret === "string" ? { clientSecret } : {}),
             ...(typeof oauth.clientMetadataUrl === "string" ? { clientMetadataUrl: oauth.clientMetadataUrl } : {}),
             ...(typeof oauth.scope === "string" ? { scope: oauth.scope } : {}),
-            ...(typeof oauth.authServerMetadataUrl === "string" ? { authServerMetadataUrl: oauth.authServerMetadataUrl } : {}),
+            ...(typeof authServerMetadataUrl === "string" ? { authServerMetadataUrl } : {}),
             ...(typeof oauth.skipIssuerMetadataValidation === "boolean"
               ? { skipIssuerMetadataValidation: oauth.skipIssuerMetadataValidation }
               : {}),

package/direct-tool-surface.ts

@@ -216,7 +216,7 @@ export function buildProxyDescription(config: McpConfig): string {
     return selected === "search";
   });
   if (searchModeServers.length > 0) {
-    desc += `\nSearch-mode servers (${searchModeServers.join(", ")}): their tools become real, schema-backed tools the first time mcp({ search }) matches them — after that, call them directly by name.\n`;
+    desc += `\nSearch-mode servers (${searchModeServers.join(", ")}): their tools become real, schema-backed tools the first time mcp({ search }) matches them or mcp({ tool }) calls them — after that, call them directly by name.\n`;
   }
 
   const disabledServers = Object.entries(config.mcpServers)

package/dist/config.js

@@ -482,12 +482,13 @@ function getConfiguredAncestorRoot(globalSources, cwd) {
         }
         try {
             const root = realpathSync(expanded);
-            if (!statSync(root).isDirectory() || !isWithin(home, root) || !isWithin(root, canonicalCwd))
+            if (!statSync(root).isDirectory() || !isWithin(home, root))
                 throw new Error();
-            valid.push(root);
+            if (isWithin(root, canonicalCwd))
+                valid.push(root);
         }
         catch {
-            console.warn(`Invalid settings.ancestorConfigRoots entry ${JSON.stringify(entry)}: expected an existing directory under HOME containing cwd`);
+            console.warn(`Invalid settings.ancestorConfigRoots entry ${JSON.stringify(entry)}: expected an existing directory under HOME`);
         }
     }
     return valid.sort((left, right) => right.length - left.length)[0];
@@ -659,7 +660,28 @@ function loadImportedConfig(importKind, cwd, warningPrefix) {
             try {
                 const value = readImportedConfig(path);
                 if (value && typeof value === "object" && !Array.isArray(value)) {
-                    merged = mergeOpenCodeConfigs(merged, value);
+                    const imported = value;
+                    const mcp = isRecord(imported.mcp) ? imported.mcp : {};
+                    // OpenCode v2 nests definitions under mcp.servers; normalize before
+                    // merging so project overrides retain the existing merge semantics.
+                    const entries = isRecord(mcp.servers)
+                        ? { ...Object.fromEntries(Object.entries(mcp).filter(([name]) => name !== "servers" && name !== "timeout")), ...mcp.servers }
+                        : mcp;
+                    const normalized = Object.fromEntries(Object.entries(entries).map(([name, entry]) => {
+                        if (!isRecord(entry) || !isRecord(entry.oauth))
+                            return [name, entry];
+                        const { client_id, client_secret, auth_server_metadata_url, ...oauth } = entry.oauth;
+                        return [name, {
+                                ...entry,
+                                oauth: {
+                                    ...oauth,
+                                    ...(client_id !== undefined ? { clientId: client_id } : {}),
+                                    ...(client_secret !== undefined ? { clientSecret: client_secret } : {}),
+                                    ...(auth_server_metadata_url !== undefined ? { authServerMetadataUrl: auth_server_metadata_url } : {}),
+                                },
+                            }];
+                    }));
+                    merged = mergeOpenCodeConfigs(merged, { ...imported, mcp: normalized });
                     highestPrecedencePath = path;
                 }
             }
@@ -844,7 +866,7 @@ function extractServers(config, kind) {
             if (!entry || typeof entry !== "object" || Array.isArray(entry))
                 continue;
             const raw = entry;
-            if (raw.enabled === false)
+            if (raw.enabled === false || raw.disabled === true)
                 continue;
             if (raw.type === "local" && Array.isArray(raw.command) && raw.command.length > 0 && raw.command.every((value) => typeof value === "string")) {
                 const env = toStringRecord(raw.environment);
@@ -872,12 +894,15 @@ function extractServers(config, kind) {
                 else if (raw.oauth && typeof raw.oauth === "object" && !Array.isArray(raw.oauth)) {
                     const oauth = raw.oauth;
                     mapped.auth = "oauth";
+                    const clientId = oauth.clientId;
+                    const clientSecret = oauth.clientSecret;
+                    const authServerMetadataUrl = oauth.authServerMetadataUrl;
                     mapped.oauth = {
-                        ...(typeof oauth.clientId === "string" ? { clientId: oauth.clientId } : {}),
-                        ...(typeof oauth.clientSecret === "string" ? { clientSecret: oauth.clientSecret } : {}),
+                        ...(typeof clientId === "string" ? { clientId } : {}),
+                        ...(typeof clientSecret === "string" ? { clientSecret } : {}),
                         ...(typeof oauth.clientMetadataUrl === "string" ? { clientMetadataUrl: oauth.clientMetadataUrl } : {}),
                         ...(typeof oauth.scope === "string" ? { scope: oauth.scope } : {}),
-                        ...(typeof oauth.authServerMetadataUrl === "string" ? { authServerMetadataUrl: oauth.authServerMetadataUrl } : {}),
+                        ...(typeof authServerMetadataUrl === "string" ? { authServerMetadataUrl } : {}),
                         ...(typeof oauth.skipIssuerMetadataValidation === "boolean"
                             ? { skipIssuerMetadataValidation: oauth.skipIssuerMetadataValidation }
                             : {}),