context-doctor 0.26.0 → 0.28.0

package/dist/gemini.js

@@ -0,0 +1,192 @@
+/**
+ * Gemini CLI chat recordings, read into the same shape as Claude Code and
+ * Codex transcripts so `session`, `watch` and the every-prompt hook work on
+ * them.
+ *
+ * Gemini CLI writes ~/.gemini/tmp/<project>/chats/session-*.jsonl: a metadata
+ * record, then one record per message (`user`, `gemini`, `info`, `error`).
+ * A message written again with the same id replaces the earlier copy (tool
+ * results and token counts arrive after the text), `{"$rewindTo": id}` drops
+ * that message and everything after it, and `{"$set": …}` updates metadata.
+ * Older versions wrote the whole conversation as one JSON document with a
+ * `messages` array; both are read.
+ *
+ * Each `gemini` message records the API's own usage (`tokens.input` is the
+ * request's promptTokenCount, cached part included), so the live context size
+ * is exact, as it is for Claude Code and Codex.
+ */
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { forEachLine } from "./session.js";
+/** True when the file's first record looks like a Gemini CLI chat (cheap: reads 4 KB). */
+export function isGeminiChat(path) {
+    if (!/\.jsonl?$/.test(path))
+        return false;
+    try {
+        const buf = Buffer.alloc(4096);
+        const fd = openSync(path, "r");
+        const n = readSync(fd, buf, 0, 4096, 0);
+        closeSync(fd);
+        const head = buf.subarray(0, n).toString("utf8");
+        return /"projectHash"\s*:/.test(head) && /"sessionId"\s*:/.test(head);
+    }
+    catch {
+        return false;
+    }
+}
+/** Text of a Gemini `content`: a string, or Part[] with `text` fields. */
+function text(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return content.map((p) => (typeof p === "string" ? p : typeof p?.text === "string" ? p.text : "")).filter(Boolean).join("\n");
+    return "";
+}
+/** What a tool call returned, as the model saw it. */
+function resultText(call) {
+    const r = call?.result;
+    if (typeof r === "string")
+        return r;
+    if (Array.isArray(r)) {
+        return r
+            .map((p) => {
+            const resp = p?.functionResponse?.response;
+            if (resp !== undefined)
+                return typeof resp?.output === "string" ? resp.output : JSON.stringify(resp);
+            return typeof p?.text === "string" ? p.text : "";
+        })
+            .filter(Boolean)
+            .join("\n");
+    }
+    return typeof call?.resultDisplay === "string" ? call.resultDisplay : r === undefined ? "" : JSON.stringify(r);
+}
+/** The ordered, de-duplicated, rewind-applied messages of a chat file. */
+export function readGeminiMessages(path) {
+    const order = [];
+    const byId = new Map();
+    let anon = 0;
+    const upsert = (m) => {
+        const id = typeof m.id === "string" ? m.id : `anon-${anon++}`;
+        if (!byId.has(id))
+            order.push(id);
+        byId.set(id, m);
+    };
+    const raw = readFileSync(path, "utf8");
+    const trimmed = raw.trimStart();
+    if (trimmed.startsWith("{") && !trimmed.includes("\n{")) {
+        // Legacy: one JSON document.
+        try {
+            const doc = JSON.parse(raw);
+            for (const m of doc.messages ?? [])
+                upsert(m);
+            return order.map((id) => byId.get(id));
+        }
+        catch {
+            /* fall through to JSONL */
+        }
+    }
+    forEachLine(path, (line) => {
+        if (!line.trim())
+            return;
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!r || typeof r !== "object")
+            return;
+        if (typeof r.$rewindTo === "string") {
+            const at = order.indexOf(r.$rewindTo);
+            if (at >= 0)
+                for (const id of order.splice(at))
+                    byId.delete(id);
+            return;
+        }
+        if (typeof r.type === "string" && ("content" in r || "toolCalls" in r))
+            upsert(r);
+    });
+    return order.map((id) => byId.get(id));
+}
+export function parseGeminiChat(path) {
+    const messages = [];
+    const usageSamples = [];
+    let model;
+    let reportedInputTokens;
+    for (const m of readGeminiMessages(path)) {
+        if (m.type === "user") {
+            const t = text(m.content);
+            if (t)
+                messages.push({ role: "user", content: t });
+        }
+        else if (m.type === "gemini") {
+            if (typeof m.model === "string")
+                model = m.model;
+            const input = Number(m.tokens?.input);
+            if (Number.isFinite(input) && input > 0) {
+                reportedInputTokens = input;
+                usageSamples.push({ index: messages.length, input });
+            }
+            const blocks = [];
+            const t = text(m.content);
+            if (t)
+                blocks.push({ type: "text", text: t });
+            const calls = Array.isArray(m.toolCalls) ? m.toolCalls : [];
+            for (const c of calls)
+                blocks.push({ type: "tool_use", id: String(c.id ?? c.name), name: String(c.name ?? "tool"), input: c.args ?? {} });
+            if (blocks.length)
+                messages.push({ role: "assistant", content: blocks });
+            const results = calls.filter((c) => c.result !== undefined || c.resultDisplay !== undefined);
+            if (results.length) {
+                messages.push({ role: "user", content: results.map((c) => ({ type: "tool_result", tool_use_id: String(c.id ?? c.name), content: resultText(c) })) });
+            }
+        }
+    }
+    return {
+        conversationJson: JSON.stringify({ messages }),
+        model,
+        messageCount: messages.length,
+        reportedInputTokens,
+        usageSamples,
+        path,
+    };
+}
+/** Gemini CLI chats on this machine: ~/.gemini/tmp/<project>/chats/session-*.json[l]. */
+export function listGeminiChats(home = homedir()) {
+    const root = join(home, ".gemini", "tmp");
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    let projects;
+    try {
+        projects = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    for (const project of projects) {
+        const dir = join(root, project, "chats");
+        let files;
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            if (!/^session-.*\.jsonl?$/.test(f))
+                continue;
+            const path = join(dir, f);
+            try {
+                const st = statSync(path);
+                out.push({ path, project: "gemini", modifiedAt: st.mtime, sizeBytes: st.size });
+            }
+            catch {
+                /* vanished */
+            }
+        }
+    }
+    return out;
+}

