pi-mcp-client 0.3.3 → 0.5.0

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.3.3",
+  "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"
   ],