@ikuma.cloud/pix-mcp 0.0.8 → 0.0.10

package/README.md

@@ -1,8 +1,8 @@
 # @ikuma.cloud/pix-mcp
 
 A small Pi MCP adapter: discover tools, load their schemas on demand, call
-those tools natively, and run user-selected MCP prompts. No scripting engine or
-model-provider-specific API is required.
+those tools natively, and use user-selected MCP prompts and resources. No
+scripting engine or model-provider-specific API is required.
 
 ## Usage
 
@@ -13,34 +13,60 @@ pi -e /absolute/path/to/pix/packages/pix-mcp
 ```
 
 Disable any other MCP adapter that would collide with the `mcp` tool,
-`/mcp-prompt` command, or flags, but keep any permission-control extensions
-enabled. Review the configuration and automatic startup behavior below before
-connecting servers.
+`/mcp-prompt` or `/mcp-resource` commands, or flags, but keep any
+permission-control extensions enabled. Review the configuration and automatic
+startup behavior below before connecting servers.
+
+From this repository, the included configuration launches the pinned MCP
+Everything server for manual prompt and resource testing:
+
+```sh
+mise run mcp:dev --mcp-config pix-mcp-test.json
+```
+
+Review the file first; `npx` downloads and runs the pinned package.
 
 ## Configuration
 
-By default, read only `.mcp.json` in Pi's working directory. There is no ancestor
-search, global config merge, automatic import, or persistent metadata cache.
-Relative `--mcp-config` paths resolve from that working directory; a stdio
-server's `cwd` resolves from the config directory and defaults to that directory.
+Without an explicit selection, the adapter reads these files in order:
 
-The adapter automatically loads the selected file and starts its enabled servers
-in all modes, without a confirmation prompt. Use `--mcp-config <path>` to select
-a different file.
+1. `<agent-dir>/mcp.json` for user-level servers. Pi's agent directory defaults
+   to `~/.pi/agent` and can be changed with `PI_CODING_AGENT_DIR`.
+2. `.mcp.json` in Pi's working directory for project-level servers.
 
-**Breaking change:** `--mcp-trust-config` has been removed. Remove it from existing
-launch commands; print and JSON sessions also load the default file automatically.
+Missing files are ignored. Project declarations replace global declarations by
+server name as complete entries; fields are not merged. A project entry with
+`"disabled": true` masks the corresponding global server. An invalid project
+entry also masks its global counterpart and reports the validation issue instead
+of starting the global definition. Relative stdio `cwd` values resolve from the
+file that declares the server and default to that file's directory. There is no
+ancestor search, cross-client import, or persistent metadata cache.
+
+Use `--mcp-config <path>` to read only that file for the session, without global
+or project fallback. A relative explicit path resolves from Pi's working
+directory. The adapter automatically starts every effective enabled server in all
+modes without a confirmation prompt.
 
-Review the file before starting Pi: it can launch arbitrary local programs and
-contact remote services. A bare `.mcp.json` is not protected by Pi's project-trust
-mechanism, and the adapter is not an OS sandbox. Set a server's `disabled` field
-to `true` to prevent it from starting.
+`getAgentDir()` cannot observe an `agentDir` supplied only through Pi 0.87's SDK
+because extensions do not receive it. Embedded users should also set
+`PI_CODING_AGENT_DIR` when they want the global file to follow an SDK override.
 
-At session startup, interactive and RPC sessions receive an `MCP config: <path>`
-notice with the resolved absolute path after the file is read. The notice
-identifies the configuration file, not whether every server connected; it never
-includes configuration contents. Missing, unreadable, or malformed files produce
-no notice. Print and JSON sessions remain silent.
+**Breaking change:** `--mcp-trust-config` has been removed. Remove it from existing
+launch commands; print and JSON sessions also load the default files
+automatically.
+
+Review both files before starting Pi: they can launch arbitrary local programs
+and contact remote services. Global servers start in every working directory. A
+bare project `.mcp.json` is not protected by Pi's project-trust mechanism, and
+the adapter is not an OS sandbox. Set a server's `disabled` field to `true` to
+prevent it from starting.
+
+At session startup, interactive and RPC sessions display every successfully
+loaded file as `MCP config (<scope>): <absolute-path>`, in precedence order. They
+display `MCP config: none found` when no applicable file exists, or a path-only
+error notice when a file fails to load. These notices occur before server startup
+and never include configuration contents or indicate that every server connected.
+Print and JSON sessions remain silent.
 
 ```json
 {
@@ -83,7 +109,7 @@ URLs, and HTTP headers.
 | `type` | `stdio`, `http`, or `streamable-http` (alias of `http`); only stdio is inferred, when `command` is present |
 | `command`, `args`, `env` | Stdio only; executable and argument array, not a shell command |
 | `url`, `headers` | Streamable HTTP only; explicit `type` required; no legacy SSE fallback or redirect following |
-| `timeout` | Hard deadline for each tool invocation or prompt retrieval, in milliseconds; default 30000 |
+| `timeout` | Hard deadline for each tool invocation, prompt retrieval, or resource read, in milliseconds; default 30000 |
 | `cwd` | Stdio extension: working directory relative to the config directory |
 | `description` | Discovery extension: optional summary, truncated to 500 characters |
 | `startupTimeoutMs` | pix extension: complete connection/initialization handshake deadline; default 30000 |
@@ -101,15 +127,17 @@ Unknown fields invalidate their server entry rather than being silently ignored.
 
 ### Configuration errors
 
-An invalid server entry is skipped without hiding healthy servers. Discovery's
-`servers` list includes a safe diagnostic for each skipped entry; a valid server
-name can still be used with `mcp({ action: "list", server: "name" })` to inspect
+An invalid server entry is skipped without hiding unrelated healthy servers.
+Discovery's `servers` list includes a safe diagnostic for each skipped entry; a
+valid server name can still be used with `mcp({ action: "list", server: "name" })` to inspect
 its status. Invalid names are replaced with their one-based entry positions.
 Diagnostics identify supported fields or migration steps without echoing URLs,
 commands, headers, argument values, or environment-variable names.
 
 Malformed JSON, invalid root structure, unknown root fields, and the file/server
-count limits remain fatal for the whole file. An invalid-only configuration
+count limits remain fatal. A fatal error in either default file prevents servers
+from the other file from starting. Each file may declare at most 32 entries, and
+the merged result may enable at most 32 servers. An invalid-only configuration
 reports that no valid servers remain. Disabled entries are omitted, not reported
 as failed connections. Correct the file and reload Pi to retry.
 
@@ -117,9 +145,9 @@ as failed connections. Correct the file and reload Pi to retry.
 
 All three deadline fields accept integers from 1 through 2,147,483,647 milliseconds
 (Node's timer-safe maximum). Each defaults independently to 30 seconds. Setting
-`"timeout": 960000` permits a 16-minute tool call or prompt retrieval without
-lengthening startup or discovery. The invocation clock starts after connection
-startup; progress does not reset it. Catalog deadlines cover all pages of one
+`"timeout": 960000` permits a 16-minute tool call, prompt retrieval, or resource
+read without lengthening startup or discovery. The invocation clock starts after
+connection startup; progress does not reset it. Catalog deadlines cover all pages of one
 snapshot; a subsequent list-change refresh starts a new deadline.
 
 HTTP deadlines cover response headers and bodies, including JSON and SSE. MCP
@@ -130,8 +158,9 @@ Upstream proxies and servers may still impose their own limits.
 
 **Breaking changes from 0.0.1:**
 
-- Replace `timeoutMs` with `timeout` for tool calls. Set `startupTimeoutMs` and
-  `catalogTimeoutMs` separately if their defaults are unsuitable. The removed
+- Replace `timeoutMs` with `timeout` for tool calls, prompt retrievals, and
+  resource reads. Set `startupTimeoutMs` and `catalogTimeoutMs` separately if
+  their defaults are unsuitable. The removed
   field produces a migration diagnostic; it is not an alias.
 - Add `"type": "http"` to remote entries that previously specified only `url`.
 - Connection strings now expand environment references beyond `env` and `headers`.
@@ -159,10 +188,9 @@ credentials; debug a failing server separately in a trusted environment.
 ## Discovery and execution
 
 At session startup, the adapter connects to enabled servers and fetches their
-advertised paginated tool and prompt catalogs. A server's configuration,
-connection, or discovery failure does not hide healthy features from other
-servers.
-Full schemas stay out of model context until selected. **Schema exposure is lazy;
+advertised paginated tool, prompt, resource, and resource-template catalogs. A
+server's configuration, connection, or discovery failure does not hide healthy
+features from other servers. Full schemas stay out of model context until selected. **Schema exposure is lazy;
 initial connections and metadata discovery are not.**
 
 The agent uses the `mcp` tool:
@@ -198,8 +226,8 @@ exceptions, schema contents, invalid tool names, and dialect URLs are not expose
 
 An unsupported output schema still fails that server's tool discovery rather than
 producing a per-tool rejection. Losing an established HTTP notification stream
-withdraws tool and prompt catalogs rather than silently keeping stale metadata;
-servers that decline the optional stream with HTTP 405 remain usable. Reload Pi
+withdraws tool, prompt, and resource catalogs rather than silently keeping stale
+metadata; servers that decline the optional stream with HTTP 405 remain usable. Reload Pi
 to reconnect a failed server or reread configuration.
 
 Pi handles provider compatibility. Some providers support transcript-anchored
@@ -282,12 +310,12 @@ every mode; `run` submits immediately and can pass an intentional empty value as
 `name=`.
 
 Arguments use shell-style quoting. Positional values map to the prompt's declared
-argument order; `name=value` selects a declared argument explicitly. Quote or escape
-an equals sign in a positional value (for example, `"a=b"` or `a\=b`) to avoid
-assignment parsing. Argument names containing `=` work when the name is quoted,
+argument order; `name=value` selects a declared argument explicitly. Quote or
+escape an equals sign in a positional value (for example, `"a=b"` or `a\=b`) to
+avoid assignment parsing. Argument names containing `=` work when the name is quoted,
 as in `"x=y"=value`. The adapter checks required arguments before sending
-`prompts/get`. Prompt retrieval uses the
-server's `timeout`; prompt discovery uses `catalogTimeoutMs` and follows pagination.
+`prompts/get`. Prompt retrieval uses the server's `timeout`; prompt discovery uses
+`catalogTimeoutMs` and follows pagination.
 Prompt list-change notifications atomically replace that server's prompt catalog.
 Duplicate or invalid prompt metadata fails only that server's prompt catalog. A
 prompt discovery failure does not hide healthy tools, and a tool discovery failure
@@ -305,6 +333,60 @@ Prompt metadata and bodies are untrusted server content. Catalog metadata stays
 in command UI; a prompt body enters model context only after the user explicitly
 runs it. Review configured servers and selected prompts accordingly.
 
+## Resources
+
+MCP resources are application-controlled and are not exposed as model-callable
+tools. Use the stable `/mcp-resource` command:
+
+```text
+/mcp-resource
+/mcp-resource list [server]
+/mcp-resource read <server> <uri-or-template> [name=value ...]
+```
+
+In TUI mode, the bare command opens a native selector for direct resources and
+resource templates. Focusing an item shows its bounded metadata but does not read
+it. Selecting a template requests every variable in declaration order and expands
+it according to [RFC 6570 Level 4](https://www.rfc-editor.org/rfc/rfc6570).
+Escape cancels without reading. The result is placed in Pi's editor for review;
+image contents use private temporary `@` references that are removed at session
+shutdown.
+
+The explicit `list` and `read` forms work in every mode. `read` immediately sends
+the resource contents as a user message and starts or queues a model turn; Pi
+commands do not provide a raw structured-result channel. A concrete URI need not
+appear in the catalog, allowing known or optional-template URIs to be read
+explicitly. Arguments are accepted only when the target exactly matches a
+cataloged template. Template variables use the same shell-style positional and
+`name=value` syntax as prompt arguments. MCP does not mark template variables as
+required: omitted variables use RFC 6570's undefined-variable behavior, leaving a
+picker input empty omits it, and explicit `name=` supplies an intentional empty
+value. The expanded result must still be a valid absolute URI. MCP completion
+requests for variable values are not supported.
+
+Each returned content item gets a server/URI source marker because one read can
+return multiple resources. Text and supported images are retained in order.
+Non-image blobs and oversized or unsupported content are omitted from the preview
+and preserved in the private full-result artifact. Unsafe terminal and
+bidirectional controls are removed from displayed or editable text; the original
+content remains in the artifact when sanitization changes it, while `_meta` is
+excluded.
+
+Direct resources and templates are discovered independently from tools and
+prompts, but committed together as one atomic per-server resource snapshot.
+Resource list-change notifications refresh both catalogs. Duplicate, malformed,
+or oversized metadata fails only that server's resource catalog. Picker
+selections are rejected if any catalog refresh replaces the selected entry while
+variables are being collected, content is being read or formatted, or the editor
+is being updated.
+
+Resource metadata, URIs, template values, and bodies are untrusted server content.
+Icons are neither displayed nor fetched, `_meta` is not retained or included in
+resource artifacts, and URIs containing userinfo credentials are rejected. A body
+enters model context only after an explicit user selection or `read` command. Resource subscriptions
+and update notifications are not supported, and resources are never reread or
+injected automatically.
+
 ## Output and limits
 
 Text, supported images, and structured content are retained. Long text gets a
@@ -314,22 +396,31 @@ content is explicitly omitted from the preview, not silently discarded. Pi's
 error-result path is text-only, so images in MCP errors are preserved in a
 full-result artifact rather than displayed inline.
 
-When necessary, the full MCP tool or prompt result is written to
+When necessary, the full MCP tool, prompt, or resource result is written to
 `pix-mcp-*/result.json` under the system temp directory (directory mode 0700,
-file mode 0600). Pi can inspect it with `read`. These artifacts may contain
-sensitive data and are **not deleted at session shutdown**; remove them when no
+file mode 0600). Pi can inspect it with `read`; resource artifacts omit `_meta`.
+These artifacts may contain sensitive data and are **not deleted at session
+shutdown**; remove them when no
 longer needed. Output limits are not a complete memory or security sandbox.
 
-Configuration is limited to 256 KiB and 32 servers. Startup connects at most four
-servers concurrently. Each tool or prompt catalog is limited to 1000 entries,
-100 pagination cursors, and 2 MiB of metadata; individual input/output schemas are
-limited to 64 KiB. Prompt arguments are limited to 256 KiB per retrieval;
-prompt and prompt-argument names are limited to 256 bytes, cannot contain Unicode
-control, format, or line-separator characters, and each prompt can declare at most
-100 arguments. Tool names must use 1–128 ASCII letters, digits,
-underscores, hyphens, or periods. Tool and prompt descriptions, prompt-argument
-descriptions, and prompt titles are limited to 16 KiB. Stdio messages are limited
-to 16 MiB.
+Each configuration file is limited to 256 KiB and 32 entries; the merged result
+can enable at most 32 servers. Startup connects at most four servers concurrently.
+Each tool or prompt catalog is limited to 1000 entries,
+100 pagination cursors, and 2 MiB of metadata. Direct resources and templates
+share a 1000-entry and 2 MiB limit, with up to 100 cursors for each endpoint.
+Individual input/output schemas are limited to 64 KiB. Prompt arguments and
+resource-template arguments are limited to 256 KiB per retrieval; prompt and
+prompt-argument names are limited to 256 bytes, cannot contain Unicode control,
+format, or line-separator characters, and each prompt can declare at most 100
+arguments. Tool names must use 1–128 ASCII letters, digits, underscores, hyphens,
+or periods. Tool and prompt descriptions, prompt-argument descriptions, and
+prompt titles are limited to 16 KiB. Resource URIs, templates, names, titles, and
+descriptions are limited to 16 KiB; MIME types and template-variable names are
+limited to 256 bytes; templates may contain at most 100 unique variables, and
+resource annotations may contain at most two audience hints. A resource read may
+return at most 100 content items and 16 MiB of serialized data.
+Stdio messages are limited to 16 MiB. HTTP JSON responses and individual SSE
+events are streaming-limited to 16 MiB plus 64 KiB of protocol framing.
 Schemas are syntax-checked before compilation; see [schema compatibility](#schema-compatibility)
 for supported dialects and the draft-07 subset. Schema nesting is limited to 64
 levels, including literal data. External schema references are unsupported, but
@@ -340,16 +431,16 @@ The adapter never automatically retries `tools/call`: a timeout or lost response
 may occur after a mutating operation took effect. Cancellation or expiration
 aborts only the affected HTTP request and sends a best-effort MCP cancellation
 notification; concurrent sibling calls remain usable. Successful output is
-validated against the schema captured when the call began; MCP error results are exempt
-from that success schema. Cancellation is best-effort at the server and does not
+validated against the schema captured when the call began; MCP error results are
+exempt from that success schema. Cancellation is best-effort at the server and does not
 roll back effects.
 
 ## Deliberately out of scope
 
-OAuth, legacy SSE transport, MCP resources APIs, prompt argument completion,
-sampling, elicitation, MCP apps, task execution, semantic search, scripting,
-config UI, and persistent catalog caching. Use a fuller adapter when those
-capabilities are required.
+OAuth, legacy SSE transport, resource subscriptions, MCP prompt/resource
+argument-value completion, sampling, elicitation, MCP apps, task execution,
+semantic search, scripting, config UI, and persistent catalog caching. Use a
+fuller adapter when those capabilities are required.
 
 ## Contributing
 

package/mcp.schema.json

@@ -33,7 +33,7 @@
         "description": { "$ref": "#/$defs/text" },
         "timeout": {
           "$ref": "#/$defs/timeout",
-          "description": "Hard deadline for one tool invocation or prompt retrieval."
+          "description": "Hard deadline for one tool invocation, prompt retrieval, or resource read."
         },
         "startupTimeoutMs": {
           "$ref": "#/$defs/timeout",

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ikuma.cloud/pix-mcp",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "MCP prompts and lazily activated native tools for Pi Coding Agent",
+  "description": "MCP resources, prompts, and lazily activated native tools for Pi Coding Agent",
   "keywords": [
     "pi-package"
   ],
@@ -22,7 +22,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
+    "@std-uritemplate/std-uritemplate": "2.0.12",
     "ajv": "8.20.0",
+    "fast-uri": "3.1.8",
     "undici": "8.10.2"
   },
   "peerDependencies": {