pi-mcp-client 0.4.0 → 0.6.0

package/docs/commands.md

@@ -0,0 +1,294 @@
+# 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, use prompts, 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 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 prompts <server>` | Browse prompt metadata, then select a prompt and enter arguments. |
+| `/mcp prompt <server> <name> [argument=value ...]` | 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, 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. |
+
+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.
+
+## 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 prompts 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`
+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.
+
+## 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:
+
+```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,159 @@
+# 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). 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. 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 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
+{
+  "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. |
+| `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
+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. 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
+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,157 @@
+# 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, 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. |
+
+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`, `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
+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 and prompt 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.