pi-mcp-client 0.5.0 → 0.7.0

package/docs/authentication.md

@@ -12,10 +12,14 @@ For externally managed bearer tokens, use
 Add the HTTP server, then log in:
 
 ```text
-/mcp add --scope global slack https://mcp.slack.com/mcp
-/mcp login slack
+/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
@@ -51,17 +55,53 @@ 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 server URL, configured client ID (if any), and
-authorization-server issuer. There is no plaintext credential fallback. PKCE
+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 use an identity based only on the server URL and optional client
-ID. Earlier credential-store entries aren't migrated or deleted. Run
-`/mcp login <server>` again after upgrading; revoke old grants at the service if
-needed. Changing scopes or the callback port doesn't select a different store.
+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
 
@@ -91,6 +131,35 @@ 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:
@@ -127,7 +196,7 @@ 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 URL and client ID still share credentials. Explicit login renews a
+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.
 
@@ -159,17 +228,20 @@ clients requiring a client secret aren't supported yet.
 
 ## Sign out
 
-Run `/mcp logout <server>` to remove stored tokens and client registrations. Logout
-also closes connections and deactivates tools for OAuth servers sharing
-the same URL and configured client ID, since they share credentials. Configuration
-and enabled state stay unchanged. Disabled servers accept logout too. Header and
-server-managed credentials remain untouched.
+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
-may need to reconnect; logout cannot recall requests already sent to a server.
+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

@@ -30,6 +30,27 @@ 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 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
@@ -45,14 +66,22 @@ They contain tool metadata, not configured credentials. Cached tool-only discove
 and activation need no connection; invocation refreshes the live catalog before
 calling the tool.
 
-Resource metadata, including template catalogs, is 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,
+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.
 
@@ -98,17 +127,24 @@ Only load configuration you trust. Server executables and secret commands run
 with your user permissions; trusted project configuration can replace global
 connections and settings.
 
-Server metadata and resource content are untrusted data. Discovery never
+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. Keeping
+`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.
+aren't implemented. Prompt selection uses explicit user commands, not the
+model-facing tool allowlist; disable the server to prevent prompt access.

package/docs/commands.md

@@ -3,7 +3,7 @@
 [Back to the README](../README.md)
 
 These are commands **you run in Pi**, not tools the assistant calls. Use them to
-manage servers, inspect capabilities, and watch resource changes. The assistant's
+manage servers, inspect capabilities, use prompts, and watch resource changes. The assistant's
 separate interface is documented in the [tool reference](tool-reference.md).
 
 ## Command reference
@@ -13,15 +13,17 @@ separate interface is documented in the [tool reference](tool-reference.md).
 | `/mcp`, `/mcp list`, `/mcp status` | Show a server status matrix with catalog and loaded-tool counts. |
 | `/mcp add --scope <scope> [options] <server> <url>` | Save an HTTP server without connecting. For stdio, use `<server> -- <command> [args...]`. |
 | `/mcp remove --scope <scope> <server>` | Remove a definition from the selected scope, retaining credentials. |
+| `/mcp import --scope <scope> <path>` | Preview and select servers from Claude/Cursor JSON or Codex TOML, then confirm a scoped import. |
 | `/mcp get <server>` | Inspect status and configuration, including disabled servers. Connection values are hidden. |
 | `/mcp tools <server>` | Browse the server's tools and inspect descriptions without activating tools. |
