@ikuma.cloud/pix-mcp 0.0.9 → 0.0.10

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.
 
@@ -384,8 +403,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.10",
   "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",
@@ -810,6 +822,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 +838,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 +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();
     }