pi-mcp-adapter 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-09-27
+
+### Highlights
+
+- Approving a project's MCP servers once now covers every git worktree of that repository, so new worktrees stop asking again.
+- The project-server approval prompt no longer disappears after `/reload` or when another extension takes over the editor. Before, that could leave MCP stuck starting and add up to 30 seconds to every prompt.
+- When a server can't connect, the agent now sees the actual error instead of just "failed".
+- Config files are safer: files saved with a Windows byte order mark now load, and a config file the adapter can't parse is no longer overwritten.
+- A dependency update fixes a high-severity denial-of-service bug in TOML config parsing.
+
+### Changed
+
+- Project MCP server approvals are now shared across a repository's git worktrees. Approving a server in one checkout covers the same folder in the others, so a new worktree no longer asks again unless the server definition differs. This works for regular, bare, and `--separate-git-dir` repositories; only the main checkout of a `--separate-git-dir` repository asks once on its own. Thanks to [@MauricioRobayo](https://github.com/MauricioRobayo) for [issue #708](https://github.com/nicobailon/pi-mcp-adapter/issues/708).
+
+### Fixed
+
+- The project MCP server approval prompt now stays on screen until you answer it, including after `/reload` and panel saves. Before, `/reload` or another extension replacing the editor could hide it, leave MCP stuck starting, and make each prompt wait up to 30 seconds. Thanks to [@Gybra](https://github.com/Gybra) for [issue #690](https://github.com/nicobailon/pi-mcp-adapter/issues/690) and [PR #691](https://github.com/nicobailon/pi-mcp-adapter/pull/691), and to [@nazerim](https://github.com/nazerim) for [issue #695](https://github.com/nicobailon/pi-mcp-adapter/issues/695).
+- Disabled project MCP servers no longer ask for approval or delay interactive startup. Thanks to [@ismailokta](https://github.com/ismailokta) for reporting [issue #685](https://github.com/nicobailon/pi-mcp-adapter/issues/685).
+- The approval prompt now labels its path as the project config that needs approval, instead of calling it the server's source. A project file that only enables a server you defined globally no longer looks like it defines the command. Thanks to [@nazerim](https://github.com/nazerim) for reporting [issue #695](https://github.com/nicobailon/pi-mcp-adapter/issues/695).
+- When a server fails to connect, the agent now sees why. `mcp({})` status, the `mcp` tool's "not available" replies, and direct tools show the connection error (for example `spawn demo ENOENT`) next to "failed 12s ago", shortened to one line. Before, only `/mcp-adapter status` and the panel showed it.
+- MCP config files saved with a UTF-8 byte order mark, as some Windows editors do, now load instead of failing to parse. This covers adapter, shared, and imported JSON configs and imported TOML configs, and `pi-mcp-adapter init` keeps the servers in such a file. Thanks to [@quifox](https://github.com/quifox) for [PR #697](https://github.com/nicobailon/pi-mcp-adapter/pull/697).
+- Adding servers, imports, or direct tools no longer overwrites an existing MCP config file that fails to parse or has the wrong shape. The adapter reports the error and leaves the file alone; empty files can still be set up. Thanks to [@quifox](https://github.com/quifox) for [PR #693](https://github.com/nicobailon/pi-mcp-adapter/pull/693).
+- Repeating a word in an MCP tool search no longer hides tools that match it. Thanks to [@kojizada490-wq](https://github.com/kojizada490-wq) for [PR #678](https://github.com/nicobailon/pi-mcp-adapter/pull/678).
+- Searching the `/mcp-adapter` panel by server name now finds disabled or unconnected servers, so you can select and enable them. Thanks to [@nazerim](https://github.com/nazerim) for reporting [issue #696](https://github.com/nicobailon/pi-mcp-adapter/issues/696).
+- When Jev semantic search times out, is rate limited, or is unavailable, the lexical fallback now returns only tools from `settings.jev.allowedServers`, as the semantic results already did. Thanks to [@quifox](https://github.com/quifox) for [PR #698](https://github.com/nicobailon/pi-mcp-adapter/pull/698).
+- Changing a stdio server's `inheritEnv` or `literalEnv` setting now refreshes its cached tools, so search and direct tools no longer show stale entries. Thanks to [@kojizada490-wq](https://github.com/kojizada490-wq) for [PR #683](https://github.com/nicobailon/pi-mcp-adapter/pull/683).
+
+### Security
+
+- `smol-toml` now requires 1.9.0 or later, which fixes a high-severity denial of service on malformed TOML. The lockfile also moves `hono`, which comes in through the MCP SDK, to a release with its moderate advisories fixed, so `npm audit` on a lockfile install reports no production vulnerabilities. Thanks to [@jvpacini-CW](https://github.com/jvpacini-CW) for [PR #694](https://github.com/nicobailon/pi-mcp-adapter/pull/694).
+
 ## [3.0.0] - 2026-09-26
 
 ### Highlights

package/README.md

@@ -463,7 +463,7 @@ You can also pass only the `code` query parameter with `args: { code: "..." }`.
 
 ### Project server trust
 
-Servers defined or changed by project-scoped MCP files (`.mcp.json`, `.pi/mcp-adapter.json`, and opted-in ancestor project files) do not run merely because a repository was opened. This includes servers brought in through project `imports`, `claudePlugins`, `settings.agentPluginPaths`, repo-local host config files (even when imports or discovery are enabled globally), or Pi packages listed in project `.pi/settings.json`. If Pi reports the project as untrusted, the adapter blocks them. In a trusted interactive session, the adapter shows the source file and command or URL and asks once before the first connection. The approval is stored under the Pi agent directory and is tied to the canonical project path, server name, and complete effective definition; changing the definition requires a new approval. Blocked servers are identified in the panel, while MCP status includes the required trust or approval action.
+Servers defined or changed by project-scoped MCP files (`.mcp.json`, `.pi/mcp-adapter.json`, and opted-in ancestor project files) do not run merely because a repository was opened. This includes servers brought in through project `imports`, `claudePlugins`, `settings.agentPluginPaths`, repo-local host config files (even when imports or discovery are enabled globally), or Pi packages listed in project `.pi/settings.json`. If Pi reports the project as untrusted, the adapter blocks them. In a trusted interactive session, the adapter shows the source file and command or URL and asks once before the first connection. The approval is stored under the Pi agent directory and is tied to the canonical project path, server name, and complete effective definition; changing the definition requires a new approval. Git worktrees of one repository share approvals for the same folder, so a new worktree only asks when its definition differs. This covers regular, bare, and `--separate-git-dir` repositories; the one exception is the main checkout of a `--separate-git-dir` repository, which git records no link to, so it asks once on its own. Blocked servers are identified in the panel, while MCP status includes the required trust or approval action.
 
 In print, JSON, and RPC sessions, an unapproved project server is skipped. To intentionally allow project servers in trusted headless sessions, set `"projectServers": "allow"` in the **user-global** `settings` object. The default is `"ask"`; project files cannot change this policy. Explicit config files, programmatic configuration, global/import/plugin servers, and runtime registrations retain their existing behavior. Project servers are always excluded from extension-load initialization and are admitted only after `session_start` supplies Pi's trust context.
 

package/cli.js

@@ -86,29 +86,31 @@ function printHelp(log = console.log) {
 }
 
 function readJsonFile(filePath) {
-  return JSON.parse(stripJsonComments(fs.readFileSync(filePath, "utf-8"), { trailingCommas: true }));
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  return text.trim() === "" ? {} : JSON.parse(stripJsonComments(text, { trailingCommas: true }));
 }
 
 function loadPiConfig() {
-  if (!fs.existsSync(PI_CONFIG_PATH)) {
+  if (!fs.lstatSync(PI_CONFIG_PATH, { throwIfNoEntry: false })) {
     return { mcpServers: {} };
   }
 
   const raw = readJsonFile(PI_CONFIG_PATH);
-  const mcpServers = raw.mcpServers ?? raw["mcp-servers"] ?? {};
-  if (!mcpServers || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
-    throw new Error(`Invalid MCP config at ${PI_CONFIG_PATH}: expected \"mcpServers\" to be an object`);
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Invalid MCP config at ${PI_CONFIG_PATH}: top-level value must be an object`);
   }
-
-  const normalized = { ...raw };
-  delete normalized["mcp-servers"];
-
-  const imports = Array.isArray(raw.imports) ? raw.imports.filter((value) => typeof value === "string") : undefined;
-  return {
-    ...normalized,
-    mcpServers,
-    imports,
-  };
+  for (const key of ["mcpServers", "mcp-servers", "settings"]) {
+    const value = raw[key];
+    if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+      throw new Error(`Invalid MCP config at ${PI_CONFIG_PATH}: ${key} must be an object`);
+    }
+  }
+  if (raw.imports !== undefined && (!Array.isArray(raw.imports) || raw.imports.some((value) => typeof value !== "string"))) {
+    throw new Error(`Invalid MCP config at ${PI_CONFIG_PATH}: imports must be an array of strings`);
+  }
+  const { "mcp-servers": legacyServers, ...normalized } = raw;
+  return { ...normalized, mcpServers: raw.mcpServers ?? legacyServers ?? {} };
 }
 
 function findAvailableImports() {

package/commands.ts

@@ -771,6 +771,8 @@ export async function openMcpPanel(
     ctx.ui.custom(
       (tui, theme, keybindings, done) => {
         return createMcpPanel(config, cache, provenanceMap, callbacks, tui, (result: McpPanelResult) => {
+          let directToolsSaved = false;
+          let directToolsFileWritten = false;
           void (async () => {
             if (!result.cancelled && result.disabledChanges.size > 0) {
               for (const [serverName, disabled] of result.disabledChanges) {
@@ -785,7 +787,10 @@ export async function openMcpPanel(
               }
             }
             if (!result.cancelled && result.changes.size > 0) {
-              writeDirectToolsConfig(result.changes, provenanceMap, config);
+              writeDirectToolsConfig(result.changes, provenanceMap, config, () => {
+                directToolsFileWritten = true;
+              });
+              directToolsSaved = true;
               await onDirectToolsConfigChanged?.(result.changes);
               ctx.ui.notify("Direct tools updated for this session.", "info");
             }
@@ -793,8 +798,15 @@ export async function openMcpPanel(
             resolve();
           })().catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
-            ctx.ui.notify(`Direct tools updated, but live refresh failed: ${message}`, "error");
-            configChanged = true;
+            if (directToolsSaved) {
+              ctx.ui.notify(`Direct tools updated, but live refresh failed: ${message}`, "error");
+              configChanged = true;
+            } else if (directToolsFileWritten) {
+              ctx.ui.notify(`Direct tools were partially saved before another write failed: ${message}`, "error");
+              configChanged = true;
+            } else {
+              ctx.ui.notify(`Failed to save direct tools: ${message}`, "error");
+            }
             done(undefined);
             resolve();
           });

package/config.ts

@@ -1,5 +1,5 @@
 // config.ts - Config loading with import support
-import { chmodSync, existsSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
@@ -11,7 +11,7 @@ import { loadClaudePluginBundles } from "./claude-plugin-loader.ts";
 import { loadPackageMcpConfigs } from "./package-mcp-loader.ts";
 import { validateJevSettings } from "./jev-client.ts";
 import { formatServerNamespace, isServerDisabled, type ClaudePluginConfig, type HostConfigDiscovery, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
-import { parseJsonWithComments, toStringRecord } from "./utils.ts";
+import { parseJsonWithComments, stripUtf8Bom, toStringRecord } from "./utils.ts";
 
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
 const AGENTS_GLOBAL_CONFIG_PATHS = [
@@ -932,7 +932,7 @@ function resolveImportCandidates(importKind: ImportKind, cwd: string): ImportedS
 
 function readImportedConfig(path: string): unknown {
   const raw = readFileSync(path, "utf-8");
-  return path.endsWith(".toml") ? parseToml(raw) : parseJsonWithComments(raw);
+  return path.endsWith(".toml") ? parseToml(stripUtf8Bom(raw)) : parseJsonWithComments(raw);
 }
 
 function loadImportedConfig(
@@ -1335,22 +1335,30 @@ function buildConfigWritePreview(filePath: string, nextRaw: Record<string, unkno
 }
 
 function readRawConfigObject(filePath: string): Record<string, unknown> {
-  if (!existsSync(filePath)) return {};
+  if (!lstatSync(filePath, { throwIfNoEntry: false })) return {};
 
   try {
-    const raw = parseJsonWithComments(readFileSync(filePath, "utf-8"));
-    return raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
-  } catch {
-    return {};
+    const text = readFileSync(filePath, "utf-8");
+    if (text.trim() === "") return {};
+    const raw = parseJsonWithComments(text);
+    if (!isRecord(raw)) throw new Error("top-level value must be an object");
+    return raw;
+  } catch (error) {
+    throw new Error(`Failed to read MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
 }
 
 function writeConfigText(writePath: string, text: string): void {
+  const originalPath = writePath;
   let mode: number | undefined;
   try {
     writePath = realpathSync(writePath);
     mode = statSync(writePath).mode & 0o777;
-  } catch {}
+  } catch (error) {
+    if (lstatSync(originalPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      throw new Error(`Cannot write MCP config at ${originalPath}: symbolic link target is unavailable`, { cause: error });
+    }
+  }
   mkdirSync(dirname(writePath), { recursive: true });
   const tmpPath = `${writePath}.${process.pid}.tmp`;
   rmSync(tmpPath, { force: true });
@@ -1380,16 +1388,7 @@ export function writeJevSemanticSearchConfig(
   effectiveJev?: unknown,
 ): { path: string; changed: boolean } {
   const filePath = overridePath ? getPiGlobalConfigPath(overridePath) : getProjectPiConfigPath(cwd);
-  let raw: Record<string, unknown> = {};
-  if (existsSync(filePath)) {
-    try {
-      const parsed = parseJsonWithComments(readFileSync(filePath, "utf8"));
-      if (!isRecord(parsed)) throw new Error("top-level value must be an object");
-      raw = parsed;
-    } catch (error) {
-      throw new Error(`Failed to update Jev settings at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-    }
-  }
+  const raw = readRawConfigObject(filePath);
   if (raw.settings !== undefined && !isRecord(raw.settings)) {
     throw new Error(`Failed to update Jev settings at ${filePath}: settings must be an object`);
   }
@@ -1408,12 +1407,21 @@ export function writeJevSemanticSearchConfig(
   return { path: filePath, changed: true };
 }
 
-function getServersObject(raw: Record<string, unknown>): Record<string, ServerEntry> {
-  const existing = raw.mcpServers ?? raw["mcp-servers"] ?? {};
-  if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
-    return {};
+function getServersObject(raw: Record<string, unknown>, filePath: string): Record<string, ServerEntry> {
+  for (const key of ["mcpServers", "mcp-servers"]) {
+    if (Object.hasOwn(raw, key) && !isRecord(raw[key])) {
+      throw new Error(`Failed to update MCP config at ${filePath}: ${key} must be an object`);
+    }
   }
-  return existing as Record<string, ServerEntry>;
+  return (raw.mcpServers ?? raw["mcp-servers"] ?? {}) as Record<string, ServerEntry>;
+}
+
+function getConfigImports(raw: Record<string, unknown>, filePath: string): ImportKind[] {
+  if (raw.imports === undefined) return [];
+  if (!Array.isArray(raw.imports) || raw.imports.some((value) => typeof value !== "string")) {
+    throw new Error(`Failed to update MCP config at ${filePath}: imports must be an array of strings`);
+  }
+  return raw.imports as ImportKind[];
 }
 
 function setServersObject(raw: Record<string, unknown>, servers: Record<string, ServerEntry>): void {
@@ -1438,18 +1446,7 @@ export function writeProjectServerDisabledOverride(
   disabled: boolean,
 ): ServerDisabledOverrideResult {
   const filePath = getProjectPiConfigPath(cwd);
-  let raw: Record<string, unknown> = {};
-  if (existsSync(filePath)) {
-    try {
-      const parsed = parseJsonWithComments(readFileSync(filePath, "utf-8"));
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("root value must be an object");
-      }
-      raw = parsed as Record<string, unknown>;
-    } catch (error) {
-      throw new Error(`Failed to read project MCP override at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-    }
-  }
+  const raw = readRawConfigObject(filePath);
 
   const serverKey = raw.mcpServers !== undefined ? "mcpServers" : raw["mcp-servers"] !== undefined ? "mcp-servers" : "mcpServers";
   const rawServers = raw[serverKey];
@@ -1565,17 +1562,17 @@ function detectRepoPrompt(summary: Omit<McpDiscoverySummary, "fingerprint" | "re
 export function previewCompatibilityImports(importKinds: ImportKind[], overridePath?: string): ConfigWritePreview {
   const targetPath = getPiGlobalConfigPath(overridePath);
   const raw = readRawConfigObject(targetPath);
-  const currentImports = Array.isArray(raw.imports) ? raw.imports.filter((value): value is ImportKind => typeof value === "string") : [];
+  const currentImports = getConfigImports(raw, targetPath);
   const merged = [...new Set([...currentImports, ...importKinds])];
   const nextRaw = { ...raw, imports: merged };
-  setServersObject(nextRaw, getServersObject(nextRaw));
+  setServersObject(nextRaw, getServersObject(nextRaw, targetPath));
   return buildConfigWritePreview(targetPath, nextRaw);
 }
 
 export function ensureCompatibilityImports(importKinds: ImportKind[], overridePath?: string): { path: string; added: ImportKind[] } {
   const targetPath = getPiGlobalConfigPath(overridePath);
   const raw = readRawConfigObject(targetPath);
-  const currentImports = Array.isArray(raw.imports) ? raw.imports.filter((value): value is ImportKind => typeof value === "string") : [];
+  const currentImports = getConfigImports(raw, targetPath);
   const merged = [...new Set([...currentImports, ...importKinds])];
   const added = merged.filter((kind) => !currentImports.includes(kind));
   if (added.length === 0) {
@@ -1583,7 +1580,7 @@ export function ensureCompatibilityImports(importKinds: ImportKind[], overridePa
   }
 
   raw.imports = merged;
-  const servers = getServersObject(raw);
+  const servers = getServersObject(raw, targetPath);
   setServersObject(raw, servers);
   writeRawConfigObject(targetPath, raw);
   return { path: targetPath, added };
@@ -1595,14 +1592,20 @@ export function buildStarterProjectConfig(): McpConfig {
   };
 }
 
+function assertScaffoldTargetAbsent(filePath: string): void {
+  if (lstatSync(filePath, { throwIfNoEntry: false })) throw new Error(`Cannot scaffold MCP config at ${filePath}: file already exists`);
+}
+
 export function previewStarterSharedConfig(target: SharedConfigTarget, cwd = process.cwd()): ConfigWritePreview {
   const targetPath = getSharedConfigPath(target, cwd);
+  assertScaffoldTargetAbsent(targetPath);
   const nextRaw = { mcpServers: buildStarterProjectConfig().mcpServers };
   return buildConfigWritePreview(targetPath, nextRaw);
 }
 
 export function writeStarterSharedConfig(target: SharedConfigTarget, cwd = process.cwd()): string {
   const targetPath = getSharedConfigPath(target, cwd);
+  assertScaffoldTargetAbsent(targetPath);
   const raw = { mcpServers: buildStarterProjectConfig().mcpServers };
   writeRawConfigObject(targetPath, raw);
   return targetPath;
@@ -1619,7 +1622,7 @@ export function writeStarterProjectConfig(cwd = process.cwd()): string {
 export function previewSharedServerEntry(filePath: string, serverName: string, entry: ServerEntry): ConfigWritePreview {
   const raw = readRawConfigObject(filePath);
   const nextRaw = { ...raw };
-  const servers = getServersObject(nextRaw);
+  const servers = getServersObject(nextRaw, filePath);
   servers[serverName] = entry;
   setServersObject(nextRaw, servers);
   return buildConfigWritePreview(filePath, nextRaw);
@@ -1627,7 +1630,7 @@ export function previewSharedServerEntry(filePath: string, serverName: string, e
 
 export function writeSharedServerEntry(filePath: string, serverName: string, entry: ServerEntry): string {
   const raw = readRawConfigObject(filePath);
-  const servers = getServersObject(raw);
+  const servers = getServersObject(raw, filePath);
   servers[serverName] = entry;
   setServersObject(raw, servers);
   writeRawConfigObject(filePath, raw);
@@ -1684,6 +1687,7 @@ export function writeDirectToolsConfig(
   changes: Map<string, true | string[] | false>,
   provenance: Map<string, ServerProvenance>,
   fullConfig: McpConfig,
+  onFileWritten?: () => void,
 ): void {
   const byPath = new Map<string, { name: string; value: true | string[] | false; prov: ServerProvenance }[]>();
 
@@ -1697,10 +1701,12 @@ export function writeDirectToolsConfig(
     byPath.get(targetPath)!.push({ name: serverName, value, prov });
   }
 
+  // Validate every target before writing any, then re-read each one: two paths can alias one file.
+  for (const filePath of byPath.keys()) getServersObject(readRawConfigObject(filePath), filePath);
+
   for (const [filePath, entries] of byPath) {
     const raw = readRawConfigObject(filePath);
-    const servers = getServersObject(raw);
-
+    const servers = getServersObject(raw, filePath);
     for (const { name, value, prov } of entries) {
       if (prov.kind === "import") {
         const fullDef = fullConfig.mcpServers[name];
@@ -1714,6 +1720,7 @@ export function writeDirectToolsConfig(
 
     setServersObject(raw, servers);
     writeRawConfigObject(filePath, raw);
+    onFileWritten?.();
   }
 }
 

package/direct-tools.ts

@@ -3,7 +3,8 @@ import { UrlElicitationRequiredError, type Client } from "@modelcontextprotocol/
 import type { McpExtensionState } from "./state.ts";
 import { disabledServerReason } from "./project-server-trust.ts";
 import type { DirectToolSpec, McpContent } from "./types.ts";
-import { lazyConnect, getFailureAgeSeconds, clearFailure } from "./init.ts";
+import { lazyConnect, clearFailure } from "./init.ts";
+import { describeFailure } from "./failure-backoff.ts";
 import { abortable, throwIfAborted } from "./abort.ts";
 import { formatSchema } from "./tool-metadata.ts";
 import { resolveMcpResultContent, transformMcpResourceContents } from "./tool-registrar.ts";
@@ -190,9 +191,9 @@ export function createDirectToolExecutor(
           details: { error: "auth_required", server: spec.serverName, message, autoAuthAttempted },
         };
       }
-      const failedAgo = getFailureAgeSeconds(state, spec.serverName);
+      const failure = describeFailure(state, spec.serverName);
       return {
-        content: [{ type: "text" as const, text: `MCP server "${spec.serverName}" not available${failedAgo !== null ? ` (failed ${failedAgo}s ago)` : ""}` }],
+        content: [{ type: "text" as const, text: `MCP server "${spec.serverName}" not available${failure !== null ? ` (${failure})` : ""}` }],
         details: { error: "server_unavailable", server: spec.serverName },
       };
     }

package/dist/config.d.ts

@@ -142,6 +142,6 @@ export declare function writeStarterProjectConfig(cwd?: string): string;
 export declare function previewSharedServerEntry(filePath: string, serverName: string, entry: ServerEntry): ConfigWritePreview;
 export declare function writeSharedServerEntry(filePath: string, serverName: string, entry: ServerEntry): string;
 export declare function getServerProvenance(overridePath?: string, cwd?: string): Map<string, ServerProvenance>;
-export declare function writeDirectToolsConfig(changes: Map<string, true | string[] | false>, provenance: Map<string, ServerProvenance>, fullConfig: McpConfig): void;
+export declare function writeDirectToolsConfig(changes: Map<string, true | string[] | false>, provenance: Map<string, ServerProvenance>, fullConfig: McpConfig, onFileWritten?: () => void): void;
 export declare function resolveConfiguredOAuthDir(raw: unknown, cwd?: string): string | undefined;
 export {};

package/dist/config.js

@@ -1,5 +1,5 @@
 // config.ts - Config loading with import support
-import { chmodSync, existsSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
@@ -11,7 +11,7 @@ import { loadClaudePluginBundles } from "./claude-plugin-loader.js";
 import { loadPackageMcpConfigs } from "./package-mcp-loader.js";
 import { validateJevSettings } from "./jev-client.js";
 import { formatServerNamespace, isServerDisabled } from "./types.js";
-import { parseJsonWithComments, toStringRecord } from "./utils.js";
+import { parseJsonWithComments, stripUtf8Bom, toStringRecord } from "./utils.js";
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
 const AGENTS_GLOBAL_CONFIG_PATHS = [
     join(homedir(), ".agents", "mcp.json"),
@@ -776,7 +776,7 @@ function resolveImportCandidates(importKind, cwd) {
 }
 function readImportedConfig(path) {
     const raw = readFileSync(path, "utf-8");
-    return path.endsWith(".toml") ? parseToml(raw) : parseJsonWithComments(raw);
+    return path.endsWith(".toml") ? parseToml(stripUtf8Bom(raw)) : parseJsonWithComments(raw);
 }
 function loadImportedConfig(importKind, cwd, warningPrefix) {
     if (importKind === "opencode") {
@@ -1155,23 +1155,33 @@ function buildConfigWritePreview(filePath, nextRaw) {
     };
 }
 function readRawConfigObject(filePath) {
-    if (!existsSync(filePath))
+    if (!lstatSync(filePath, { throwIfNoEntry: false }))
         return {};
     try {
-        const raw = parseJsonWithComments(readFileSync(filePath, "utf-8"));
-        return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+        const text = readFileSync(filePath, "utf-8");
+        if (text.trim() === "")
+            return {};
+        const raw = parseJsonWithComments(text);
+        if (!isRecord(raw))
+            throw new Error("top-level value must be an object");
+        return raw;
     }
-    catch {
-        return {};
+    catch (error) {
+        throw new Error(`Failed to read MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }
 function writeConfigText(writePath, text) {
+    const originalPath = writePath;
     let mode;
     try {
         writePath = realpathSync(writePath);
         mode = statSync(writePath).mode & 0o777;
     }
-    catch { }
+    catch (error) {
+        if (lstatSync(originalPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+            throw new Error(`Cannot write MCP config at ${originalPath}: symbolic link target is unavailable`, { cause: error });
+        }
+    }
     mkdirSync(dirname(writePath), { recursive: true });
     const tmpPath = `${writePath}.${process.pid}.tmp`;
     rmSync(tmpPath, { force: true });
@@ -1199,18 +1209,7 @@ export function writeSharedConfigText(filePath, text) {
 }
 export function writeJevSemanticSearchConfig(overridePath, cwd, allowedServers, effectiveJev) {
     const filePath = overridePath ? getPiGlobalConfigPath(overridePath) : getProjectPiConfigPath(cwd);
-    let raw = {};
-    if (existsSync(filePath)) {
-        try {
-            const parsed = parseJsonWithComments(readFileSync(filePath, "utf8"));
-            if (!isRecord(parsed))
-                throw new Error("top-level value must be an object");
-            raw = parsed;
-        }
-        catch (error) {
-            throw new Error(`Failed to update Jev settings at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-        }
-    }
+    const raw = readRawConfigObject(filePath);
     if (raw.settings !== undefined && !isRecord(raw.settings)) {
         throw new Error(`Failed to update Jev settings at ${filePath}: settings must be an object`);
     }
@@ -1229,12 +1228,21 @@ export function writeJevSemanticSearchConfig(overridePath, cwd, allowedServers,
     writeRawConfigObject(filePath, raw);
     return { path: filePath, changed: true };
 }
-function getServersObject(raw) {
-    const existing = raw.mcpServers ?? raw["mcp-servers"] ?? {};
-    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
-        return {};
+function getServersObject(raw, filePath) {
+    for (const key of ["mcpServers", "mcp-servers"]) {
+        if (Object.hasOwn(raw, key) && !isRecord(raw[key])) {
+            throw new Error(`Failed to update MCP config at ${filePath}: ${key} must be an object`);
+        }
     }
-    return existing;
+    return (raw.mcpServers ?? raw["mcp-servers"] ?? {});
+}
+function getConfigImports(raw, filePath) {
+    if (raw.imports === undefined)
+        return [];
+    if (!Array.isArray(raw.imports) || raw.imports.some((value) => typeof value !== "string")) {
+        throw new Error(`Failed to update MCP config at ${filePath}: imports must be an array of strings`);
+    }
+    return raw.imports;
 }
 function setServersObject(raw, servers) {
     delete raw["mcp-servers"];
@@ -1247,19 +1255,7 @@ function setServersObject(raw, servers) {
  */
 export function writeProjectServerDisabledOverride(overridePath, cwd, serverName, disabled) {
     const filePath = getProjectPiConfigPath(cwd);
-    let raw = {};
-    if (existsSync(filePath)) {
-        try {
-            const parsed = parseJsonWithComments(readFileSync(filePath, "utf-8"));
-            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-                throw new Error("root value must be an object");
-            }
-            raw = parsed;
-        }
-        catch (error) {
-            throw new Error(`Failed to read project MCP override at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-        }
-    }
+    const raw = readRawConfigObject(filePath);
     const serverKey = raw.mcpServers !== undefined ? "mcpServers" : raw["mcp-servers"] !== undefined ? "mcp-servers" : "mcpServers";
     const rawServers = raw[serverKey];
     if (rawServers !== undefined && (!rawServers || typeof rawServers !== "object" || Array.isArray(rawServers))) {
@@ -1368,23 +1364,23 @@ function detectRepoPrompt(summary, cwd = process.cwd()) {
 export function previewCompatibilityImports(importKinds, overridePath) {
     const targetPath = getPiGlobalConfigPath(overridePath);
     const raw = readRawConfigObject(targetPath);
-    const currentImports = Array.isArray(raw.imports) ? raw.imports.filter((value) => typeof value === "string") : [];
+    const currentImports = getConfigImports(raw, targetPath);
     const merged = [...new Set([...currentImports, ...importKinds])];
     const nextRaw = { ...raw, imports: merged };
-    setServersObject(nextRaw, getServersObject(nextRaw));
+    setServersObject(nextRaw, getServersObject(nextRaw, targetPath));
     return buildConfigWritePreview(targetPath, nextRaw);
 }
 export function ensureCompatibilityImports(importKinds, overridePath) {
     const targetPath = getPiGlobalConfigPath(overridePath);
     const raw = readRawConfigObject(targetPath);
-    const currentImports = Array.isArray(raw.imports) ? raw.imports.filter((value) => typeof value === "string") : [];
+    const currentImports = getConfigImports(raw, targetPath);
     const merged = [...new Set([...currentImports, ...importKinds])];
     const added = merged.filter((kind) => !currentImports.includes(kind));
     if (added.length === 0) {
         return { path: targetPath, added: [] };
     }
     raw.imports = merged;
-    const servers = getServersObject(raw);
+    const servers = getServersObject(raw, targetPath);
     setServersObject(raw, servers);
     writeRawConfigObject(targetPath, raw);
     return { path: targetPath, added };
@@ -1394,13 +1390,19 @@ export function buildStarterProjectConfig() {
         mcpServers: {},
     };
 }
+function assertScaffoldTargetAbsent(filePath) {
+    if (lstatSync(filePath, { throwIfNoEntry: false }))
+        throw new Error(`Cannot scaffold MCP config at ${filePath}: file already exists`);
+}
 export function previewStarterSharedConfig(target, cwd = process.cwd()) {
     const targetPath = getSharedConfigPath(target, cwd);
+    assertScaffoldTargetAbsent(targetPath);
     const nextRaw = { mcpServers: buildStarterProjectConfig().mcpServers };
     return buildConfigWritePreview(targetPath, nextRaw);
 }
 export function writeStarterSharedConfig(target, cwd = process.cwd()) {
     const targetPath = getSharedConfigPath(target, cwd);
+    assertScaffoldTargetAbsent(targetPath);
     const raw = { mcpServers: buildStarterProjectConfig().mcpServers };
     writeRawConfigObject(targetPath, raw);
     return targetPath;
@@ -1414,14 +1416,14 @@ export function writeStarterProjectConfig(cwd = process.cwd()) {
 export function previewSharedServerEntry(filePath, serverName, entry) {
     const raw = readRawConfigObject(filePath);
     const nextRaw = { ...raw };
-    const servers = getServersObject(nextRaw);
+    const servers = getServersObject(nextRaw, filePath);
     servers[serverName] = entry;
     setServersObject(nextRaw, servers);
     return buildConfigWritePreview(filePath, nextRaw);
 }
 export function writeSharedServerEntry(filePath, serverName, entry) {
     const raw = readRawConfigObject(filePath);
-    const servers = getServersObject(raw);
+    const servers = getServersObject(raw, filePath);
     servers[serverName] = entry;
     setServersObject(raw, servers);
     writeRawConfigObject(filePath, raw);
@@ -1469,7 +1471,7 @@ export function getServerProvenance(overridePath, cwd = process.cwd()) {
     }
     return provenance;
 }
-export function writeDirectToolsConfig(changes, provenance, fullConfig) {
+export function writeDirectToolsConfig(changes, provenance, fullConfig, onFileWritten) {
     const byPath = new Map();
     for (const [serverName, value] of changes) {
         const prov = provenance.get(serverName);
@@ -1480,9 +1482,12 @@ export function writeDirectToolsConfig(changes, provenance, fullConfig) {
             byPath.set(targetPath, []);
         byPath.get(targetPath).push({ name: serverName, value, prov });
     }
+    // Validate every target before writing any, then re-read each one: two paths can alias one file.
+    for (const filePath of byPath.keys())
+        getServersObject(readRawConfigObject(filePath), filePath);
     for (const [filePath, entries] of byPath) {
         const raw = readRawConfigObject(filePath);
-        const servers = getServersObject(raw);
+        const servers = getServersObject(raw, filePath);
         for (const { name, value, prov } of entries) {
             if (prov.kind === "import") {
                 const fullDef = fullConfig.mcpServers[name];
@@ -1496,6 +1501,7 @@ export function writeDirectToolsConfig(changes, provenance, fullConfig) {
         }
         setServersObject(raw, servers);
         writeRawConfigObject(filePath, raw);
+        onFileWritten?.();
     }
 }
 export function resolveConfiguredOAuthDir(raw, cwd = process.cwd()) {