@ikuma.cloud/pix-mcp 0.0.6 → 0.0.8

package/README.md

@@ -1,8 +1,8 @@
 # @ikuma.cloud/pix-mcp
 
-A small Pi MCP adapter: discover tools, load their schemas on demand, then call
-those tools natively. No scripting engine or model-provider-specific API is
-required.
+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.
 
 ## Usage
 
@@ -12,9 +12,10 @@ To load this package in an existing Pi installation:
 pi -e /absolute/path/to/pix/packages/pix-mcp
 ```
 
-Disable any other MCP adapter that would collide with the `mcp` tool or flags,
-but keep any permission-control extensions enabled. Review the configuration
-and automatic startup behavior below before connecting servers.
+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.
 
 ## Configuration
 
@@ -82,7 +83,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, in milliseconds; default 30000 |
+| `timeout` | Hard deadline for each tool invocation or prompt retrieval, 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 |
@@ -116,10 +117,10 @@ 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 without lengthening startup or
-discovery. The call 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.
+`"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
+snapshot; a subsequent list-change refresh starts a new deadline.
 
 HTTP deadlines cover response headers and bodies, including JSON and SSE. MCP
 requests borrow the host's HTTP/proxy routing but override its header/body idle
@@ -158,8 +159,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
-paginated tool catalogs. A server's configuration, connection, or discovery
-failure does not hide tools from other servers.
+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;
 initial connections and metadata discovery are not.**
 
@@ -194,11 +196,11 @@ For example, `draft07-reference` identifies unsupported draft-07 references;
 returned by list, search, and load, and replaced on each catalog refresh. Raw
 exceptions, schema contents, invalid tool names, and dialect URLs are not exposed.
 
-An unsupported output schema still fails that server's discovery rather than
+An unsupported output schema still fails that server's tool discovery rather than
 producing a per-tool rejection. Losing an established HTTP notification stream
-also withdraws tools rather than silently keeping a stale catalog; servers that
-decline the optional stream with HTTP 405 remain usable. Reload Pi to reconnect
-a failed server or reread configuration.
+withdraws tool and prompt 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
 schema additions; others rebuild the tool set and may invalidate prompt caches.
@@ -257,6 +259,52 @@ complete draft-07 converter. For unsupported dialect constructs, the server must
 supply an equivalent supported schema—not merely remove or change `$schema`.
 Embedded draft-07 declarations inside a 2020-12 document also remain unsupported.
 
+## Prompts
+
+MCP prompts are user-controlled and are not exposed as model-callable tools. Use
+the stable `/mcp-prompt` command so catalog changes do not leave stale slash
+commands behind:
+
+```text
+/mcp-prompt
+/mcp-prompt list [server]
+/mcp-prompt run <server> <prompt> [name=value ...]
+```
+
+In TUI mode, `/mcp-prompt` without arguments opens a native prompt selector
+that shows the focused prompt's title and description, followed by native input
+dialogs. Required and optional arguments are requested in declaration order;
+leaving an optional input empty omits it. The rendered prompt is placed in Pi's
+editor so you can review or modify it before sending. Image blocks are stored in
+private temporary files and inserted as `@` references. Escape cancels without
+retrieving the prompt. The explicit `list` and `run` forms remain available in
+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,
+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.
+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
+does not hide healthy prompts.
+
+Pi cannot insert an arbitrary MCP message sequence with its original roles. A
+single user message is passed through; multi-message prompts are flattened with
+explicit `[user]` and `[assistant]` markers. Text, supported images, and embedded
+text or supported-image resources are retained. Resource links become textual
+references. Audio and other binary content are omitted from the preview and
+preserved in a private full-result artifact. MCP argument completion requests are
+not supported.
+
+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.
+
 ## Output and limits
 
 Text, supported images, and structured content are retained. Long text gets a
@@ -266,17 +314,22 @@ 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 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 longer needed. Output limits are not a
-complete memory or security sandbox.
+When necessary, the full MCP tool or prompt 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
+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 catalog is limited to 1000 tools, 100 pagination
-cursors, and 2 MiB of metadata; individual input/output schemas are limited to
-64 KiB. Tool names must use 1–128 ASCII letters, digits, underscores, hyphens, or
-periods; descriptions are limited to 16 KiB. Stdio messages are limited to 16 MiB.
+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.
 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
@@ -293,9 +346,10 @@ roll back effects.
 
 ## Deliberately out of scope
 
-OAuth, legacy SSE transport, MCP prompts/resources APIs, 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, 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.
 
 ## Contributing
 

package/mcp.schema.json

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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ikuma.cloud/pix-mcp",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "MCP discovery and lazily activated native tools for Pi Coding Agent",
+  "description": "MCP prompts and lazily activated native tools for Pi Coding Agent",
   "keywords": [
     "pi-package"
   ],
