turntax 0.2.0 → 0.3.0

package/dist/core/audit.js

@@ -1,7 +1,9 @@
 import { buildAdvice } from './advice.js';
 import { classify, detectTools } from './classify.js';
+import { defersTools, serverKey } from './mcp.js';
 import { countO200k, offlineCounter } from './tokenize.js';
 import { TOOLS } from './tools.js';
+import { classifyUser } from './user.js';
 export function modelsForTool(tool, models) {
     const spec = TOOLS.find((t) => t.id === tool);
     return spec.families.length ? models.filter((m) => spec.families.includes(m.family)) : models;
@@ -15,9 +17,12 @@ function counterFor(model, opts) {
 }
 export async function audit(files, opts) {
     const turns = opts.turns ?? 100;
-    const allUnits = classify(files);
-    const toolIds = opts.tools ?? detectTools(allUnits);
+    const allUnits = [...classify(files), ...classifyUser(opts.userFiles ?? [])];
+    const servers = opts.mcp?.servers ?? [];
+    const toolIds = opts.tools ??
+        [...new Set([...detectTools(allUnits), ...servers.filter((s) => !s.disabled).map((s) => s.tool)])].sort((a, b) => TOOLS.findIndex((t) => t.id === a) - TOOLS.findIndex((t) => t.id === b));
     const units = allUnits.filter((u) => toolIds.includes(u.tool));
+    const mcp = servers.filter((s) => toolIds.includes(s.tool)).map((s) => mcpRow(s, opts.mcp?.measured));
     // Count each distinct text once per model, only for the tools that run that model.
     const counts = new Map();
     for (const model of opts.models) {
@@ -39,6 +44,8 @@ export async function audit(files, opts) {
         };
         if (u.importedFrom)
             row.importedFrom = u.importedFrom;
+        if (u.scope)
+            row.scope = u.scope;
         if (u.mode !== 'ignored')
             for (const m of modelsForTool(u.tool, opts.models)) {
                 const c = counts.get(m.id)?.get(u.text);
@@ -51,21 +58,48 @@ export async function audit(files, opts) {
         const spec = TOOLS.find((t) => t.id === id);
         const rows = files_.filter((r) => r.tool === id);
         const always = rows.filter((r) => r.mode === 'always');
-        const onDemand = rows.filter((r) => r.mode === 'on-demand');
+        const repoAlways = always.filter((r) => !r.scope);
+        const userAlways = always.filter((r) => r.scope === 'user');
+        const onDemand = rows.filter((r) => r.mode === 'on-demand' && !r.scope);
         const models = modelsForTool(id, opts.models).map((m) => modelCost(m, always, turns));
+        const toolMcp = mcp.filter((r) => r.tool === id && r.status !== 'disabled');
+        const mcpTokens = (scope) => sum(toolMcp.filter((r) => r.scope === scope).map((r) => r.o200k ?? 0));
+        const perTurnO200k = sum(repoAlways.map((r) => r.o200k));
+        const userPerTurnO200k = sum(userAlways.map((r) => r.o200k)) + mcpTokens('user');
+        const mcpPerTurnO200k = mcpTokens('project');
         return {
             tool: id,
             name: spec.name,
-            alwaysFiles: new Set(always.map((r) => r.path)).size,
+            alwaysFiles: new Set(repoAlways.map((r) => r.path)).size,
             onDemandFiles: new Set(onDemand.map((r) => r.path)).size,
-            perTurnO200k: sum(always.map((r) => r.o200k)),
+            perTurnO200k,
             onDemandO200k: sum(onDemand.map((r) => r.o200k)),
+            userAlwaysFiles: new Set(userAlways.map((r) => r.path)).size,
+            userPerTurnO200k,
+            mcpServers: toolMcp.length,
+            mcpPerTurnO200k,
+            mcpMeasured: toolMcp.every((r) => r.status === 'measured'),
+            totalPerTurnO200k: perTurnO200k + mcpPerTurnO200k + userPerTurnO200k,
             models,
             notes: spec.notes,
             sources: spec.sources,
         };
     });
-    return { turns, tools, files: files_, advice: buildAdvice(units, files, opts.advice), models: opts.models };
+    const adviceFiles = [...files, ...(opts.userFiles ?? [])];
+    return { turns, tools, files: files_, advice: buildAdvice(units, adviceFiles, opts.advice), models: opts.models, mcp };
+}
+function mcpRow(s, measured) {
+    const row = { name: s.name, tool: s.tool, configPath: s.configPath, scope: s.scope, transport: s.transport, status: 'not-measured' };
+    if (s.disabled)
+        return { ...row, status: 'disabled' };
+    const m = measured?.get(serverKey(s));
+    if (!m)
+        return row;
+    if ('error' in m)
+        return { ...row, status: 'failed', error: m.error };
+    if (defersTools(s))
+        return { ...row, status: 'measured', tools: m.tools, o200k: m.namesO200k, deferredO200k: m.o200k };
+    return { ...row, status: 'measured', tools: m.tools, o200k: m.o200k };
 }
 function modelCost(model, always, turns) {
     const counts = always.map((r) => r.counts[model.id]);

package/dist/core/diff.js

@@ -0,0 +1,63 @@
+export function diffReports(before, after, base) {
+    const ids = [...new Set([...after.tools.map((t) => t.tool), ...before.tools.map((t) => t.tool)])];
+    const tools = ids.map((id) => {
+        const a = after.tools.find((t) => t.tool === id);
+        const b = before.tools.find((t) => t.tool === id);
+        const av = a?.perTurnO200k ?? null;
+        const bv = b?.perTurnO200k ?? null;
+        return { tool: id, name: (a ?? b).name, before: bv, after: av, delta: (av ?? 0) - (bv ?? 0) };
+    });
+    const alwaysFiles = (r) => {
+        const m = new Map();
+        for (const f of r.files) {
+            if (f.mode !== 'always' || f.scope === 'user')
+                continue;
+            const key = `${f.path}\0${f.part}`;
+            const prev = m.get(key);
+            if (prev)
+                prev.tools.add(f.tool);
+            else
+                m.set(key, { path: f.path, part: f.part, o200k: f.o200k, tools: new Set([f.tool]) });
+        }
+        return m;
+    };
+    const bf = alwaysFiles(before);
+    const af = alwaysFiles(after);
+    const files = [];
+    for (const key of new Set([...bf.keys(), ...af.keys()])) {
+        const b = bf.get(key);
+        const a = af.get(key);
+        const delta = (a?.o200k ?? 0) - (b?.o200k ?? 0);
+        if (a && b && delta === 0)
+            continue;
+        files.push({
+            path: (a ?? b).path,
+            part: (a ?? b).part,
+            before: b?.o200k ?? null,
+            after: a?.o200k ?? null,
+            delta,
+            tools: [...new Set([...(b?.tools ?? []), ...(a?.tools ?? [])])],
+        });
+    }
+    files.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta) || x.path.localeCompare(y.path));
+    const servers = (r) => new Set((r.mcp ?? []).filter((s) => s.scope === 'project' && s.status !== 'disabled').map((s) => `${s.name} (${s.tool})`));
+    const bs = servers(before);
+    const as = servers(after);
+    return {
+        base,
+        tools,
+        files,
+        mcp: { added: [...as].filter((s) => !bs.has(s)), removed: [...bs].filter((s) => !as.has(s)) },
+    };
+}
+/** Largest per-turn increase across agents (0 when nothing grew). */
+export function maxIncrease(diff) {
+    return Math.max(0, ...diff.tools.map((t) => t.delta));
+}
+/** Validates a parsed JSON report enough to diff against it. */
+export function asDiffInput(data) {
+    const r = data;
+    if (!r || !Array.isArray(r.tools) || !Array.isArray(r.files))
+        throw new Error('not a turntax --json report');
+    return r;
+}

package/dist/core/mcp.js

@@ -0,0 +1,227 @@
+const CHECKED_AT = '2026-10-11';
+/** Where each agent reads MCP servers from. Paths and keys come from the cited pages. */
+export const MCP_CONFIGS = [
+    { tool: 'claude-code', path: '.mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://code.claude.com/docs/en/mcp' },
+    { tool: 'cursor', path: '.cursor/mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://cursor.com/docs/context/mcp' },
+    { tool: 'copilot', path: '.vscode/mcp.json', scope: 'project', key: 'servers', shape: 'vscode', source: 'https://code.visualstudio.com/docs/copilot/customization/mcp-servers' },
+    { tool: 'gemini-cli', path: '.gemini/settings.json', scope: 'project', key: 'mcpServers', shape: 'gemini', source: 'https://geminicli.com/docs/tools/mcp-server/' },
+    { tool: 'kiro', path: '.kiro/settings/mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://kiro.dev/docs/mcp/configuration/' },
+    { tool: 'roo-code', path: '.roo/mcp.json', scope: 'project', key: 'mcpServers', shape: 'standard', source: 'https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo' },
+    { tool: 'opencode', path: 'opencode.json', scope: 'project', key: 'mcp', shape: 'opencode', source: 'https://opencode.ai/docs/mcp-servers/' },
+    { tool: 'opencode', path: 'opencode.jsonc', scope: 'project', key: 'mcp', shape: 'opencode', source: 'https://opencode.ai/docs/mcp-servers/' },
+    { tool: 'zed', path: '.zed/settings.json', scope: 'project', key: 'context_servers', shape: 'zed', source: 'https://zed.dev/docs/ai/mcp' },
+    { tool: 'codex', path: '.codex/config.toml', scope: 'project', key: 'mcp_servers', shape: 'codex-toml', source: 'https://learn.chatgpt.com/docs/extend/mcp' },
+    { tool: 'claude-code', path: '.claude.json', scope: 'user', key: 'mcpServers', shape: 'claude-json', source: 'https://code.claude.com/docs/en/mcp' },
+    { tool: 'cursor', path: '.cursor/mcp.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://cursor.com/docs/context/mcp' },
+    { tool: 'gemini-cli', path: '.gemini/settings.json', scope: 'user', key: 'mcpServers', shape: 'gemini', source: 'https://geminicli.com/docs/tools/mcp-server/' },
+    { tool: 'kiro', path: '.kiro/settings/mcp.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://kiro.dev/docs/mcp/configuration/' },
+    { tool: 'windsurf', path: '.config/devin/mcp_config.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://docs.devin.ai/desktop/cascade/mcp' },
+    { tool: 'windsurf', path: 'AppData/Roaming/devin/mcp_config.json', scope: 'user', key: 'mcpServers', shape: 'standard', source: 'https://docs.devin.ai/desktop/cascade/mcp' },
+    { tool: 'codex', path: '.codex/config.toml', scope: 'user', key: 'mcp_servers', shape: 'codex-toml', source: 'https://learn.chatgpt.com/docs/extend/mcp' },
+    { tool: 'opencode', path: '.config/opencode/opencode.json', scope: 'user', key: 'mcp', shape: 'opencode', source: 'https://opencode.ai/docs/mcp-servers/' },
+];
+export const MCP_CHECKED_AT = CHECKED_AT;
+/** True for a repo-relative path that holds project MCP servers for some agent. */
+export function isMcpConfigFile(path) {
+    return MCP_CONFIGS.some((c) => c.scope === 'project' && c.path === path);
+}
+/** Home-relative paths of user-level MCP configs. */
+export const USER_MCP_PATHS = [...new Set(MCP_CONFIGS.filter((c) => c.scope === 'user').map((c) => c.path))];
+/** JSON with comments and trailing commas (VS Code, Zed and OpenCode accept both). */
+export function parseJsonc(text) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            out += c;
+            if (c === '\\')
+                out += text[++i] ?? '';
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"') {
+            inString = true;
+            out += c;
+        }
+        else if (c === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+        }
+        else if (c === '/' && text[i + 1] === '*') {
+            i = text.indexOf('*/', i + 2);
+            if (i < 0)
+                break;
+            i++;
+        }
+        else
+            out += c;
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1').replace(/^/, ''));
+}
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const strings = (v) => (Array.isArray(v) ? v.map(String) : undefined);
+const record = (v) => isObj(v) ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, String(x)])) : undefined;
+function fromStandard(name, v, gemini = false) {
+    const type = String(v.type ?? v.transport ?? '').toLowerCase();
+    // Gemini CLI has no type field: `httpUrl` is streamable HTTP and `url` is SSE.
+    // Elsewhere `url` (Windsurf: `serverUrl`) is streamable HTTP unless the type says SSE.
+    const httpUrl = typeof v.httpUrl === 'string' ? v.httpUrl : undefined;
+    const url = httpUrl ?? (typeof v.url === 'string' ? v.url : typeof v.serverUrl === 'string' ? v.serverUrl : undefined);
+    const transport = !url ? 'stdio' : httpUrl ? 'http' : gemini || type === 'sse' ? 'sse' : 'http';
+    return {
+        name,
+        transport,
+        command: typeof v.command === 'string' ? v.command : undefined,
+        args: strings(v.args),
+        env: record(v.env),
+        cwd: typeof v.cwd === 'string' ? v.cwd : undefined,
+        url,
+        headers: record(v.headers),
+        disabled: v.disabled === true || v.enabled === false,
+        ...(v.alwaysLoad === true ? { alwaysLoad: true } : {}),
+    };
+}
+function fromOpencode(name, v) {
+    const command = strings(v.command) ?? [];
+    const remote = v.type === 'remote' || typeof v.url === 'string';
+    return {
+        name,
+        transport: remote ? 'http' : 'stdio',
+        command: remote ? undefined : command[0],
+        args: remote ? undefined : command.slice(1),
+        env: record(v.environment),
+        url: typeof v.url === 'string' ? v.url : undefined,
+        headers: record(v.headers),
+        disabled: v.enabled === false,
+    };
+}
+function fromZed(name, v) {
+    // Older Zed settings nest the command: { "command": { "path", "args", "env" } }.
+    if (isObj(v.command)) {
+        const c = v.command;
+        return fromStandard(name, { ...v, command: c.path ?? c.command, args: c.args, env: c.env });
+    }
+    return fromStandard(name, v);
+}
+function serversIn(container, shape) {
+    if (!isObj(container))
+        return [];
+    return Object.entries(container)
+        .filter(([, v]) => isObj(v))
+        .map(([name, v]) => shape === 'opencode'
+        ? fromOpencode(name, v)
+        : shape === 'zed'
+            ? fromZed(name, v)
+            : fromStandard(name, v, shape === 'gemini'));
+}
+/** Minimal TOML reader for Codex `[mcp_servers.<name>]` tables: strings, string arrays and inline tables. */
+export function parseCodexToml(text) {
+    const servers = {};
+    let current = null;
+    let sub = null;
+    const value = (raw) => {
+        const t = raw.trim();
+        if (t.startsWith('['))
+            return [...t.matchAll(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2] ?? '');
+        if (t.startsWith('{'))
+            return Object.fromEntries([...t.matchAll(/([\w-]+|"[^"]*")\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')/g)].map((m) => [m[1].replace(/"/g, ''), m[2] ?? m[3] ?? '']));
+        if (t === 'true' || t === 'false')
+            return t === 'true';
+        const s = /^"((?:[^"\\]|\\.)*)"|^'([^']*)'/.exec(t);
+        return s ? (s[1] ?? s[2]) : t;
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const header = /^\s*\[\s*mcp_servers\.(?:"([^"]+)"|([\w-]+))(?:\.(\w+))?\s*\]/.exec(line);
+        if (header) {
+            const name = (header[1] ?? header[2]);
+            servers[name] ??= {};
+            current = servers[name];
+            sub = header[3] ?? null;
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            current = null;
+            continue;
+        }
+        const kv = /^\s*([\w-]+)\s*=\s*(.+?)\s*(?:#.*)?$/.exec(line);
+        if (!kv || !current)
+            continue;
+        if (sub) {
+            const table = (current[sub] ??= {});
+            table[kv[1]] = value(kv[2]);
+        }
+        else
+            current[kv[1]] = value(kv[2]);
+    }
+    // Codex calls HTTP headers `http_headers`.
+    for (const v of Object.values(servers))
+        if (isObj(v) && v.http_headers && !v.headers)
+            v.headers = v.http_headers;
+    return servers;
+}
+/**
+ * Parses the MCP configs among `files`. Project files use repo-relative paths; user files are passed
+ * with a `~/` prefix. `projectRoot` (absolute) selects the per-project entry in ~/.claude.json.
+ */
+export function parseMcpConfigs(files, projectRoot) {
+    const servers = [];
+    const problems = [];
+    for (const f of files) {
+        const user = f.path.startsWith('~/');
+        const rel = user ? f.path.slice(2) : f.path;
+        const specs = MCP_CONFIGS.filter((c) => c.path === rel && c.scope === (user ? 'user' : 'project'));
+        if (!specs.length)
+            continue;
+        let data;
+        try {
+            data = specs[0].shape === 'codex-toml' ? parseCodexToml(f.text) : parseJsonc(f.text);
+        }
+        catch (e) {
+            problems.push({ path: f.path, message: `could not be parsed: ${e.message}` });
+            continue;
+        }
+        if (!isObj(data))
+            continue;
+        for (const spec of specs) {
+            const containers = spec.shape === 'codex-toml'
+                ? [data]
+                : spec.shape === 'claude-json'
+                    ? [data.mcpServers, projectEntry(data, projectRoot)?.mcpServers]
+                    : [data[spec.key]];
+            for (const c of containers)
+                for (const s of serversIn(c, spec.shape))
+                    servers.push({ ...s, tool: spec.tool, configPath: f.path, scope: spec.scope });
+        }
+    }
+    return { servers, problems };
+}
+/** The `projects["<abs path>"]` entry of ~/.claude.json for this repository, matched case- and slash-insensitively. */
+function projectEntry(data, root) {
+    if (!root || !isObj(data.projects))
+        return undefined;
+    const norm = (p) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    const hit = Object.entries(data.projects).find(([p]) => norm(p) === norm(root));
+    return hit && isObj(hit[1]) ? hit[1] : undefined;
+}
+/** Same server started by several agents or configs: one launch, one measurement. */
+export function serverKey(s) {
+    return JSON.stringify([s.transport, s.command ?? '', s.args ?? [], s.url ?? '', s.cwd ?? '']);
+}
+/**
+ * Claude Code defers MCP tool definitions by default (tool search): only tool names are in context
+ * until a tool is used. A server with `alwaysLoad: true` is exempt.
+ */
+export function defersTools(s) {
+    return s.tool === 'claude-code' && !s.alwaysLoad;
+}
+export const DEFERRED_NOTE = 'Claude Code defers MCP tool definitions by default (tool search): only tool names load every turn; full definitions load when a tool is used. Set ENABLE_TOOL_SEARCH=false or alwaysLoad: true to load them upfront.';
+/** Tool names only, as listed when definitions are deferred. */
+export function toolNamesText(tools) {
+    return tools.map((t) => t.name).join('\n');
+}
+/** The text an agent receives for a server's tools, as one JSON document per tool. */
+export function toolDefinitionsText(tools) {
+    return tools.map((t) => JSON.stringify({ name: t.name, description: t.description ?? '', input_schema: t.inputSchema ?? {} })).join('\n');
+}

