context-doctor 0.31.0 → 0.32.0

package/dist/install.js

@@ -68,11 +68,35 @@ function serverEntry() {
  * wrapper that every working Windows MCP config uses.
  *
  * Exported so the platform branch is testable from any host OS.
+ *
+ * npx resolves its first operand as a PACKAGE name. context-doctor-mcp is
+ * only a bin inside the context-doctor package, so `npx -y context-doctor-mcp`
+ * asked npm for a package that does not exist: unless a global install
+ * happened to put that command on PATH, every app got a server that never
+ * started. The main bin's `mcp` subcommand is the same server.
  */
 export function npxLauncher(platformName) {
     return platformName === "win32"
-        ? { command: "cmd", args: ["/c", "npx", "-y", "context-doctor-mcp"] }
-        : { command: "npx", args: ["-y", "context-doctor-mcp"] };
+        ? { command: "cmd", args: ["/c", "npx", "-y", "context-doctor", "mcp"] }
+        : { command: "npx", args: ["-y", "context-doctor", "mcp"] };
+}
+/**
+ * True for the launcher installs before 0.31.2 wrote: npx asked to run a
+ * package named context-doctor-mcp, which is not on npm. npx does fall back
+ * to a command of that name already on PATH, so it starts where a global
+ * install provides one; everywhere else npm answers 404.
+ */
+export function launcherNamesMissingPackage(entry) {
+    if (!entry)
+        return false;
+    const words = [String(entry.command ?? ""), ...(Array.isArray(entry.args) ? entry.args.map(String) : [])];
+    const npx = words.findIndex((w) => /(^|[\\/])npx(\.cmd)?$/i.test(w));
+    if (npx === -1)
+        return false;
+    const rest = words.slice(npx + 1);
+    if (rest.some((w) => w === "-p" || w.startsWith("--package")))
+        return false;
+    return rest.find((w) => !w.startsWith("-")) === "context-doctor-mcp";
 }
 export function readJson(path) {
     if (!existsSync(path))
@@ -84,10 +108,26 @@ export function readJson(path) {
         throw new Error(`${path} exists but is not valid JSON — fix or remove it first (${e.message})`);
     }
 }
-export function writeJsonWithBackup(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
+/**
+ * Config files already backed up (or found absent) in this process.
+ *
+ * One install writes ~/.claude/settings.json up to three times (prompt hook,
+ * compaction hook, status line). Copying before every write left a .backup
+ * that already held our own first write, so the user's original was gone
+ * before the run even finished. The first write of a run keeps the original.
+ */
+const backedUp = new Set();
+/** Copy `path` to its .context-doctor.backup, once per run. */
+export function backupOnce(path) {
+    if (backedUp.has(path))
+        return;
+    backedUp.add(path);
     if (existsSync(path))
         copyFileSync(path, path + ".context-doctor.backup");
+}
+export function writeJsonWithBackup(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    backupOnce(path);
     writeFileSync(path, JSON.stringify(data, null, 2));
 }
 /**
@@ -95,7 +135,7 @@ export function writeJsonWithBackup(path, data) {
  * Used to prefer a global `context-doctor` install for the hook: a stable
  * location that survives both package updates and Node upgrades.
  */
-function binOnPath(name) {
+export function binOnPath(name) {
     const exts = platform() === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
     for (const dir of (process.env.PATH ?? "").split(delimiter)) {
         if (!dir)
@@ -344,41 +384,131 @@ function installSkillInto(skillDest) {
 export function codexDir() {
     return join(homedir(), ".codex");
 }
+// Our key as TOML allows it to be written: bare or quoted, any spacing.
+const OUR_KEY = String.raw `\s*mcp_servers\s*\.\s*(?:context-doctor|"context-doctor"|'context-doctor')\s*`;
+/** Our table's header, with or without a trailing comment. */
+const OUR_HEADER = new RegExp(String.raw `^\s*\[${OUR_KEY}\]\s*(?:#.*)?$`);
+/** A subtable of ours, e.g. [mcp_servers.context-doctor.env]. */
+const OUR_SUBHEADER = new RegExp(String.raw `^\s*\[${OUR_KEY}\.[^\]]*\]\s*(?:#.*)?$`);
+const ANY_HEADER = /^\s*\[/;
+/**
+ * [start, end) line ranges of our tables (and, when asked, our subtables).
+ *
+ * A table runs to the next header, except that comment lines directly above
+ * that header describe IT: they stay with the next table rather than being
+ * deleted along with ours.
+ */
+function codexTableRanges(lines, withSubtables) {
+    const ranges = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!OUR_HEADER.test(lines[i]) && !(withSubtables && OUR_SUBHEADER.test(lines[i])))
+            continue;
+        let end = i + 1;
+        while (end < lines.length && !ANY_HEADER.test(lines[end]))
+            end++;
+        if (end < lines.length) {
+            let k = end;
+            while (k > i + 1 && /^\s*(#.*)?$/.test(lines[k - 1]))
+                k--;
+            // Blank lines after our last key are ours; the comments after them are not.
+            while (k < end && lines[k].trim() === "")
+                k++;
+            end = k;
+        }
+        ranges.push([i, end]);
+        i = end - 1;
+    }
+    return ranges;
+}
+/**
+ * Lines that define context-doctor WITHOUT a header of its own:
+ *   [mcp_servers] context-doctor = { command = "npx", ... }   (inline table)
+ *   [mcp_servers] context-doctor.command = "npx"               (dotted keys)
+ *   mcp_servers.context-doctor.command = "npx"                 (dotted, at the root)
+ * Appending a [mcp_servers.context-doctor] table next to any of these defines
+ * the key twice, which is invalid TOML, so these are refused instead.
+ */
+function inlineCodexDefinition(lines) {
+    const found = [];
+    let table = ""; // "" = the root table; null = inside an array of tables
+    const norm = (s) => s.replace(/\s+/g, "").replace(/["']/g, "");
+    lines.forEach((line, i) => {
+        if (/^\s*\[\[/.test(line)) {
+            table = null;
+            return;
+        }
+        const header = line.match(/^\s*\[([^\[\]]*)\]\s*(?:#.*)?$/);
+        if (header) {
+            table = norm(header[1]);
+            return;
+        }
+        const key = line.match(/^\s*([A-Za-z0-9_\-."' ]+?)\s*=/)?.[1];
+        if (key === undefined || table === null)
+            return;
+        const full = norm(table ? `${table}.${key}` : key);
+        const ours = full === "mcp_servers.context-doctor" || full.startsWith("mcp_servers.context-doctor.");
+        if ((table === "mcp_servers" || table === "") && ours)
+            found.push(i);
+        else if (table === "" && full === "mcp_servers" && /["']?context-doctor["']?\s*=/.test(line))
+            found.push(i);
+    });
+    return found;
+}
+function refuseInlineCodexDefinition(lines) {
+    const at = inlineCodexDefinition(lines);
+    if (at.length > 0) {
+        throw new Error(`config.toml defines context-doctor as an inline table or dotted keys (line ${at[0] + 1}), which cannot be edited safely line by line; ` +
+            "replace it with a [mcp_servers.context-doctor] table, or delete it, and re-run. Nothing was changed.");
+    }
+}
 /**
  * Add or replace our [mcp_servers.context-doctor] table in config.toml without
  * a TOML library: the file is the user's, so everything outside our own table
  * is copied through byte for byte. Our table is delimited by its header and the
- * next header (or EOF).
+ * next header (or EOF). Our subtables (e.g. an env the user added) are kept.
  */
 export function upsertCodexMcpTable(toml, entry) {
-    const header = "[mcp_servers.context-doctor]";
-    const table = `${header}\n` +
+    const table = `[mcp_servers.context-doctor]\n` +
         `command = ${JSON.stringify(entry.command)}\n` +
         `args = [${entry.args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
     const lines = toml.split("\n");
-    const start = lines.findIndex((l) => l.trim() === header);
-    if (start === -1) {
+    refuseInlineCodexDefinition(lines);
+    const [first, ...duplicates] = codexTableRanges(lines, false);
+    if (!first) {
         const sep = toml.length === 0 || toml.endsWith("\n\n") ? "" : toml.endsWith("\n") ? "\n" : "\n\n";
         return toml + sep + table;
     }
-    let end = start + 1;
-    while (end < lines.length && !/^\s*\[/.test(lines[end]))
-        end++;
-    // Trim trailing blank lines inside our block so we do not accumulate them.
-    const before = lines.slice(0, start).join("\n");
-    const after = lines.slice(end).join("\n");
+    // A second table of ours is what earlier versions appended after a header
+    // they did not recognise; it makes the file invalid, so repair it here.
+    const kept = lines.filter((_, i) => !duplicates.some(([s, e]) => i >= s && i < e));
+    const before = kept.slice(0, first[0]).join("\n");
+    const after = kept.slice(first[1]).join("\n");
     return `${before}${before.length ? "\n" : ""}${table}${after.length ? "\n" + after : ""}`;
 }
 export function removeCodexMcpTable(toml) {
-    const header = "[mcp_servers.context-doctor]";
     const lines = toml.split("\n");
-    const start = lines.findIndex((l) => l.trim() === header);
-    if (start === -1)
+    refuseInlineCodexDefinition(lines);
+    // Subtables go too: a [mcp_servers.context-doctor.env] left alone defines
+    // a server with no command, which Codex reports as broken.
+    const ranges = codexTableRanges(lines, true);
+    if (ranges.length === 0)
         return toml;
-    let end = start + 1;
-    while (end < lines.length && !/^\s*\[/.test(lines[end]))
-        end++;
-    return [...lines.slice(0, start), ...lines.slice(end)].join("\n").replace(/\n{3,}/g, "\n\n");
+    return lines.filter((_, i) => !ranges.some(([s, e]) => i >= s && i < e)).join("\n").replace(/\n{3,}/g, "\n\n");
+}
+/**
+ * The command and args of our Codex server, or undefined when config.toml
+ * does not define one. Reads the inline forms too: Codex runs those fine.
+ */
+export function codexMcpEntry(toml) {
+    const lines = toml.split("\n");
+    const [first] = codexTableRanges(lines, false);
+    const inline = inlineCodexDefinition(lines);
+    if (!first && inline.length === 0)
+        return undefined;
+    const text = first ? lines.slice(first[0] + 1, first[1]).join("\n") : inline.map((i) => lines[i]).join("\n");
+    const command = text.match(/(?:^|[\s{,.])command\s*=\s*(["'])(.*?)\1/m)?.[2];
+    const argsText = text.match(/(?:^|[\s{,.])args\s*=\s*\[([^\]]*)\]/m)?.[1] ?? "";
+    return { command, args: [...argsText.matchAll(/(["'])(.*?)\1/g)].map((m) => m[2]) };
 }
 function installCodex(entry, failures) {
     const dir = codexDir();
@@ -389,8 +519,7 @@ function installCodex(entry, failures) {
         const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
         const next = upsertCodexMcpTable(current, entry);
         if (next !== current) {
-            if (existsSync(configPath))
-                copyFileSync(configPath, configPath + ".context-doctor.backup");
+            backupOnce(configPath);
             writeFileSync(configPath, next);
         }
         console.log(`✓ Codex: MCP server added (${configPath})`);
@@ -430,7 +559,7 @@ function uninstallCodex() {
             const current = readFileSync(configPath, "utf8");
             const next = removeCodexMcpTable(current);
             if (next !== current) {
-                copyFileSync(configPath, configPath + ".context-doctor.backup");
+                backupOnce(configPath);
                 writeFileSync(configPath, next);
                 console.log("✓ Codex: MCP server removed");
             }
@@ -561,7 +690,70 @@ export function runInstall(options = {}) {
     }
     return { failures };
 }
-export function runUninstall() {
+/**
+ * Autopilot points Claude Code at a local proxy (env.ANTHROPIC_BASE_URL in
+ * settings.json), kept alive by a login service and by this package's hook.
+ * Uninstalling around it left that address in place with nothing behind it,
+ * so every new Claude Code session failed to reach the API. It is switched
+ * off first, exactly as `autopilot off` does it (setting before service).
+ */
+async function uninstallAutopilot() {
+    const { autopilotOff, autopilotPaths, proxyUrl, DEFAULT_AUTOPILOT_PORT } = await import("./autopilot.js");
+    const paths = autopilotPaths();
+    // Only for a home that has autopilot: removing the service addresses
+    // systemd and the Windows task scheduler by NAME, not by anything under
+    // this home, so a home without autopilot must never reach them.
+    if (!existsSync(paths.config))
+        return;
+    // The port, read before `off` deletes the file; a damaged file usually
+    // still names it.
+    let port = DEFAULT_AUTOPILOT_PORT;
+    try {
+        port = Number(readFileSync(paths.config, "utf8").match(/"port"\s*:\s*(\d+)/)?.[1] ?? port);
+    }
+    catch {
+        /* unreadable: the default port */
+    }
+    try {
+        // `autopilot pause` is advice for someone keeping the package; not here.
+        for (const line of await autopilotOff(paths))
+            if (!line.includes("autopilot pause"))
+                console.log(line);
+    }
+    catch (e) {
+        console.error(`✗ Autopilot: ${e.message} (run: context-doctor autopilot off)`);
+        return;
+    }
+    // `off` restores only what a readable config describes. A damaged one
+    // leaves the proxy address in settings.json, which is the dead-port case.
+    try {
+        const settings = readJson(paths.settings);
+        if (settings.env?.ANTHROPIC_BASE_URL === proxyUrl(port)) {
+            delete settings.env.ANTHROPIC_BASE_URL;
+            if (Object.keys(settings.env).length === 0)
+                delete settings.env;
+            writeJsonWithBackup(paths.settings, settings);
+            console.log(`✓ Claude Code no longer routed through ${proxyUrl(port)} (autopilot's config could not say what address, if any, it had replaced)`);
+        }
+    }
+    catch (e) {
+        console.error(`✗ Autopilot: ${e.message}`);
+    }
+}
+/** Everything of ours under ~/.claude besides configs: state, ledger, autopilot bookkeeping. */
+const OUR_CLAUDE_FILES = [
+    ".context-doctor-hook-state.json",
+    ".context-doctor-hook-state.d",
+    ".context-doctor-ledger.jsonl",
+    ".context-doctor-calibration.json",
+    ".context-doctor-autopilot-cleared.json",
+    ".context-doctor-autopilot-paused",
+    ".context-doctor-proxy.log",
+    ".context-doctor-proxy-restart",
+];
+export async function runUninstall() {
+    // First: if anything below fails, Claude Code must still reach the API.
+    await uninstallAutopilot();
     for (const target of targets().filter((t) => t.detect())) {
         try {
             if (!existsSync(target.configPath))
@@ -585,11 +777,12 @@ export function runUninstall() {
     uninstallHook();
     uninstallStatusLine();
     uninstallCodex();
-    // Remove our bookkeeping files too — uninstall means gone.
-    for (const file of [".context-doctor-hook-state.json", ".context-doctor-ledger.jsonl"]) {
+    // Remove our bookkeeping files too — uninstall means gone. The hook's
+    // per-session state is a directory, one small file per session.
+    for (const file of OUR_CLAUDE_FILES) {
         const p = join(homedir(), ".claude", file);
         if (existsSync(p)) {
-            rmSync(p);
+            rmSync(p, { recursive: true, force: true });
             console.log(`✓ Removed ${file}`);
         }
     }

package/dist/ledger.js

@@ -55,11 +55,18 @@ export function foldTotals(entries) {
             out.proxyUsd += e.usd ?? 0;
             out.proxyRequests += e.requests ?? 0;
         }
-        else {
+        else if ((e.ev === "check" || e.ev === undefined) && e.sid !== "doctor-probe") {
+            // Exactly what the live reports (impact, dashboard) count, or totals
+            // jump when the ledger rotates. Not every other event is a check:
+            // cold_resume and precompact are not, and precompact's tok is a
+            // CHARACTER count that read as hundreds of tokens of "shrinkage".
+            // "doctor-probe" came from `doctor` before 0.30, not from the hook.
             out.checks++;
             if (e.warn)
                 out.warnings++;
-            if (e.sid && typeof e.tok === "number")
+            // "mcp-sketch" was one id shared by unrelated chats (until 0.24): its
+            // sizes are not one session's, so no shrinkage is read from them.
+            if (e.sid && e.sid !== "mcp-sketch" && typeof e.tok === "number")
                 perSession.set(e.sid, [...(perSession.get(e.sid) ?? []), e.tok]);
         }
     }

package/dist/mcp.d.ts

@@ -5,7 +5,7 @@
  * Plug into Claude Desktop, ChatGPT desktop (developer mode), Cursor, or any
  * MCP client:
  *
- *   { "mcpServers": { "context-doctor": { "command": "npx", "args": ["-y", "context-doctor-mcp"] } } }
+ *   { "mcpServers": { "context-doctor": { "command": "npx", "args": ["-y", "context-doctor", "mcp"] } } }
  *
  * Tools:
  *   profile_context   — analyze a conversation/prompt, report token breakdown + findings

package/dist/mcp.js

@@ -5,7 +5,7 @@
  * Plug into Claude Desktop, ChatGPT desktop (developer mode), Cursor, or any
  * MCP client:
  *
- *   { "mcpServers": { "context-doctor": { "command": "npx", "args": ["-y", "context-doctor-mcp"] } } }
+ *   { "mcpServers": { "context-doctor": { "command": "npx", "args": ["-y", "context-doctor", "mcp"] } } }
  *
  * Tools:
  *   profile_context   — analyze a conversation/prompt, report token breakdown + findings
@@ -52,7 +52,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer({ fileAccess = true } = {}) {
-    const server = new McpServer({ name: "context-doctor", version: "0.31.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.32.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/mcpschema.d.ts

@@ -45,7 +45,22 @@ export interface McpUsage {
 export declare function toolPrefixName(server: string): string;
 /** MCP servers Claude Code starts in `cwd`, with their launch configs. */
 export declare function claudeMcpConfigs(cwd?: string, home?: string): McpServerConfig[];
-/** MCP calls per server over the last `days`, from Claude Code transcripts (a cheap line scan, no JSON parse per line). */
+/**
+ * MCP calls per server over the last `days`, from Claude Code transcripts
+ * and their subagents' (`<session>/subagents/agent-*.jsonl`). Only lines
+ * naming an MCP tool or ToolSearch are parsed.
+ *
+ * Subagents: on the author's machine 49 Gmail and 23 Slack connector calls
+ * were made only by subagents, so scanning the top-level transcripts alone
+ * told the user to remove a server their subagents use. Once per call: a
+ * forked session starts as a copy of its parent's history, the same rows
+ * (uuid) holding the same calls (tool_use id), so a call is counted once by
+ * the two together; like replyCounter, that leaves alone hand-made
+ * transcripts that reuse an id. Each call by its own row's time: a file
+ * touched in the window also holds every older call of its session (2,983
+ * of them in one 30-day count). Rows without a timestamp count with their
+ * file.
+ */
 export declare function mcpUsage(days?: number, paths?: string[]): McpUsage;
 /** Connect to one server the way a client does and size its tool list. */
 export declare function measureServer(cfg: McpServerConfig, timeoutMs?: number): Promise<McpServerSize>;

package/dist/mcpschema.js

@@ -16,10 +16,11 @@
  * up; with it on, an unused server costs about its tool names, not its
  * schemas. Usage of ToolSearch in the transcripts says whether that is so.
  */
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { forEachLine, listSessions } from "./session.js";
+import { subagentDir } from "./subagents.js";
 import { estimateTokens } from "./tokens.js";
 const CLAUDE = "claude-opus-5";
 /** Claude Code's spelling of a server name inside tool names. */
@@ -51,22 +52,79 @@ export function claudeMcpConfigs(cwd = process.cwd(), home = homedir()) {
     }
     return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-/** MCP calls per server over the last `days`, from Claude Code transcripts (a cheap line scan, no JSON parse per line). */
+/**
+ * MCP calls per server over the last `days`, from Claude Code transcripts
+ * and their subagents' (`<session>/subagents/agent-*.jsonl`). Only lines
+ * naming an MCP tool or ToolSearch are parsed.
+ *
+ * Subagents: on the author's machine 49 Gmail and 23 Slack connector calls
+ * were made only by subagents, so scanning the top-level transcripts alone
+ * told the user to remove a server their subagents use. Once per call: a
+ * forked session starts as a copy of its parent's history, the same rows
+ * (uuid) holding the same calls (tool_use id), so a call is counted once by
+ * the two together; like replyCounter, that leaves alone hand-made
+ * transcripts that reuse an id. Each call by its own row's time: a file
+ * touched in the window also holds every older call of its session (2,983
+ * of them in one 30-day count). Rows without a timestamp count with their
+ * file.
+ */
 export function mcpUsage(days = 30, paths) {
     const since = Date.now() - days * 86_400_000;
     const files = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
     const calls = new Map();
+    const counted = new Set();
     let toolSearchSessions = 0;
     for (const path of files) {
         let searched = false;
-        forEachLine(path, (line) => {
-            if (!line.includes('"tool_use"'))
+        const scan = (file) => forEachLine(file, (line) => {
+            if (!line.includes('"tool_use"') || (!line.includes('"name":"mcp__') && !line.includes('"name":"ToolSearch"')))
+                return;
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            const content = e?.message?.content;
+            if (!Array.isArray(content))
                 return;
-            for (const m of line.matchAll(/"name":"mcp__([^"]+?)__[^"]+"/g))
-                calls.set(m[1], (calls.get(m[1]) ?? 0) + 1);
-            if (!searched && line.includes('"name":"ToolSearch"'))
-                searched = true;
+            // Whether a session defers MCP definitions is a property of the
+            // session, so ToolSearch counts whenever it was used; calls are dated.
+            const before = Date.parse(e?.timestamp) < since;
+            for (const b of content) {
+                if (b?.type !== "tool_use" || typeof b.name !== "string")
+                    continue;
+                if (b.name === "ToolSearch") {
+                    searched = true;
+                    continue;
+                }
+                if (before)
+                    continue;
+                const server = /^mcp__(.+?)__./.exec(b.name)?.[1];
+                if (!server)
+                    continue;
+                if (typeof b.id === "string" && typeof e.uuid === "string") {
+                    const key = `${e.uuid}\0${b.id}`;
+                    if (counted.has(key))
+                        continue;
+                    counted.add(key);
+                }
+                calls.set(server, (calls.get(server) ?? 0) + 1);
+            }
         });
+        scan(path);
+        let agents = [];
+        try {
+            agents = readdirSync(subagentDir(path)).filter((f) => f.endsWith(".jsonl"));
+        }
+        catch { /* no subagents */ }
+        for (const a of agents) {
+            try {
+                scan(join(subagentDir(path), a));
+            }
+            catch { /* one unreadable subagent must not sink the report */ }
+        }
         if (searched)
             toolSearchSessions++;
     }
@@ -74,24 +132,37 @@ export function mcpUsage(days = 30, paths) {
 }
 /** Connect to one server the way a client does and size its tool list. */
 export async function measureServer(cfg, timeoutMs = 15_000) {
-    const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
-    const client = new Client({ name: "context-doctor-overhead", version: "1" });
-    let transport;
-    if (cfg.command) {
-        const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
-        transport = new StdioClientTransport({
-            command: cfg.command,
-            args: cfg.args ?? [],
-            env: { ...process.env, ...(cfg.env ?? {}) },
-            stderr: "ignore",
-        });
+    if (!cfg.command && !(cfg.url && cfg.type !== "sse")) {
+        return { name: cfg.name, error: cfg.type === "sse" ? "SSE server: not measured" : "no command or url" };
     }
-    else if (cfg.url && cfg.type !== "sse") {
-        const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
-        transport = new StreamableHTTPClientTransport(new URL(cfg.url));
+    // The SDK is a dependency of the npm package, but the Claude Code plugin runs
+    // dist/ from a git checkout with no node_modules. An import failure there
+    // used to abort the whole `overhead --mcp` report; it is a per-server note.
+    let client;
+    let transport;
+    try {
+        const sdk = await import("@modelcontextprotocol/sdk/client/index.js");
+        client = new sdk.Client({ name: "context-doctor-overhead", version: "1" });
+        if (cfg.command) {
+            const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+            transport = new StdioClientTransport({
+                command: cfg.command,
+                args: cfg.args ?? [],
+                env: { ...process.env, ...(cfg.env ?? {}) },
+                stderr: "ignore",
+            });
+        }
+        else {
+            const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+            transport = new StreamableHTTPClientTransport(new URL(cfg.url));
+        }
     }
-    else {
-        return { name: cfg.name, error: cfg.type === "sse" ? "SSE server: not measured" : "no command or url" };
+    catch (e) {
+        const code = e?.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+            return { name: cfg.name, error: "MCP SDK not installed (not measured)" };
+        }
+        return { name: cfg.name, error: String(e?.message ?? e).split("\n")[0].slice(0, 100) };
     }
     let timer;
     const work = (async () => {