pi-mcp-client 0.9.0 → 0.10.0

package/docs/authentication.md

@@ -200,6 +200,81 @@ sharing a name, URL, and client ID still share credentials. Explicit login renew
 dynamic registration when its requested options change. `/mcp get example` shows
 the requested scopes and callback address without connecting.
 
+## Use DPoP-bound tokens
+
+DPoP binds an access token to a signing key, so possession of the token alone
+isn't enough to use it. Enable it for an OAuth HTTP server whose service supports
+ES256 proofs:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthDpop": true
+    }
+  }
+}
+```
+
+Run `/mcp reload`, then `/mcp login example`. For a new definition, you can use
+`/mcp add --scope global --oauth-dpop example https://mcp.example.com/mcp`.
+
+Only explicit login creates a key. The private key stays in the OS credential
+store alongside the named server's OAuth credentials, bound to its issuer and
+registered client. Connections and token refreshes reuse it across sessions;
+proofs and server nonces aren't persisted. There is no plaintext fallback, and
+keys aren't stored in configuration or session history. This protects keys at
+rest, not against a compromised Pi process or OS account.
+
+The SDK signs fresh request proofs and handles bounded nonce challenges. Enabling
+DPoP requests proof support; it doesn't require the service to issue bound tokens.
+If the service issues Bearer access tokens, resource requests still use Bearer
+authentication. Refresh tokens can be DPoP-bound independently; their binding is
+retained even if the access token is Bearer or the signing key is lost.
+`/mcp get example` shows whether DPoP is configured, not whether a grant is bound.
+
+If a bound access or refresh token's key is missing, sign in again at the same
+issuer. If the key is corrupt or belongs to a different client, use
+`/mcp logout example` before signing in. Login checks the signing key before
+opening the browser. Disabling DPoP doesn't convert bound tokens to Bearer
+tokens: enable it again or log out and obtain a new grant.
+Logout removes the key and tokens locally and attempts remote token revocation.
+A changed issuer requires explicit logout before trusting its replacement.
+
+## Approve additional permissions
+
+A server can reject a request with an OAuth scope challenge—for example, when
+searching works but creating an issue requires write access. The operation stops
+with `oauth_scope_required`; it doesn't open a browser or retry automatically.
+
+Run the indicated command yourself:
+
+```text
+/mcp login example
+```
+
+Page through the server's requested scope names and the combined set of configured,
+previously granted, and requested scopes. In the terminal, press `a` on the last
+page to approve; in RPC, select **Approve sign-in**. Approving starts a fresh login.
+You can also use `--no-browser`. Declining, cancelling sign-in, or a failed token
+exchange leaves your existing grant unchanged. Reloading configuration cancels
+an active login. After signing in, explicitly retry the operation; sign-in never
+replays it. Successful grants retain their requested scopes even when the service
+omits the optional scope field from its token response. If previously granted
+scopes are unknown, the review warns that they might not be retained. Configure
+`oauthScopes` with the permissions you need rather than relying on unspecified
+service defaults. After review, the sign-in dialog shows a scope count instead
+of repeating the full list.
+
+Scope names are untrusted service data, not instructions. Requests are bounded to
+100 scope names and kept only in this Pi session for ten minutes. Reloading
+configuration, ending the session, or logging out discards them. Login uses the
+configured server's OAuth discovery, not URLs supplied in a scope challenge.
+Invalid or missing scope names require checking `oauthScopes` against the service's
+requirements instead. Headless operation reports the challenge but cannot approve
+additional permissions.
+
 ## Sign in remotely or without launching a browser
 
 When Pi runs over SSH, or you don't want it to launch a browser, use:

package/docs/commands.md

@@ -20,7 +20,7 @@ The model's separate interface is documented in the [tool reference](tool-refere
 | `/mcp reload` | Apply configuration changes without restarting Pi. |
 | `/mcp enable <server>` | Enable a server in its effective configuration file. |
 | `/mcp disable <server>` | Disable a server, close its connection, and deactivate its tools. |
-| `/mcp login <server> [--no-browser]` | Authenticate an HTTP server without changing its configuration; optionally paste the callback URL in an interactive dialog. |
+| `/mcp login <server> [--no-browser]` | Authenticate an HTTP server or review additional permissions it requested; optionally paste the callback URL in an interactive dialog. Configuration stays unchanged. |
 | `/mcp logout <server>` | Remove local OAuth credentials and attempt remote revocation, including for disabled servers. |
 | `/mcp reconnect <server>` | Replace a connection and refresh its catalog. |
 | `/mcp refresh <server>` | Refresh tool, resource, and prompt metadata without fetching content or loading additional tools. |
