@ikuma.cloud/pix-mcp 0.0.9 → 0.0.11

package/README.md

@@ -28,28 +28,45 @@ Review the file first; `npx` downloads and runs the pinned package.
 
 ## Configuration
 
-By default, read only `.mcp.json` in Pi's working directory. There is no ancestor
-search, global config merge, automatic import, or persistent metadata cache.
-Relative `--mcp-config` paths resolve from that working directory; a stdio
-server's `cwd` resolves from the config directory and defaults to that directory.
+Without an explicit selection, the adapter reads these files in order:
 
-The adapter automatically loads the selected file and starts its enabled servers
-in all modes, without a confirmation prompt. Use `--mcp-config <path>` to select
-a different file.
+1. `<agent-dir>/mcp.json` for user-level servers. Pi's agent directory defaults
+   to `~/.pi/agent` and can be changed with `PI_CODING_AGENT_DIR`.
+2. `.mcp.json` in Pi's working directory for project-level servers.
 
-**Breaking change:** `--mcp-trust-config` has been removed. Remove it from existing
-launch commands; print and JSON sessions also load the default file automatically.
+Missing files are ignored. Project declarations replace global declarations by
+server name as complete entries; fields are not merged. A project entry with
+`"disabled": true` masks the corresponding global server. An invalid project
+entry also masks its global counterpart and reports the validation issue instead
+of starting the global definition. Relative stdio `cwd` values resolve from the
+file that declares the server and default to that file's directory. There is no
+ancestor search, cross-client import, or persistent metadata cache.
+
+Use `--mcp-config <path>` to read only that file for the session, without global
+or project fallback. A relative explicit path resolves from Pi's working
+directory. The adapter automatically starts every effective enabled server in all
+modes without a confirmation prompt.
 
-Review the file before starting Pi: it can launch arbitrary local programs and
-contact remote services. A bare `.mcp.json` is not protected by Pi's project-trust
-mechanism, and the adapter is not an OS sandbox. Set a server's `disabled` field
-to `true` to prevent it from starting.
+`getAgentDir()` cannot observe an `agentDir` supplied only through Pi 0.87's SDK
+because extensions do not receive it. Embedded users should also set
+`PI_CODING_AGENT_DIR` when they want the global file to follow an SDK override.
 
-At session startup, interactive and RPC sessions receive an `MCP config: <path>`
-notice with the resolved absolute path after the file is read. The notice
-identifies the configuration file, not whether every server connected; it never
-includes configuration contents. Missing, unreadable, or malformed files produce
-no notice. Print and JSON sessions remain silent.
+**Breaking change:** `--mcp-trust-config` has been removed. Remove it from existing
+launch commands; print and JSON sessions also load the default files
+automatically.
+
+Review both files before starting Pi: they can launch arbitrary local programs
+and contact remote services. Global servers start in every working directory. A
+bare project `.mcp.json` is not protected by Pi's project-trust mechanism, and
+the adapter is not an OS sandbox. Set a server's `disabled` field to `true` to
+prevent it from starting.
+
+At session startup, interactive and RPC sessions display every successfully
+loaded file as `MCP config (<scope>): <absolute-path>`, in precedence order. They
+display `MCP config: none found` when no applicable file exists, or a path-only
+error notice when a file fails to load. These notices occur before server startup
+and never include configuration contents or indicate that every server connected.
+Print and JSON sessions remain silent.
 
 ```json
 {
@@ -110,15 +127,17 @@ Unknown fields invalidate their server entry rather than being silently ignored.
 
 ### Configuration errors
 
-An invalid server entry is skipped without hiding healthy servers. Discovery's
-`servers` list includes a safe diagnostic for each skipped entry; a valid server
-name can still be used with `mcp({ action: "list", server: "name" })` to inspect
+An invalid server entry is skipped without hiding unrelated healthy servers.
+Discovery's `servers` list includes a safe diagnostic for each skipped entry; a
+valid server name can still be used with `mcp({ action: "list", server: "name" })` to inspect
 its status. Invalid names are replaced with their one-based entry positions.
 Diagnostics identify supported fields or migration steps without echoing URLs,
 commands, headers, argument values, or environment-variable names.
 
 Malformed JSON, invalid root structure, unknown root fields, and the file/server
-count limits remain fatal for the whole file. An invalid-only configuration
+count limits remain fatal. A fatal error in either default file prevents servers
+from the other file from starting. Each file may declare at most 32 entries, and
+the merged result may enable at most 32 servers. An invalid-only configuration
 reports that no valid servers remain. Disabled entries are omitted, not reported
 as failed connections. Correct the file and reload Pi to retry.
 
@@ -282,8 +301,9 @@ commands behind:
 
 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
+dialogs. Each dialog shows the argument description when the server provides
+one. 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
@@ -384,8 +404,9 @@ These artifacts may contain sensitive data and are **not deleted at session
 shutdown**; remove them when no
 longer needed. Output limits are not a complete memory or security sandbox.
 
-Configuration is limited to 256 KiB and 32 servers. Startup connects at most four
-servers concurrently. Each tool or prompt catalog is limited to 1000 entries,
+Each configuration file is limited to 256 KiB and 32 entries; the merged result
+can enable at most 32 servers. Startup connects at most four servers concurrently.
+Each tool or prompt catalog is limited to 1000 entries,
 100 pagination cursors, and 2 MiB of metadata. Direct resources and templates
 share a 1000-entry and 2 MiB limit, with up to 100 cursors for each endpoint.
 Individual input/output schemas are limited to 64 KiB. Prompt arguments and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikuma.cloud/pix-mcp",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "publishConfig": {
     "access": "public"
   },

package/src/config.ts

@@ -31,6 +31,19 @@ export interface Config {
   servers: ServerConfig[];
   issues: ConfigIssue[];
 }
+export interface MergedConfig {
+  servers: ServerConfig[];
+  issues: ConfigIssue[];
+}
+
+type ConfigDeclaration = ServerConfig | ConfigIssue | undefined;
+// Raw names can contain credentials. Keep precedence identities private while
+// exposing only validated server names or positional issue labels.
+const declarationsByConfig = new WeakMap<
+  Config,
+  Map<string, ConfigDeclaration>
+>();
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,48}$/;
 
 class ConfigError extends Error {
   readonly field: string | undefined;
@@ -121,7 +134,7 @@ function parseServer(
   path: string,
   env: NodeJS.ProcessEnv,
 ): ServerConfig | undefined {
-  if (!/^[A-Za-z0-9_-]{1,48}$/.test(name))
+  if (!SERVER_NAME_PATTERN.test(name))
     invalid(
       undefined,
       "Server names must contain 1–48 ASCII letters, digits, underscores, or hyphens.",
@@ -268,15 +281,17 @@ export async function readConfig(
     invalid("mcpServers", "At most 32 servers are supported.");
   const servers: ServerConfig[] = [];
   const issues: ConfigIssue[] = [];
+  const declarations = new Map<string, ConfigDeclaration>();
   for (const [index, [name, raw]] of entries.entries()) {
     try {
       const server = parseServer(name, raw, path, env);
+      declarations.set(name, server);
       if (server) servers.push(server);
     } catch (error) {
       // Invalid names and unknown keys can themselves contain credentials. Only
       // validated names and our fixed validation messages reach discovery.
-      issues.push({
-        name: /^[A-Za-z0-9_-]{1,48}$/.test(name)
+      const issue: ConfigIssue = {
+        name: SERVER_NAME_PATTERN.test(name)
           ? name
           : `Invalid server #${index + 1}`,
         ...(error instanceof ConfigError && error.field
@@ -286,8 +301,38 @@ export async function readConfig(
           error instanceof ConfigError
             ? error.message
             : "Invalid MCP configuration. Server could not be validated.",
-      });
+      };
+      declarations.set(name, issue);
+      issues.push(issue);
     }
   }
