pi-mcp-client 0.8.0 → 0.9.0

package/docs/behavior.md

@@ -51,6 +51,41 @@ 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.
 
+## Server requests for input
+
+During a tool call, a server can ask you for information or send you to a web
+page. Pi shows each request in a dialog that names the requesting server. The
+model never sees or answers these dialogs, and the tool call waits until you
+respond. Time spent answering doesn't count against the
+[tool timeout](configuration.md#pi-specific-options).
+
+Form requests list the requested fields with their current values, including
+server defaults. Select a field to change it; Pi validates each value against
+the field's type and constraints. Only **Submit** sends values to the server.
+**Decline** refuses the request, and **Cancel** or Esc dismisses it; the server
+receives no values either way. Don't enter passwords, API keys, or payment
+details in a form. Servers must use a web page for sensitive information.
+
+Web page requests show the site and the full URL before anything opens.
+**Open in browser** launches your default browser. **I'll open it myself**
+confirms without launching one, which is useful over SSH; copy the URL first.
+Pi opens only HTTPS pages, or HTTP pages on this computer, and refuses URLs with
+embedded credentials. Site names with internationalized characters appear in
+their encoded `xn--` form with a warning. Information you enter on the page goes
+to that site, not to Pi.
+
+Some servers refuse to run a tool until you complete a step on a web page. After
+you open the page, Pi waits until the server confirms completion or you choose
+**Done**. The tool doesn't run again automatically: the model receives the
+outcome and can call the tool again after you complete the step.
+
+Pi accepts server requests only in interactive sessions and only while a tool
+call to that server is running. Requests at other times, including during
+resource reads and prompt previews, are refused without a dialog. Headless
+sessions don't offer this capability to servers, so servers that support it
+fall back to their non-interactive behavior. Dialogs appear one at a time.
+Stopping the tool call or ending the session closes any open request.
+
 ## Discovery and caching
 
 Connections start on demand, never while the extension factory loads. A search
@@ -125,7 +160,8 @@ see [large results](troubleshooting.md#large-results) for size limits.
 
 Only load configuration you trust. Server executables and secret commands run
 with your user permissions; trusted project configuration can replace global
-connections and settings.
+connections and settings. See [project trust](#project-trust) for when a
+project's `.mcp.json` loads.
 
 Configuration imports require an explicit file, scope, selection, and final
 confirmation. Import previews hide connection values; review the source file
@@ -148,3 +184,28 @@ Pi's tool restrictions to prevent discovery and resource operations. Already act
 native tools have their own tool restrictions. Per-resource permission policies
 aren't implemented. Prompt selection uses explicit user commands, not the
 model-facing tool allowlist; disable the server to prevent prompt access.
+
+## Project trust
+
+A project's `.mcp.json` can start local commands, so it loads only after an
+explicit trust decision for the folder. Pi asks for trust only in folders with Pi
+project resources, such as `.pi/settings.json` or `.agents/skills`, and trusts
+other folders implicitly. The extension doesn't rely on that implicit trust:
+
+- **Folders with Pi project resources:** Pi's decision applies, including
+  `--approve` and session-only trust.
+- **Other folders:** a saved decision for the folder or a parent folder applies.
+  Without one, Pi's `defaultProjectTrust` setting applies: `always` loads project
+  servers and `never` ignores them. With the default `ask`, interactive sessions
+  ask when a `.mcp.json` exists, and headless sessions ignore the file.
+- **Untrusted folders:** `--no-approve` or a refusal in Pi always ignores project
+  servers.
+
+Saved answers go to Pi's project trust store, so they also apply to Pi project
+resources. Use Pi's `/trust` command to save or change a decision, then run
+`/mcp reload`; MCP servers don't require a restart. In folders without Pi project
+resources, `--approve` doesn't trust `.mcp.json`; save a decision instead.
+
+Only session start and `/mcp reload` ask. Other configuration commands, such as
+`/mcp add` and `/mcp import`, use the current decision. Untrusted project files
+are neither read nor changed.

package/docs/commands.md

@@ -120,8 +120,9 @@ capabilities you need.
 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.
+- **Project:** `.mcp.json` in the current
+  [trusted project](behavior.md#project-trust). Untrusted project files are
+  neither read nor changed.
 
 Add an HTTP server by URL, or a stdio server after `--`:
 
@@ -194,7 +195,8 @@ automatically; no conversion file is needed:
 ```
 
 The command requires an interactive TUI or RPC session and an explicit
-`--scope global` or `--scope project`. Project scope requires a trusted project.
+`--scope global` or `--scope project`. Project scope requires a
+[trusted project](behavior.md#project-trust).
 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.
 

package/docs/configuration.md

@@ -3,9 +3,10 @@
 [Back to the README](../README.md)
 
 You configure which servers the model 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
+`~/.pi/agent/mcp.json`, or `.mcp.json` in a
+[trusted project](behavior.md#project-trust). 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
@@ -16,8 +17,10 @@ MCP configuration standard. Live configuration must use JSON, not VS Code's
 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.
+Project servers need an explicit trust decision even in folders that Pi trusts
+implicitly; see [project trust](behavior.md#project-trust). An explicitly named
+import source is read as data for review; saving into project scope still
+requires project trust.
 
 ```json
 {
@@ -44,13 +47,24 @@ scope still requires project trust.
 | `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. |
+| `env` | Environment variables for stdio, in addition to a minimal inherited set. |
 | `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.
 
+Stdio servers don't inherit Pi's environment. They receive only the MCP SDK's
+default set (`HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, and `USER` on Unix, and
+similar system variables on Windows) plus `env`. Pass other variables a server
+needs explicitly, for example a custom browser location:
+
+```json
+"env": {
+  "PLAYWRIGHT_BROWSERS_PATH": "${PLAYWRIGHT_BROWSERS_PATH}"
+}
+```
+
 Only stdio and Streamable HTTP are supported. The extension rejects `type: "sse"`
 and unsupported connection fields rather than silently changing their meaning.
 
@@ -128,7 +142,7 @@ server definition:
 | `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. |
+| `toolTimeoutMs` | Optional timeout for tool calls only, from 100 to 600000 ms. Overrides `timeoutMs` for calls without changing metadata or resource deadlines. Time spent answering [server requests](behavior.md#server-requests-for-input) doesn't count. |
 | `protocol` | `auto` (default) for SDK protocol-version negotiation, or `legacy` for an explicit legacy handshake. |
 
 OAuth client IDs, scopes, and callback ports require HTTP without an Authorization

package/docs/tool-reference.md

@@ -71,6 +71,13 @@ is needed, first use follows three steps: discover, activate, then call the nati
 tool. There is no invocation proxy. Previously loaded tools remain available;
 [session behavior](behavior.md#sessions) describes restoration and tool restrictions.
 
+A call can pause while the user answers a
+[server request for input](behavior.md#server-requests-for-input); the model
+never sees the dialog or its values unless the server includes them in its
+result. When a server requires a browser step first, the call fails with an
+`elicitation_*` diagnostic and isn't replayed. After `elicitation_completed`,
+the model can call the tool again.
+
 ## Read resources as context
 
 For a request such as “Use the authentication guide to explain this API,” the

package/docs/troubleshooting.md

@@ -37,6 +37,9 @@ unavailable server isn't an empty catalog.
 | `subscriptions_unsupported` | Choose a server with subscription support, or ask the model to read when needed. |
 | `subscription_limit` | Remove a watch before adding another; the limit is 50 per connection. |
 | `catalog_changed` | Ask the model to retry discovery after the server catalog settles. |
+| `elicitation_required` | The server needs you to complete a step on a web page before the tool runs. Use an interactive session, then ask the model to retry. |
+| `elicitation_declined` | You declined or dismissed the server's web page request, so the tool didn't run. Ask the model to retry when you're ready. |
+| `elicitation_completed` | You completed the server's web page step. The tool didn't run yet; the model can call it again. |
 | `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. |
@@ -69,6 +72,21 @@ 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.
 
+## Missing project servers
+
+A project's `.mcp.json` loads only after an explicit trust decision, even in
+folders that Pi otherwise trusts implicitly. Headless sessions ignore it when no
+decision exists. Run Pi's `/trust` command to save a decision, then run
+`/mcp reload`. See [project trust](behavior.md#project-trust).
+
+## Missing server dependencies
+
+If a stdio server reports a missing browser, SDK, credential, or configuration
+file that works in your shell, it probably reads an environment variable that
+it doesn't receive. Servers don't inherit Pi's environment; pass the variable
+through `env`, for example `PLAYWRIGHT_BROWSERS_PATH`. See
+[files and transports](configuration.md#files-and-transports).
+
 ## Large results
 
 Text output is limited to 2,000 lines or 50 KiB, including resource reads and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-client",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "MCP tools for Pi, discovered on demand and called natively through the official SDK.",
   "type": "module",
   "license": "MIT",