@@ -145,6 +145,7 @@ Windows paths with backslashes, single quotes preserve the path verbatim.
 | `--oauth-client-id ID` | Use a pre-registered public client. |
 | `--oauth-scope SCOPE` | Request an OAuth scope. Repeat for additional scopes. |
 | `--oauth-callback-port PORT` | Set the loopback callback port. |
+| `--oauth-dpop` | Request DPoP-bound OAuth tokens using an OS-backed signing key. |
 
 Retain environment references rather than typing tokens:
 

package/docs/configuration.md

@@ -137,6 +137,7 @@ server definition:
 | `oauthClientId` | Optional pre-registered public client ID. Supports `${ENV_VAR}` interpolation, not secret commands. |
 | `oauthScopes` | Optional array of 1–100 unique OAuth scope tokens to request at login. Omitted scopes use SDK/server defaults. Values are literal, without interpolation. |
 | `oauthCallbackPort` | Optional loopback callback port, from 1 to 65535. Defaults to `19847`. |
+| `oauthDpop` | Opt in to DPoP proofs with ES256 keys stored in the OS keyring. Defaults to `false`. Run a fresh login after enabling it. |
 | `disabled` | Prevent this server from connecting or exposing tools and resources. |
 | `includeTools` | Optional allowlist of original MCP tool names; `*` matches any sequence. An empty list exposes no tools. |
 | `excludeTools` | Denylist applied after `includeTools`. |
@@ -145,7 +146,7 @@ server definition:
 | `toolTimeoutMs` | Optional timeout for tool calls only, from 100 to 600000 ms. Overrides `timeoutMs` for calls without changing metadata or resource deadlines. Time spent answering [server requests](behavior.md#server-requests-for-input) doesn't count. |
 | `protocol` | `auto` (default) for SDK protocol-version negotiation, or `legacy` for an explicit legacy handshake. |
 
-OAuth client IDs, scopes, and callback ports require HTTP without an Authorization
+OAuth client IDs, scopes, callback ports, and DPoP require HTTP without an Authorization
 header. HTTP authentication is automatic; remove the obsolete `oauth` field from
 existing definitions. See [authentication](authentication.md).
 

package/docs/troubleshooting.md

@@ -45,6 +45,8 @@ unavailable server isn't an empty catalog.
 | `oauth_registration_rejected` | The server rejected dynamic registration. Check public/native client eligibility and the callback URL, or configure an approved public client ID. |
 | `oauth_client_rejected` | Check the client ID, app approval, and public-client authentication (token endpoint method `none`). A rejected client doesn't necessarily mean a client secret is required. |
 | `oauth_pkce_unsupported` | The authorization server must support S256 PKCE. Login without PKCE isn't supported. |
+| `oauth_scope_required` | Run `/mcp login <server>` to review additional permissions, then explicitly retry the operation. |
+| `oauth_dpop_unavailable` | Enable DPoP again, or log out before signing in if you disabled it deliberately or its stored key is corrupt or mismatched. |
 | `oauth_scope_rejected` | Check `oauthScopes` against the service's allowed scopes and app permissions. Reload after changes, then log in again. |
 | `oauth_grant_rejected` | Log in again for a fresh code. If it still fails, check the client and exact callback URL. |
 | `oauth_redirect_rejected` | Register the exact callback host, port, and `/callback` path shown by `/mcp get <server>`. Manual login uses the same callback URL. |
@@ -72,6 +74,14 @@ remain visible as content, even when the tool reports an error; they aren't
 sanitized transport diagnostics. Tool-call failures aren't replayed automatically;
 verify the outcome before retrying.
 
+## OAuth warnings in the terminal
+
+The MCP SDK can print a sanitized warning when a refresh token expires or is
+revoked. In an interactive terminal, this can temporarily disrupt the display
+until Pi redraws it. Remote error details are removed, but these SDK warnings
+can't currently be routed through Pi's UI. Follow the accompanying diagnostic
+if another login is needed; the warning alone doesn't mean sign-in started.
+
 ## Missing project servers
 
 A project's `.mcp.json` loads only after an explicit trust decision, even in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-client",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "MCP tools for Pi, discovered on demand and called natively through the official SDK.",
   "type": "module",
   "license": "MIT",
@@ -39,8 +39,9 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/client": "2.1.0",
     "@napi-rs/keyring": "^1.3.0",
+    "jose": "^6.1.3",
     "minisearch": "^7.2.0",
     "smol-toml": "^1.8.0"
   },
@@ -48,7 +49,7 @@
     "@earendil-works/pi-ai": "^0.85.1",
     "@earendil-works/pi-coding-agent": "^0.85.1",
     "@earendil-works/pi-tui": "^0.85.1",
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/server": "2.1.0",
     "@types/bun": "^1.3.0",
     "@types/node": "^24.0.0",
     "esbuild": "^0.25.0",