package/dist/hook.js

@@ -199,8 +199,10 @@ export async function runHook() {
             // systemMessage is shown to the user in the app; additionalContext goes to the model.
             if (notice)
                 out.systemMessage = notice;
+            // Gemini CLI's prompt hook is BeforeAgent; it reads the same output shape.
+            const event = input.hook_event_name === "BeforeAgent" ? "BeforeAgent" : "UserPromptSubmit";
             if (lines.length > 0)
-                out.hookSpecificOutput = { hookEventName: "UserPromptSubmit", additionalContext: block };
+                out.hookSpecificOutput = { hookEventName: event, additionalContext: block };
             console.log(JSON.stringify(out));
         };
         if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR) {

package/dist/index.d.ts

@@ -26,3 +26,9 @@ export * from "./autopilot.js";
 export * from "./savings.js";
 export * from "./coldresume.js";
 export * from "./compactwindow.js";
+export * from "./pack.js";
+export * from "./overhead.js";
+export * from "./split.js";
+export * from "./mcpschema.js";
+export * from "./wrap.js";
+export * from "./ci.js";

package/dist/index.js

@@ -21,3 +21,9 @@ export * from "./autopilot.js";
 export * from "./savings.js";
 export * from "./coldresume.js";
 export * from "./compactwindow.js";
+export * from "./pack.js";
+export * from "./overhead.js";
+export * from "./split.js";
+export * from "./mcpschema.js";
+export * from "./wrap.js";
+export * from "./ci.js";

package/dist/install.d.ts

@@ -6,6 +6,8 @@
  * Every config edit is a careful JSON merge with a .backup file written first.
  * `context-doctor uninstall` reverses it.
  */
+export declare function geminiSettingsPath(): string;
+export declare function geminiCliPresent(): boolean;
 /**
  * How to invoke the published package as an MCP server on a given platform.
  *

package/dist/install.js

@@ -25,8 +25,19 @@ function targets() {
         { name: "Claude Desktop", configPath: desktop, detect: () => existsSync(dirname(desktop)) },
         { name: "Claude Code", configPath: claudeCode, detect: () => existsSync(claudeCode) || existsSync(join(homedir(), ".claude")) },
         { name: "Cursor", configPath: cursor, detect: () => existsSync(join(homedir(), ".cursor")) },
+        { name: "Gemini CLI", configPath: geminiSettingsPath(), detect: geminiCliPresent },
     ];
 }
+// -- Gemini CLI: MCP servers and hooks both live in ~/.gemini/settings.json,
+// hooks in Claude Code's shape under the event BeforeAgent (its prompt hook).
+// ~/.gemini alone is not enough to call it present: Google's Antigravity IDE
+// creates it too, without the CLI.
+export function geminiSettingsPath() {
+    return join(homedir(), ".gemini", "settings.json");
+}
+export function geminiCliPresent() {
+    return existsSync(geminiSettingsPath()) || existsSync(join(homedir(), ".gemini", "tmp")) || binOnPath("gemini") !== null;
+}
 /**
  * The server command to write into configs.
  *
@@ -204,12 +215,12 @@ function installHook() {
  * ({hooks:{UserPromptSubmit:[{hooks:[{type:"command",command}]}]}}), so one
  * writer serves both; only the path differs.
  */
-function installHookInto(settingsPath, gateDir) {
+function installHookInto(settingsPath, gateDir, event = "UserPromptSubmit") {
     if (!existsSync(gateDir))
         return null; // that app is not on this machine
     const settings = readJson(settingsPath);
     settings.hooks = settings.hooks ?? {};
-    const entries = settings.hooks.UserPromptSubmit ?? [];
+    const entries = settings.hooks[event] ?? [];
     const want = hookCommand();
     // Re-running install must REPAIR a stale entry, not skip it. Earlier versions
     // wrote a version-pinned node binary; if we only checked "is it present?" an
@@ -223,20 +234,21 @@ function installHookInto(settingsPath, gateDir) {
         // Replace every entry of ours with exactly one correct entry.
         const others = entries.filter((e) => !isOurHookEntry(e));
         others.push({ hooks: [{ type: "command", command: want }] });
-        settings.hooks.UserPromptSubmit = others;
+        settings.hooks[event] = others;
         writeJsonWithBackup(settingsPath, settings);
         return settingsPath;
     }
     else {
         return settingsPath; // already correct — leave the file untouched
     }
-    settings.hooks.UserPromptSubmit = entries;
+    settings.hooks[event] = entries;
     writeJsonWithBackup(settingsPath, settings);
     return settingsPath;
 }
 function uninstallHook() {
     uninstallHookFrom(join(homedir(), ".claude", "settings.json"), "Claude Code every-prompt hook");
     uninstallHookFrom(join(homedir(), ".codex", "hooks.json"), "Codex every-prompt hook");
+    uninstallHookFrom(geminiSettingsPath(), "Gemini CLI every-prompt hook", "BeforeAgent");
     uninstallCursorHook();
 }
 /**
@@ -285,18 +297,18 @@ function uninstallCursorHook() {
     writeJsonWithBackup(path, config);
     console.log("✓ Cursor after-tool-call hook removed");
 }
-function uninstallHookFrom(settingsPath, label) {
+function uninstallHookFrom(settingsPath, label, event = "UserPromptSubmit") {
     if (!existsSync(settingsPath))
         return;
     const settings = readJson(settingsPath);
-    const entries = settings.hooks?.UserPromptSubmit;
+    const entries = settings.hooks?.[event];
     if (!entries)
         return;
     const filtered = entries.filter((e) => !isOurHookEntry(e));
     if (filtered.length !== entries.length) {
-        settings.hooks.UserPromptSubmit = filtered;
+        settings.hooks[event] = filtered;
         if (filtered.length === 0)
-            delete settings.hooks.UserPromptSubmit;
+            delete settings.hooks[event];
         writeJsonWithBackup(settingsPath, settings);
         console.log(`✓ ${label} removed`);
     }
@@ -441,7 +453,7 @@ export function runInstall(options = {}) {
     const entry = serverEntry();
     const found = targets().filter((t) => t.detect());
     if (found.length === 0 && !existsSync(codexDir())) {
-        console.log("No supported AI apps detected (Claude Desktop, Claude Code, Cursor).");
+        console.log("No supported AI apps detected (Claude Desktop, Claude Code, Cursor, Codex, Gemini CLI).");
         console.log("Manual setup — add to your app's MCP config:");
         console.log(JSON.stringify({ mcpServers: { "context-doctor": entry } }, null, 2));
         return { failures: [] };
@@ -497,6 +509,17 @@ export function runInstall(options = {}) {
         failures.push("Cursor hook");
     }
     installCodex(entry, failures);
+    if (geminiCliPresent()) {
+        try {
+            const hook = installHookInto(geminiSettingsPath(), join(homedir(), ".gemini"), "BeforeAgent");
+            if (hook)
+                console.log(`✓ Gemini CLI every-prompt hook installed (${hook})`);
+        }
+        catch (e) {
+            console.error(`✗ Gemini CLI hook: ${e.message}`);
+            failures.push("Gemini CLI hook");
+        }
+    }
     if (options.statusLine) {
         try {
             switch (installStatusLine()) {

package/dist/mcp.d.ts

@@ -11,5 +11,6 @@
  *   profile_context   — analyze a conversation/prompt, report token breakdown + findings
  *   optimize_context  — apply safe strategies, return the slimmed conversation
  *   context_best_practices — curated checklist for a given provider/use case
+ *   pack_context      — only the chunks of big files a question needs, within a token budget
  */
 export {};

package/dist/mcp.js

@@ -11,6 +11,7 @@
  *   profile_context   — analyze a conversation/prompt, report token breakdown + findings
  *   optimize_context  — apply safe strategies, return the slimmed conversation
  *   context_best_practices — curated checklist for a given provider/use case
+ *   pack_context      — only the chunks of big files a question needs, within a token budget
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -22,6 +23,7 @@ import { renderProfile } from "./report.js";
 import { formatTokens } from "./tokens.js";
 import { recordLedger } from "./ledger.js";
 import { runSketch } from "./sketch.js";
+import { packContextSemantic, readSources, renderPack } from "./pack.js";
 /**
  * Server instructions are injected by MCP clients (Claude Desktop, Cursor, …)
  * into the system context of EVERY conversation where this server is enabled.
@@ -38,18 +40,19 @@ import { runSketch } from "./sketch.js";
 // thresholds keep it from firing on every turn, which would cost more context
 // than it saves.
 const SERVER_INSTRUCTIONS = `Context hygiene rules (always on):
-1. Summarize any paste or tool result over ~2k tokens into the points you will use, then work from the summary; never carry it verbatim.
-2. Reference earlier content by name; never re-quote it. Never inline base64.
-3. When the conversation passes ~30 turns, or holds 3+ large pastes, or the user asks about tokens, cost, speed or limits: call profile_context BEFORE answering and act on its top finding. In a chat app pass a \`sketch\` (turn count + the large/repeated blocks, ~120 tokens), not the conversation. Do not estimate token counts yourself.
-4. If optimize_context returns a pruned-turns digest, you write the ≤150-token replacement summary.`;
+1. Summarize any paste or tool result over ~2k tokens into the points you need; never carry it verbatim.
+2. Refer to earlier content by name; never re-quote it or inline base64.
+3. Past ~30 turns or 3+ large pastes, or when asked about tokens, cost, speed or limits: call profile_context BEFORE answering and act on its top finding. In a chat app pass a \`sketch\` (turns + large/repeated blocks), not the conversation. Do not estimate token counts yourself.
+4. If optimize_context returns a pruned-turns digest, write its ≤150-token summary.
+5. To answer from a large file or folder you won't edit, call pack_context with the question; don't read it whole.`;
 const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-base64", "prune-history"];
 /**
  * Build a fully-configured server instance. A factory (not a singleton) so the
  * stateless HTTP mode can hand every request its own server, per the MCP SDK's
  * recommended pattern.
  */
-function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.26.0" }, { instructions: SERVER_INSTRUCTIONS });
+function createServer({ fileAccess = true } = {}) {
+    const server = new McpServer({ name: "context-doctor", version: "0.28.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({
@@ -83,7 +86,7 @@ function createServer() {
         const profile = profileConversation(parseConversation(conversation), model);
         return { content: [{ type: "text", text: renderProfile(profile) }] };
     });
-    server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using deterministic strategies: dedupe repeated content, trim stale tool results, strip base64 blobs, optionally prune old history. Returns the slimmed conversation JSON plus a savings summary. No LLM calls — safe and inspectable. Call this after profile_context finds recoverable waste and the user wants it fixed; add the prune-history strategy only with the user's consent, then write the replacement summary yourself as the result instructs.", {
+    server.tool("optimize_context", "Rewrite a conversation to reclaim tokens with deterministic strategies (dedupe, trim stale tool results, strip base64; prune-history is optional and lossy). Returns the slimmed JSON and a savings summary; no LLM calls. Use after profile_context finds recoverable waste the user wants fixed. Add prune-history only with the user's consent, then write the replacement summary as the result instructs.", {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array)"),
         strategies: z.array(z.enum(STRATEGY_IDS)).optional()
             .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add trim-tool-calls to shrink big inline file writes, or prune-history for lossy compaction of old turns."),
@@ -133,6 +136,31 @@ function createServer() {
         }
         return { content };
     });
+    server.tool("pack_context", "Read only the parts of large files a question needs: chunks files or folders along their structure, ranks the chunks against `query` and returns the best that fit `max_tokens`, each with an id and line range. No query: an outline; pick with `ids`. Use instead of reading a big doc, log or folder whole when not editing it. Text, code, PDF, Word, PowerPoint, ODT.", {
+        paths: z.array(z.string()).max(50).optional().describe("Files or folders (absolute, or relative to the server's cwd)"),
+        text: z.string().optional().describe("Raw text to pack instead of files"),
+        query: z.string().optional().describe("The question; omit for an outline"),
+        max_tokens: z.number().int().positive().max(200_000).optional().describe("Budget, default 4000"),
+        ids: z.array(z.string()).max(200).optional().describe("Chunk ids from an outline or result, e.g. docs/guide.md#4"),
+        model: z.string().optional().describe("Model the budget is counted for (default Claude)"),
+        semantic: z.boolean().optional().describe("Also rank by meaning (local Ollama embeddings)"),
+    }, 
+    // Reads files, never writes. Clients (Codex, ChatGPT) may skip approval for read-only tools.
+    { title: "Pack context", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ paths, text, query, max_tokens, ids, model, semantic }) => {
+        const err = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+        if (paths?.length && !fileAccess) {
+            return err("This server runs over HTTP and does not read files. Pass the document as `text`.");
+        }
+        const { sources, skipped } = paths?.length ? readSources(paths) : { sources: [], skipped: [] };
+        if (text)
+            sources.push({ name: "text", text });
+        if (sources.length === 0) {
+            return err(skipped.length ? `Nothing readable: ${skipped.join("; ")}` : "Pass `paths` (files or folders) or `text`.");
+        }
+        const result = await packContextSemantic(sources, { query, budget: max_tokens, ids, model, semantic });
+        const note = skipped.length ? `\nSkipped: ${skipped.slice(0, 10).join("; ")}${skipped.length > 10 ? ` (+${skipped.length - 10} more)` : ""}` : "";
+        return { content: [{ type: "text", text: renderPack(result) + note }] };
+    });
     // A prompt shows up in Claude Desktop's "+" menu, so a user can run a checkup
     // with one click instead of typing a request. It is the only proactive
     // surface MCP offers besides `instructions`.
@@ -245,7 +273,7 @@ if (argv.includes("--http")) {
                 setHeader(req, "accept", "application/json, text/event-stream");
             }
             // Fresh server + transport per request (stateless — nothing shared).
-            const server = createServer();
+            const server = createServer({ fileAccess: false });
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined,
                 // A client that never asked for a stream gets plain JSON back.

package/dist/mcpschema.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The MCP schema tax: what each MCP server's tool definitions add to every
+ * request, and whether the server is used at all.
+ *
+ * Tool definitions (name, description, JSON schema) ride in the request's
+ * `tools` array, so they are part of the fixed overhead `overhead` measures;
+ * transcripts never contain them. Two sources:
+ *  - usage, from transcripts: every MCP call is a tool_use named
+ *    `mcp__<server>__<tool>`, which also reveals servers the app provides
+ *    (desktop browser, connectors) that no config file lists;
+ *  - size, by asking each configured server for its tool list, exactly as
+ *    Claude Code does at startup. That launches the servers, so it runs only
+ *    when asked (`overhead --mcp`).
+ *
+ * Claude Code's tool search defers MCP definitions until the model looks them
+ * 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.
+ */
+export interface McpServerConfig {
+    name: string;
+    scope: "user" | "project" | ".mcp.json";
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    type?: string;
+}
+export interface McpServerSize {
+    name: string;
+    tools?: number;
+    /** Tokens of the full definitions: what an up-front load costs on every request. */
+    schemaTokens?: number;
+    /** Tokens of the tool names alone: roughly what a deferred load costs. */
+    nameTokens?: number;
+    error?: string;
+}
+export interface McpUsage {
+    /** Calls per server name (as it appears in tool names), main chain and subagents. */
+    calls: Map<string, number>;
+    sessions: number;
+    /** Sessions in which the model used ToolSearch, i.e. MCP definitions were deferred. */
+    toolSearchSessions: number;
+}
+/** Claude Code's spelling of a server name inside tool names. */
+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). */
+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

@@ -0,0 +1,125 @@
+/**
+ * The MCP schema tax: what each MCP server's tool definitions add to every
+ * request, and whether the server is used at all.
+ *
+ * Tool definitions (name, description, JSON schema) ride in the request's
+ * `tools` array, so they are part of the fixed overhead `overhead` measures;
+ * transcripts never contain them. Two sources:
+ *  - usage, from transcripts: every MCP call is a tool_use named
+ *    `mcp__<server>__<tool>`, which also reveals servers the app provides
+ *    (desktop browser, connectors) that no config file lists;
+ *  - size, by asking each configured server for its tool list, exactly as
+ *    Claude Code does at startup. That launches the servers, so it runs only
+ *    when asked (`overhead --mcp`).
+ *
+ * Claude Code's tool search defers MCP definitions until the model looks them
+ * 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 { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { forEachLine, listSessions } from "./session.js";
+import { estimateTokens } from "./tokens.js";
+const CLAUDE = "claude-opus-5";
+/** Claude Code's spelling of a server name inside tool names. */
+export function toolPrefixName(server) {
+    return server.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/** MCP servers Claude Code starts in `cwd`, with their launch configs. */
+export function claudeMcpConfigs(cwd = process.cwd(), home = homedir()) {
+    const out = new Map();
+    const addAll = (servers, scope) => {
+        for (const [name, c] of Object.entries(servers ?? {})) {
+            if (c && typeof c === "object")
+                out.set(name, { name, scope, command: c.command, args: c.args, env: c.env, url: c.url, type: c.type });
+        }
+    };
+    try {
+        const cfg = JSON.parse(readFileSync(join(home, ".claude.json"), "utf8"));
+        addAll(cfg.mcpServers, "user");
+        addAll(cfg.projects?.[resolve(cwd)]?.mcpServers, "project");
+    }
+    catch {
+        /* absent */
+    }
+    try {
+        addAll(JSON.parse(readFileSync(join(cwd, ".mcp.json"), "utf8")).mcpServers, ".mcp.json");
+    }
+    catch {
+        /* absent */
+    }
+    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). */
+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();
+    let toolSearchSessions = 0;
+    for (const path of files) {
+        let searched = false;
+        forEachLine(path, (line) => {
+            if (!line.includes('"tool_use"'))
+                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;
+        });
+        if (searched)
+            toolSearchSessions++;
+    }
+    return { calls, sessions: files.length, toolSearchSessions };
+}
+/** 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",
+        });
+    }
+    else if (cfg.url && cfg.type !== "sse") {
+        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" };
+    }
+    let timer;
+    const work = (async () => {
+        await client.connect(transport);
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : {});
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor && tools.length < 5000);
+        const prefix = `mcp__${toolPrefixName(cfg.name)}__`;
+        const schemaTokens = tools.reduce((s, t) => s + estimateTokens(JSON.stringify({ name: prefix + t.name, description: t.description ?? "", input_schema: t.inputSchema ?? {} }), CLAUDE), 0);
+        const nameTokens = tools.reduce((s, t) => s + estimateTokens(prefix + t.name + "\n", CLAUDE), 0);
+        return { name: cfg.name, tools: tools.length, schemaTokens, nameTokens };
+    })();
+    const timeout = new Promise((res) => {
+        timer = setTimeout(() => res({ name: cfg.name, error: `no answer in ${timeoutMs / 1000}s` }), timeoutMs);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    catch (e) {
+        const msg = String(e?.message ?? e).split("\n")[0];
+        return { name: cfg.name, error: /401|403|unauthori[sz]ed/i.test(msg) ? "needs sign-in (not measured)" : msg.slice(0, 100) };
+    }
+    finally {
+        clearTimeout(timer);
+        await client.close().catch(() => { });
+    }
+}