@pi-archimedes/mcp 2.3.0

package/src/config-write.ts

@@ -0,0 +1,207 @@
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stripJsonComments } from "./config.js";
+import type { ServerDef } from "./types.js";
+
+/**
+ * Safe write-back helpers for the project-local Pi override file
+ * `<cwd>/<CONFIG_DIR_NAME>/mcp.json` (ADR 0002: the /mcp command and the
+ * management panel only ever write the single changed field here).
+ *
+ * Security rules:
+ * - Only ONE field is ever added (`disabled` or `directTools`) — under
+ *   `mcpServers[serverName]`. No other field is ever read into these
+ *   helpers and written out, so credentials are never copied.
+ * - The read is tolerant (`//` comments via `stripJsonComments`, trailing
+ *   comma, missing/empty file → `{ mcpServers: {} }`), but a file that
+ *   doesn't parse is REFUSED (throw) rather than silently overwritten —
+ *   clobbering an unknown/corrupt file could destroy credentials.
+ * - The write is atomic: tmp file in the same dir, then rename over the
+ *   target (same pattern as `@pi-archimedes/core` settings-io).
+ */
+
+/** Parsed override document; extra top-level keys are preserved as-is. */
+type McpOverrideDoc = Record<string, unknown> & { mcpServers: Record<string, Record<string, unknown>> };
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Atomic write of a JSON document: tmp file in the SAME dir as the target,
+ * then rename over the target. 2-space indent + trailing newline. The
+ * parent dir is created (recursive) when missing. Named path (not cwd+
+ * config file) so both the override writer above, the project writer below,
+ * and outside callers (setup-panel scaffold) share this exact pattern.
+ * On a failed rename the tmp file is removed before re-throwing.
+ */
+export function writeJsonFileAtomic(path: string, doc: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = path + ".tmp";
+  const json = JSON.stringify(doc, null, 2) + "\n";
+  writeFileSync(tmp, json, "utf-8");
+  try {
+    renameSync(tmp, path);
+  } catch (e) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+    throw e;
+  }
+}
+
+function configPath(cwd: string): string {
+  return join(cwd, CONFIG_DIR_NAME, "mcp.json");
+}
+
+/**
+ * Read the project-local override file into a doc object.
+ * Missing or empty file → `{ mcpServers: {} }`. Unparseable or
+ * wrongly-shaped file → throw (never clobber data we cannot understand).
+ */
+function readDoc(cwd: string): McpOverrideDoc {
+  const path = configPath(cwd);
+  if (!existsSync(path)) return { mcpServers: {} };
+  const raw = readFileSync(path, "utf-8");
+  if (raw.trim() === "") return { mcpServers: {} };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripJsonComments(raw));
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — unparseable JSON: ${msg}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — top level is not an object`);
+  }
+  const mcpServers = parsed.mcpServers;
+  if (mcpServers !== undefined && !isPlainObject(mcpServers)) {
+    throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — "mcpServers" is not an object`);
+  }
+  const servers: Record<string, Record<string, unknown>> = {};
+  if (isPlainObject(mcpServers)) {
+    for (const [name, def] of Object.entries(mcpServers)) {
+      if (!isPlainObject(def)) {
+        throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — "mcpServers.${name}" is not an object`);
+      }
+      servers[name] = def;
+    }
+  }
+  return { ...parsed, mcpServers: servers };
+}
+
+/** Atomic write of the Pi override file (shared writer, `configPath` target). */
+function writeDoc(cwd: string, doc: McpOverrideDoc): void {
+  writeJsonFileAtomic(configPath(cwd), doc);
+}
+
+/**
+ * Set one field on one server entry, read-modify-write. Existing fields of
+ * that server, all other servers, and any extra top-level keys are preserved
+ * untouched; the only bytes added are the single field being written.
+ */
+function writeServerField(cwd: string, serverName: string, field: "disabled" | "directTools", value: unknown): void {
+  const doc = readDoc(cwd);
+  const server = doc.mcpServers[serverName] ?? {};
+  server[field] = value;
+  doc.mcpServers[serverName] = server;
+  writeDoc(cwd, doc);
+}
+
+/**
+ * Write only `{ disabled }` for a server into `<cwd>/<CONFIG_DIR_NAME>/mcp.json`
+ * (creating the dir and file if missing). Never copies credentials.
+ */
+export function writeServerDisabled(cwd: string, serverName: string, disabled: boolean): void {
+  writeServerField(cwd, serverName, "disabled", disabled);
+}
+
+/**
+ * Write only `{ directTools }` for a server into the same file.
+ * `true` exposes all tools directly, `false` hides them, a `string[]`
+ * exposes the named subset. Never copies credentials.
+ */
+export function writeServerDirectTools(cwd: string, serverName: string, value: true | false | string[]): void {
+  writeServerField(cwd, serverName, "directTools", value);
+}
+
+// ── Project-shared file (<cwd>/.mcp.json) — server DEFINITIONS ──────────────
+//
+// Distinct from the Pi override file above: this is the project-shared
+// `.mcp.json` (the layer `loadAllServerDefs` reads at working-dir precedence)
+// where NEW server DEFINITIONS belong. Imported/known/scaffolded servers are
+// merged IN here so they are discoverable by the normal config cascade.
+//
+// Read is tolerant (`//` comments / trailing comma / missing file → `{ mcpServers: {} }`)
+// via `stripJsonComments`, but a file that doesn't parse is REFUSED (throw) for the
+// same credential-safety reason as the override writer. The rewrite drops `//`
+// comments in that file — an accepted trade-off: this file is machine-managed by
+// the setup panel, so comment preservation is deliberately not enforced.
+
+type McpProjectDoc = Record<string, unknown> & { mcpServers: Record<string, unknown> };
+
+function projectConfigPath(cwd: string): string {
+  return join(cwd, ".mcp.json");
+}
+
+/**
+ * Read the project-shared `.mcp.json` into a doc object.
+ * Missing/empty file → `{ mcpServers: {} }`. Unparseable or wrongly-shaped
+ * file → throw (never clobber data we cannot understand).
+ */
+function readProjectDoc(cwd: string): McpProjectDoc {
+  const path = projectConfigPath(cwd);
+  if (!existsSync(path)) return { mcpServers: {} };
+  const raw = readFileSync(path, "utf-8");
+  if (raw.trim() === "") return { mcpServers: {} };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripJsonComments(raw));
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — unparseable JSON: ${msg}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — top level is not an object`);
+  }
+  const mcpServers = parsed.mcpServers;
+  if (mcpServers !== undefined && !isPlainObject(mcpServers)) {
+    throw new Error(`[archimedes/mcp] Refusing to overwrite ${path} — "mcpServers" is not an object`);
+  }
+  return { ...parsed, mcpServers: isPlainObject(mcpServers) ? mcpServers : {} };
+}
+
+/** Atomic write of the project-shared file (shared writer, `projectConfigPath` target). */
+function writeProjectDoc(cwd: string, doc: McpProjectDoc): void {
+  writeJsonFileAtomic(projectConfigPath(cwd), doc);
+}
+
+/**
+ * Merge new server definitions into `<cwd>/.mcp.json` (project-shared, NOT
+ * the Pi override file). Add-if-absent: an EXISTING entry for a given server
+ * name is left completely untouched; all other top-level keys and all other
+ * servers are preserved verbatim. Atomic tmp+rename, 2-space indent.
+ */
+export function mergeServerDefinitions(cwd: string, servers: Record<string, ServerDef>): void {
+  const doc = readProjectDoc(cwd);
+  for (const [name, def] of Object.entries(servers)) {
+    if (doc.mcpServers[name] === undefined) {
+      doc.mcpServers[name] = def;
+    }
+  }
+  writeProjectDoc(cwd, doc);
+}
+
+/**
+ * The server names currently defined in `<cwd>/.mcp.json` (empty list when
+ * the file is absent or empty). Shares the same refuses-on-unparseable rule
+ * as the writers — a corrupt file surfaces as an error instead of a guess.
+ */
+export function existingProjectServerNames(cwd: string): string[] {
+  return Object.keys(readProjectDoc(cwd).mcpServers);
+}

package/src/config.test.ts

@@ -0,0 +1,468 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { McpConfig, ServerDef } from "./types.js";
+import { DEFAULT_MCP_CONFIG } from "./types.js";
+import {
+  stripJsonComments,
+  mergeServerDefs,
+  resolveServerSettings,
+  loadServerDefs,
+  loadAllServerDefs,
+  URL_BOUND_AUTH_FIELDS,
+} from "./config.js";
+
+const globalConfig: McpConfig = { ...DEFAULT_MCP_CONFIG };
+
+const stdio = (extra: Record<string, unknown> = {}): ServerDef =>
+  ({ type: "stdio", command: "node", ...extra }) as ServerDef;
+
+const http = (extra: Record<string, unknown> = {}): ServerDef =>
+  ({ type: "http", url: "http://example.com", ...extra }) as ServerDef;
+
+describe("stripJsonComments", () => {
+  it("parses JSON with // comments and trailing commas", () => {
+    const raw = `{
+      // top-level comment
+      "mcpServers": {
+        "a": { "command": "node" }, // stdio server
+        "b": { "url": "http://x", "headers": { "X-Api": "k" } },
+      },
+    }`;
+    const parsed = JSON.parse(stripJsonComments(raw));
+    expect(parsed.mcpServers.a.command).toBe("node");
+    expect(parsed.mcpServers.b.url).toBe("http://x");
+    expect(parsed.mcpServers.b.headers).toEqual({ "X-Api": "k" });
+  });
+
+  it("does not strip // inside string literals", () => {
+    const raw = `{ "url": "https://example.com/path", "args": ["a//b"] } // trailing comment`;
+    const parsed = JSON.parse(stripJsonComments(raw));
+    expect(parsed.url).toBe("https://example.com/path");
+    expect(parsed.args).toEqual(["a//b"]);
+  });
+
+  it("strips block comments and keeps plain JSON unchanged", () => {
+    const raw = `{ /* block\ncomment */ "a": 1 }`;
+    const parsed = JSON.parse(stripJsonComments(raw));
+    expect(parsed.a).toBe(1);
+    const plain = `{"a": [1, 2, 3]}`;
+    expect(stripJsonComments(plain)).toBe(plain);
+  });
+});
+
+describe("URL_BOUND_AUTH_FIELDS", () => {
+  it("covers auth, headers, and bearerTokenEnv", () => {
+    expect([...URL_BOUND_AUTH_FIELDS].sort()).toEqual(["auth", "bearerTokenEnv", "headers"]);
+  });
+});
+
+describe("mergeServerDefs", () => {
+  it("higher layer overrides lower for the same server", () => {
+    const merged = mergeServerDefs([
+      { a: stdio({ command: "old" }) },
+      { a: stdio({ command: "new" }) },
+    ]);
+    expect(merged.a).toMatchObject({ command: "new" });
+  });
+
+  it("merges field-level: unspecified fields are inherited from lower layers", () => {
+    const merged = mergeServerDefs([
+      { a: stdio({ command: "node", args: ["x.js"], env: { K: "v" } }) },
+      { a: stdio({ command: "bun" }) },
+    ]);
+    expect(merged.a).toEqual({ type: "stdio", command: "bun", args: ["x.js"], env: { K: "v" } });
+  });
+
+  it("keeps a server present only in a lower layer", () => {
+    const merged = mergeServerDefs([
+      { low: stdio({ command: "node" }) },
+      { high: stdio({ command: "bun" }) },
+    ]);
+    expect(merged.low).toMatchObject({ command: "node" });
+    expect(merged.high).toMatchObject({ command: "bun" });
+  });
+
+  it("drops inherited auth/headers/bearerTokenEnv when a higher layer changes the url", () => {
+    const merged = mergeServerDefs([
+      {
+        s: http({
+          url: "http://old",
+          auth: { token: "secret" },
+          headers: { "X-Api": "k" },
+          bearerTokenEnv: "TOKEN",
+        }),
+      },
+      { s: http({ url: "http://new" }) },
+    ]);
+    const def = merged.s as ServerDef;
+    expect(def).toMatchObject({ url: "http://new" });
+    expect("auth" in def).toBe(false);
+    expect("headers" in def).toBe(false);
+    expect("bearerTokenEnv" in def).toBe(false);
+  });
+
+  it("keeps inherited auth fields when the url is unchanged", () => {
+    const merged = mergeServerDefs([
+      { s: http({ url: "http://same", auth: { token: "secret" }, headers: { "X-Api": "k" } }) },
+      { s: http({ url: "http://same", directTools: true }) },
+    ]);
+    const def = merged.s as ServerDef;
+    expect(def).toMatchObject({
+      url: "http://same",
+      directTools: true,
+      auth: { token: "secret" },
+      headers: { "X-Api": "k" },
+    });
+  });
+
+  it("keeps inherited auth fields when the higher layer has no url", () => {
+    const merged = mergeServerDefs([
+      { s: http({ url: "http://same", bearerTokenEnv: "TOKEN" }) },
+      { s: { type: "http", idleTimeout: 5 } as ServerDef }, // no url in this layer
+    ]);
+    expect(merged.s).toMatchObject({ url: "http://same", bearerTokenEnv: "TOKEN", idleTimeout: 5 });
+  });
+
+  it("keeps auth fields the higher layer specifies for the new url", () => {
+    const merged = mergeServerDefs([
+      { s: http({ url: "http://old", auth: { token: "old-secret" } }) },
+      { s: http({ url: "http://new", auth: { token: "new-secret" } }) },
+    ]);
+    expect(merged.s).toMatchObject({ url: "http://new", auth: { token: "new-secret" } });
+  });
+});
+
+describe("resolveServerSettings", () => {
+  it("applies defaults when nothing is set per-server", () => {
+    const s = resolveServerSettings(stdio(), globalConfig);
+    expect(s.lifecycle).toBe("lazy");
+    expect(s.idleTimeout).toBe(globalConfig.idleTimeout);
+    expect(s.toolPrefix).toBe(globalConfig.toolPrefix);
+    expect(s.directTools).toBe(globalConfig.directTools);
+  });
+
+  it("per-server idleTimeout wins over global", () => {
+    const s = resolveServerSettings(stdio({ idleTimeout: 5 }), globalConfig);
+    expect(s.idleTimeout).toBe(5);
+  });
+
+  it("per-server idleTimeout of 0 is honored (disables) rather than falling back to global", () => {
+    const s = resolveServerSettings(stdio({ idleTimeout: 0 }), globalConfig);
+    expect(s.idleTimeout).toBe(0);
+  });
+
+  it("global toolPrefix is used when per-server is absent, per-server wins when present", () => {
+    expect(resolveServerSettings(stdio(), globalConfig).toolPrefix).toBe(globalConfig.toolPrefix);
+    const custom: McpConfig = { ...globalConfig, toolPrefix: "mcp" };
+    expect(resolveServerSettings(stdio(), custom).toolPrefix).toBe("mcp");
+    expect(resolveServerSettings(stdio({ toolPrefix: "none" }), custom).toolPrefix).toBe("none");
+  });
+
+  it("per-server directTools wins over global", () => {
+    expect(resolveServerSettings(stdio({ directTools: ["t1"] }), globalConfig).directTools).toEqual(["t1"]);
+    expect(resolveServerSettings(stdio({ directTools: false }), globalConfig).directTools).toBe(false);
+  });
+
+  it("passes through includeTools/excludeTools/requestTimeoutMs/exposeResources/debug/protocolVersion", () => {
+    const s = resolveServerSettings(
+      stdio({
+        includeTools: ["a"],
+        excludeTools: ["b"],
+        requestTimeoutMs: 5000,
+        exposeResources: true,
+        debug: true,
+        protocolVersion: "2025-06-18",
+      }),
+      globalConfig,
+    );
+    expect(s.includeTools).toEqual(["a"]);
+    expect(s.excludeTools).toEqual(["b"]);
+    expect(s.requestTimeoutMs).toBe(5000);
+    expect(s.exposeResources).toBe(true);
+    expect(s.debug).toBe(true);
+    expect(s.protocolVersion).toBe("2025-06-18");
+  });
+
+  it("omits passthrough fields when not set per-server", () => {
+    const s = resolveServerSettings(stdio(), globalConfig);
+    expect("includeTools" in s).toBe(false);
+    expect("excludeTools" in s).toBe(false);
+    expect("requestTimeoutMs" in s).toBe(false);
+    expect("exposeResources" in s).toBe(false);
+    expect("debug" in s).toBe(false);
+    expect("protocolVersion" in s).toBe(false);
+  });
+});
+
+describe("loadServerDefs (integration with temp dirs)", () => {
+  let home: string;
+  let agentDir: string;
+  let wd: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "mcp-home-"));
+    agentDir = mkdtempSync(join(tmpdir(), "mcp-agent-"));
+    wd = mkdtempSync(join(tmpdir(), "mcp-wd-"));
+  });
+
+  afterEach(() => {
+    for (const dir of [home, agentDir, wd]) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  const write = (dir: string, rel: string, content: string): void => {
+    const p = join(dir, rel);
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, content);
+  };
+
+  it("loads all six precedence layers in order, with comments and url-binding applied", () => {
+    // 1. ~/.config/mcp/mcp.json (lowest)
+    write(
+      home,
+      join(".config", "mcp", "mcp.json"),
+      JSON.stringify({
+        mcpServers: {
+          svc: { type: "http", url: "http://v1", auth: { token: "tok" } },
+          onlyLow: { type: "stdio", command: "node" },
+        },
+      }),
+    );
+    // 2. ~/.agents/mcp.json — same url, adds a field (auth must survive)
+    write(
+      home,
+      join(".agents", "mcp.json"),
+      JSON.stringify({
+        mcpServers: { svc: { type: "http", url: "http://v1", directTools: true } },
+      }),
+    );
+    // 3. ~/.agents/mcp/mcp.json — url changes: inherited auth must be dropped
+    write(
+      home,
+      join(".agents", "mcp", "mcp.json"),
+      JSON.stringify({ mcpServers: { svc: { type: "http", url: "http://v2" } } }),
+    );
+    // 4. <agentDir>/mcp.json — with // comments and trailing commas
+    write(
+      agentDir,
+      "mcp.json",
+      `{
+        // agent dir config
+        "mcpServers": {
+          "svc": { "type": "http", "url": "http://v2" }, // unchanged url
+        },
+      }`,
+    );
+    // 5. <cwd>/.mcp.json — adds a new server
+    write(
+      wd,
+      ".mcp.json",
+      JSON.stringify({ mcpServers: { local: { type: "stdio", command: "bun" } } }),
+    );
+    // 6. <cwd>/.pi/mcp.json (highest) — per-server setting override
+    write(
+      wd,
+      join(".pi", "mcp.json"),
+      JSON.stringify({ mcpServers: { svc: { type: "http", url: "http://v2", idleTimeout: 3 } } }),
+    );
+
+    const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+
+    const svc = defs["svc"];
+    expect(svc).toMatchObject({ type: "http", url: "http://v2", directTools: true, idleTimeout: 3 });
+    expect("auth" in (svc ?? {})).toBe(false);
+    expect(defs["onlyLow"]).toMatchObject({ command: "node" });
+    expect(defs["local"]).toMatchObject({ command: "bun" });
+    expect(Object.keys(defs).sort()).toEqual(["local", "onlyLow", "svc"]);
+  });
+
+  it("excludes disabled servers and still honors disabled from a higher layer", () => {
+    write(
+      wd,
+      ".mcp.json",
+      JSON.stringify({
+        mcpServers: {
+          off: { type: "stdio", command: "node", disabled: true },
+          on: { type: "stdio", command: "node" },
+        },
+      }),
+    );
+    write(
+      home,
+      join(".config", "mcp", "mcp.json"),
+      JSON.stringify({ mcpServers: { off: { type: "stdio", command: "node" } } }),
+    );
+    const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+    expect("off" in defs).toBe(false);
+    expect(defs["on"]).toMatchObject({ command: "node" });
+  });
+
+  it("loadAllServerDefs keeps disabled servers (flag intact) while loadServerDefs excludes them", () => {
+    write(
+      wd,
+      ".mcp.json",
+      JSON.stringify({
+        mcpServers: {
+          off: { type: "stdio", command: "node", disabled: true },
+          on: { type: "stdio", command: "node" },
+        },
+      }),
+    );
+    write(
+      home,
+      join(".config", "mcp", "mcp.json"),
+      JSON.stringify({ mcpServers: { off: { type: "stdio", command: "node" } } }),
+    );
+    const all = loadAllServerDefs(wd, { homeDir: home, agentDir });
+    expect("off" in all).toBe(true);
+    expect(all["off"]).toMatchObject({ command: "node", disabled: true });
+    expect(all["on"]).toMatchObject({ command: "node" });
+    const active = loadServerDefs(wd, { homeDir: home, agentDir });
+    expect("off" in active).toBe(false);
+    expect(active["on"]).toMatchObject({ command: "node" });
+  });
+
+  describe("auth-type warning", () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('does not warn for auth: "oauth" (string)', () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: { svc: { type: "http", url: "http://x", auth: "oauth" } },
+        }),
+      );
+      const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+      expect(defs["svc"]).toMatchObject({ url: "http://x", auth: "oauth" });
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it("does not warn for bearer { token }, an OAuth config, or a single known field", () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: {
+            bearer: { type: "http", url: "http://x", auth: { token: "tok" } },
+            cfg: {
+              type: "http",
+              url: "http://y",
+              auth: { grantType: "client_credentials", clientId: "fixed-client" },
+            },
+            single: { type: "http", url: "http://z", auth: { clientId: "fixed-client" } },
+          },
+        }),
+      );
+      const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+      expect(Object.keys(defs).sort()).toEqual(["bearer", "cfg", "single"]);
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it("warns (but keeps) servers whose auth object has no known fields, even with a non-string token", () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: {
+            garbage: { type: "http", url: "http://x", auth: { foo: 1 } },
+            tokNum: { type: "http", url: "http://y", auth: { token: 5 } },
+          },
+        }),
+      );
+      const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+      expect(defs["garbage"]).toMatchObject({ url: "http://x" });
+      expect(defs["tokNum"]).toMatchObject({ url: "http://y" });
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it("warns (but keeps) servers with unknown auth shapes (other strings, numbers)", () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: {
+            bad: { type: "http", url: "http://x", auth: "azure-ad" },
+            num: { type: "http", url: "http://y", auth: 42 },
+          },
+        }),
+      );
+      const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+      expect(defs["bad"]).toMatchObject({ url: "http://x" });
+      expect(defs["num"]).toMatchObject({ url: "http://y" });
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+      expect(warnSpy.mock.calls.map((c) => c[0]).join("\n")).toContain("\"azure-ad\"");
+    });
+  });
+
+  describe("shape-based classification and mangled defs", () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it("loads a url server without a type field and does not warn", () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: {
+            api: { url: "https://api.example/mcp", headers: { Authorization: "Bearer x" } },
+          },
+        }),
+      );
+      const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+      expect(defs["api"]).toMatchObject({
+        url: "https://api.example/mcp",
+        headers: { Authorization: "Bearer x" },
+      });
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it("skips a def with neither a url nor a command and warns", () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: { broken: { foo: 1 }, ok: { url: "http://x" } },
+        }),
+      );
+      const defs = loadServerDefs(wd, { homeDir: home, agentDir });
+      expect("broken" in defs).toBe(false);
+      expect(defs["ok"]).toMatchObject({ url: "http://x" });
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const msg = warnSpy.mock.calls[0]?.[0] as string;
+      expect(msg).toContain('Server "broken"');
+      expect(msg).toContain("url");
+      expect(msg).toContain("command");
+    });
+
+    it("loadAllServerDefs keeps mangled defs intact (flag-intact principle)", () => {
+      write(
+        wd,
+        ".mcp.json",
+        JSON.stringify({
+          mcpServers: { broken: { foo: 1 } },
+        }),
+      );
+      const all = loadAllServerDefs(wd, { homeDir: home, agentDir });
+      expect(all["broken"]).toMatchObject({ foo: 1 });
+    });
+  });
+});