+| `/mcp prompt <server> [name] [argument=value ...]` | Browse prompts or open a named prompt with prefilled arguments, then fetch and review a preview. |
 | `/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 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 and resource metadata without reading resources or loading additional tools. |
+| `/mcp refresh <server>` | Refresh tool, resource, and prompt metadata without fetching content or loading additional tools. |
 | `/mcp subscribe <server> <uri>` | Watch changes to one exact resource URI without fetching content. |
 | `/mcp unsubscribe <server> <uri>` | Stop watching one resource. |
 | `/mcp subscriptions` | List active resource watches and their change markers. |
@@ -59,6 +61,40 @@ change, ask the assistant to activate the exact tool again. See
 aren't retried automatically; verify whether an interrupted operation completed
 before trying again.
 
+## Use server prompts
+
+Prompts are server-maintained task instructions that **you** choose to use. For a
+server that provides an `explain` prompt, browse or open it directly:
+
+```text
+/mcp prompt docs
+/mcp prompt docs explain topic="OAuth flows"
+```
+
+1. Select a prompt. Browsing fetches metadata only and doesn't add anything to the
+   conversation.
+2. Select an argument to edit its string value. Required arguments must be supplied;
+   optional arguments can remain omitted. An empty string is distinct from an
+   omitted value. Inline `argument=value` pairs prefill the editor. Quoting follows
+   the configuration commands' rules, without shell or environment expansion.
+3. Choose **Fetch preview** to send the arguments to the selected MCP server.
+   Your conversation and local files aren't automatically shared. Argument values
+   are limited to 4,096 characters each and 64 KiB in total.
+4. Review the source-labeled messages using **Next page** and **Previous page**.
+   Choose **Back** to change arguments, or **Cancel** to discard the preview.
+5. Choose **Use prompt** to send exactly the reviewed snapshot to the model and
+   start a turn. This saves the content in the session. No second fetch occurs.
+
+Text and embedded text resources are supported. Images, audio, binary resources,
+and other unsupported blocks are identified in the preview and prevent use of the
+whole prompt; they aren't silently omitted. Prompts exceeding 2,000 lines or
+50 KiB are refused, not truncated or written to spill files. Links aren't followed.
+
+These commands require an interactive TUI or RPC session. In the TUI, press Escape
+to cancel a pending fetch. Cancelling doesn't undo arguments already sent to the
+server. Using a prompt doesn't activate tools or approve their side effects. See
+[prompt snapshots](behavior.md#prompt-snapshots) for trust and lifecycle behavior.
+
 ## Enable and disable servers
 
 Use `/mcp disable <server>` or `/mcp enable <server>` to change the `disabled`
@@ -142,6 +178,92 @@ atomically. New files are private; existing file permissions are preserved. If
 global and project configuration point to the same file, scoped edits are refused
 until you separate them. Empty configuration files are retained rather than deleted.
 
+## Import server definitions
+
+Import directly from an explicitly named local file. JSON and TOML are detected
+automatically; no conversion file is needed:
+
+```text
+/mcp import --scope global ~/.codex/config.toml
+/mcp import --scope global ~/.claude.json
+/mcp import --scope project "/path with spaces/mcp.json"
+```
+
+The command requires an interactive TUI or RPC session and an explicit
+`--scope global` or `--scope project`. Project scope requires a trusted project.
+Relative source paths resolve against Pi's current directory; `~/` is supported.
+The path isn't evaluated by a shell, and no application settings are scanned.
+
+1. If the source contains other top-level settings, confirm that only MCP server
+   definitions should be considered. Model, permission, and credential-store
+   settings aren't imported.
+2. For a Claude file containing `projects.<path>.mcpServers`, choose a source
+   group or **All groups**. Global and project definitions remain separate during
+   review. A source project doesn't select or authorize the destination scope.
+3. Review each server's name, transport, enabled state, and any validation or
+   unsupported-field problems. Commands, arguments, URLs, headers, and environment
+   values stay hidden. Review the original file before importing connections you
+   don't already trust. Unsupported entries can only be skipped; their fields
+   aren't silently dropped.
+4. Choose **Skip**, add the definition, or **Choose a different name**. Name
+   conflicts require an explicit replacement or override choice. A replacement
+   replaces the entire definition, including headers and environment variables;
+   credentials and other fields aren't merged. A global import shadowed by a
+   project definition is labeled as such and doesn't change the effective server.
+5. Review the selected destination names and actions, then confirm the import.
+   The confirmation warns that inline credentials are copied with the selected
+   definitions. Existing Pi OAuth credentials are retained, but no external
+   credential store is read or migrated.
+
+Nothing is saved until the final confirmation. Cancellation, a session or trust
+change, or a changed destination configuration prevents saving the preview. All
+selected definitions are validated and written together using one atomic file
+replacement, then applied through the normal configuration reconciliation.
+The source snapshot isn't reread after confirmation, and the source and
+destination cannot be the same file. No server starts, secret command runs,
+login opens, or tool activates during import. Enabled connections become
+available on demand afterward; imported disabled servers stay disabled.
+
+### Supported formats
+
+Files must be UTF-8 and are limited to 1 MiB and 100 servers across all source
+groups. Only stdio and Streamable HTTP are supported. JSON comments, JSON trailing
+commas, SSE, VS Code, and MCPorter formats aren't supported. TOML comments,
+multiline strings, quoted keys, and trailing commas follow TOML syntax.
+
+**Claude/Cursor JSON:** Read a top-level `mcpServers` object and, for Claude,
+`projects.<path>.mcpServers` groups. Supported server fields are `type`, `command`,
+`args`, `cwd`, `env`, `url`, `headers`, `disabled`, and `description`.
+`${VAR}` references are preserved and must resolve in Pi before import. Default
+expressions and client-specific variables such as `${env:TOKEN}` or
+`${workspaceFolder}` are refused rather than translated. In environment and
+header values, bare `$VAR` and leading `!` remain literal: the importer escapes
+them so they don't become Pi variable expansions or secret commands.
+
+**Codex TOML:** Read the `mcp_servers` table, with these mappings:
+
+| Codex setting | Imported setting |
+| --- | --- |
+| `command`, `args`, `cwd`, `url` | Copied without resolving values. Literal `${...}` in these fields is refused because Pi would interpolate it. |
+| `enabled` | Inverted to `disabled`. |
+| `env`, `http_headers` | Literal environment/header values, including literal `${VAR}`, `$VAR`, and `!`. |
+| `env_vars`, `env_http_headers`, `bearer_token_env_var` | Unresolved environment references, not copies of their current values. Overlapping entries are refused. |
+| `startup_timeout_sec` or `startup_timeout_ms` | `startupTimeoutMs`, defaulting to Codex's 10 seconds. Both source options together are refused. |
+| `tool_timeout_sec` | `toolTimeoutMs`, defaulting to Codex's 60 seconds. |
+| `enabled_tools`, `disabled_tools` | `includeTools`, `excludeTools`. Names containing `*` are refused rather than converted into wildcard patterns. |
+| `scopes` | `oauthScopes`. |
+
+Timeouts must fit Pi's 100–600000 ms range. Startup and tool deadlines stay
+separate; they don't replace the timeout for metadata or resource requests.
+Only local execution is supported. `required = true`, remote environment
+placement, remote `env_vars` entries, and per-server/tool approval policies are
+refused rather than dropped. `required = false` and
+`experimental_environment = "local"` are accepted.
+
+For either format, relative executable, argument, and working-directory paths
+retain Pi's path semantics, not the source application's or import file's
+directory; verify them before importing.
+
 ## Watch resource changes
 
 Subscriptions are explicit user commands, not model-facing tool operations:

package/docs/configuration.md

@@ -4,15 +4,20 @@
 
 You configure which servers the assistant can access. Add connections to
 `~/.pi/agent/mcp.json`, or `.mcp.json` in a trusted project. For command-based
-setup, see [Add and remove servers](commands.md#add-and-remove-servers).
+setup, see [Add and remove servers](commands.md#add-and-remove-servers). To reuse
+an existing Claude/Cursor JSON or Codex TOML file, see
+[Import server definitions](commands.md#import-server-definitions).
 
 ## Files and transports
 
 The files use the common Claude/Cursor-style `mcpServers` format, not a universal
-MCP configuration standard. VS Code's `servers` format and Codex's TOML format
-aren't supported. `PI_CODING_AGENT_DIR` overrides the global Pi directory.
+MCP configuration standard. Live configuration must use JSON, not VS Code's
+`servers` format or Codex TOML. The import command can translate Codex TOML into
+this format. `PI_CODING_AGENT_DIR` overrides the global Pi directory.
 Project definitions replace same-named global definitions in full; fields and
-filters aren't merged. Untrusted project files are neither read nor changed.
+filters aren't merged. Untrusted project definitions aren't loaded or edited.
+An explicitly named import source is read as data for review; saving into project
+scope still requires project trust.
 
 ```json
 {
@@ -122,6 +127,8 @@ server definition:
 | `includeTools` | Optional allowlist of original MCP tool names; `*` matches any sequence. An empty list exposes no tools. |
 | `excludeTools` | Denylist applied after `includeTools`. |
 | `timeoutMs` | Request timeout, from 100 to 600000 ms. Defaults: 15 seconds for discovery/HTTP requests, 30 seconds for stdio tool calls. |
+| `startupTimeoutMs` | Optional timeout for SDK connection setup and protocol negotiation, from 100 to 600000 ms. Defaults to `timeoutMs` or 15 seconds. |
+| `toolTimeoutMs` | Optional timeout for tool calls only, from 100 to 600000 ms. Overrides `timeoutMs` for calls without changing metadata or resource deadlines. |
 | `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
@@ -130,7 +137,9 @@ existing definitions. See [authentication](authentication.md).
 
 Every definition must include a `url` or `command`, even when `disabled` is true.
 These options are specific to Pi MCP Client, not standardized MCP connection
-fields. Other clients may reject them when you copy a definition.
+fields. Other clients may reject them when you copy a definition. The import command
+accepts only its documented subset of server fields and refuses unsupported
+entries rather than dropping options.
 
 Tool filters don't restrict resource reads. See
 [trust and permissions](behavior.md#trust-and-permissions) for access boundaries

package/docs/tool-reference.md

@@ -11,7 +11,7 @@ The `mcp_tools` tool supports four mutually exclusive operations:
 
 | Operation | What the assistant can do | What it doesn't do |
 | --- | --- | --- |
-| `query` | Discover tool and resource metadata. | Read content or activate tools. |
+| `query` | Discover tool, resource, and prompt metadata. | Read content or activate tools. |
 | `activate` | Load full schemas for exact tool identifiers. | Invoke tools. |
 | `read` | Fetch one resource as conversation context. | Activate tools or follow links automatically. |
 | `complete` | Request server suggestions for a template variable. | Read resources, activate tools, or select a value. |
@@ -30,8 +30,8 @@ mcp_tools({ query: "database schema", server: "warehouse", limit: 5 })
 mcp_tools({ query: "list teams", server: "linear", kind: "tools" })
 ```
 
-`kind` defaults to `all`, or accepts `tools` and `resources`. Discovery returns up
-to five candidates by default, or up to 50 with `limit`, across both kinds.
+`kind` defaults to `all`, or accepts `tools`, `resources`, and `prompts`. Discovery
+returns up to five candidates by default, or up to 50 with `limit`, across all kinds.
 
 Tool candidates show an exact activation identifier, a short description,
 required parameter names only, and `[loaded]` if already active. Resource
@@ -39,9 +39,19 @@ candidates show the owning server, title or name, exact URI, description, and
 content type when supplied. Concrete resources and tools include exact next-call
 arguments; templates include a read-call shape and variable names.
 
+Prompt candidates show the owning server, name, description, argument metadata,
+and a user-only command such as `/mcp prompt docs explain`. The assistant can
+recommend this command but can't retrieve or run prompts through `mcp_tools`.
+Only you can [select, preview, and use a prompt](commands.md#use-server-prompts).
+
+```js
+// Discover prompt metadata without fetching the prompt content.
+mcp_tools({ query: "explain authentication", server: "docs", kind: "prompts" })
+```
+
 Search uses local BM25-based ranking of metadata, with names and resource titles
 weighted more strongly than descriptions, and support for prefix matching.
-Resource content isn't fetched or searched. See
+Resource and prompt content isn't fetched or searched. See
 [discovery and caching](behavior.md#discovery-and-caching) for connection behavior.
 
 ## Activate and call tools

package/docs/troubleshooting.md

@@ -37,13 +37,28 @@ unavailable server isn't an empty catalog.
 | `subscriptions_unsupported` | Choose a server with subscription support, or ask the assistant to read when needed. |
 | `subscription_limit` | Remove a watch before adding another; the limit is 50 per connection. |
 | `catalog_changed` | Ask the assistant to retry discovery after the server catalog settles. |
-| `oauth_failed` | Browser access to the callback and support for public clients, using dynamic registration or the configured client ID. |
+| `oauth_failed` | An unclassified OAuth failure. Check the service's requirements and `/mcp get <server>` for the client type, scopes, and callback URL. Only public/PKCE clients are supported, not clients requiring a secret. |
+| `oauth_client_required` | The server doesn't support dynamic registration. Configure `oauthClientId` for a registered public/PKCE client and register the exact callback URL. Reload, then log in again. |
+| `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_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. |
+| `oauth_endpoint_insecure` | The token endpoint must use HTTPS unless it is on loopback. Don't disable TLS verification. |
 | `oauth_issuer_changed` | Verify the authorization-server change before logging out and logging in again. |
 | `callback_unavailable` | Another process using the configured loopback port (default 19847). Change `oauthCallbackPort` or use `/mcp login <server> --no-browser`. |
 | `busy` | Wait for discovery to finish before reconnecting. |
 | `cancelled` | Retry when ready; verify any interrupted tool operation first. |
 | `operation_failed` | An unclassified failure; inspect server status and configuration. |
 
+If login fails before opening a browser, check client registration first.
+For Slack, see [Slack setup requirements](authentication.md#slack-setup-requirements).
+Use `--no-browser` for browser launch or callback reachability problems, not
+registration failures. Diagnostics use known failure categories rather than
+printing server error descriptions, which can contain credentials or private URLs.
+An unknown error remains `oauth_failed`; it doesn't prove a callback problem.
+
 For setup details, see [Configuration](configuration.md),
 [Authentication](authentication.md), and [Commands](commands.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-client",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MCP tools for Pi, discovered on demand and called natively through the official SDK.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,8 @@
   "dependencies": {
     "@modelcontextprotocol/client": "2.0.0",
     "@napi-rs/keyring": "^1.3.0",
-    "minisearch": "^7.2.0"
+    "minisearch": "^7.2.0",
+    "smol-toml": "^1.8.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.85.1",