-  return { path, servers, issues };
+  const config = { path, servers, issues };
+  declarationsByConfig.set(config, declarations);
+  return config;
+}
+
+export function mergeConfigs(configs: Config[]): MergedConfig {
+  const declarations = new Map<string, ConfigDeclaration>();
+  for (const config of configs) {
+    const sourceDeclarations = declarationsByConfig.get(config);
+    if (!sourceDeclarations)
+      invalid(undefined, "Configuration declarations are unavailable.");
+    for (const [name, declaration] of sourceDeclarations) {
+      // Reinsertion makes effective declaration order follow source precedence.
+      declarations.delete(name);
+      declarations.set(name, declaration);
+    }
+  }
+  const merged: MergedConfig = { servers: [], issues: [] };
+  for (const declaration of declarations.values()) {
+    if (!declaration) continue;
+    if ("message" in declaration) merged.issues.push(declaration);
+    else merged.servers.push(declaration);
+  }
+  if (merged.servers.length > 32)
+    invalid(
+      "mcpServers",
+      "At most 32 enabled servers are supported across merged configurations.",
+    );
+  return merged;
 }

package/src/index.ts

@@ -1,9 +1,10 @@
 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,
@@ -13,7 +14,12 @@ import type {
 } 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,
@@ -69,6 +75,12 @@ interface ResourceSelection {
   item: ResourceEntry;
 }
 
+type ConfigScope = "explicit" | "global" | "project";
+interface ConfigSource {
+  scope: ConfigScope;
+  path: string;
+}
+
 interface State {
   alive: boolean;
   status: string;
@@ -111,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",
@@ -448,9 +460,14 @@ export default function mcp(pi: ExtensionAPI) {
     const dialogOptions = ctx.signal ? { signal: ctx.signal } : undefined;
     const argumentTokens: PromptArgumentToken[] = [];
     for (const argument of item.prompt.arguments ?? []) {
+      const description = compact(argument.description ?? "", 160);
+      const label = `${argument.name} (${argument.required ? "required" : "optional"})`;
+      const guidance = argument.required
+        ? "Enter a value"
+        : "Leave empty to omit";
       const value = await ctx.ui.input(
-        `${argument.name} (${argument.required ? "required" : "optional"})`,
-        argument.required ? "Enter a value" : "Leave empty to omit",
+        [label, description, guidance].filter(Boolean).join("\n"),
+        undefined,
         dialogOptions,
       );
       if (value === undefined) return;
@@ -810,6 +827,8 @@ export default function mcp(pi: ExtensionAPI) {
 
   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.",
@@ -824,19 +843,51 @@ export default function mcp(pi: ExtensionAPI) {
       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
@@ -870,9 +921,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();
     }