@ikuma.cloud/pix-mcp 0.0.8 → 0.0.10

package/src/index.ts

@@ -1,20 +1,46 @@
 import { resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  ExtensionContext,
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import type { Prompt, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type {
+  Prompt,
+  Resource,
+  ResourceTemplate,
+  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 {
+  mergeConfigs,
+  readConfig,
+  type ConfigIssue,
+  type ServerConfig,
+} from "./config.ts";
 import {
   formatEditableContent,
   formatResult,
   removeEditablePromptGuard,
 } from "./output.ts";
 import { pickPrompt } from "./prompt-picker.ts";
+import { pickResource } from "./resource-picker.ts";
+import {
+  formatResourceList,
+  formatResourceResult,
+  parseResourceCommand,
+  resourceCompletions,
+  resourceEntryKey,
+  resourceKey,
+  resourceTemplateVariables,
+  resolveResourceUri,
+  type ResourceArgumentToken,
+  type ResourceCommand,
+  type ResourceEntry,
+  type TemplateResourceEntry,
+} from "./resources.ts";
 import {
   formatPromptList,
   formatPromptResult,
@@ -44,17 +70,29 @@ interface PromptSelection {
   item: PromptEntry;
 }
 
+interface ResourceSelection {
+  command: ResourceCommand;
+  item: ResourceEntry;
+}
+
+type ConfigScope = "explicit" | "global" | "project";
+interface ConfigSource {
+  scope: ConfigScope;
+  path: string;
+}
+
 interface State {
   alive: boolean;
   status: string;
   entries: Map<string, Entry>;
   prompts: Map<string, PromptEntry>;
+  resources: Map<string, ResourceEntry>;
   loaded: Map<string, string>;
   connections: Map<string, Connection>;
   rejected: Map<string, Rejections>;
   configIssues: ConfigIssue[];
-  promptDraftCleanups: Set<() => Promise<void>>;
-  promptDraftGuards: Set<string>;
+  draftCleanups: Set<() => Promise<void>>;
+  draftGuards: Set<string>;
 }
 
 const discoveryParameters = Type.Object(
@@ -85,7 +123,7 @@ export default function mcp(pi: ExtensionAPI) {
   pi.registerFlag("mcp-config", {
     type: "string",
     description:
-      "Read this MCP config file for this session (default: .mcp.json).",
+      "Read only this MCP config file for this session (otherwise merge the global and project configs).",
   });
   pi.registerCommand("mcp-prompt", {
     description: "Select, list, or run a user-controlled MCP prompt",
@@ -178,8 +216,8 @@ export default function mcp(pi: ExtensionAPI) {
               ensureSelectedPromptCurrent();
               ctx.signal?.throwIfAborted();
               ctx.ui.pasteToEditor(draft.text);
-              owner.promptDraftCleanups.add(draft.cleanup);
-              if (draft.guard) owner.promptDraftGuards.add(draft.guard);
+              owner.draftCleanups.add(draft.cleanup);
+              if (draft.guard) owner.draftGuards.add(draft.guard);
             } catch (error) {
               await draft.cleanup();
               throw error;
@@ -202,6 +240,197 @@ export default function mcp(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("mcp-resource", {
+    description: "Select, list, or read a user-controlled MCP resource",
+    getArgumentCompletions: (prefix) =>
+      resourceCompletions(
+        prefix,
+        [...(state?.resources.values() ?? [])],
+        state?.connections.keys() ?? [],
+      ),
+    async handler(input, ctx) {
+      try {
+        const owner = state;
+        if (!owner) throw new Error("MCP session has not started.");
+        current(owner);
+        const editBeforeSending = ctx.mode === "tui" && input.trim() === "";
+        const selection = editBeforeSending
+          ? await chooseResource(owner, ctx)
+          : undefined;
+        const command =
+          selection?.command ??
+          (editBeforeSending ? undefined : parseResourceCommand(input));
+        if (!command) return;
+        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 resourceStatus = [
+            ...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.resourceStatus}`,
+              ),
+          ].join("\n");
+          const text = `${resourceStatus}${resourceStatus ? "\n\n" : ""}${formatResourceList(
+            [...owner.resources.values()],
+            command.server,
+          )}`;
+          if (!ctx.hasUI) throw new Error(text);
+          ctx.ui.notify(text, "info");
+          return;
+        }
+
+        const direct = owner.resources.get(
+          resourceKey(command.server, "resource", command.target),
+        );
+        const template = owner.resources.get(
+          resourceKey(command.server, "template", command.target),
+        );
+        const item =
+          selection?.item ??
+          (command.argumentTokens.length > 0 ? template : (direct ?? template));
+        const selectedKey = item ? resourceEntryKey(item) : undefined;
+        const ensureSelectedResourceCurrent = () => {
+          if (
+            selection &&
+            selectedKey &&
+            owner.resources.get(selectedKey) !== item
+          )
+            throw new Error(
+              "MCP resource catalog changed. Open the picker again.",
+            );
+        };
+        ensureSelectedResourceCurrent();
+        const templateEntry =
+          item?.kind === "template"
+            ? item
+            : template?.kind === "template"
+              ? template
+              : undefined;
+        const uri = resolveResourceUri(
+          command.target,
+          templateEntry,
+          command.argumentTokens,
+        );
+        const connection = owner.connections.get(command.server);
+        if (!connection) throw new Error("MCP connection unavailable.");
+        if (ctx.mode === "tui")
+          ctx.ui.setStatus(
+            "mcp-resource",
+            `Loading ${command.server} / ${compact(uri, 120)}…`,
+          );
+        try {
+          const result = await connection.readResource(uri, ctx.signal);
+          current(owner);
+          ensureSelectedResourceCurrent();
+          const formatted = await formatResourceResult(command.server, result);
+          current(owner);
+          ensureSelectedResourceCurrent();
+          ctx.signal?.throwIfAborted();
+          if (editBeforeSending) {
+            const draft = await formatEditableContent(formatted.content);
+            try {
+              current(owner);
+              ensureSelectedResourceCurrent();
+              ctx.signal?.throwIfAborted();
+              ctx.ui.pasteToEditor(draft.text);
+              owner.draftCleanups.add(draft.cleanup);
+              if (draft.guard) owner.draftGuards.add(draft.guard);
+            } catch (error) {
+              await draft.cleanup();
+              throw error;
+            }
+          } else {
+            pi.sendUserMessage(
+              formatted.content,
+              ctx.isIdle() ? undefined : { deliverAs: "followUp" },
+            );
+          }
+        } finally {
+          if (ctx.mode === "tui") ctx.ui.setStatus("mcp-resource", undefined);
+        }
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "MCP resource failed.";
+        if (!ctx.hasUI) throw new Error(message);
+        ctx.ui.notify(message, "error");
+      }
+    },
+  });
+
+  async function chooseResource(
+    owner: State,
+    ctx: ExtensionCommandContext,
+  ): Promise<ResourceSelection | undefined> {
+    const entries = [...owner.resources.values()].sort(
+      (a, b) =>
+        a.server.localeCompare(b.server, "en") ||
+        resourceEntryKey(a).localeCompare(resourceEntryKey(b), "en"),
+    );
+    if (entries.length === 0) {
+      ctx.ui.notify("No MCP resources are available.", "warning");
+      return;
+    }
+
+    const item = await pickResource(entries, ctx);
+    if (!item) return;
+    ctx.signal?.throwIfAborted();
+
+    const key = resourceEntryKey(item);
+    const ensureCurrent = () => {
+      current(owner);
+      if (owner.resources.get(key) !== item)
+        throw new Error("MCP resource catalog changed. Open the picker again.");
+    };
+    ensureCurrent();
+
+    const dialogOptions = ctx.signal ? { signal: ctx.signal } : undefined;
+    const argumentTokens: ResourceArgumentToken[] = [];
+    if (item.kind === "template") {
+      for (const variable of item.variables) {
+        const value = await ctx.ui.input(
+          `${variable} (optional)`,
+          "Leave empty to omit",
+          dialogOptions,
+        );
+        if (value === undefined) return;
+        ctx.signal?.throwIfAborted();
+        ensureCurrent();
+        if (value !== "")
+          argumentTokens.push({
+            value: `${variable}=${value}`,
+            separator: variable.length,
+          });
+      }
+    }
+
+    return {
+      command: {
+        action: "read",
+        server: item.server,
+        target:
+          item.kind === "resource"
+            ? item.resource.uri
+            : item.template.uriTemplate,
+        argumentTokens,
+      },
+      item,
+    };
+  }
+
   async function choosePrompt(
     owner: State,
     ctx: ExtensionCommandContext,
@@ -441,6 +670,35 @@ export default function mcp(pi: ExtensionAPI) {
     }
   }
 
+  function synchronizeResources(
+    owner: State,
+    config: ServerConfig,
+    resources: Resource[],
+    templates: ResourceTemplate[],
+  ) {
+    if (!owner.alive || state !== owner) return;
+    for (const [key, item] of owner.resources) {
+      if (item.server === config.name) owner.resources.delete(key);
+    }
+    for (const resource of resources) {
+      const item: ResourceEntry = {
+        kind: "resource",
+        server: config.name,
+        resource,
+      };
+      owner.resources.set(resourceEntryKey(item), item);
+    }
+    for (const template of templates) {
+      const item: TemplateResourceEntry = {
+        kind: "template",
+        server: config.name,
+        template,
+        variables: resourceTemplateVariables(template.uriTemplate),
+      };
+      owner.resources.set(resourceEntryKey(item), item);
+    }
+  }
+
   function synchronize(owner: State, config: ServerConfig, tools: Tool[]) {
     if (!owner.alive || state !== owner) return;
     const previous = new Map(
@@ -551,45 +809,80 @@ export default function mcp(pi: ExtensionAPI) {
     owner.alive = false;
     state = undefined;
     deactivate(owned);
-    const promptDraftCleanups = [...owner.promptDraftCleanups];
-    owner.promptDraftCleanups.clear();
-    owner.promptDraftGuards.clear();
+    const draftCleanups = [...owner.draftCleanups];
+    owner.draftCleanups.clear();
+    owner.draftGuards.clear();
     await Promise.all([
       ...[...owner.connections.values()].map((connection) =>
         connection.close(),
       ),
-      ...promptDraftCleanups.map((cleanup) => cleanup()),
+      ...draftCleanups.map((cleanup) => cleanup()),
     ]);
   }
 
   async function start(ctx: ExtensionContext) {
     await stop();
+    const showConfigNotices =
+      ctx.hasUI && (ctx.mode === "tui" || ctx.mode === "rpc");
     const owner: State = {
       alive: true,
       status: "No MCP servers configured.",
       entries: new Map(),
       prompts: new Map(),
+      resources: new Map(),
       loaded: new Map(),
       connections: new Map(),
       rejected: new Map(),
       configIssues: [],
-      promptDraftCleanups: new Set(),
-      promptDraftGuards: new Set(),
+      draftCleanups: new Set(),
+      draftGuards: new Set(),
     };
     state = owner;
+    let failureNotice: string | undefined;
     try {
       const flag = pi.getFlag("mcp-config");
-      const explicit = typeof flag === "string" && flag.length > 0;
-      const path = resolve(ctx.cwd, explicit ? flag : ".mcp.json");
-      const config = await readConfig(path);
+      if (flag === "") {
+        failureNotice = "MCP config (explicit) failed: no path provided";
+        throw new Error(
+          "The explicitly selected MCP configuration path is empty.",
+        );
+      }
+      const explicit = typeof flag === "string";
+      const sources: ConfigSource[] = explicit
+        ? [{ scope: "explicit", path: resolve(ctx.cwd, flag) }]
+        : [
+            {
+              scope: "global",
+              path: resolve(getAgentDir(), "mcp.json"),
+            },
+            { scope: "project", path: resolve(ctx.cwd, ".mcp.json") },
+          ];
+      const loaded = [];
+      for (const source of sources) {
+        failureNotice = `MCP config (${source.scope}) failed: ${source.path}`;
+        const config = await readConfig(source.path);
+        current(owner);
+        failureNotice = undefined;
+        if (config) {
+          loaded.push({ ...source, config });
+          if (showConfigNotices)
+            ctx.ui.notify(
+              `MCP config (${source.scope}): ${source.path}`,
+              "info",
+            );
+        }
+      }
       current(owner);
-      if (!config) {
+      if (loaded.length === 0) {
         if (explicit)
           owner.status =
             "The explicitly selected MCP configuration does not exist.";
+        if (showConfigNotices) ctx.ui.notify("MCP config: none found", "info");
         return;
       }
-      if (ctx.hasUI) ctx.ui.notify(`MCP config: ${path}`, "info");
+      failureNotice = "MCP configuration merge failed.";
+      const config = mergeConfigs(loaded.map((source) => source.config));
+      failureNotice = undefined;
       owner.configIssues = config.issues;
       owner.status =
         config.issues.length > 0
@@ -606,6 +899,8 @@ export default function mcp(pi: ExtensionAPI) {
             server,
             (tools) => synchronize(owner, server, tools),
             (prompts) => synchronizePrompts(owner, server, prompts),
+            (resources, templates) =>
+              synchronizeResources(owner, server, resources, templates),
           ),
         );
       }
@@ -621,9 +916,12 @@ export default function mcp(pi: ExtensionAPI) {
         }),
       );
     } catch (error) {
-      if (owner.alive)
+      if (owner.alive) {
         owner.status =
           error instanceof Error ? error.message : "MCP initialization failed.";
+        if (showConfigNotices)
+          ctx.ui.notify(failureNotice ?? "MCP initialization failed.", "error");
+      }
     } finally {
       if (owner.alive && state === owner) registerDiscovery();
     }
@@ -637,7 +935,7 @@ export default function mcp(pi: ExtensionAPI) {
     const consumed = new Set<string>();
     const removeKnownGuards = (text: string) => {
       let next = text;
-      for (const guard of owner.promptDraftGuards) {
+      for (const guard of owner.draftGuards) {
         if (!next.includes(guard)) continue;
         next = removeEditablePromptGuard(next, guard);
         consumed.add(guard);
@@ -654,7 +952,7 @@ export default function mcp(pi: ExtensionAPI) {
           : block,
       );
     }
-    for (const guard of consumed) owner.promptDraftGuards.delete(guard);
+    for (const guard of consumed) owner.draftGuards.delete(guard);
     if (consumed.size > 0) return { message: { ...event.message, content } };
   });
 

package/src/output.ts

@@ -29,6 +29,7 @@ interface ContentOptions {
   structuredContent?: unknown;
   preserveErrorImages?: boolean;
   preserveOrder?: boolean;
+  artifactRequired?: boolean;
 }
 
 export async function formatContent(
@@ -83,6 +84,7 @@ export async function formatContent(
     textTruncated ||
     omitted ||
     largeDetails ||
+    options.artifactRequired === true ||
     (options.preserveErrorImages === true && images.length > 0);
   let fullOutputPath: string | undefined;
   if (truncated) {
@@ -141,7 +143,7 @@ export async function formatContent(
   };
 }
 
-function createEditablePromptGuard(): string {
+function createEditableContentGuard(): string {
   const bytes = randomBytes(8);
   let guard = "\u2060\u2063";
   for (const byte of bytes)
@@ -154,12 +156,12 @@ export function removeEditablePromptGuard(text: string, guard: string): string {
   return text.replaceAll(guard, "");
 }
 
-function prepareEditablePrompt(text: string): {
+function prepareEditableContent(text: string): {
   text: string;
   guard?: string;
 } {
   // The TUI interprets leading / and ! as commands. An invisible guard keeps
-  // untrusted prompt text inert in the editor and is removed at message_end.
+  // untrusted staged text inert in the editor and is removed at message_end.
   const sanitized = text
     .replace(/\r\n?/gu, "\n")
     .replace(/\p{Cc}/gu, (character) =>
@@ -167,7 +169,7 @@ function prepareEditablePrompt(text: string): {
     )
     .replace(/[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu, "");
   if (!/^[!/]/u.test(sanitized.trimStart())) return { text: sanitized };
-  const guard = createEditablePromptGuard();
+  const guard = createEditableContentGuard();
   return { text: `${guard}${sanitized}`, guard };
 }
 
@@ -190,12 +192,9 @@ export async function formatEditableContent(
         text += block.text;
         continue;
       }
-      imageDirectory ??= await mkdtemp(join(tmpdir(), "pix-mcp-prompt-"));
+      imageDirectory ??= await mkdtemp(join(tmpdir(), "pix-mcp-draft-"));
       const extension = imageExtensions[block.mimeType] ?? "img";
-      const path = join(
-        imageDirectory,
-        `prompt-image-${++imageIndex}.${extension}`,
-      );
+      const path = join(imageDirectory, `image-${++imageIndex}.${extension}`);
       await writeFile(path, Buffer.from(block.data, "base64"), { mode: 0o600 });
       const separator = text.endsWith("\n\n")
         ? ""
@@ -210,7 +209,7 @@ export async function formatEditableContent(
     throw error;
   }
   return {
-    ...prepareEditablePrompt(text),
+    ...prepareEditableContent(text),
     cleanup: async () => {
       if (imageDirectory)
         await rm(imageDirectory, { recursive: true, force: true });

package/src/prompts.ts

@@ -4,6 +4,12 @@ import type {
   Prompt,
 } from "@modelcontextprotocol/sdk/types.js";
 import { compact } from "./catalog.ts";
+import {
+  quoteCommandArgument,
+  renderCommandToken,
+  tokenizeCommand,
+  type CommandToken,
+} from "./command.ts";
 import { formatContent } from "./output.ts";
 
 export interface PromptEntry {
@@ -11,10 +17,7 @@ export interface PromptEntry {
   prompt: Prompt;
 }
 
-export interface PromptArgumentToken {
-  value: string;
-  separator?: number;
-}
+export type PromptArgumentToken = CommandToken;
 
 export type PromptCommand =
   | { action: "list"; server?: string }
@@ -30,7 +33,7 @@ export function promptKey(server: string, name: string): string {
 }
 
 export function parsePromptCommand(input: string): PromptCommand {
-  const tokens = tokenize(input);
+  const tokens = tokenizeCommand(input, "prompt");
   const action = tokens.shift()?.value;
   if (action === "list") {
     if (tokens.length > 1) throw new Error("Usage: /mcp-prompt list [server]");
@@ -120,15 +123,15 @@ export function formatPromptList(
     const argumentsHint = (entry.prompt.arguments ?? [])
       .map((argument) =>
         argument.required
-          ? `<${quote(argument.name)}>`
-          : `[${quote(argument.name)}]`,
+          ? `<${quoteCommandArgument(argument.name)}>`
+          : `[${quoteCommandArgument(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}` : ""}`;
+    const line = `${entry.server} ${quoteCommandArgument(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;
@@ -149,7 +152,7 @@ export function promptCompletions(
   const trailingSpace = /\s$/.test(prefix);
   let tokens: PromptArgumentToken[];
   try {
-    tokens = tokenize(prefix);
+    tokens = tokenizeCommand(prefix);
   } catch {
     return null;
   }
@@ -191,7 +194,7 @@ export function promptCompletions(
       )
       .sort((a, b) => a.prompt.name.localeCompare(b.prompt.name, "en"));
     return prompts.map((entry) => ({
-      value: `run ${quote(server)} ${quote(entry.prompt.name)}`,
+      value: `run ${quoteCommandArgument(server)} ${quoteCommandArgument(entry.prompt.name)}`,
       label: entry.prompt.name,
       ...(entry.prompt.description || entry.prompt.title
         ? {
@@ -237,9 +240,9 @@ export function promptCompletions(
   }
   const base = [
     "run",
-    quote(server),
-    quote(selected.prompt.name),
-    ...supplied.map((token) => quote(token.value)),
+    quoteCommandArgument(server),
+    quoteCommandArgument(selected.prompt.name),
+    ...supplied.map(renderCommandToken),
   ].join(" ");
   const arguments_ = definitions.filter(
     (argument) =>
@@ -247,7 +250,7 @@ export function promptCompletions(
   );
   return arguments_.length > 0
     ? arguments_.map((argument) => ({
-        value: `${base} ${quote(argument.name)}=`,
+        value: `${base} ${quoteCommandArgument(argument.name)}=`,
         label: `${argument.name}=`,
         ...(argument.description
           ? { description: compact(argument.description, 100) }
@@ -262,66 +265,11 @@ function completionItems(
   label: (value: string) => string,
 ) {
   return values.map((value) => ({
-    value: `${prefix}${quote(value)}`,
+    value: `${prefix}${quoteCommandArgument(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;
-}
-
 function hasUsablePromptContent(
   content: GetPromptResult["messages"][number]["content"],
 ): boolean {