pi-mcp-client 0.4.0 → 0.5.0

package/docs/behavior.md

@@ -0,0 +1,114 @@
+# 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.
+
+## 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, 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,
+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.
+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.
+
+Server metadata and resource 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
+`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.

package/docs/commands.md

@@ -0,0 +1,171 @@
+# Commands
+
+[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
+separate interface is documented in the [tool reference](tool-reference.md).
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `/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 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 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 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. |
+
+See [Authentication](authentication.md) for login and logout procedures, and
+[Apply changes](configuration.md#apply-changes) for reload behavior.
+
+## Inspect servers and tools
+
+The `/mcp` status matrix distinguishes idle (`○`), connected (`●`), connecting
+(`▶︎`), disabled (`○`), and failed (`✘︎`) servers. Idle is normal: connections open
+on demand. A dash (`—`) means the catalog hasn't been fetched, not that the server
+has no tools. The **Loaded** column counts tools currently active for the
+assistant.
+
+Use `/mcp get <server>` to check the effective transport, protocol, filters,
+and connection status without connecting or running secret commands. Connection
+values—including commands, arguments, URLs, headers, and environment variables—
+are hidden because any of them can contain credentials. Authentication status
+shows whether OAuth tokens are stored, not whether they are valid. A locked or
+unavailable credential store is reported separately from missing tokens. Header
+and stdio credentials are identified as externally managed; inspection never
+executes them.
+
+Use `/mcp tools <server>` to fetch the current catalog and browse a scrollable
+list. Rows show tool names and descriptions, trimmed to the terminal width with
+an ellipsis. Select a tool to see a multiline signature and parameter details,
+with each parameter in a separate paragraph. Browsing respects your include and
+exclude filters and doesn't activate tools or add their schemas to the assistant's
+context. This command requires an interactive UI.
+
+Refreshing a catalog doesn't replace active tool definitions. After a schema
+change, ask the assistant to activate the exact tool again. See
+[tool changes and caching](behavior.md#discovery-and-caching). Failed tool calls
+aren't retried automatically; verify whether an interrupted operation completed
+before trying again.
+
+## Enable and disable servers
+
+Use `/mcp disable <server>` or `/mcp enable <server>` to change the `disabled`
+option without editing JSON. The command reports which scope changed: the trusted
+project's `.mcp.json` if it defines the server, otherwise the global
+`~/.pi/agent/mcp.json`. Untrusted project files are neither read nor changed.
+
+Toggles preserve other values, including secret references, and reformat the file
+as indented JSON. Repeating a toggle that's already set leaves the file unchanged.
+Both commands wait for active agent work to finish, then
+[apply the configuration](configuration.md#apply-changes).
+
+Disabling removes the server from discovery and deactivates its tools. Enabling
+doesn't connect, authenticate, or load tools; ask the assistant to discover the
+capabilities you need.
+
+## Add and remove servers
+
+Both commands require an explicit `--scope global` or `--scope project`:
+
+- **Global:** `~/.pi/agent/mcp.json`.
+- **Project:** `.mcp.json` in the current trusted project. Untrusted project files
+  are neither read nor changed.
+
+Add an HTTP server by URL, or a stdio server after `--`:
+
+```text
+/mcp add --scope global docs https://docs.mcp.cloudflare.com/mcp
+/mcp add --scope project local -- node "/path with spaces/server.js"
+```
+
+Put options before the server name. `--transport http` or `--transport stdio` is
+optional; the URL form selects HTTP and the `--` form selects stdio. Arguments
+support single and double quotes and backslash escaping, but are never evaluated
+by a shell. Shell syntax such as `$(...)`, pipes, and globs stays literal. For
+Windows paths with backslashes, single quotes preserve the path verbatim.
+
+| Option | Purpose |
+| --- | --- |
+| `--replace` | Replace the complete definition in the selected scope, or create an override of a same-named definition in the other scope. Existing fields aren't merged. |
+| `--header 'Name: value'` | Add an HTTP header. Repeat for different header names. |
+| `--env KEY=value` | Add a stdio environment override. Repeat for different variable names. |
+| `--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. |
+
+Retain environment references rather than typing tokens:
+
+```text
+/mcp add --scope global --header 'Authorization: Bearer ${DOCS_TOKEN}' docs https://mcp.example.com/mcp
+/mcp add --scope global --oauth-client-id '${CLIENT_ID}' service https://mcp.example.com/mcp
+```
+
+Define referenced environment variables before running the command. Validation
+checks the resolved configuration, but saves the references, not their values.
+Secret commands in headers or environment overrides are saved without running
+them. Avoid literal credentials in command input or project files; use
+[environment references and secret commands](configuration.md#secret-commands).
+
+Adding never starts a server, opens a browser, or activates tools. Duplicate names
+in global or trusted project configuration are rejected unless you supply
+`--replace`. Project definitions take precedence; writing a global definition
+doesn't replace a project override. Other server options, such as tool filters,
+remain available by editing the configuration file.
+
+Remove a definition from a specific scope:
+
+```text
+/mcp remove --scope project local
+```
+
+Removal is distinct from disabling and logout: it deletes the selected definition,
+not its OAuth credentials. Run `/mcp logout <server>` first if you also want to
+remove credentials. Removing a project override exposes any same-named global
+definition; the command reports when a definition in the other scope remains.
+Removing a name absent from the selected scope fails without changing either file.
+
+Successful edits [apply immediately](configuration.md#apply-changes). Writes
+preserve unrelated settings, follow existing file symlinks, and replace files
+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.
+
+## Watch resource changes
+
+Subscriptions are explicit user commands, not model-facing tool operations:
+
+```text
+/mcp subscribe warehouse schema://tables/events
+/mcp subscriptions
+/mcp unsubscribe warehouse schema://tables/events
+```
+
+Use an exact absolute URI from discovery, a template read, or a resource link.
+The configured server must support resource subscriptions. The extension uses the
+SDK's negotiated protocol: legacy resource subscriptions or modern filtered
+streams. It never opens the URI as a file or generic URL.
+
+An update marks the watch as changed (`↻`) and shows a UI notification. Repeated
+updates coalesce into that marker until you unsubscribe. No content is fetched,
+no model turn starts, and existing resource results remain unchanged. Ask the
+assistant to read the resource for a new snapshot; unsubscribe and subscribe again
+to reset the change marker.
+
+Watches are memory-only, limited to 50 per server connection, and require an
+interactive UI (TUI or RPC). Repeating a subscribe command is idempotent. Session
+replacement, tree navigation, configuration reload, disconnection, and exit clear
+the affected watches. They are never restored or automatically retried; use
+`/mcp subscriptions` to inspect active watches. Cancellation and connection
+failures can leave an uncertain server-side outcome; cleanup is best-effort.

package/docs/configuration.md

@@ -0,0 +1,150 @@
+# Configuration
+
+[Back to the README](../README.md)
+
+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).
+
+## 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.
+Project definitions replace same-named global definitions in full; fields and
+filters aren't merged. Untrusted project files are neither read nor changed.
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${DOCS_TOKEN}"
+      }
+    },
+    "local": {
+      "command": "node",
+      "args": ["/absolute/path/to/server.js"],
+      "env": {
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+| Field | Purpose |
+| --- | --- |
+| `type` | Optional `stdio` or `http`. If omitted, inferred from `command` or `url`. A conflicting type is rejected. |
+| `command`, `args` | Executable and arguments for a stdio server. No shell is used. |
+| `cwd` | Working directory for stdio; defaults to Pi's current directory. Relative paths resolve there. |
+| `env` | Additional environment variables for stdio. |
+| `url` | Streamable HTTP endpoint; mutually exclusive with `command`. |
+| `headers` | HTTP request headers, including optional bearer authentication. |
+
+Strings in `command`, `args`, `cwd`, `env`, `url`, and `headers` support `${VAR}`
+interpolation. Missing variables prevent that server from connecting.
+
+Only stdio and Streamable HTTP are supported. The extension rejects `type: "sse"`
+and unsupported connection fields rather than silently changing their meaning.
+
+The extension uses `@modelcontextprotocol/client` 2.0.0 and defaults to automatic
+SDK protocol-version negotiation. On stdio, negotiation probes using an additional
+short-lived process. Set `"protocol": "legacy"` if the server requires an explicit
+legacy handshake.
+
+## Secret commands
+
+In **`headers` and stdio `env` values only**, a leading `!` runs a secret-generating
+shell command when the server connects:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "!token=$(op read 'op://Private/Example/token') && printf 'Bearer %s' \"$token\""
+      }
+    }
+  }
+}
+```
+
+These two fields also support Pi-style `$VAR` interpolation, `$$` for a literal
+`$`, and `$!` for a literal `!`. Only a leading `!` in the original configuration
+triggers execution; interpolated values and command output never do. Shell
+commands handle their own variable expansion.
+
+Commands use `/bin/sh` on Unix or Pi's shell selection on Windows, inherit Pi's
+process environment, and run in the server's configured `cwd` (the project
+directory by default). They run once per connection, including reconnections,
+not during configuration loading, status display, or cached discovery. Cold
+searches and activations can connect and therefore execute commands. Concurrent
+connection requests share the same resolution.
+
+The extension trims stdout and rejects empty output, nonzero exits, output above
+64 KiB, and resolution taking more than 10 seconds (or a shorter `timeoutMs`).
+Session shutdown cancels pending commands. Cancelling an individual search or
+activation stops waiting but leaves shared connection work running for other
+callers.
+
+The extension discards command stderr and doesn't include resolved secrets in
+errors, session records, or catalog caches. Commands themselves remain responsible
+for avoiding side effects or writing secrets to disk. Only configure commands you
+trust; project configuration still requires project trust.
+
+## Pi-specific options
+
+Put descriptions, authentication choices, filters, and timeouts directly in each
+server definition:
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "https://mcp.example.com/mcp",
+      "description": "Search product documentation",
+      "includeTools": ["get_*", "search_*"]
+    }
+  }
+}
+```
+
+| Field | Purpose |
+| --- | --- |
+| `description` | Short capability description for the assistant's server directory. |
+| `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`. |
+| `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`. |
+| `timeoutMs` | Request timeout, from 100 to 600000 ms. Defaults: 15 seconds for discovery/HTTP requests, 30 seconds for stdio tool calls. |
+| `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
+header. HTTP authentication is automatic; remove the obsolete `oauth` field from
+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.
+
+Tool filters don't restrict resource reads. See
+[trust and permissions](behavior.md#trust-and-permissions) for access boundaries
+and [authentication](authentication.md) for OAuth setup.
+
+## Apply changes
+
+After editing a file, run `/mcp reload`. The extension validates the new
+configuration before replacing the current setup; invalid configuration leaves
+the previous setup intact. Reload closes connections, which reopen on demand,
+and deactivates tools from changed, removed, or disabled definitions. Unchanged
+active tools remain available.
+
+Server-management commands apply saved changes using the same reconciliation.
+Other running Pi sessions pick up those changes when you reload their MCP
+configuration. See [Commands](commands.md) for toggling, inspecting, adding, and
+removing servers.

package/docs/tool-reference.md

@@ -0,0 +1,147 @@
+# Assistant tool reference
+
+[Back to the README](../README.md)
+
+This page documents **the assistant's interface**. The examples illustrate tool
+calls the assistant makes; they aren't slash commands or JavaScript for you to
+run. Describe your task in natural language. For operations you control directly,
+see [Commands](commands.md).
+
+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. |
+| `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. |
+
+The assistant passes exactly one of `query`, `activate`, `read`, or `complete`.
+The optional `kind`, `server`, and `limit` fields are query-only; reads and
+completions carry their server inside their respective objects.
+
+## Discover capabilities
+
+```js
+// Search tool and resource metadata on one server.
+mcp_tools({ query: "database schema", server: "warehouse", limit: 5 })
+
+// Restrict one search to tools.
+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.
+
+Tool candidates show an exact activation identifier, a short description,
+required parameter names only, and `[loaded]` if already active. Resource
+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.
+
+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
+[discovery and caching](behavior.md#discovery-and-caching) for connection behavior.
+
+## Activate and call tools
+
+```js
+mcp_tools({ activate: ["linear.list_teams", "linear.get_team"] })
+```
+
+Activation accepts 1–50 exact `server.tool` or `mcp__server__tool` identifiers,
+ignores duplicates, and works without a prior search. Typos never activate fuzzy
+matches: failures list nearby catalog names when available so the assistant can
+retry with an exact identifier. Each identifier reports `loaded`, `already loaded`,
+or `not loaded` with a reason. Partial success keeps the tools that loaded.
+
+Full schemas become available on the model turn after activation. When discovery
+is needed, first use follows three steps: discover, activate, then call the native
+tool. There is no invocation proxy. Previously loaded tools remain available;
+[session behavior](behavior.md#sessions) describes restoration and tool restrictions.
+
+## Read resources as context
+
+For a request such as “Use the authentication guide to explain this API,” the
+assistant can discover and read relevant context:
+
+```js
+mcp_tools({ query: "authentication guide", kind: "resources" })
+mcp_tools({ read: { server: "docs", uri: "docs://authentication" } })
+```
+
+A read fetches one exact resource URI through its configured server's MCP
+`resources/read` operation. It doesn't open a local file or make a generic HTTP
+request, even for `file:` or `https:` URIs. There is no fallback when the server
+can't read the URI. The server still controls which data it returns.
+
+Tool-returned resource links include an exact `mcp_tools({read: ...})` call. The
+assistant can read such links directly, without prior discovery or activation;
+linked resources don't have to appear in the catalog.
+
+Reading attaches content as the tool result itself, not as a second message. The
+result identifies the source server and URIs and labels the content as untrusted
+data. See [resource snapshots](behavior.md#resource-snapshots) for freshness and
+session privacy, and [large results](troubleshooting.md#large-results) for output
+limits and private spill files.
+
+## Read parameterized resources
+
+Discovery also lists URI templates, such as `schema://tables/{table}`, without
+enumerating every possible table. Templates have a `[template]` label, variable
+names, and a read-call shape. The assistant supplies known argument values:
+
+```js
+mcp_tools({ query: "table schema", server: "warehouse", kind: "resources" })
+mcp_tools({
+  read: {
+    server: "warehouse",
+    template: "schema://tables/{table}",
+    arguments: { table: "events" }
+  }
+})
+```
+
+The `read` object accepts either `uri` or `template` plus `arguments`, never both.
+The selected server must advertise the exact template. The official SDK expands
+strings or string arrays into a concrete URI, then reads it through that same
+server. Template variables aren't an input schema: no required fields or allowed
+values are inferred. The assistant should use values from your request or prior
+results and ask you when a needed value is unknown rather than inventing an
+identifier.
+
+Argument data is limited to 64 KiB and expanded URIs to 4,096 characters. Template
+reads share exact reads' authorization, cancellation, output limits, and snapshot
+rules. Expanded output includes the template, supplied arguments, and resource
+content; see [result display](behavior.md#result-display).
+
+## Complete resource arguments
+
+The assistant can ask a server for suggested values for one advertised template
+variable:
+
+```js
+mcp_tools({
+  complete: {
+    server: "warehouse",
+    template: "schema://tables/{table}",
+    argument: { name: "table", value: "ev" }
+  }
+})
+```
+
+`value` is the current prefix and can be empty. For dependent suggestions, the
+assistant can add `arguments: { knownVariable: "value" }` inside `complete`.
+These context values must be strings, not arrays. The server must advertise
+completion support and the exact template; the variable must occur in that
+template.
+
+The result contains `values` and, when supplied by the server, `total` and
+`hasMore`. A narrower prefix can reduce the matches. Suggestions are untrusted
+server data, not a required-field schema or instructions. Requests are limited
+to 64 KiB; output uses the same [limits and spill files](troubleshooting.md#large-results)
+as other results.
+
+Resource subscriptions aren't part of this tool. Only you can
+[watch resource changes](commands.md#watch-resource-changes) with `/mcp` commands.

package/docs/troubleshooting.md

@@ -0,0 +1,67 @@
+# Troubleshooting
+
+[Back to the README](../README.md)
+
+Start with `/mcp` to inspect server status and `/mcp get <server>` to inspect
+configuration without connecting. Failures use a consistent code, a short
+explanation, and a recovery hint, for example:
+
+```text
+linear: [authentication_required] Authentication is required. Run /mcp login linear.
+```
+
+## Diagnostic codes
+
+Search and tool results also carry structured diagnostics in their result details:
+`code`, `operation`, optional `server`, `message`, and `hint`. Partial discovery
+keeps healthy servers' results and identifies servers it couldn't search. An
+unavailable server isn't an empty catalog.
+
+| Code | What to check |
+| --- | --- |
+| `configuration_invalid` | JSON syntax, supported fields, transport type, and required environment variables. Run `/mcp reload` after editing. |
+| `authentication_required` | Run `/mcp login <server>` for OAuth, or check the Authorization header. |
+| `permission_denied` | Account permissions, OAuth scopes, and service access policy. |
+| `credential_store_unavailable` | Unlock or enable the OS keyring; Linux needs a Secret Service session. |
+| `secret_lookup_failed` | Secret helper installation, login, exit status, nonempty stdout, and output size. |
+| `connection_failed` | Server executable, working directory, endpoint, network, and TLS configuration. |
+| `timeout` | Server responsiveness and the applicable request, secret-command, or OAuth time limit. |
+| `protocol_error` | Server compatibility and the `protocol` setting. |
+| `tool_changed` | Check server filters and ask the assistant to activate the exact tool again for its current schema. Run `/mcp reload` if connection configuration changed. |
+| `tool_error` | The server's tool result and inputs; verify the outcome before retrying. |
+| `resource_invalid` | The assistant needs an exact absolute resource URI from discovery or a tool-returned link. |
+| `resource_not_found` | Refresh resource metadata or obtain a new link. |
+| `resources_unsupported` | Ask the assistant to use the server's tools instead, or choose a resource-capable server. |
+| `completions_unsupported` | Supply known template values; the assistant should ask you if a value is missing. |
+| `completion_invalid` | The assistant needs an advertised template variable and a string prefix. |
+| `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_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. |
+
+For setup details, see [Configuration](configuration.md),
+[Authentication](authentication.md), and [Commands](commands.md).
+
+Diagnostics never echo raw exception messages, HTTP bodies, command stderr,
+credential values, or stack traces. Unknown errors stay generic rather than being
+classified by potentially sensitive message text. Server-provided tool results
+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.
+
+## Large results
+
+Text output is limited to 2,000 lines or 50 KiB, including resource reads and
+completions. Larger results are saved in private temporary files, with paths
+included in the output. Full tool results use JSON files. Supported images pass
+through within an 8 MiB base64 budget; unsupported or oversized binary content is
+retained in the full result file.
+
+A resource read fetches the server's full response before applying output limits;
+it isn't a streaming or partial-content reader. Temporary result files aren't
+automatically deleted and may contain sensitive data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP tools for Pi, discovered on demand and called natively through the official SDK.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],