@@ -28,11 +28,13 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.87.1",
     "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
     "typebox": "1.3.27"
   }
 }

package/src/catalog.ts

@@ -78,7 +78,7 @@ export function summary(item: Entry) {
 
 export function compact(value: string, limit: number): string {
   const text = value
-    .replace(/\p{Cc}/gu, " ")
+    .replace(/[\p{C}\p{Zl}\p{Zp}]/gu, " ")
     .replace(/\s+/g, " ")
     .trim();
   return text.length <= limit ? text : `${text.slice(0, limit)}…`;

package/src/client.ts

@@ -7,9 +7,13 @@ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { mediaTypeEssence } from "@modelcontextprotocol/sdk/shared/mediaType.js";
 import {
   CallToolResultSchema,
+  GetPromptResultSchema,
+  ListPromptsResultSchema,
   ListToolsResultSchema,
+  PromptListChangedNotificationSchema,
   ToolSchema,
   ToolListChangedNotificationSchema,
+  type Prompt,
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { ServerConfig } from "./config.ts";
@@ -28,25 +32,46 @@ const catalogResultSchema = ListToolsResultSchema.extend({
   }).array(),
 });
 
+// Prompt identifiers are rendered in command UI and diagnostics, so bound them
+// and reject control, format, and line-separator characters before they enter state.
+const promptIdentifier = (value: string) =>
+  Buffer.byteLength(value) > 0 &&
+  Buffer.byteLength(value) <= 256 &&
+  !/[\p{C}\p{Zl}\p{Zp}]/u.test(value);
+
 export class Connection {
   readonly client: Client;
   readonly config: ServerConfig;
   status = "Not connected";
+  toolStatus = "Not discovered";
+  promptStatus = "Not discovered";
   instructions = "";
   #transport: StdioClientTransport | StreamableHTTPClientTransport;
   #lifetime = new AbortController();
   #initializing: Promise<void> | undefined;
   #refreshing: Promise<void> | undefined;
+  #promptRefreshing: Promise<void> | undefined;
   #closing: Promise<void> | undefined;
   #dirty = false;
+  #promptDirty = false;
   #stopped = false;
+  #connected = false;
+  #toolsReady = false;
+  #promptsReady = false;
   #changed: (tools: Tool[]) => void;
+  #promptsChanged: (prompts: Prompt[]) => void;
+  #promptNames = new Set<string>();
   #outputValidators = new Map<string, ReturnType<typeof compileSchema>>();
   #operation = new AsyncLocalStorage<AbortSignal>();
 
-  constructor(config: ServerConfig, changed: (tools: Tool[]) => void) {
+  constructor(
+    config: ServerConfig,
+    changed: (tools: Tool[]) => void,
+    promptsChanged: (prompts: Prompt[]) => void = () => {},
+  ) {
     this.config = config;
     this.#changed = changed;
+    this.#promptsChanged = promptsChanged;
     this.client = new Client(
       { name: "pix-mcp", version: "0.0.0" },
       { capabilities: {}, jsonSchemaValidator: schemaValidator },
@@ -86,19 +111,47 @@ export class Connection {
         }
       },
     );
+    this.client.setNotificationHandler(
+      PromptListChangedNotificationSchema,
+      async () => {
+        if (this.#stopped) return;
+        try {
+          await this.refreshPrompts();
+        } catch {
+          /* refresh already clears the stale catalog */
+        }
+      },
+    );
   }
 
   #disconnect() {
     if (this.#stopped || this.#lifetime.signal.aborted) return;
     this.status = "Disconnected; reload Pi to reconnect";
+    this.toolStatus = "Unavailable";
+    this.promptStatus = "Unavailable";
+    this.#connected = false;
+    this.#toolsReady = false;
+    this.#promptsReady = false;
     this.#lifetime.abort(
       new Error("MCP connection is unavailable; reload Pi to reconnect."),
     );
     this.#outputValidators.clear();
+    this.#promptNames.clear();
     this.#changed([]);
+    this.#promptsChanged([]);
     void this.client.close().catch(() => {});
   }
 
+  #updateStatus() {
+    if (!this.#connected || this.#stopped) return;
+    if (this.#toolsReady && this.#promptsReady) this.status = "Connected";
+    else if (this.#toolsReady)
+      this.status = "Connected; prompt discovery failed";
+    else if (this.#promptsReady)
+      this.status = "Connected; tool discovery failed";
+    else this.status = "Discovery failed; reload Pi to retry";
+  }
+
   async #deadline<T>(
     timeout: number,
     signal: AbortSignal | undefined,
@@ -250,29 +303,51 @@ export class Connection {
         clearTimeout(handshakeTimer);
       }
       this.#lifetime.signal.throwIfAborted();
+      this.#connected = true;
+      this.status = "Discovering";
       this.instructions = this.client.getInstructions() ?? "";
-      await this.refresh();
     } catch {
       if (!this.#stopped) {
         this.status =
-          "Connection or discovery failed; check configuration/authentication and reload Pi";
+          "Connection failed; check configuration/authentication and reload Pi";
+        this.toolStatus = "Unavailable";
+        this.promptStatus = "Unavailable";
         this.#changed([]);
+        this.#promptsChanged([]);
       }
       await this.client.close().catch(() => {});
-      throw new Error(
-        `MCP server ${this.config.name}: connection or discovery failed.`,
-      );
+      throw new Error(`MCP server ${this.config.name}: connection failed.`);
     }
+    const results = await Promise.allSettled([
+      this.refresh(),
+      this.refreshPrompts(),
+    ]);
+    if (results.some((result) => result.status === "rejected"))
+      throw new Error(`MCP server ${this.config.name}: discovery failed.`);
   }
 
   refresh(): Promise<void> {
     this.#dirty = true;
-    this.#refreshing ??= this.#refresh().finally(() => {
-      this.#refreshing = undefined;
-    });
+    this.#refreshing ??= this.#drainToolRefreshes();
     return this.#refreshing;
   }
 
+  async #drainToolRefreshes(): Promise<void> {
+    let failed = false;
+    let failure: unknown;
+    try {
+      await this.#refresh();
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    // Clear ownership and inspect dirty state without an await between them. A
+    // notification queued as the prior refresh settles must start another pass.
+    this.#refreshing = undefined;
+    if (this.#dirty && !this.#stopped) return this.refresh();
+    if (failed) throw failure;
+  }
+
   async #refresh(): Promise<void> {
     try {
       while (this.#dirty && !this.#stopped) {
@@ -337,18 +412,187 @@ export class Connection {
             signal.throwIfAborted();
             if (!this.#stopped) {
               this.#outputValidators = validators;
-              this.status = "Connected";
+              this.#toolsReady = true;
+              this.toolStatus = "Available";
               this.#changed(tools);
+              this.#updateStatus();
             }
           },
         );
       }
     } catch {
       if (!this.#stopped) {
-        this.status = "Discovery failed; reload Pi to retry";
+        this.#toolsReady = false;
+        this.toolStatus = "Discovery failed; reload Pi to retry";
+        this.#outputValidators.clear();
         this.#changed([]);
+        this.#updateStatus();
       }
-      throw new Error(`MCP server ${this.config.name}: discovery failed.`);
+      throw new Error(`MCP server ${this.config.name}: tool discovery failed.`);
+    }
+  }
+
+  refreshPrompts(): Promise<void> {
+    this.#promptDirty = true;
+    this.#promptRefreshing ??= this.#drainPromptRefreshes();
+    return this.#promptRefreshing;
+  }
+
+  async #drainPromptRefreshes(): Promise<void> {
+    let failed = false;
+    let failure: unknown;
+    try {
+      await this.#refreshPrompts();
+    } catch (error) {
+      failed = true;
+      failure = error;
+    }
+    this.#promptRefreshing = undefined;
+    if (this.#promptDirty && !this.#stopped) return this.refreshPrompts();
+    if (failed) throw failure;
+  }
+
+  async #refreshPrompts(): Promise<void> {
+    try {
+      while (this.#promptDirty && !this.#stopped) {
+        this.#promptDirty = false;
+        const prompts: Prompt[] = [];
+        const cursors = new Set<string>();
+        const names = new Set<string>();
+        const supportsPrompts = Boolean(
+          this.client.getServerCapabilities()?.prompts,
+        );
+        let cursor: string | undefined;
+        let bytes = 0;
+        await this.#deadline(
+          this.config.catalogTimeoutMs,
+          undefined,
+          async (signal) => {
+            if (supportsPrompts) {
+              do {
+                const page = await this.#deadline(
+                  this.config.catalogTimeoutMs,
+                  signal,
+                  (requestSignal) =>
+                    this.client.request(
+                      {
+                        method: "prompts/list",
+                        params: cursor === undefined ? {} : { cursor },
+                      },
+                      ListPromptsResultSchema,
+                      {
+                        signal: requestSignal,
+                        timeout: this.config.catalogTimeoutMs,
+                      },
+                    ),
+                );
+                bytes += Buffer.byteLength(JSON.stringify(page));
+                if (
+                  bytes > 2 * 1024 * 1024 ||
+                  prompts.length + page.prompts.length > 1000
+                )
+                  throw new Error("Catalog limit");
+                for (const prompt of page.prompts) {
+                  if (
+                    !promptIdentifier(prompt.name) ||
+                    Buffer.byteLength(prompt.title ?? "") > 16 * 1024 ||
+                    Buffer.byteLength(prompt.description ?? "") > 16 * 1024 ||
+                    (prompt.arguments?.length ?? 0) > 100
+                  )
+                    throw new Error("Invalid prompt metadata");
+                  if (names.has(prompt.name))
+                    throw new Error("Duplicate prompt name");
+                  const argumentNames = new Set<string>();
+                  for (const argument of prompt.arguments ?? []) {
+                    if (
+                      !promptIdentifier(argument.name) ||
+                      Buffer.byteLength(argument.description ?? "") > 16 * 1024
+                    )
+                      throw new Error("Invalid prompt argument metadata");
+                    if (argumentNames.has(argument.name))
+                      throw new Error("Duplicate prompt argument name");
+                    argumentNames.add(argument.name);
+                  }
+                  names.add(prompt.name);
+                  prompts.push(prompt);
+                }
+                cursor = page.nextCursor;
+                if (cursor !== undefined) {
+                  if (cursors.has(cursor) || cursors.size >= 100)
+                    throw new Error("Invalid pagination");
+                  cursors.add(cursor);
+                }
+              } while (cursor !== undefined);
+            }
+            signal.throwIfAborted();
+            if (!this.#stopped) {
+              this.#promptNames = names;
+              this.#promptsReady = true;
+              this.promptStatus = supportsPrompts
+                ? "Available"
+                : "Not supported";
+              this.#promptsChanged(prompts);
+              this.#updateStatus();
+            }
+          },
+        );
+      }
+    } catch {
+      if (!this.#stopped) {
+        this.#promptsReady = false;
+        this.promptStatus = "Discovery failed; reload Pi to retry";
+        this.#promptNames.clear();
+        this.#promptsChanged([]);
+        this.#updateStatus();
+      }
+      throw new Error(
+        `MCP server ${this.config.name}: prompt discovery failed.`,
+      );
+    }
+  }
+
+  async getPrompt(
+    name: string,
+    args: Record<string, string> | undefined,
+    signal?: AbortSignal,
+  ) {
+    await this.start().catch(() => {});
+    const combined = signal
+      ? AbortSignal.any([signal, this.#lifetime.signal])
+      : this.#lifetime.signal;
+    combined.throwIfAborted();
+    if (!this.#promptsReady || !this.#promptNames.has(name))
+      throw new Error("MCP prompt is unavailable; list prompts again.");
+    if (args && Buffer.byteLength(JSON.stringify(args)) > 256 * 1024)
+      throw new Error("MCP prompt arguments exceed 256 KiB.");
+    try {
+      return await this.#deadline(
+        this.config.timeout,
+        combined,
+        (requestSignal) =>
+          this.client.request(
+            {
+              method: "prompts/get",
+              params: {
+                name,
+                ...(args && Object.keys(args).length > 0
+                  ? { arguments: args }
+                  : {}),
+              },
+            },
+            GetPromptResultSchema,
+            {
+              signal: requestSignal,
+              timeout: this.config.timeout,
+              resetTimeoutOnProgress: false,
+            },
+          ),
+      );
+    } catch {
+      combined.throwIfAborted();
+      throw new Error(
+        `MCP server ${this.config.name}: prompt request failed or timed out.`,
+      );
     }
   }
 
@@ -357,11 +601,13 @@ export class Connection {
     args: Record<string, unknown>,
     signal?: AbortSignal,
   ) {
-    await this.start();
+    await this.start().catch(() => {});
     const combined = signal
       ? AbortSignal.any([signal, this.#lifetime.signal])
       : this.#lifetime.signal;
     combined.throwIfAborted();
+    if (!this.#toolsReady)
+      throw new Error("MCP tool catalog is unavailable; reload Pi to retry.");
     const outputValidator = this.#outputValidators.get(name);
     try {
       // SDK callTool consults a mutable per-page validator after the response and
@@ -408,6 +654,14 @@ export class Connection {
     this.#stopped = true;
     this.#lifetime.abort();
     this.status = "Closed";
+    this.toolStatus = "Closed";
+    this.promptStatus = "Closed";
+    this.#toolsReady = false;
+    this.#promptsReady = false;
+    this.#outputValidators.clear();
+    this.#promptNames.clear();
+    this.#changed([]);
+    this.#promptsChanged([]);
     if (
       this.#transport instanceof StreamableHTTPClientTransport &&
       this.#transport.sessionId
@@ -417,5 +671,6 @@ export class Connection {
     await this.client.close().catch(() => {});
     await this.#initializing?.catch(() => {});
     await this.#refreshing?.catch(() => {});
+    await this.#promptRefreshing?.catch(() => {});
   }
 }