@ikuma.cloud/pix-mcp 0.0.6 → 0.0.7

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,41 @@ 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 list [server]
+/mcp-prompt run <server> <prompt> [name=value ...]
+```
+
+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 +303,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 +335,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.7",
   "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"
   ],

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(() => {});
   }
 }

package/src/index.ts

@@ -4,11 +4,20 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Prompt, Tool } from "@modelcontextprotocol/sdk/types.js";
 import { compact, entry, search, summary, type Entry } from "./catalog.ts";
 import { Connection } from "./client.ts";
 import { readConfig, type ConfigIssue, type ServerConfig } from "./config.ts";
 import { formatResult } from "./output.ts";
+import {
+  formatPromptList,
+  formatPromptResult,
+  parsePromptCommand,
+  promptCompletions,
+  promptKey,
+  resolvePromptArguments,
+  type PromptEntry,
+} from "./prompts.ts";
 import { prepareSchema } from "./schema.ts";
 import { ToolRejectionError, type RejectionCode } from "./rejection.ts";
 
@@ -26,6 +35,7 @@ interface State {
   alive: boolean;
   status: string;
   entries: Map<string, Entry>;
+  prompts: Map<string, PromptEntry>;
   loaded: Map<string, string>;
   connections: Map<string, Connection>;
   rejected: Map<string, Rejections>;
@@ -62,6 +72,83 @@ export default function mcp(pi: ExtensionAPI) {
     description:
       "Read this MCP config file for this session (default: .mcp.json).",
   });
+  pi.registerCommand("mcp-prompt", {
+    description: "List or run a user-selected MCP prompt",
+    getArgumentCompletions: (prefix) =>
+      promptCompletions(prefix, [...(state?.prompts.values() ?? [])]),
+    async handler(input, ctx) {
+      try {
+        const owner = state;
+        if (!owner) throw new Error("MCP session has not started.");
+        current(owner);
+        const command = parsePromptCommand(input);
+        if (command.action === "list") {
+          if (
+            command.server &&
+            !owner.connections.has(command.server) &&
+            !owner.configIssues.some((issue) => issue.name === command.server)
+          )
+            throw new Error("Unknown MCP server.");
+          const promptStatus = [
+            ...owner.configIssues
+              .filter(
+                (issue) => !command.server || issue.name === command.server,
+              )
+              .map((issue) => `${issue.name}: ${issue.message}`),
+            ...[...owner.connections.values()]
+              .filter(
+                (connection) =>
+                  !command.server || connection.config.name === command.server,
+              )
+              .map(
+                (connection) =>
+                  `${connection.config.name}: ${connection.promptStatus}`,
+              ),
+          ].join("\n");
+          const text = `${promptStatus}${promptStatus ? "\n\n" : ""}${formatPromptList(
+            [...owner.prompts.values()],
+            command.server,
+          )}`;
+          if (!ctx.hasUI) throw new Error(text);
+          ctx.ui.notify(text, "info");
+          return;
+        }
+        const item = owner.prompts.get(promptKey(command.server, command.name));
+        if (!item)
+          throw new Error(
+            "Unknown or unavailable MCP prompt. List prompts again.",
+          );
+        const connection = owner.connections.get(command.server);
+        if (!connection) throw new Error("MCP connection unavailable.");
+        const args = resolvePromptArguments(
+          item.prompt,
+          command.argumentTokens,
+        );
+        const result = await connection.getPrompt(
+          item.prompt.name,
+          args,
+          ctx.signal,
+        );
+        current(owner);
+        const formatted = await formatPromptResult(
+          result,
+          item.server,
+          item.prompt.name,
+        );
+        current(owner);
+        ctx.signal?.throwIfAborted();
+        pi.sendUserMessage(
+          formatted.content,
+          ctx.isIdle() ? undefined : { deliverAs: "followUp" },
+        );
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "MCP prompt failed.";
+        if (!ctx.hasUI) throw new Error(message);
+        ctx.ui.notify(message, "error");
+      }
+    },
+  });
 
   function deactivate(names: Iterable<string>) {
     const removed = new Set(names);
@@ -230,6 +317,23 @@ export default function mcp(pi: ExtensionAPI) {
     if (active) pi.setActiveTools(active);
   }
 
+  function synchronizePrompts(
+    owner: State,
+    config: ServerConfig,
+    prompts: Prompt[],
+  ) {
+    if (!owner.alive || state !== owner) return;
+    for (const [key, item] of owner.prompts) {
+      if (item.server === config.name) owner.prompts.delete(key);
+    }
+    for (const prompt of prompts) {
+      owner.prompts.set(promptKey(config.name, prompt.name), {
+        server: config.name,
+        prompt,
+      });
+    }
+  }
+
   function synchronize(owner: State, config: ServerConfig, tools: Tool[]) {
     if (!owner.alive || state !== owner) return;
     const previous = new Map(
@@ -351,6 +455,7 @@ export default function mcp(pi: ExtensionAPI) {
       alive: true,
       status: "No MCP servers configured.",
       entries: new Map(),
+      prompts: new Map(),
       loaded: new Map(),
       connections: new Map(),
       rejected: new Map(),
@@ -382,7 +487,11 @@ export default function mcp(pi: ExtensionAPI) {
       for (const server of config.servers) {
         owner.connections.set(
           server.name,
-          new Connection(server, (tools) => synchronize(owner, server, tools)),
+          new Connection(
+            server,
+            (tools) => synchronize(owner, server, tools),
+            (prompts) => synchronizePrompts(owner, server, prompts),
+          ),
         );
       }
       // Bound startup concurrency without letting one broken server hide healthy ones.

package/src/output.ts

@@ -2,7 +2,10 @@ import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type {
+  CallToolResult,
+  ContentBlock,
+} from "@modelcontextprotocol/sdk/types.js";
 
 export const MAX_TEXT_BYTES = 24 * 1024;
 const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
@@ -20,12 +23,27 @@ function preview(text: string): string {
     .join("\n");
 }
 
-export async function formatResult(result: CallToolResult) {
+interface ContentOptions {
+  artifact: unknown;
+  structuredContent?: unknown;
+  preserveErrorImages?: boolean;
+  preserveOrder?: boolean;
+}
+
+export async function formatContent(
+  blocks: ContentBlock[],
+  options: ContentOptions,
+) {
   const text: string[] = [];
   const images: ImageContent[] = [];
+  const ordered: (TextContent | ImageContent)[] = [];
+  const addText = (value: string) => {
+    text.push(value);
+    ordered.push({ type: "text", text: value });
+  };
   let omitted = false;
-  for (const block of result.content) {
-    if (block.type === "text") text.push(block.text);
+  for (const block of blocks) {
+    if (block.type === "text") addText(block.text);
     else if (
       block.type === "image" &&
       images.length < MAX_IMAGES &&
@@ -35,53 +53,77 @@ export async function formatResult(result: CallToolResult) {
       // Padding can give three decoded sizes the same encoded length.
       Buffer.byteLength(block.data, "base64") <= MAX_IMAGE_BYTES
     ) {
-      images.push({
+      const image: ImageContent = {
         type: "image",
         data: block.data,
         mimeType: block.mimeType,
-      });
+      };
+      images.push(image);
+      ordered.push(image);
     } else {
-      text.push(`[MCP ${block.type} content omitted; see full result.]`);
+      addText(`[MCP ${block.type} content omitted; see full result.]`);
       omitted = true;
     }
   }
-  if (result.structuredContent !== undefined) {
-    text.push(
-      `Structured content:\n${JSON.stringify(result.structuredContent)}`,
+  if (options.structuredContent !== undefined) {
+    addText(
+      `Structured content:\n${JSON.stringify(options.structuredContent)}`,
     );
   }
   const fullText = text.join("\n\n") || "(No text output)";
   const bounded = preview(fullText);
-  const structured = result.structuredContent;
+  const structured = options.structuredContent;
   const largeDetails =
     structured !== undefined &&
     Buffer.byteLength(JSON.stringify(structured)) > MAX_DETAILS_BYTES;
-  // Pi 0.87 turns thrown tool errors into text only. Preserve error images in
-  // the full-result artifact before the native execution wrapper throws.
   const truncated =
     bounded !== fullText ||
     omitted ||
     largeDetails ||
-    (result.isError === true && images.length > 0);
+    (options.preserveErrorImages === true && images.length > 0);
   let fullOutputPath: string | undefined;
   if (truncated) {
     const directory = await mkdtemp(join(tmpdir(), "pix-mcp-"));
     fullOutputPath = join(directory, "result.json");
-    await writeFile(fullOutputPath, JSON.stringify(result, null, 2), {
+    await writeFile(fullOutputPath, JSON.stringify(options.artifact, null, 2), {
       mode: 0o600,
     });
   }
-  const content: (TextContent | ImageContent)[] = [
-    {
-      type: "text",
-      text:
-        bounded +
-        (fullOutputPath
-          ? `\n\nFull MCP result: ${fullOutputPath}\nUse read with offset/limit to inspect it.`
-          : ""),
-    },
-    ...images,
-  ];
+  const artifactNotice = fullOutputPath
+    ? `Full MCP result: ${fullOutputPath}\nUse read with offset/limit to inspect it.`
+    : undefined;
+  let content: (TextContent | ImageContent)[];
+  if (options.preserveOrder) {
+    content = [];
+    let offset = 0;
+    let textIndex = 0;
+    for (const block of ordered) {
+      if (block.type === "image") {
+        content.push(block);
+        continue;
+      }
+      const value = `${textIndex++ > 0 ? "\n\n" : ""}${block.text}`;
+      // Slice the already byte/line-bounded preview itself; value supplies only
+      // the original block boundary needed to preserve image ordering.
+      const visible = bounded.slice(offset, offset + value.length);
+      offset += visible.length;
+      if (!visible) continue;
+      const previous = content.at(-1);
+      if (previous?.type === "text") previous.text += visible;
+      else content.push({ type: "text", text: visible });
+    }
+    if (textIndex === 0) content.unshift({ type: "text", text: bounded });
+    if (artifactNotice)
+      content.push({ type: "text", text: `\n\n${artifactNotice}` });
+  } else {
+    content = [
+      {
+        type: "text",
+        text: bounded + (artifactNotice ? `\n\n${artifactNotice}` : ""),
+      },
+      ...images,
+    ];
+  }
   return {
     content,
     details: {
@@ -94,3 +136,13 @@ export async function formatResult(result: CallToolResult) {
     },
   };
 }
+
+export function formatResult(result: CallToolResult) {
+  // Pi 0.87 turns thrown tool errors into text only. Preserve error images in
+  // the full-result artifact before the native execution wrapper throws.
+  return formatContent(result.content, {
+    artifact: result,
+    structuredContent: result.structuredContent,
+    preserveErrorImages: result.isError === true,
+  });
+}

package/src/prompts.ts

@@ -0,0 +1,366 @@
+import type {
+  ContentBlock,
+  GetPromptResult,
+  Prompt,
+} from "@modelcontextprotocol/sdk/types.js";
+import { compact } from "./catalog.ts";
+import { formatContent } from "./output.ts";
+
+export interface PromptEntry {
+  server: string;
+  prompt: Prompt;
+}
+
+export interface PromptArgumentToken {
+  value: string;
+  separator?: number;
+}
+
+export type PromptCommand =
+  | { action: "list"; server?: string }
+  | {
+      action: "run";
+      server: string;
+      name: string;
+      argumentTokens: PromptArgumentToken[];
+    };
+
+export function promptKey(server: string, name: string): string {
+  return JSON.stringify([server, name]);
+}
+
+export function parsePromptCommand(input: string): PromptCommand {
+  const tokens = tokenize(input);
+  const action = tokens.shift()?.value;
+  if (action === "list") {
+    if (tokens.length > 1) throw new Error("Usage: /mcp-prompt list [server]");
+    const server = tokens[0]?.value;
+    return { action, ...(server ? { server } : {}) };
+  }
+  if (action === "run") {
+    const server = tokens.shift()?.value;
+    const name = tokens.shift()?.value;
+    if (!server || !name)
+      throw new Error(
+        "Usage: /mcp-prompt run <server> <prompt> [name=value ...]",
+      );
+    return { action, server, name, argumentTokens: tokens };
+  }
+  throw new Error(
+    "Usage: /mcp-prompt list [server] | /mcp-prompt run <server> <prompt> [name=value ...]",
+  );
+}
+
+export function resolvePromptArguments(
+  prompt: Prompt,
+  tokens: (PromptArgumentToken | string)[],
+): Record<string, string> | undefined {
+  const declared = new Set(
+    (prompt.arguments ?? []).map((argument) => argument.name),
+  );
+  const named = new Map<string, string>();
+  const positional: string[] = [];
+  for (const token of tokens) {
+    const value = typeof token === "string" ? token : token.value;
+    const separator =
+      typeof token === "string" ? token.indexOf("=") : token.separator;
+    const candidate = value.slice(0, separator);
+    if (separator !== undefined && separator > 0 && declared.has(candidate)) {
+      const name = candidate;
+      if (named.has(name))
+        throw new Error(`Prompt argument ${name} was provided more than once.`);
+      named.set(name, value.slice(separator + 1));
+    } else positional.push(value);
+  }
+
+  const result = Object.create(null) as Record<string, string>;
+  let position = 0;
+  for (const argument of prompt.arguments ?? []) {
+    const namedValue = named.get(argument.name);
+    const value = namedValue ?? positional[position];
+    if (namedValue === undefined && value !== undefined) position++;
+    if (value !== undefined) result[argument.name] = value;
+    named.delete(argument.name);
+  }
+  if (position < positional.length)
+    throw new Error("Too many positional prompt arguments were provided.");
+  for (const [name, value] of named) result[name] = value;
+
+  const missing = (prompt.arguments ?? [])
+    .filter(
+      (argument) =>
+        argument.required === true && !Object.hasOwn(result, argument.name),
+    )
+    .map((argument) => argument.name);
+  if (missing.length > 0)
+    throw new Error(
+      `Missing required prompt arguments: ${missing.join(", ")}.`,
+    );
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+export function formatPromptList(
+  entries: PromptEntry[],
+  server?: string,
+): string {
+  const selected = entries
+    .filter((entry) => !server || entry.server === server)
+    .sort(
+      (a, b) =>
+        a.server.localeCompare(b.server, "en") ||
+        a.prompt.name.localeCompare(b.prompt.name, "en"),
+    );
+  if (selected.length === 0)
+    return server
+      ? `No MCP prompts are available from ${server}.`
+      : "No MCP prompts are available.";
+  const lines = ["Available MCP prompts:"];
+  let shown = 0;
+  for (const entry of selected) {
+    const argumentsHint = (entry.prompt.arguments ?? [])
+      .map((argument) =>
+        argument.required
+          ? `<${quote(argument.name)}>`
+          : `[${quote(argument.name)}]`,
+      )
+      .join(" ");
+    const description = compact(
+      entry.prompt.description ?? entry.prompt.title ?? "",
+      160,
+    );
+    const line = `${entry.server} ${quote(entry.prompt.name)}${argumentsHint ? ` ${argumentsHint}` : ""}${description ? ` — ${description}` : ""}`;
+    if (shown >= 100 || lines.join("\n").length + line.length > 15_000) {
+      lines.push(`${selected.length - shown} additional prompts omitted.`);
+      break;
+    }
+    lines.push(line);
+    shown++;
+  }
+  lines.push(
+    "Run one with /mcp-prompt run <server> <prompt> [name=value ...].",
+  );
+  return lines.join("\n");
+}
+
+export function promptCompletions(
+  prefix: string,
+  entries: PromptEntry[],
+): { value: string; label: string; description?: string }[] | null {
+  const trailingSpace = /\s$/.test(prefix);
+  let tokens: PromptArgumentToken[];
+  try {
+    tokens = tokenize(prefix);
+  } catch {
+    return null;
+  }
+  if (tokens.length === 0)
+    return [
+      { value: "list", label: "list", description: "List MCP prompts" },
+      { value: "run", label: "run", description: "Run an MCP prompt" },
+    ];
+  if (tokens.length === 1 && !trailingSpace) {
+    return ["list", "run"]
+      .filter((action) => action.startsWith(tokens[0]?.value ?? ""))
+      .map((action) => ({ value: action, label: action }));
+  }
+  const action = tokens[0]?.value;
+  if (action !== "list" && action !== "run") return null;
+  const servers = [...new Set(entries.map((entry) => entry.server))].sort();
+  const completingServer =
+    tokens.length === 1 || (tokens.length === 2 && !trailingSpace);
+  if (completingServer) {
+    const current = trailingSpace ? "" : (tokens[1]?.value ?? "");
+    return completionItems(
+      servers.filter((server) => server.startsWith(current)),
+      `${action} `,
+      (server) => server,
+    );
+  }
+  if (action === "list") return null;
+  const server = tokens[1]?.value;
+  if (!server || !servers.includes(server)) return null;
+  if (
+    (tokens.length === 2 && trailingSpace) ||
+    (tokens.length === 3 && !trailingSpace)
+  ) {
+    const current = trailingSpace ? "" : (tokens[2]?.value ?? "");
+    const prompts = entries
+      .filter(
+        (entry) =>
+          entry.server === server && entry.prompt.name.startsWith(current),
+      )
+      .sort((a, b) => a.prompt.name.localeCompare(b.prompt.name, "en"));
+    return prompts.map((entry) => ({
+      value: `run ${quote(server)} ${quote(entry.prompt.name)}`,
+      label: entry.prompt.name,
+      ...(entry.prompt.description || entry.prompt.title
+        ? {
+            description: compact(
+              entry.prompt.description ?? entry.prompt.title ?? "",
+              100,
+            ),
+          }
+        : {}),
+    }));
+  }
+  const name = tokens[2]?.value;
+  const selected = entries.find(
+    (entry) => entry.server === server && entry.prompt.name === name,
+  );
+  if (!selected) return null;
+  const supplied = tokens.slice(3);
+  const currentToken = trailingSpace ? undefined : supplied.pop();
+  const current = currentToken?.value ?? "";
+  if (currentToken?.separator !== undefined) return null;
+  const definitions = selected.prompt.arguments ?? [];
+  const declared = new Set(definitions.map((argument) => argument.name));
+  const named = new Set<string>();
+  let positional = 0;
+  for (const token of supplied) {
+    const candidate = token.value.slice(0, token.separator);
+    if (
+      token.separator !== undefined &&
+      token.separator > 0 &&
+      declared.has(candidate)
+    )
+      named.add(candidate);
+    else positional++;
+  }
+  const satisfied = new Set<string>();
+  let position = 0;
+  for (const argument of definitions) {
+    if (named.has(argument.name)) satisfied.add(argument.name);
+    else if (position < positional) {
+      satisfied.add(argument.name);
+      position++;
+    }
+  }
+  const base = [
+    "run",
+    quote(server),
+    quote(selected.prompt.name),
+    ...supplied.map((token) => quote(token.value)),
+  ].join(" ");
+  const arguments_ = definitions.filter(
+    (argument) =>
+      !satisfied.has(argument.name) && argument.name.startsWith(current),
+  );
+  return arguments_.length > 0
+    ? arguments_.map((argument) => ({
+        value: `${base} ${quote(argument.name)}=`,
+        label: `${argument.name}=`,
+        ...(argument.description
+          ? { description: compact(argument.description, 100) }
+          : {}),
+      }))
+    : null;
+}
+
+function completionItems(
+  values: string[],
+  prefix: string,
+  label: (value: string) => string,
+) {
+  return values.map((value) => ({
+    value: `${prefix}${quote(value)}`,
+    label: label(value),
+  }));
+}
+
+function quote(value: string): string {
+  return /^[A-Za-z0-9_.:/-]+$/.test(value)
+    ? value
+    : `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function tokenize(input: string): PromptArgumentToken[] {
+  const tokens: PromptArgumentToken[] = [];
+  let token = "";
+  let separator: number | undefined;
+  let quote: '"' | "'" | undefined;
+  let escaped = false;
+  let started = false;
+  for (const character of input) {
+    if (escaped) {
+      token += character;
+      escaped = false;
+      started = true;
+    } else if (character === "\\" && quote !== "'") {
+      escaped = true;
+      started = true;
+    } else if (quote) {
+      if (character === quote) quote = undefined;
+      else token += character;
+      started = true;
+    } else if (character === '"' || character === "'") {
+      quote = character;
+      started = true;
+    } else if (/\s/u.test(character)) {
+      if (started) {
+        tokens.push({
+          value: token,
+          ...(separator !== undefined ? { separator } : {}),
+        });
+        token = "";
+        separator = undefined;
+        started = false;
+      }
+    } else {
+      if (character === "=" && separator === undefined)
+        separator = token.length;
+      token += character;
+      started = true;
+    }
+  }
+  if (quote) throw new Error("Unterminated quote in prompt arguments.");
+  if (escaped) throw new Error("Trailing escape in prompt arguments.");
+  if (started)
+    tokens.push({
+      value: token,
+      ...(separator !== undefined ? { separator } : {}),
+    });
+  return tokens;
+}
+
+export async function formatPromptResult(
+  result: GetPromptResult,
+  server: string,
+  name: string,
+) {
+  if (result.messages.length === 0)
+    throw new Error("MCP prompt returned no messages.");
+  const blocks: ContentBlock[] = [
+    { type: "text", text: `[MCP prompt from ${server}/${name}]` },
+  ];
+  const showRoles =
+    result.messages.length > 1 || result.messages[0]?.role !== "user";
+  for (const message of result.messages) {
+    if (showRoles) blocks.push({ type: "text", text: `[${message.role}]` });
+    const content = message.content;
+    if (content.type === "resource") {
+      if ("text" in content.resource) {
+        blocks.push({
+          type: "text",
+          text: `[MCP embedded resource ${content.resource.uri}]\n${content.resource.text}`,
+        });
+      } else if (
+        content.resource.mimeType &&
+        ["image/png", "image/jpeg", "image/gif", "image/webp"].includes(
+          content.resource.mimeType,
+        )
+      ) {
+        blocks.push({
+          type: "image",
+          data: content.resource.blob,
+          mimeType: content.resource.mimeType,
+        });
+      } else blocks.push(content);
+    } else if (content.type === "resource_link") {
+      blocks.push({
+        type: "text",
+        text: `[MCP resource link ${content.name}: ${content.uri}]`,
+      });
+    } else blocks.push(content);
+  }
+  return formatContent(blocks, { artifact: result, preserveOrder: true });
+}