pi-mcp-client 0.4.0 → 0.6.0

package/docs/authentication.md

@@ -0,0 +1,247 @@
+# Authentication
+
+[Back to the README](../README.md)
+
+You manage authentication through `/mcp login` and `/mcp logout`. The assistant
+can't initiate an OAuth login: only your explicit login command opens the browser.
+For externally managed bearer tokens, use
+[headers and secret commands](configuration.md#secret-commands) instead.
+
+## Sign in with OAuth
+
+Add the HTTP server, then log in:
+
+```text
+/mcp add --scope global example https://mcp.example.com/mcp
+/mcp login example
+```
+
+Replace the example URL with your server's URL. This flow requires dynamic
+client registration or a [pre-registered public client](#use-a-pre-registered-client).
+Adding a URL alone isn't enough for servers such as Slack.
+
+Login uses the effective server definition (the trusted project override, if
+present; otherwise the global definition) and starts the SDK's OAuth discovery
+and authorization flow. It doesn't change configuration files. Adding a server
+still doesn't connect or open a browser.
+
+HTTP servers use automatic authentication by default:
+
+- Configured Authorization headers take precedence over OAuth.
+- Otherwise, connections reuse stored OAuth tokens when available. The SDK
+  handles authentication challenges and refreshes existing grants.
+- Without a grant, an authentication challenge asks you to run `/mcp login`.
+  Discovery and tool calls never register a new client or open a browser.
+- A missing or locked keyring doesn't block public servers. If the server
+  requires OAuth, an unavailable keyring is an error; no credentials are stored
+  outside the OS credential store.
+
+The `oauth` configuration field and `--oauth` switch aren't supported. Remove
+these from existing definitions and commands; HTTP authentication is automatic.
+
+If the server uses an Authorization header, login asks you to remove that header
+before switching to OAuth; it never replaces existing header credentials.
+Stdio servers manage their own authentication and don't support OAuth login.
+
+The extension supports public clients with dynamic registration or a
+pre-registered client ID. Both use PKCE and a loopback callback at
+`http://127.0.0.1:19847/callback` by default. Normal login opens a local listener
+that your browser must be able to reach.
+
+Authentication times out after two minutes; you can cancel it with Escape in the
+terminal UI. Explicit login always starts a fresh authorization flow, even if a
+refresh token is already stored. The browser callback page identifies **Pi MCP
+Client** and asks you to return to Pi; receiving a callback doesn't yet mean the
+token exchange succeeded.
+
+OAuth tokens and client registrations are stored in the operating system
+credential store, bound to the configured server name, URL, client ID (if any),
+and authorization-server issuer. There is no plaintext credential fallback. PKCE
+verifiers and callback state stay in memory. Linux requires a working Secret
+Service/keyring session.
+
+### Upgrade from earlier versions
+
+Credentials now include the configured server name in their identity. Earlier
+entries keyed only by URL and client ID aren't migrated or deleted: assigning a
+shared grant to a name could select the wrong account. Run `/mcp login <server>`
+again for each named connection after upgrading. Revoke old grants at the service
+if needed; the new logout command doesn't remove those earlier keyring entries.
+Changing scopes or the callback port doesn't select a different store.
+
+## Use multiple accounts
+
+Each named server has its own OAuth login, even when multiple definitions use
+the same endpoint and client ID. No profile setting is required:
+
+```json
+{
+  "mcpServers": {
+    "cloudflare-personal": { "url": "https://mcp.cloudflare.com/mcp" },
+    "cloudflare-work": { "url": "https://mcp.cloudflare.com/mcp" }
+  }
+}
+```
+
+Log in to each connection separately:
+
+```text
+/mcp login cloudflare-personal
+/mcp login cloudflare-work
+```
+
+Choose the intended account in the browser for each login. Names are local
+labels, not verified account identities, and don't change browser cookies. Use
+`--no-browser` to open the authorization URL in a different browser profile if
+needed. Both connections can remain active; tool names identify their server.
+
+Definitions with the same name, URL, and client ID reuse credentials across
+projects. Global and trusted project definitions still resolve to one effective
+definition per name. Use different names when you need separate accounts.
+
+Renaming a server or changing its URL or client ID requires a new login. Log out
+before making these changes if you want to remove the old credentials. Removing
+a server definition alone doesn't delete its credentials.
+
+## Use a pre-registered client
+
+For a server without dynamic registration, register a **public/native** client
+with the service, using the exact callback URL and token endpoint authentication
+method `none`. Then configure its client ID:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthClientId": "${EXAMPLE_OAUTH_CLIENT_ID}"
+    }
+  }
+}
+```
+
+Run `/mcp reload`, then `/mcp login example`. The configured ID is used for login,
+token refresh, and revocation; the extension never falls back to dynamic
+registration if it is rejected. `/mcp get example` identifies the client as
+pre-registered without printing the ID.
+
+Changing the client ID selects separate credentials and requires a new login.
+Log out before changing or removing the ID if you want to delete its old
+credentials. After the first successful grant, a pre-registered client is pinned
+to its authorization-server issuer. If that issuer changes, verify the server
+configuration before logging out and logging in again to trust the replacement.
+
+### Slack setup requirements
+
+[Slack doesn't support dynamic client registration](https://docs.slack.dev/ai/slack-mcp-server/).
+Without a registered client, login fails before opening a browser. Configure
+`oauthClientId` with your Slack app's client ID, and ensure the app supports
+public-client PKCE. Apps requiring a client secret aren't supported by this
+extension. Slack also requires an eligible internal or Marketplace-published
+app and any workspace administrator approval required by your workspace.
+
+Register the exact callback URL shown by `/mcp get slack` in the app settings
+(default: `http://127.0.0.1:19847/callback`). For example:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "url": "https://mcp.slack.com/mcp",
+      "oauthClientId": "${SLACK_OAUTH_CLIENT_ID}"
+    }
+  }
+}
+```
+
+Set the environment variable before starting Pi. Run `/mcp reload`, then
+`/mcp login slack`. A configured ID appears as **OAuth (pre-registered public
+client)** in `/mcp get slack`; the ID itself stays hidden. A client ID alone
+doesn't guarantee that the app permits this login flow or callback address.
+`--no-browser` doesn't fix registration or app-approval problems.
+
+## Set scopes and callback ports
+
+Configure scopes and a callback port in the server definition:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthScopes": ["read", "write"],
+      "oauthCallbackPort": 19848
+    }
+  }
+}
+```
+
+Or set them when adding the server:
+
+```text
+/mcp add --scope global --oauth-scope read --oauth-scope write --oauth-callback-port 19848 example https://mcp.example.com/mcp
+```
+
+The callback becomes `http://127.0.0.1:19848/callback`. Pre-registered clients must
+allow that exact URL. The listener stays bound to loopback; arbitrary callback
+hosts and paths aren't supported. If the port is occupied, choose another port or
+use manual login.
+
+Scopes are case-sensitive OAuth tokens, each up to 256 characters, without spaces,
+quotes, or backslashes. Omit `oauthScopes` to retain SDK/server-driven selection;
+an empty array is rejected. The SDK may also request `offline_access` when the
+service advertises refresh-token support. Requested scopes aren't a guarantee of
+granted permissions or a per-tool permission policy.
+
+After changing these options, run `/mcp reload`, then `/mcp login example`.
+Changing configuration never starts authorization or revokes existing grants.
+Scopes and callback ports don't select separate credential stores: definitions
+sharing a name, URL, and client ID still share credentials. Explicit login renews a
+dynamic registration when its requested options change. `/mcp get example` shows
+the requested scopes and callback address without connecting.
+
+## Sign in remotely or without launching a browser
+
+When Pi runs over SSH, or you don't want it to launch a browser, use:
+
+```text
+/mcp login example --no-browser
+```
+
+1. Open the authorization URL shown in Pi's interactive dialog in your browser.
+2. Complete sign-in. The browser may show a connection error at the loopback
+   callback address; this is expected when the browser and Pi run on different
+   machines.
+3. Copy the full callback URL from the browser's address bar and paste it into
+   the **Callback URL** dialog in Pi, not into chat or a slash command.
+
+Manual login doesn't open a browser or bind a callback port. The extension
+validates the callback address, state, and authorization response before
+exchanging the code. It doesn't write authorization URLs or pasted callbacks to
+session entries, catalogs, notifications, or logs. Treat the callback URL as
+sensitive; your browser history and clipboard may still contain it.
+
+`--no-browser` still requires an interactive UI and an available OS credential
+store. It isn't unattended authentication: print and JSON modes refuse OAuth
+login. Use externally managed bearer headers for unattended access. Confidential
+clients requiring a client secret aren't supported yet.
+
+## Sign out
+
+Run `/mcp logout <server>` to remove that named server's stored tokens and client
+registrations, close its connection, and deactivate its tools. Other named
+servers keep their local credentials, connections, and active tools, even when
+they use the same URL and client ID. Configuration and enabled state stay
+unchanged. Disabled servers accept logout too. Header and server-managed
+credentials remain untouched.
+
+Local removal happens before a bounded attempt to revoke tokens at the original
+authorization server. The result distinguishes accepted revocation, unsupported
+revocation, and unconfirmed revocation. When revocation isn't confirmed, remove the
+grant at the service if needed. Repeating logout is safe. Other running Pi sessions
+using the same named credentials may need to reconnect; logout cannot recall
+requests already sent to a server. Remote revocation behavior depends on the
+service and can affect related grants beyond this local connection.
+
+Removing a server definition doesn't remove its credentials. Log out before
+[removing the definition](commands.md#add-and-remove-servers) if you want both.

package/docs/behavior.md

@@ -0,0 +1,150 @@
+# Behavior and permissions
+
+[Back to the README](../README.md)
+
+This page explains how the extension manages state and displays results. For the
+assistant's tool-call interface, see the [tool reference](tool-reference.md).
+
+## Sessions
+
+- Active tools accumulate rather than rotating with each prompt.
+- Resume and branch navigation restore tools activated through `mcp_tools` on
+  the selected branch. Discovery results never restore tools.
+- Compaction retains the acquired tool set. New sessions start fresh.
+- Pi uses native deferred loading where supported by the model and provider.
+  Other providers receive the expanded tool list normally.
+- Discovery respects server filters; activation also respects Pi's tool exclusions.
+  An explicit tool allowlist must include both `mcp_tools` and the native tools
+  the assistant needs to load.
+
+## Resource snapshots
+
+Resource reads never start OAuth login, follow links in resource bodies, or
+subscribe to live updates. Repeated reads fetch fresh content; earlier results
+stay as snapshots. Resuming a session or navigating its branches doesn't re-read
+resources. Watches have their own
+[memory-only lifecycle](commands.md#watch-resource-changes) and never fetch content
+automatically.
+
+Resource content and selected metadata, including URIs, become session data and
+may be sensitive. [Private spill files](troubleshooting.md#large-results) can also
+contain sensitive data and aren't automatically deleted.
+
+## Prompt snapshots
+
+Prompt discovery fetches metadata only. You explicitly enter arguments and fetch a
+preview through `/mcp prompts` or `/mcp prompt`. Only **Use prompt** adds the
+reviewed snapshot to the conversation and starts a model turn. Cancelling a
+preview adds no message and doesn't write a spill file. Arguments already sent to
+the server can't be recalled.
+
+The transcript labels accepted snapshots **mcp prompt** with their server, name,
+and message count. Expand the entry to inspect its contents. Server-provided
+`user` and `assistant` roles remain fields in source-labeled data, not fabricated
+conversation history or system instructions. Terminal control sequences are
+removed before previewing and sending text. Selecting a prompt grants no additional
+tool permissions and never activates tools.
+
+Previously accepted snapshots don't change or refetch on catalog notifications,
+resume, or branch navigation. Session replacement, tree navigation, and
+configuration reload invalidate pending selections. The agent must be idle when
+you choose **Use prompt**; another active turn is never silently interrupted.
+Accepted content becomes session data and may contain sensitive information.
+
+## Discovery and caching
+
+Connections start on demand, never while the extension factory loads. A search
+without the requested cached metadata contacts configured servers, with at most
+four server discoveries in flight. A server-scoped search only contacts that
+server. Activation discovers only the servers named by its identifiers, with the
+same concurrency bound. Failed servers are reported as unavailable, not mistaken
+for an empty catalog.
+
+Tool catalogs are cached privately under `~/.pi/agent/cache/pi-mcp-client/`, keyed
+by server configuration and working directory. Disk caches expire after 24 hours.
+They contain tool metadata, not configured credentials. Cached tool-only discovery
+and activation need no connection; invocation refreshes the live catalog before
+calling the tool.
+
+Resource metadata, including template catalogs, and prompt metadata are held only
+in memory for up to five minutes, not written to the tool catalog cache. Mixed
+discovery therefore may connect even when tools are cached on disk. Resource-list notifications,
+disconnection, and explicit refresh invalidate resource metadata without reading
+content. Tool and resource catalog failures are reported independently; healthy
+candidates remain available. The SDK handles pagination. Resource catalogs are
+limited to 10,000 entries and 4 MiB of descriptor data; oversized catalogs fail
+rather than silently returning a partial list. Reads bypass the SDK content cache.
+
+Prompt-list notifications invalidate only prompt metadata; they never fetch prompt
+content or change a pending preview. Disconnection and explicit refresh also
+invalidate prompt metadata. Prompt catalog failures don't suppress healthy
+tool or resource candidates. The SDK handles prompt pagination. Prompt catalogs
+share the 10,000-entry and 4 MiB limits and reject invalid or duplicate descriptors
+rather than presenting a partial catalog.
+
+Connections remain open until shutdown or an explicit lifecycle action such as
+reconnection or configuration reload.
+
+When a connected server reports a tool-list change, the extension invalidates its
+memory and disk catalogs. The next discovery or activation fetches the current
+list, including new or removed tools. Notifications don't replace active tool
+definitions: the assistant must activate changed schemas again before use. Calls
+validate the live catalog before execution and refuse removed or changed tools.
+Disconnected, cache-only searches can't receive notifications and still use the
+24-hour disk-cache expiry.
+
+## Result display
+
+The UI labels discovery calls **mcp discover**, activation calls **mcp activate**,
+resource reads **mcp read**, and argument completions **mcp complete**.
+
+Discovery rows show `○` for inactive candidates and `●` for already active tools,
+without a status suffix. These reflect the state when discovery runs; earlier
+results don't update retroactively. Activation results use `✔︎` for success and
+`✘︎` for failure. Descriptions stay gray; identifiers remain prominent.
+
+Exact and template reads use the same compact status row:
+
+```text
+mcp read
+ ✔︎ warehouse · schema://tables/events
+```
+
+Expand a tool result to see JSON objects and arrays formatted with two-space
+indentation and syntax highlighting. Explicit JSON resource MIME types (including
+`application/*+json`) and structured content identify JSON without guessing.
+Other explicit MIME types stay plain text; unlabeled text is checked for JSON.
+
+Formatting changes only the display, not the response sent to the assistant.
+Invalid or truncated JSON stays plain text. Results that would exceed formatting
+limits also stay plain text. Resource-link MIME types describe the linked content,
+not the displayed link label. Supported images use the existing result display;
+see [large results](troubleshooting.md#large-results) for size limits.
+
+## Trust and permissions
+
+Only load configuration you trust. Server executables and secret commands run
+with your user permissions; trusted project configuration can replace global
+connections and settings.
+
+Configuration imports require an explicit file, scope, selection, and final
+confirmation. Import previews hide connection values; review the source file
+before trusting it. Inline credentials are copied only with the selected whole
+server definitions. Importing doesn't run or authenticate servers, but enabled
+imports can execute programs or send credentials when used afterward.
+
+Server metadata, resource content, and prompt content are untrusted data. Discovery never
+activates tools. Explicit activation exposes schemas but doesn't approve tool
+side effects or provide per-call confirmation. Use tool filters and Pi permission
+extensions for additional controls. Cancelling a call doesn't guarantee that the
+server rolled back its effects. The extension doesn't retry failed tool
+invocations; verify an interrupted operation's outcome before trying again.
+
+`includeTools` and `excludeTools` apply only to tools, not resources or prompts. Keeping
+`mcp_tools` available permits resource reads from enabled servers, subject to the
+server's authorization. `kind: "tools"` filters one search; it isn't an access
+restriction. Disable a server to prevent all access, or exclude `mcp_tools` through
+Pi's tool restrictions to prevent discovery and resource operations. Already active
+native tools have their own tool restrictions. Per-resource permission policies
+aren't implemented. Prompt selection uses explicit user commands, not the
+model-facing tool allowlist; disable the server to prevent prompt access.