, openInfo = false): string {
const loud = findings.filter((f) => f.severity !== 'info');
const info = findings.filter((f) => f.severity === 'info');
const c = counts(findings);
const summary = [c.error && plural(c.error, 'error', 'errors'), c.warn && plural(c.warn, 'warning', 'warnings'), c.info && `${c.info} info`].filter(Boolean).join(', ') || 'None';
return `
${loud.map((f) => tile(f, ids?.get(f))).join('\n')}
${info.length ? `${loud.length ? 'Info findings' : 'All findings are info'}${chip('neutral', String(info.length))}${CHEVRON}
${info.map((f) => tile(f, ids?.get(f))).join('\n')}
` : ''}
${findings.length ? '' : `${CHECK}No findings
`}
`;
}
function card(label: string, value: string, note: string | undefined, table: string, legend?: string, extra = ''): string {
return `
${esc(label)}${esc(value)}${note ? `${esc(note)}` : ''}
${extra}
${table}
${legend ? `` : ''}
`;
}
function page(title: string, body: string): string {
return `
${esc(title)}
`;
}
const isWrite = (t: MenuTool) => (t.annotations as { readOnlyHint?: unknown } | undefined)?.readOnlyHint === false;
const protocolLine = (server: Menu['server']) => (server.protocolVersion ? `Protocol ${esc(server.protocolVersion)}${server.era === 'legacy' ? ', 2025 handshake' : ''}` : '');
const appOnlyChip = 'App only';
const signed = (n: number) => (n > 0 ? `+${num(n)}` : n < 0 ? `−${num(-n)}` : '0');
export interface SnapshotHtmlOptions {
/** stdio or http, for the subtitle. */
transport?: string;
/** --client: what the menu costs under that client. */
cost?: ClientCost;
/** --lists asked for that the server doesn't offer. */
notOffered?: string[];
/** Where the menu file was written. */
outPath?: string;
}
/** The snapshot page. It counts as the text report does: every tool the server lists, app-only ones marked. */
export function snapshotHtml(menu: Menu, findings: Finding[], options: SnapshotHtmlOptions = {}): string {
const c = counts(findings);
const { appOnly } = agentMenu(menu);
const max = Math.max(1, ...menu.tools.map((t) => t.tokens));
const writes = menu.tools.filter(isWrite).length;
const status = statuses(findings);
const rows = menu.tools
.map((t, i) => `| ${i} | ${esc(t.name)}${isAppOnly(t) ? appOnlyChip : isWrite(t) ? chip('purple', 'Writes') : ''} |
| ~${num(t.tokens)} | ${status(t.name)} |
`)
.join('\n');
const table = `| # | Tool | Share of tokens | Tokens | Status |
${rows}
`;
const lists = [menu.prompts && plural(menu.prompts.length, 'prompt', 'prompts'), menu.resources && plural(menu.resources.length, 'resource', 'resources'), menu.resourceTemplates && plural(menu.resourceTemplates.length, 'resource template', 'resource templates')].filter(Boolean);
const notes = [
appOnly ? `${plural(appOnly.tools, 'tool isn\'t', 'tools aren\'t')} shown to the agent (MCP Apps visibility without "model", ~${num(appOnly.tokens)} tokens).` : '',
options.cost ? `${upper(costLine(options.cost))}.` : '',
lists.length ? `Also listed: ${lists.join(', ')}.` : '',
options.notOffered?.length ? `Not offered by the server: ${options.notOffered.join(', ')}.` : '',
options.outPath ? `Menu written to ${options.outPath}.` : '',
].filter(Boolean);
const name = menu.server.name ?? 'MCP server';
const body = `${heading(name, menu.server.version, ['Snapshot', protocolLine(menu.server), esc(options.transport ?? '')].filter(Boolean))}
${stat('tools', 'Tools', String(menu.tools.length), writes ? ['purple', plural(writes, 'write tool', 'write tools')] : undefined)}
${options.cost?.upfront !== undefined ? stat('tokens', `Up front, as ${options.cost.label}`, `~${num(options.cost.upfront)}`, ['neutral', `of ~${num(menu.totalTokens)}`]) : stat('tokens', 'Tokens up front', `~${num(menu.totalTokens)}`, ['neutral', 'estimate'])}
${stat('error', 'Errors', String(c.error), c.error ? undefined : ['lime', 'None'])}
${stat('warn', 'Warnings', String(c.warn), c.warn ? undefined : ['lime', 'None'])}
${card('Tool menu, in server order', plural(menu.tools.length, 'tool', 'tools'), notes.join(' ') || undefined, table)}
${panel('Findings', findings)}
`;
return page(`toolmenu snapshot: ${name}`, body);
}
export interface DiffHtmlOptions {
/** The two menu files, as given on the command line. */
paths?: [string, string];
}
/**
* The diff page, from what diffMenus compared and decided (`tools`, from its onTools):
* the tools after the ignore globs, and which were added, removed and renamed. Token
* totals are the result's, which leave app-only tools out, as the text report's do.
*/
export function diffHtml(result: DiffResult, tools: DiffTools, options: DiffHtmlOptions = {}): string {
const old = new Map(tools.before.map((t) => [t.name, t]));
const added = new Set(tools.added);
const renamedTo = new Map(tools.renamed.map((r) => [r.to, r.from]));
const gone = new Set(tools.removed);
const removed = tools.before.filter((t) => gone.has(t.name));
const described = new Set(result.findings.filter((f) => f.rule === 'diff/description').flatMap(toolsOf));
const max = Math.max(1, ...tools.after.map((t) => t.tokens), ...removed.map((t) => t.tokens));
const rows = tools.after.map((t, i) => {
const from = renamedTo.get(t.name);
const was = added.has(t.name) ? undefined : old.get(from ?? t.name)?.tokens;
const kept = was === undefined ? 0 : Math.min(was, t.tokens);
const delta = was === undefined ? undefined : t.tokens - was;
const change = was === undefined ? chip('lime', 'New') : delta! > 0 ? chip('yellow', `+${num(delta!)}`) : delta! < 0 ? chip('soft', `−${num(-delta!)}`) : '0';
const tag = from ? `Renamed` : isAppOnly(t) ? appOnlyChip : described.has(t.name) ? chip('purple', 'Description') : '';
return `| ${tools.positions[i] ?? i} | ${esc(t.name)}${tag}${from ? ` was ${esc(from)} ` : ''} |
| ${was === undefined ? '–' : `~${num(was)}`} | ~${num(t.tokens)} | ${change} |
`;
});
for (const t of removed) {
rows.push(`| – | ${esc(t.name)} |
| ~${num(t.tokens)} | – | ${chip('rose', 'Removed')} |
`);
}
const table = `| # | Tool | Now | Before | After | Change |
${rows.join('\n')}
`;
const t = result.tokens;
const share = t.before > 0 ? (Math.abs(t.delta) / t.before) * 100 : 0;
const growth = t.before === 0 ? signed(t.delta) : `${t.delta > 0 ? '+' : '−'}${share < 1 ? '<1' : Math.round(share)}%`;
const grew = tools.after.filter((x) => !added.has(x.name) && x.tokens > (old.get(renamedTo.get(x.name) ?? x.name)?.tokens ?? Infinity)).length;
const k = result.classes;
const bump = result.suggestedBump;
const [v0, v1] = [result.before.version, result.after.version];
const versions = v0 && v1 ? (v0 === v1 ? `Both report ${esc(v1)}` : `${esc(v0)} → ${esc(v1)}`) : '';
const file = (path: string) => `${esc(basename(path))}`;
const files = options.paths ? `${file(options.paths[0])} → ${file(options.paths[1])}` : '';
// Removing or renaming a tool breaks callers: rose whenever either happened, whatever was added.
const moves = [added.size && `${added.size} new`, removed.length && `${removed.length} gone`, tools.renamed.length && `${tools.renamed.length} renamed`].filter(Boolean);
const toolsChip: [string, string] | undefined = moves.length ? [removed.length || tools.renamed.length ? 'rose' : 'lime', moves.join(', ')] : tools.ignored ? ['soft', `${tools.ignored} ignored`] : undefined;
const name = result.after.name ?? result.before.name ?? 'MCP server';
const body = `${heading(name, undefined, ['Diff', files, versions].filter(Boolean))}
${stat('break', 'Breaking changes', String(k.breaking.changes), k.breaking.changes ? ['rose', plural(k.breaking.tools, 'tool', 'tools')] : ['lime', 'None'])}
${stat('tag', 'Suggested bump', bump === 'none' ? 'None' : upper(bump), k.minor.changes ? ['soft', plural(k.minor.changes, 'minor change', 'minor changes')] : undefined)}
${stat('tools', 'Tools', String(tools.after.length), toolsChip)}
${stat('tokens', 'Tokens up front', `~${num(t.after)}`, t.delta ? [t.delta > 0 ? 'yellow' : 'lime', growth] : ['soft', 'unchanged'])}
${card('Token change, per tool', `${signed(t.delta)} tokens`, `${plural(grew, 'tool', 'tools')} grew, ${added.size} new, ${removed.length} removed${tools.renamed.length ? `, ${tools.renamed.length} renamed` : ''} · ~${num(t.before)} → ~${num(t.after)}`, table, 'BeforeAdded since')}
${panel('Changes', result.findings)}
`;
return page(`toolmenu diff: ${name}`, body);
}
/** The session page. `menus`: the menu after each step, from session's onStepMenu. */
export function sessionHtml(result: SessionResult, menus: Map = new Map()): string {
const c = counts(result.findings);
const ids = new Map(result.findings.map((f, i) => [f, `finding-${i + 1}`]));
const stepsOf = (f: Finding) => (f.steps?.length ? f.steps : f.step !== undefined ? [f.step] : []);
const byStep = new Map();
for (const f of result.findings) for (const n of stepsOf(f)) byStep.set(n, [...(byStep.get(n) ?? []), f]);
const before = byStep.get(0) ?? [];
const shown = new Set([...result.steps.map((s) => s.index), ...(before.length ? [0] : [])]);
// One scale for every strip: the tools after a step and those it removed, against the largest.
const total = (menu: StepTool[]) => menu.reduce((n, t) => n + t.tokens, 0);
const max = Math.max(1, ...[...menus.values()].map(total));
const changed = result.steps.filter((s) => s.changed).map((s) => s.index);
const span = changed.length ? upper(stepsText(changed)) : 'No';
const strip = (menu: StepTool[] | undefined) =>
menu ? `${menu.map((t) => ``).join('')}
` : '–';
const fill = (menu: StepTool[] | undefined) => (menu ? `${strip(menu)}
` : strip(menu));
// The step's status first: a call answered before the menu couldn't be listed still failed.
const outcome = (s: SessionResult['steps'][number]) =>
s.status === 'timed-out' ? chip('yellow', 'Timed out')
: s.status === 'failed' && s.outcome === 'answered' ? 'Failed after'
: s.outcome === 'answered' ? chip('soft', 'Answered')
: s.outcome === 'tool-error' ? chip('yellow', 'Tool error')
: s.outcome === 'failed' ? chip('rose', 'Failed')
: s.outcome === 'not-sent' ? chip('rose', 'Not sent')
: s.outcome === 'needs-input' ? chip('purple', 'Asked for input')
: '–';
const links = (index: number) => (byStep.get(index) ?? []).map((f) => `${esc(f.rule)}`).join('');
const rows = result.steps.map((s) => {
const tags = links(s.index);
return `| ${s.index} | ${esc(s.label)}${s.note ? `${esc(s.note)} ` : ''}${tags ? `${tags} ` : ''} | ${outcome(s)} | ${fill(menus.get(s.index))} | ${s.tools} | ~${num(s.tokens)} |
`;
});
if (before.length) rows.unshift(`| 0 | Before the first step ${links(0)} | – | – | ${result.baseline.tools} | ~${num(result.baseline.tokens)} |
`);
const table = `| # | Step | Call | Menu after it | Tools | Tokens |
${rows.join('\n')}
`;
const grew = result.final.tokens - result.baseline.tokens;
const fresh = result.connectionCheck === 'same' ? 'A fresh process starts with the same menu.' : result.connectionCheck === 'different' ? 'A fresh process starts with a different menu.' : undefined;
// Info findings start folded, unless a step row links into them.
const linkedInfo = result.findings.some((f) => f.severity === 'info' && stepsOf(f).some((n) => shown.has(n)));
// --auto: what it called and what it left out, as the text report says it.
const auto = result.auto ? autoSummary(result.auto) : [];
const autoBlock = auto.length ? `${esc(upper(auto[0].replace(/^auto: /, '')))}
${auto.length > 1 ? `${auto.slice(1).map((l) => `- ${esc(l.trim())}
`).join('')}
` : ''} ` : '';
const name = result.server.name ?? 'MCP server';
const body = `${heading(name, result.server.version, ['Session', `${esc(result.scenario)}`, protocolLine(result.server), esc(result.transport)].filter(Boolean))}
${stat('error', 'Errors', String(c.error), c.error ? undefined : ['lime', 'None'])}
${stat('warn', 'Warnings', String(c.warn), c.warn ? undefined : ['lime', 'None'])}
${stat('steps', 'Menu changed', span, ['soft', plural(result.steps.length, 'step', 'steps')])}
${stat('tokens', 'Tokens up front', `~${num(result.final.tokens)}`, grew ? [grew > 0 ? 'yellow' : 'lime', `${signed(grew)} in the session`] : ['soft', 'unchanged'])}
${card('The scenario, step by step', `${result.baseline.tools} → ${plural(result.final.tools, 'tool', 'tools')}`, fresh, table, 'A tool, sized by tokensInserted mid-listAppendedEdited or movedRemoved', autoBlock)}
${panel('Findings', result.findings, ids, linkedInfo)}
`;
return page(`toolmenu session: ${name}`, body);
}
const CSS = `
:root{--accent-500:#6E56CF;--mint:#5EEAB5;--text-primary:#0A0A0A;--text-secondary:#737373;--text-tertiary:#A3A3A3;--bg-full:#FFFFFF;--bg-primary:#FFFFFF;--bg-secondary:#F7F7F7;--bg-tertiary:#EBEBEB;--bg-inner:#FFFFFF;--border:#EBEBEB;--separator:#EBEBEB;--track:#EBEBEB;--bar:#6E56CF;--bar-soft:#EBE7FB;--lime-bg:#D9F99D;--lime-text:#3F6212;--rose-bg:#FECDD3;--rose-text:#9F1239;--yellow-bg:#FEF08A;--yellow-text:#854D0E;--purple-bg:#F3E8FF;--purple-text:#9333EA;--dot-rose:#F43F5E;--dot-rose-halo:#FFE4E6;--dot-yellow:#EAB308;--dot-yellow-halo:#FEF9C3;--shadow-card:0 1px 1px 0 rgb(0 0 0 / .05);--font-sans:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;--font-mono:"JetBrains Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;color-scheme:light}
@media (prefers-color-scheme:dark){:root{--text-primary:#FAFAFA;--text-secondary:#A3A3A3;--text-tertiary:#8F8F8F;--bg-full:#121212;--bg-primary:#262626;--bg-secondary:#171717;--bg-tertiary:#3A3A3A;--bg-inner:#262626;--border:#404040;--separator:#3A3A3A;--track:#333333;--bar:#9580E2;--bar-soft:#4B3F82;--lime-bg:rgb(26 46 5 / .6);--lime-text:#84CC16;--rose-bg:rgb(76 5 25 / .6);--rose-text:#F43F5E;--yellow-bg:rgb(66 32 6 / .6);--yellow-text:#EAB308;--purple-bg:rgb(88 28 135 / .5);--purple-text:#D8B4FE;--dot-rose-halo:rgb(76 5 25 / .8);--dot-yellow-halo:rgb(66 32 6 / .8);--shadow-card:0 0 0 1px rgb(255 255 255 / .04);color-scheme:dark}}
*{box-sizing:border-box}
body{margin:0;background:var(--bg-full);color:var(--text-primary);font-family:var(--font-sans);font-size:14px;line-height:20px;-webkit-font-smoothing:antialiased}
p{margin:0}
.t-title-1{font-size:24px;line-height:34px;font-weight:500;margin:0}
.t-headline{font-size:16px;line-height:22px;font-weight:500}
.t-body-m{font-size:14px;line-height:20px;font-weight:500}
.t-body{font-size:14px;line-height:20px;font-weight:400}
.t-body2{font-size:13px;line-height:18px;font-weight:400}
.t-cap-m{font-size:12px;line-height:16px;font-weight:500;letter-spacing:.15px}
.sec{color:var(--text-secondary)}.ter{color:var(--text-tertiary)}.tnum{font-variant-numeric:tabular-nums}
.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}
code,.mono{font-family:var(--font-mono);font-size:12.5px}
a{color:inherit}
:focus-visible{outline:2px solid var(--accent-500);outline-offset:2px;border-radius:6px}
svg{flex:none}
.page{max-width:1200px;margin:0 auto;padding:20px 16px 40px;display:grid;gap:24px}
main{display:grid;gap:24px}
.brand{display:flex;align-items:center;gap:8px}.brand svg{width:28px;height:28px}
.head .sub{display:flex;flex-wrap:wrap;gap:4px 16px;margin-top:2px}
.stats{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:16px}
.stat{display:flex;flex-direction:column;justify-content:space-between;gap:18px;min-height:132px;padding:16px;border-radius:16px;background:var(--bg-secondary);min-width:0}
.stat .icon{display:flex;padding:6px;border-radius:6px;background:var(--bg-primary);align-self:flex-start}
.stat .icon svg{width:20px;height:20px}
.stat .val{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
.chip{display:inline-flex;align-items:center;padding:2px 6px;border-radius:6px;white-space:nowrap;font-size:14px;line-height:20px;font-weight:500;text-decoration:none}
.chip.sm{font-size:12px;line-height:16px;letter-spacing:.15px}
.chip.lime{background:var(--lime-bg);color:var(--lime-text)}.chip.rose{background:var(--rose-bg);color:var(--rose-text)}.chip.yellow{background:var(--yellow-bg);color:var(--yellow-text)}.chip.purple{background:var(--purple-bg);color:var(--purple-text)}.chip.neutral{background:var(--bg-tertiary);color:var(--text-secondary)}.chip.soft{background:var(--bg-secondary);color:var(--text-secondary)}
.sdot{display:inline-flex;width:12px;height:12px;border-radius:50%;align-items:center;justify-content:center}
.sdot::after{content:"";width:6px;height:6px;border-radius:50%}
.sdot.rose{background:var(--dot-rose-halo)}.sdot.rose::after{background:var(--dot-rose)}
.sdot.yellow{background:var(--dot-yellow-halo)}.sdot.yellow::after{background:var(--dot-yellow)}
.check{width:16px;height:16px;color:var(--mint)}
.main{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(0,1fr);gap:16px;align-items:start}
.main>*{min-width:0}
.card{border:1px solid var(--border);border-radius:24px;background:var(--bg-primary);overflow:hidden}
.card-head{display:flex;flex-direction:column;gap:2px;padding:18px 20px 14px}
.card-foot{display:flex;flex-wrap:wrap;gap:6px 16px;padding:12px 20px 16px;border-top:1px solid var(--separator)}
.legend i{display:inline-block;width:10px;height:10px;border-radius:3px;margin-right:6px;vertical-align:-1px}
.k-bar{background:var(--bar)}.k-mint{background:var(--mint)}.k-ins{background:var(--dot-rose)}.k-app{background:var(--dot-yellow)}.k-edit{box-shadow:inset 0 0 0 1.5px var(--dot-rose)}.k-rem{background:repeating-linear-gradient(135deg,var(--dot-rose) 0 2px,transparent 2px 4px)}
.scroll{overflow-x:auto}
table{width:100%;border-collapse:collapse;text-align:left}
th{padding:10px 12px;font-size:14px;line-height:20px;font-weight:500;color:var(--text-tertiary);white-space:nowrap;background:var(--bg-secondary);border-top:1px solid var(--separator);border-bottom:1px solid var(--separator)}
td{padding:10px 12px;font-weight:500;vertical-align:middle}
tbody tr:not(:last-child){border-bottom:1px solid var(--separator)}
th:first-child,td:first-child{padding-left:20px}th:last-child,td:last-child{padding-right:20px}
.num{text-align:right;font-variant-numeric:tabular-nums;white-space:nowrap}
td.pos{color:var(--text-tertiary);font-variant-numeric:tabular-nums;width:1%}
td.name{white-space:nowrap}td.name .chip{margin-left:6px}
.status{width:1%;text-align:center}
tr.gone td.name{color:var(--text-secondary);text-decoration:line-through}
.meter{position:relative;height:6px;border-radius:999px;background:var(--track);min-width:90px;overflow:hidden}
.meter span{position:absolute;left:0;top:0;bottom:0;border-radius:999px;background:var(--bar)}
.meter span.grow{background:var(--mint)}.meter span.ghost{background:var(--text-tertiary)}
td.bar{width:34%}
.fill{min-width:4px}
.strip{display:flex;overflow:hidden;border-radius:3px;min-width:0}
.strip span{flex-basis:0;min-width:0;height:8px;background:var(--bar-soft);box-shadow:inset -1px 0 0 var(--bg-primary)}
td:has(.fill){min-width:150px}
tr.changed .strip span{background:var(--bar)}
.strip .inserted,tr.changed .strip .inserted{background:var(--dot-rose)}
.strip .appended,tr.changed .strip .appended{background:var(--dot-yellow)}
.strip .edited,.strip .moved,tr.changed .strip .edited,tr.changed .strip .moved{background:transparent;box-shadow:inset 0 0 0 1.5px var(--dot-rose)}
.strip .removed,tr.changed .strip .removed{background:repeating-linear-gradient(135deg,var(--dot-rose) 0 2px,transparent 2px 4px);opacity:.7}
td.step{max-width:280px}td.step code{overflow-wrap:anywhere}
.tags{display:flex;gap:6px;flex-wrap:wrap}td .tags{margin-top:6px}
.panel{background:var(--bg-secondary);border-radius:24px;padding:8px;display:grid;gap:8px}
.panel-head{padding:10px 10px 4px}
.tile{display:grid;gap:6px;padding:12px;border-radius:10px;background:var(--bg-inner);box-shadow:var(--shadow-card);scroll-margin-top:16px}
.tile:target{box-shadow:0 0 0 2px var(--accent-500)}
.tile-top{display:flex;justify-content:space-between;gap:10px;align-items:flex-start}
.tile-top .mono{font-weight:500;font-size:13px;overflow-wrap:anywhere}
.tile p{max-width:64ch}
.detail{margin:0;padding:0;list-style:none;display:grid;gap:2px;color:var(--text-secondary);overflow-wrap:anywhere}
.next b{font-weight:500;color:var(--text-secondary)}
details.more>summary{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;gap:10px;padding:12px;border-radius:10px;background:var(--bg-inner);box-shadow:var(--shadow-card)}
details.more>summary::-webkit-details-marker{display:none}
details.more>summary svg{color:var(--text-secondary);transition:transform .2s ease}
details.more[open]>summary svg{transform:rotate(180deg)}
details.more[open]>summary{margin-bottom:8px}
details.more .list{display:grid;gap:8px}
.row-gap{display:flex;gap:8px;align-items:center}
details.auto{margin:0 20px 14px;padding:10px 12px;border-radius:10px;background:var(--bg-secondary)}
details.auto summary{cursor:pointer}
details.auto ul{margin:8px 0 0;padding-left:18px;display:grid;gap:2px}
.empty{display:flex;gap:8px;align-items:center;padding:12px;border-radius:10px;background:var(--bg-inner);box-shadow:var(--shadow-card)}
.foot{display:flex;flex-wrap:wrap;gap:4px 20px}.foot a{color:var(--accent-500)}
@media (max-width:1000px){.stats{grid-template-columns:repeat(2,minmax(0,1fr))}.main{grid-template-columns:minmax(0,1fr)}}
@media (max-width:480px){.stat{min-height:116px;padding:14px}.stat .t-title-1{font-size:20px;line-height:28px}td.bar{min-width:110px}}
@media (prefers-reduced-motion:reduce){details.more>summary svg{transition:none}}
@media print{.card,.panel,.stat{break-inside:avoid}details.more::details-content{content-visibility:visible;display:block}}
`;