package/dist/core/render.js

@@ -1,3 +1,4 @@
+import { DEFERRED_NOTE } from './mcp.js';
 export const METHOD_LABEL = {
     'offline-exact': 'exact (offline tokenizer)',
     'offline-proxy': 'estimate (o200k_base proxy)',
@@ -32,7 +33,11 @@ export function groupTools(report) {
             .filter((f) => f.tool === t.tool && f.mode !== 'ignored')
             .map((f) => [f.path, f.part, f.mode, f.o200k])
             .sort();
-        const key = JSON.stringify([files, t.models.map(({ model, perTurn, method, reason }) => [model, perTurn, method, reason])]);
+        const key = JSON.stringify([
+            files,
+            t.models.map(({ model, perTurn, method, reason }) => [model, perTurn, method, reason]),
+            report.mcp.filter((m) => m.tool === t.tool).map((m) => [m.configPath, m.name, m.status, m.o200k]),
+        ]);
         const g = groups.get(key);
         if (g)
             g.names.push(t.name);
@@ -54,9 +59,112 @@ export function groupFiles(report) {
     }
     return [...groups.values()];
 }
-/** Highest always-loaded o200k total across the reported tools. */
+/**
+ * Highest per-turn o200k total across the reported tools, for the badge and --max-tokens:
+ * repository files plus measured project MCP tool definitions. User-level files never count here.
+ */
 export function headlineTokens(report) {
-    return Math.max(0, ...report.tools.map((t) => t.perTurnO200k));
+    return Math.max(0, ...report.tools.map((t) => t.perTurnO200k + (t.mcpPerTurnO200k ?? 0)));
+}
+/** MCP cell: measured tokens, a "+" when some servers could not be measured, or how many are unmeasured. */
+export function mcpCell(t) {
+    if (!t.mcpServers)
+        return '-';
+    if (t.mcpMeasured)
+        return fmtTokens(t.mcpPerTurnO200k);
+    return t.mcpPerTurnO200k > 0 ? `${fmtTokens(t.mcpPerTurnO200k)}+` : `${t.mcpServers} not measured`;
+}
+function signed(n) {
+    return n > 0 ? `+${fmtTokens(n)}` : n < 0 ? `-${fmtTokens(-n)}` : '0';
+}
+function fmtMaybe(n) {
+    return n === null ? '-' : fmtTokens(n);
+}
+/** Agents with the same before/after numbers share one line. */
+function groupDeltas(diff) {
+    const groups = new Map();
+    for (const t of diff.tools) {
+        const key = `${t.before}|${t.after}`;
+        const g = groups.get(key);
+        if (g)
+            g.names.push(t.name);
+        else
+            groups.set(key, { names: [t.name], before: t.before, after: t.after, delta: t.delta });
+    }
+    return [...groups.values()].sort((a, b) => b.delta - a.delta);
+}
+export function renderDiffText(diff) {
+    const out = [`Change vs ${diff.base} (o200k tokens per turn, repository files)`];
+    const changed = groupDeltas(diff).filter((g) => g.delta !== 0);
+    if (!changed.length)
+        out.push('  No change in per-turn tokens.');
+    else {
+        const rows = [['before', 'after', 'change', 'agents']];
+        for (const g of changed)
+            rows.push([fmtMaybe(g.before), fmtMaybe(g.after), signed(g.delta), g.names.join(', ')]);
+        out.push(table(rows, '  '));
+    }
+    if (diff.files.length) {
+        out.push('  Files loaded every turn');
+        const rows = [['before', 'after', 'change', 'file']];
+        for (const f of diff.files)
+            rows.push([fmtMaybe(f.before), fmtMaybe(f.after), signed(f.delta), f.part === 'full' ? f.path : `${f.path} (${f.part})`]);
+        out.push(table(rows, '    '));
+    }
+    for (const s of diff.mcp.added)
+        out.push(`  MCP server added: ${s}`);
+    for (const s of diff.mcp.removed)
+        out.push(`  MCP server removed: ${s}`);
+    return out.join('\n');
+}
+export function renderDiffMarkdown(diff) {
+    const out = [`## Change vs \`${diff.base}\``, ''];
+    const changed = groupDeltas(diff).filter((g) => g.delta !== 0);
+    if (!changed.length)
+        out.push('No change in per-turn tokens (o200k, repository files).');
+    else {
+        out.push('o200k tokens added to every turn by repository instruction files.', '');
+        out.push('| Agents | Before | After | Change |', '| --- | ---: | ---: | ---: |');
+        for (const g of changed)
+            out.push(`| ${g.names.join(', ')} | ${fmtMaybe(g.before)} | ${fmtMaybe(g.after)} | **${signed(g.delta)}** |`);
+    }
+    if (diff.files.length) {
+        out.push('', '| File loaded every turn | Before | After | Change |', '| --- | ---: | ---: | ---: |');
+        for (const f of diff.files)
+            out.push(`| \`${f.part === 'full' ? f.path : `${f.path} (${f.part})`}\` | ${fmtMaybe(f.before)} | ${fmtMaybe(f.after)} | ${signed(f.delta)} |`);
+    }
+    if (diff.mcp.added.length || diff.mcp.removed.length) {
+        out.push('');
+        for (const s of diff.mcp.added)
+            out.push(`- MCP server added: ${s}`);
+        for (const s of diff.mcp.removed)
+            out.push(`- MCP server removed: ${s}`);
+    }
+    return out.join('\n');
+}
+/** MCP rows that are identical apart from the agent, merged. */
+function groupMcp(rows) {
+    const groups = new Map();
+    for (const r of rows) {
+        const key = JSON.stringify([r.configPath, r.name, r.status, r.tools, r.o200k, r.error]);
+        const g = groups.get(key);
+        if (g)
+            g.tools.push(r.tool);
+        else
+            groups.set(key, { row: r, tools: [r.tool] });
+    }
+    return [...groups.values()];
+}
+function mcpDetail(r) {
+    if (r.status === 'measured')
+        return r.deferredO200k === undefined
+            ? `${r.tools} tools`
+            : `${r.tools} tools; names only, full definitions (${fmtTokens(r.deferredO200k)}) load when used`;
+    if (r.status === 'disabled')
+        return 'disabled in the config';
+    if (r.status === 'failed')
+        return r.error ?? 'failed';
+    return 'run with --mcp to count its tool definitions';
 }
 export function renderText(report, root) {
     const out = [];
@@ -66,11 +174,25 @@ export function renderText(report, root) {
         out.push('No agent instruction files found.');
         return out.join('\n');
     }
+    if (report.diff) {
+        out.push(renderDiffText(report.diff));
+        out.push('');
+    }
+    const showMcp = report.tools.some((t) => t.mcpServers > 0);
+    const showUser = report.tools.some((t) => t.userAlwaysFiles > 0 || t.userPerTurnO200k > 0);
+    const extra = [...(showMcp ? ['mcp/turn'] : []), ...(showUser ? ['user/turn'] : []), ...(showMcp || showUser ? ['total'] : [])];
     const rows = [
-        ['always', 'o200k/turn', 'on-demand', 'model', 'tokens/turn', 'counted by', `${report.turns} turns`, 'cached', 'agents'],
+        ['always', 'o200k/turn', 'on-demand', ...extra, 'model', 'tokens/turn', 'counted by', `${report.turns} turns`, 'cached', 'agents'],
     ];
     for (const { names, tool: t } of groupTools(report)) {
-        const head = [String(t.alwaysFiles), fmtTokens(t.perTurnO200k), fmtTokens(t.onDemandO200k)];
+        const head = [
+            String(t.alwaysFiles),
+            fmtTokens(t.perTurnO200k),
+            fmtTokens(t.onDemandO200k),
+            ...(showMcp ? [mcpCell(t)] : []),
+            ...(showUser ? [fmtTokens(t.userPerTurnO200k)] : []),
+            ...(showMcp || showUser ? [fmtTokens(t.totalPerTurnO200k) + (t.mcpMeasured ? '' : '+')] : []),
+        ];
         const blank = head.map(() => '');
         const agents = names.join(', ');
         if (!t.models.length)
@@ -93,6 +215,14 @@ export function renderText(report, root) {
         fileRows.push([f.mode, name + (f.importedFrom ? ` <- @${f.importedFrom}` : ''), fmtTokens(f.o200k), f.trigger, tools.join(', ')]);
     }
     out.push(table(fileRows, '  '));
+    if (report.mcp.length) {
+        out.push('');
+        out.push('MCP servers (tool definitions are sent every turn)');
+        const mcpRows = [['status', 'server', 'config', 'o200k', 'detail', 'agents']];
+        for (const { row: r, tools } of groupMcp(report.mcp))
+            mcpRows.push([r.status, r.name, r.configPath, r.o200k === undefined ? '-' : fmtTokens(r.o200k), mcpDetail(r), tools.join(', ')]);
+        out.push(table(mcpRows, '  '));
+    }
     const notes = [...new Set(report.files.flatMap((f) => f.notes.map((n) => `${f.path}: ${n}`)))];
     if (notes.length) {
         out.push('');
@@ -119,6 +249,10 @@ function footer(report) {
         'o200k = OpenAI o200k_base, counted offline. It is a reference for every file, not a Claude or Gemini count.',
         'Claude and Gemini tokenizers are not public: their counts come only from the vendor APIs (--claude-api, --gemini-api).',
         `Cost = tokens/turn x ${report.turns} turns x input price. "Cached" assumes every turn reads the context from the prompt cache.`,
+        ...(report.mcp.length
+            ? ['MCP tool definitions are counted as JSON with o200k (an estimate of what the agent sends) and are not included in model costs.']
+            : []),
+        ...(report.mcp.some((m) => m.deferredO200k !== undefined) ? [DEFERRED_NOTE] : []),
         'Prices (USD per 1M input tokens):',
     ];
     for (const m of report.models) {
@@ -129,6 +263,8 @@ function footer(report) {
 }
 export function renderMarkdown(report) {
     const out = ['# Agent context tax report', ''];
+    if (report.diff)
+        out.push(renderDiffMarkdown(report.diff), '');
     out.push(`Every agent re-sends its always-loaded instruction files with each turn. Costs are for ${report.turns} turns.`, '');
     out.push('## Per agent', '');
     out.push('| Agents | Model | Tokens / turn | Counted by | Uncached | Cached |', '| --- | --- | ---: | --- | ---: | ---: |');
@@ -141,6 +277,17 @@ export function renderMarkdown(report) {
                 ? `| ${agents} | ${m.label} | - | ${m.reason ?? ''} | - | - |`
                 : `| ${agents} | ${m.label} | ${fmtTokens(m.perTurn)} | ${METHOD_LABEL[m.method]} | ${fmtUsd(m.uncached)} | ${fmtUsd(m.cached)} |`);
     }
+    if (report.tools.some((t) => t.mcpServers > 0 || t.userAlwaysFiles > 0 || t.userPerTurnO200k > 0)) {
+        out.push('', '### Every turn, by source (o200k)', '');
+        out.push('| Agents | Repository files | MCP tools | User level | Total |', '| --- | ---: | ---: | ---: | ---: |');
+        for (const { names, tool: t } of groupTools(report))
+            out.push(`| ${names.join(', ')} | ${fmtTokens(t.perTurnO200k)} | ${mcpCell(t)} | ${fmtTokens(t.userPerTurnO200k)} | ${fmtTokens(t.totalPerTurnO200k)}${t.mcpMeasured ? '' : '+'} |`);
+    }
+    if (report.mcp.length) {
+        out.push('', '## MCP servers', '', '| Status | Server | Config | o200k tokens | Detail | Agents |', '| --- | --- | --- | ---: | --- | --- |');
+        for (const { row: r, tools } of groupMcp(report.mcp))
+            out.push(`| ${r.status} | ${escapeCell(r.name)} | \`${r.configPath}\` | ${r.o200k === undefined ? '-' : fmtTokens(r.o200k)} | ${escapeCell(mcpDetail(r))} | ${tools.join(', ')} |`);
+    }
     out.push('', '## Files', '', '| Mode | File | o200k tokens | Loads | Agents |', '| --- | --- | ---: | --- | --- |');
     for (const { file: f, tools } of groupFiles(report)) {
         const name = f.part === 'full' ? f.path : `${f.path} (${f.part})`;
@@ -157,6 +304,10 @@ export function renderMarkdown(report) {
     out.push('- o200k = OpenAI `o200k_base`, counted offline; a reference, not a Claude or Gemini count.');
     out.push('- Claude counts come only from Anthropic `count_tokens`; Gemini counts only from Google `countTokens`.');
     out.push('- "Cached" assumes every turn reads the context from the prompt cache.');
+    if (report.mcp.length)
+        out.push('- MCP tool definitions are counted as JSON with o200k, an estimate of what the agent sends; they are not in the model costs.');
+    if (report.mcp.some((m) => m.deferredO200k !== undefined))
+        out.push(`- ${DEFERRED_NOTE}`);
     for (const m of report.models)
         out.push(`- ${m.label}: $${m.inputPerMTok ?? 'n/a'} input / $${m.cachedInputPerMTok ?? 'n/a'} cached per 1M tokens ([source](${m.source}), checked ${m.checkedAt}).`);
     out.push('', badgeMarkdown(report));
@@ -177,3 +328,17 @@ export function badgeUrl(report) {
 export function badgeMarkdown(report) {
     return `[![context tax (o200k)](${badgeUrl(report)})](https://github.com/TorutDev/turntax)`;
 }
+export const PR_COMMENT_MARKER = '<!-- turntax-report -->';
+const COMMENT_LIMIT = 60_000;
+/**
+ * A pull request comment: the change against the base branch first, the full report folded below.
+ * Starts with a marker so the GitHub Action can update its own comment instead of adding new ones.
+ */
+export function renderPrComment(report) {
+    const top = report.diff ? renderDiffMarkdown(report.diff) : '## Agent context tax';
+    const headline = `Largest per-turn cost: **${fmtTokens(headlineTokens(report))}** o200k tokens (repository files and measured project MCP tools).`;
+    let full = renderMarkdown({ ...report, diff: undefined }).replace(/^# .*\n\n/, '');
+    if (full.length > COMMENT_LIMIT)
+        full = full.slice(0, COMMENT_LIMIT) + '\n\n_Report cut to fit in a comment; the job summary has all of it._\n';
+    return [PR_COMMENT_MARKER, top, '', headline, '', '<details><summary>Full report</summary>', '', full, '</details>', ''].join('\n');
+}