@v1nvn/readability-mcp 0.17.0 → 0.19.0

package/dist/index.js

@@ -1,9 +1,867 @@
 #!/usr/bin/env node
-import { $ as outlineInputShape, A as extractListOutputShape, B as extractLinksInputShape, C as resolveLazyImages, D as chunkTextOutputShape, E as isElement, F as chunkTextInputSchema, G as extractSectionInputSchema, H as extractListInputShape, I as chunkTextInputShape, J as extractTablesInputShape, K as extractSectionInputShape, L as extractGridInputSchema, M as extractTablesOutputShape, N as outlineOutputShape, O as extractGridOutputShape, P as outputSchemaShape, Q as outlineInputSchema, R as extractGridInputShape, S as normalizeDocument, T as buildDocument, U as extractMetadataInputSchema, V as extractListInputSchema, W as extractMetadataInputShape, X as htmlToMarkdownInputShape, Y as htmlToMarkdownInputSchema, Z as localPathField, _ as detectGating, a as sanitizeHtml, at as registerResources, b as isReaderable, c as computeTextMetrics, d as renderTable, et as selectorsSchema, f as resolveHeaderKeys, g as absolutize, h as detectPagination, i as toMarkdown, it as toErrorResult, j as extractMetadataOutputShape, k as extractLinksOutputShape, l as nonEmpty, m as readHtmlFile, n as registerExtractTool, nt as logger, o as formatPayload, ot as loadConfig, p as resolveCellText, q as extractTablesInputSchema, r as truncateMarkdown, rt as ExtractionError, s as resolveMetadata, t as extractArticleFromHtml, tt as chunkMarkdown, u as parseTableMatrix, v as TraceCollector, w as resolveReadabilityOptions, x as applySelectors, y as assembleDiagnostics, z as extractLinksInputSchema } from "./assets/extract-BWRBFiUP.js";
+import { $ as resolveLazyImages, A as selectorsSchema, B as absolutize, C as extractTablesInputSchema, D as localPathField, E as htmlToMarkdownInputShape, F as detectGating, G as sanitizeHtml, H as renderTable, I as TraceCollector, J as computeTextMetrics, K as isReaderable, L as assembleDiagnostics, M as truncateMarkdown, N as detectPagination, O as outlineInputSchema, P as resolveMetadata, Q as normalizeDocument, R as chunkMarkdown, S as extractSectionInputShape, T as htmlToMarkdownInputSchema, U as resolveHeaderKeys, V as parseTableMatrix, W as resolveCellText, X as nonEmpty, Y as countWords, Z as applySelectors, _ as extractListInputSchema, a as extractLinksOutputShape, at as registerResources, b as extractMetadataInputShape, c as extractTablesOutputShape, ct as presetForSite, d as chunkTextInputSchema, dt as logger, et as resolveReadabilityOptions, f as chunkTextInputShape, ft as loadConfig, g as extractLinksInputShape, h as extractLinksInputSchema, i as extractGridOutputShape, it as toErrorResult, j as readHtmlFile, k as outlineInputShape, l as outlineOutputShape, lt as removePreset, m as extractGridInputShape, n as registerExtractTool, nt as isElement, o as extractListOutputShape, ot as addPreset, p as extractGridInputSchema, q as formatPayload, r as chunkTextOutputShape, rt as ExtractionError, s as extractMetadataOutputShape, st as normalizeSiteKey, t as extractArticleFromHtml, tt as buildDocument, u as outputSchemaShape, ut as selectorMisses, v as extractListInputShape, w as extractTablesInputShape, x as extractSectionInputSchema, y as extractMetadataInputSchema, z as toMarkdown } from "./assets/extract-BF4w5w8k.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { z } from "zod";
 import { Readability } from "@mozilla/readability";
+//#region src/preset-cache.ts
+var PRESETS_DIR_ENV = "READABILITY_MCP_PRESETS_DIR";
+var presetFileSchema = z.object({
+	site: z.string().min(1),
+	detectors: z.array(z.string().min(1)).min(1),
+	scope: z.object({
+		include: z.string().min(1).optional(),
+		exclude: z.array(z.string().min(1)).min(1).optional()
+	}).refine((scope) => scope.include !== void 0 || scope.exclude !== void 0, { message: "scope must carry include or exclude" })
+});
+function resolvePresetsDir(env = process.env) {
+	const override = env[PRESETS_DIR_ENV];
+	if (override !== void 0) return override.trim() === "" ? void 0 : override;
+	const root = env.XDG_CACHE_HOME || join(homedir(), process.platform === "darwin" ? "Library/Caches" : ".cache");
+	return join(root, "readability-mcp", "presets");
+}
+function loadPresetDir(dir) {
+	let names;
+	try {
+		names = readdirSync(dir).filter((name) => name.endsWith(".json")).sort();
+	} catch (err) {
+		if (err.code === "ENOENT") logger.debug(`no preset directory at ${dir}`);
+		else logger.warn(`preset directory unreadable: ${dir}`);
+		return {
+			loaded: 0,
+			pruned: 0,
+			skipped: 0
+		};
+	}
+	const ranked = rankPresetFiles(dir, names);
+	const pruned = pruneRanked(dir, ranked.slice(64));
+	let loaded = 0;
+	let skipped = 0;
+	for (const { name } of ranked.slice(0, 64)) if (loadPresetFile(join(dir, name))) loaded++;
+	else skipped++;
+	if (loaded > 0) logger.info(`loaded ${loaded} site preset(s) from ${dir}`);
+	if (pruned > 0) logger.info(`pruned ${pruned} preset file(s) beyond the 64-file bound`);
+	return {
+		loaded,
+		pruned,
+		skipped
+	};
+}
+function loadPresets(env = process.env) {
+	const dir = resolvePresetsDir(env);
+	return dir ? loadPresetDir(dir) : void 0;
+}
+function rankPresetFiles(dir, names) {
+	const ranked = [];
+	for (const name of names) try {
+		ranked.push({
+			name,
+			mtimeMs: statSync(join(dir, name)).mtimeMs
+		});
+	} catch {}
+	ranked.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	return ranked;
+}
+function pruneRanked(dir, ranked) {
+	let pruned = 0;
+	for (const { name } of ranked) try {
+		unlinkSync(join(dir, name));
+		pruned++;
+	} catch (err) {
+		logger.warn(`could not prune preset file ${name}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return pruned;
+}
+function savePreset(preset, env = process.env) {
+	const dir = resolvePresetsDir(env);
+	if (!dir) return {
+		persisted: false,
+		reason: "preset-directory-disabled"
+	};
+	const shape = presetFileSchema.safeParse(preset);
+	if (!shape.success) return {
+		persisted: false,
+		reason: shape.error.issues[0]?.message ?? "invalid preset shape"
+	};
+	const key = normalizeSiteKey(preset.site);
+	if (!key) return {
+		persisted: false,
+		reason: "site-is-not-a-hostname"
+	};
+	const path = join(dir, `${key}.json`);
+	try {
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(path, `${JSON.stringify(shape.data, null, 2)}\n`);
+	} catch (err) {
+		return {
+			persisted: false,
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+	pruneRanked(dir, rankPresetFiles(dir, readdirSync(dir).filter((name) => name.endsWith(".json"))).slice(64));
+	return {
+		path,
+		persisted: true
+	};
+}
+function loadPresetFile(path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		logger.warn(`${path}: not readable JSON (${err instanceof Error ? err.message : String(err)}), preset skipped`);
+		return false;
+	}
+	const result = presetFileSchema.safeParse(parsed);
+	if (!result.success) {
+		logger.warn(`${path}: ${result.error.issues[0]?.message}, preset skipped`);
+		return false;
+	}
+	if (!normalizeSiteKey(result.data.site)) {
+		logger.warn(`${path}: site is not a hostname, preset skipped`);
+		return false;
+	}
+	addPreset(result.data);
+	return true;
+}
+//#endregion
+//#region src/host-sampling.ts
+var SAMPLING_TIMEOUT_MS = 3e5;
+async function sampleText$1(server, args) {
+	const result = await server.server.createMessage({
+		messages: [{
+			role: "user",
+			content: {
+				type: "text",
+				text: args.userText
+			}
+		}],
+		systemPrompt: args.systemPrompt,
+		maxTokens: args.maxTokens
+	}, { timeout: SAMPLING_TIMEOUT_MS });
+	if (result.content.type !== "text") throw new Error(`host sampling returned non-text content (${result.content.type})`);
+	return result.content.text;
+}
+var SuggestParseError = class extends Error {
+	rawText;
+	constructor(message, rawText) {
+		super(message);
+		this.rawText = rawText;
+	}
+};
+function extractJsonReply(text) {
+	const trimmed = text.replace(/^[\s\S]*?```(?:json)?\s*\n?([\s\S]*?)\n?```[\s\S]*$/, "$1").trim();
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		const start = trimmed.indexOf("{");
+		const end = trimmed.lastIndexOf("}");
+		if (start !== -1 && end > start) try {
+			return JSON.parse(trimmed.slice(start, end + 1));
+		} catch {}
+		throw new SuggestParseError(`host sampling returned text that does not parse as JSON (${trimmed.slice(0, 80)}…)`, trimmed);
+	}
+}
+async function sampleJson(server, args) {
+	return extractJsonReply(await sampleText$1(server, args));
+}
+var DEBRIS_PROBES = [
+	{
+		label: "player-controls",
+		pattern: /Loaded:\s*\d+%/
+	},
+	{
+		label: "player-controls",
+		pattern: /Duration Time \d+:\d\d/
+	},
+	{
+		label: "metered-barrier",
+		pattern: /read your last free article|subscribe to continue reading/i
+	}
+];
+function assessLostSignal(input) {
+	const wordCount = countWords(input.contentText);
+	const nearEmpty = wordCount < 120;
+	const debrisProbes = [...new Set(DEBRIS_PROBES.filter((probe) => probe.pattern.test(input.contentText)).map((probe) => probe.label))];
+	const reasons = [
+		...input.fallbackUsed ? ["fallback-used"] : [],
+		...nearEmpty ? ["near-empty"] : [],
+		...debrisProbes.map((label) => `debris:${label}`)
+	];
+	return {
+		debrisProbes,
+		fallbackUsed: input.fallbackUsed,
+		gatedReason: input.gated?.likely ? input.gated.reason : void 0,
+		nearEmpty,
+		reasons,
+		wordCount
+	};
+}
+var PRICE_TABLE = {
+	"Upper:Lower": .2,
+	"Lower:Upper": .5,
+	"Symbol:Upper": .4,
+	"Symbol:Lower": .3,
+	"Symbol:Digit": .9,
+	"Upper:Digit": 1.4,
+	"Lower:Digit": 1.3,
+	"Digit:Upper": 1.4,
+	"Digit:Lower": 1.5,
+	"Digit:Symbol": 1.2,
+	"Upper:Symbol": .2,
+	"Lower:Symbol": .2,
+	"Digit:Digit": 1.2,
+	"Symbol:Symbol": .3,
+	"Upper:Upper": .1,
+	"Lower:Lower": .1,
+	"Other:Other": 0
+};
+function classifyChar(ch) {
+	if (/[A-Z]/.test(ch)) return "Upper";
+	if (/[a-z]/.test(ch)) return "Lower";
+	if (/[0-9]/.test(ch)) return "Digit";
+	if (/[-_]/.test(ch)) return "Symbol";
+	return "Other";
+}
+function transitionPrice(from, to) {
+	return PRICE_TABLE[`${from}:${to}`] ?? 1;
+}
+function gibberishScore(value) {
+	if (value.length < 2) return 0;
+	let absolute = 0;
+	let previous = null;
+	for (const ch of value) {
+		const current = classifyChar(ch);
+		if (previous !== null) absolute += transitionPrice(previous, current);
+		previous = current;
+	}
+	return absolute / Math.max(1, value.length - 1);
+}
+function exceedsThreshold(value) {
+	return value.length >= 4 && gibberishScore(value) >= .3;
+}
+function isGeneratedIdentifier(value) {
+	if (exceedsThreshold(value)) return true;
+	return value.split(/[-_]/).some((segment) => exceedsThreshold(segment));
+}
+var SAMPLE_MAX_CHARS = 80;
+var NON_CONTENT_SELECTOR = "script, style, noscript, template";
+var HOP_ATTRIBUTE_WHITELIST = [
+	"itemprop",
+	"role",
+	"data-testid"
+];
+function buildChainOutline(input) {
+	const { document } = buildDocument(input.html, input.baseUrl);
+	normalizeDocument(document, { cleanChrome: input.cleanChrome });
+	resolveLazyImages(document);
+	const scope = input.mode === "page" ? void 0 : input.mode.scope;
+	if (scope) applySelectors(document, scope);
+	const scopeRoot = scope?.include ? document.body.querySelector(scope.include) ?? void 0 : void 0;
+	const min = scope ? 40 : 200;
+	const candidates = [];
+	for (const element of (scopeRoot ?? document.body).querySelectorAll("*")) {
+		if (element.closest(NON_CONTENT_SELECTOR)) continue;
+		const own = ownTextLength(element);
+		if (own >= min) candidates.push({
+			element,
+			own
+		});
+	}
+	return scope ? groupedOutline(candidates, scopeRoot) : flatOutline(candidates);
+}
+function flatOutline(candidates) {
+	const lines = [];
+	let truncated = false;
+	for (const candidate of [...candidates].sort((a, b) => b.own - a.own)) {
+		if (lines.length >= 60) {
+			truncated = true;
+			break;
+		}
+		const line = ancestorsUpTo(candidate.element, void 0).map((element) => hopWithSizes(element)).join(" > ");
+		if (lines.join("\n---\n").length + line.length > 6e3) {
+			truncated = true;
+			break;
+		}
+		lines.push(line);
+	}
+	return {
+		chainCount: lines.length,
+		text: lines.join("\n---\n"),
+		truncated
+	};
+}
+function groupedOutline(candidates, scopeRoot) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const chain = ancestorsUpTo(candidate.element, scopeRoot).map((element) => renderHop(element));
+		if (scopeRoot) chain.push(renderHop(scopeRoot));
+		const key = chain.join(" > ");
+		const existing = groups.get(key);
+		if (existing) {
+			existing.count += 1;
+			existing.min = Math.min(existing.min, candidate.own);
+			existing.max = Math.max(existing.max, candidate.own);
+		} else groups.set(key, {
+			chain: key,
+			count: 1,
+			min: candidate.own,
+			max: candidate.own,
+			sample: sampleText(candidate.element)
+		});
+	}
+	const lines = [];
+	let truncated = false;
+	const sorted = [...groups.values()].sort((a, b) => a.min - b.min);
+	for (const group of sorted) {
+		if (lines.length >= 60) {
+			truncated = true;
+			break;
+		}
+		const line = `${group.chain} (own:${group.min}..${group.max}, ×${group.count}) sample: "${group.sample}"`;
+		if (lines.join("\n").length + line.length > 6e3) {
+			truncated = true;
+			break;
+		}
+		lines.push(line);
+	}
+	return {
+		chainCount: lines.length,
+		text: lines.join("\n"),
+		truncated
+	};
+}
+function ancestorsUpTo(element, stop) {
+	const hops = [];
+	let node = element;
+	const body = element.ownerDocument.body;
+	while (node && node !== stop && node !== body) {
+		hops.push(node);
+		node = node.parentElement;
+	}
+	return hops;
+}
+function hopWithSizes(element) {
+	const own = ownTextLength(element);
+	const all = element.textContent.length;
+	return `${renderHop(element)} (own:${own}, all:${all})`;
+}
+function ownTextLength(element) {
+	let own = 0;
+	for (const node of element.childNodes) if (node.nodeType === node.TEXT_NODE) own += (node.textContent ?? "").length;
+	return own;
+}
+function renderHop(element) {
+	let hop = element.tagName.toLowerCase();
+	const id = element.id;
+	if (id && !isGeneratedIdentifier(id)) hop += `#${id}`;
+	const classes = (element.getAttribute("class") ?? "").split(/\s+/).filter(Boolean).filter((className) => !isGeneratedIdentifier(className));
+	if (classes.length > 0) hop += `.${classes.join(".")}`;
+	for (const attribute of HOP_ATTRIBUTE_WHITELIST) {
+		const value = element.getAttribute(attribute);
+		if (value) hop += `[${attribute}="${value}"]`;
+	}
+	return hop;
+}
+function sampleText(element) {
+	const text = element.textContent.trim().replace(/\s+/g, " ");
+	return text.length > SAMPLE_MAX_CHARS ? `${text.slice(0, SAMPLE_MAX_CHARS)}…` : text;
+}
+//#endregion
+//#region src/policy/selector-lint.ts
+var POSITIONAL_PSEUDO_RE = /:(?:nth(?:-last)?(?:-child|-of-type)|first(?:-child|-of-type)|last(?:-child|-of-type)|only(?:-child|-of-type))\b/i;
+var CONTAINS_PSEUDO_RE = /:contains\s*\(/i;
+function quotedSegmentsOut(selector) {
+	return selector.replace(/(["'])(?:\\.|(?!\1)[\s\S])*\1/g, "\"\"");
+}
+function identifierTokens(selector) {
+	return [...quotedSegmentsOut(selector).matchAll(/[.#]([A-Za-z0-9_-]+)/g)].map((match) => match[1]);
+}
+function lintSelectorText(selector) {
+	if (CONTAINS_PSEUDO_RE.test(selector)) return {
+		kind: "contains-pseudo",
+		selector,
+		detail: ":contains is not standard CSS and changes the result silently"
+	};
+	const positional = POSITIONAL_PSEUDO_RE.exec(selector);
+	if (positional) return {
+		kind: "positional-pseudo",
+		selector,
+		detail: `${positional[0]} depends on this page's child order, not the site's layout`
+	};
+	for (const token of identifierTokens(selector)) if (isGeneratedIdentifier(token)) return {
+		kind: "generated-identifier",
+		selector,
+		detail: `"${token}" reads as a generated hash that changes on deploy`
+	};
+}
+function lintProposal({ document, detectors, scope }) {
+	const violations = [];
+	const selectors = [
+		...detectors,
+		...scope.include ? [scope.include] : [],
+		...scope.exclude ?? []
+	];
+	for (const selector of selectors) {
+		const violation = lintSelectorText(selector);
+		if (violation) violations.push(violation);
+	}
+	let includeRoot;
+	if (scope.include && !violations.some((violation) => violation.selector === scope.include)) try {
+		includeRoot = document.body.querySelector(scope.include) ?? void 0;
+	} catch {
+		violations.push({
+			kind: "unparseable",
+			selector: scope.include,
+			detail: "the selector engine rejects this selector"
+		});
+	}
+	for (const detector of detectors) {
+		if (violations.some((violation) => violation.selector === detector)) continue;
+		if (selectorMisses(document, detector)) violations.push({
+			kind: "no-match",
+			selector: detector,
+			detail: "detector matches nothing on this page"
+		});
+	}
+	if (scope.include && !includeRoot && !violations.some((violation) => violation.selector === scope.include)) violations.push({
+		kind: "no-match",
+		selector: scope.include,
+		detail: "include matches nothing inside <body>, where applySelectors searches"
+	});
+	for (const selector of scope.exclude ?? []) {
+		if (violations.some((violation) => violation.selector === selector)) continue;
+		try {
+			if (document.querySelectorAll(selector).length === 0) violations.push({
+				kind: "no-match",
+				selector,
+				detail: "exclude matches nothing on this page"
+			});
+		} catch {
+			violations.push({
+				kind: "unparseable",
+				selector,
+				detail: "the selector engine rejects this selector"
+			});
+		}
+	}
+	if (includeRoot) for (const selector of scope.exclude ?? []) {
+		if (violations.some((violation) => violation.selector === selector)) continue;
+		try {
+			for (const match of document.querySelectorAll(selector)) if (match.contains(includeRoot)) {
+				violations.push({
+					kind: "exclude-shadows-include",
+					selector,
+					detail: "this exclude removes the include root itself"
+				});
+				break;
+			}
+		} catch {}
+	}
+	return violations;
+}
+//#endregion
+//#region src/tools/suggest-preset.ts
+var SUGGEST_SYSTEM_PROMPT = `You propose site-level CSS presets for a web-article extractor. The extractor removes every "exclude" match document-wide, then keeps the FIRST match of "include" in document order as the entire page body (the search runs inside <body>). An exclude matching an ancestor of the include root destroys it.
+
+Rules:
+- "include": exactly ONE selector that matches an element inside <body> on THIS page. A non-matching selector silently does nothing.
+- "exclude": selectors naming debris containers (video players, carousels, caption figures, comment blocks, promo modules).
+- "detectors": 1-3 selectors naming stable site-template containers that also match on other pages of the same site. Their loss is what retires the preset, so they must be structural, not per-page.
+- Forbidden — statically rejected and fed back to you: :nth-child and every positional pseudo (:first-child, :last-of-type, :only-child, ...), :contains, and generated hash class names (css-1a2b3c, content_1tsiE, BoxStyles_x__Wo6Z4).
+- Prefer itemprop, role, data-testid, ids, and stable class-name stems; quote attribute values exactly as rendered in the material.
+- The material shows every text-bearing node as a CSS chain with text sizes. It deliberately carries no article prose.
+Return strict JSON only — no prose, no code fences.`;
+var suggestPresetInputShape = {
+	localPath: localPathField,
+	baseUrl: z.url().describe("A URL of the site the page belongs to — its host names the preset. Required: without a host there is no site key to store a preset under, and presets only resolve for pages whose site matches."),
+	secondPath: localPathField.optional().describe("A second capture of the SAME site. The converged preset must verify on it too — detectors match, extraction clean — before anything is persisted; without it the preset is verified on the proposal page alone."),
+	maxSamplingCalls: z.number().int().min(1).max(8).describe("Upper bound on host-model sampling calls for this run. Round one (include + detectors) and round two (excludes) each consume a call, rejected proposals consume retries. A budget of 1 skips round two.").default(4)
+};
+var suggestPresetInputSchema = z.object(suggestPresetInputShape);
+var proposalSchema = z.object({
+	detectors: z.array(z.string().min(1)).min(1).max(6),
+	scope: z.object({
+		include: z.string().min(1),
+		exclude: z.array(z.string().min(1)).max(12).optional()
+	})
+});
+var excludeProposalSchema = z.object({ exclude: z.array(z.string().min(1)).max(12) });
+var MAX_SAMPLING_TOKENS = 1024;
+var SUGGEST_PRESET_TOOL_DESCRIPTION = `Ask the HOST's model to propose a site preset (detectors + selectors) for a page whose extraction was lost, then verify it: proposals are validated deterministically, applied through the real pipeline, and a converged preset is stored in memory and persisted to the local preset cache so later extractions of the same site apply it automatically. Runs a bounded two-round loop over MCP \`sampling/createMessage\` — the server embeds no model. The tool is only listed when the connected client advertises the sampling capability, and it refuses to run when the baseline extraction looks healthy: call it after \`extract\` reports gated content, a fallback extraction, a near-empty result, or visible debris such as video-player controls.`;
+var triggerShape = {
+	fired: z.boolean().describe("Whether the suggest loop ran at all."),
+	reasons: z.array(z.string()).describe("Why the loop ran (the lost signals observed on the baseline extraction), or why it refused."),
+	wordCount: z.number().describe("Word count of the baseline extraction; 0 when the loop never ran."),
+	debrisProbes: z.array(z.string()).describe("Debris signatures matched in the baseline extraction text."),
+	gatedReason: z.string().optional().describe("The gating signal reported by the baseline extraction, if any.")
+};
+var suggestPresetOutputShape = {
+	schemaVersion: z.literal(1).describe("Structured-content schema version."),
+	content: z.string().describe("Human-readable report of the run."),
+	trigger: z.object(triggerShape).describe("Baseline lost-signal verdict."),
+	preset: z.object({
+		site: z.string().describe("The host the preset is keyed by."),
+		detectors: z.array(z.string()).describe("Template fingerprints that must keep matching."),
+		scope: z.object({
+			include: z.string().optional(),
+			exclude: z.array(z.string()).optional()
+		}).describe("The accepted selector scope.")
+	}).optional().describe("The preset that converged, present only when one was accepted and verified."),
+	verification: z.object({
+		applied: z.boolean().describe("Whether the stored preset resolved and applied during the verification extraction."),
+		converged: z.boolean().describe("Whether the verification extraction came back clean."),
+		verifiedPages: z.number().int().min(1).max(2).describe("Pages the preset verified on: 2 only when secondPath was given and the preset verified on that capture too."),
+		wordCountBefore: z.number().describe("Baseline extraction word count."),
+		wordCountAfter: z.number().describe("Verification extraction word count.")
+	}).optional().describe("Result of extracting with the preset actually stored."),
+	secondVerification: z.object({
+		applied: z.boolean().describe("Whether the preset resolved and applied on the second capture."),
+		converged: z.boolean().describe("Whether the second-capture extraction came back clean."),
+		wordCountAfter: z.number().describe("Second-capture extraction word count.")
+	}).optional().describe("Verification on the secondPath capture; absent when secondPath was not given or the capture belongs to another site."),
+	persistence: z.object({
+		persisted: z.boolean().describe("Whether the preset file was written to the local preset cache directory."),
+		path: z.string().optional().describe("The file written, when persisted."),
+		reason: z.string().optional().describe("Why nothing was persisted, when it was not.")
+	}).optional().describe("Outcome of the disk write; absent when the run never accepted a preset."),
+	sampling: z.object({
+		calls: z.number().int().describe("Sampling calls actually made."),
+		budget: z.number().int().describe("The budget this run was given."),
+		budgetExhausted: z.boolean().describe("Whether the budget ran out before the loop could converge.")
+	}).describe("Sampling accounting for this run.")
+};
+function registerSuggestPresetTool(server) {
+	return server.registerTool("suggest_preset", {
+		title: "Suggest a site preset using the host model",
+		description: SUGGEST_PRESET_TOOL_DESCRIPTION,
+		inputSchema: suggestPresetInputShape,
+		outputSchema: suggestPresetOutputShape
+	}, async (rawArgs) => {
+		const args = suggestPresetInputSchema.parse(rawArgs);
+		try {
+			return await runSuggestLoop(args, server);
+		} catch (err) {
+			logger.error(`suggest_preset failed: ${err instanceof Error ? err.message : String(err)}`);
+			return toErrorResult(err);
+		}
+	});
+}
+async function runSuggestLoop(args, server) {
+	const site = normalizeSiteKey(args.baseUrl);
+	if (!site) throw new Error(`baseUrl does not name a site: ${args.baseUrl}`);
+	const html = readHtmlFile(args.localPath);
+	const secondHtml = args.secondPath ? readHtmlFile(args.secondPath) : void 0;
+	const state = {
+		budget: args.maxSamplingCalls,
+		calls: 0,
+		exhausted: false
+	};
+	if (presetForSite(site)) return report(state, { trigger: {
+		debrisProbes: [],
+		fired: false,
+		reasons: ["preset-exists"],
+		wordCount: 0
+	} });
+	const baseline = extractText(html, args.baseUrl);
+	const canonicalSite = normalizeSiteKey(baseline.metadata.canonical);
+	if (canonicalSite && canonicalSite !== site) throw new Error(`baseUrl names ${site} but the page's canonical URL names ${canonicalSite} — the capture does not belong to the site the preset would be keyed by.`);
+	const baselineEvidence = assessLostSignal({
+		contentText: baseline.content,
+		fallbackUsed: baseline.diagnostics.fallbackUsed ?? false,
+		gated: baseline.diagnostics.gated
+	});
+	const trigger = {
+		debrisProbes: baselineEvidence.debrisProbes,
+		fired: baselineEvidence.reasons.length > 0,
+		gatedReason: baselineEvidence.gatedReason,
+		reasons: baselineEvidence.reasons,
+		wordCount: baselineEvidence.wordCount
+	};
+	if (!trigger.fired) return report(state, { trigger });
+	const core = await proposeCore(html, args.baseUrl, site, baseline, trigger, state, server);
+	if (!core) return report(state, { trigger });
+	const excludes = await proposeExcludes(html, args.baseUrl, core, state, server);
+	const preset = {
+		detectors: core.detectors,
+		site,
+		scope: {
+			exclude: excludes.length > 0 ? excludes : void 0,
+			include: core.scope.include
+		}
+	};
+	addPreset({
+		detectors: preset.detectors,
+		scope: preset.scope,
+		site: preset.site
+	});
+	const verification = extractText(html, args.baseUrl);
+	const verificationEvidence = assessLostSignal({
+		contentText: verification.content,
+		fallbackUsed: verification.diagnostics.fallbackUsed ?? false,
+		gated: verification.diagnostics.gated
+	});
+	const applied = verification.presetSignal?.applied === true;
+	const converged = applied && verificationEvidence.reasons.length === 0;
+	const verdict = {
+		applied,
+		converged,
+		verifiedPages: 1,
+		wordCountAfter: verificationEvidence.wordCount,
+		wordCountBefore: trigger.wordCount
+	};
+	if (!converged) {
+		removePreset(preset.site);
+		state.persistence = {
+			persisted: false,
+			reason: "not-converged"
+		};
+		return report(state, {
+			preset,
+			trigger,
+			verification: verdict
+		});
+	}
+	let secondVerification;
+	if (secondHtml) {
+		const second = extractText(secondHtml, args.baseUrl);
+		const secondCanonicalSite = normalizeSiteKey(second.metadata.canonical);
+		if (secondCanonicalSite && secondCanonicalSite !== site) {
+			removePreset(preset.site);
+			state.persistence = {
+				persisted: false,
+				reason: "second-page-canonical-mismatch"
+			};
+			return report(state, {
+				preset,
+				trigger,
+				verification: verdict
+			});
+		}
+		const secondEvidence = assessLostSignal({
+			contentText: second.content,
+			fallbackUsed: second.diagnostics.fallbackUsed ?? false,
+			gated: second.diagnostics.gated
+		});
+		const secondApplied = second.presetSignal?.applied === true;
+		const secondConverged = secondApplied && secondEvidence.reasons.length === 0;
+		secondVerification = {
+			applied: secondApplied,
+			converged: secondConverged,
+			wordCountAfter: secondEvidence.wordCount
+		};
+		if (!secondConverged) {
+			removePreset(preset.site);
+			state.persistence = {
+				persisted: false,
+				reason: "second-page-not-converged"
+			};
+			return report(state, {
+				preset,
+				secondVerification,
+				trigger,
+				verification: verdict
+			});
+		}
+		verdict.verifiedPages = 2;
+	}
+	state.persistence = savePreset(preset);
+	return report(state, {
+		preset,
+		secondVerification,
+		trigger,
+		verification: verdict
+	});
+}
+function report(state, parts) {
+	const lines = [];
+	if (!parts.trigger.fired) lines.push(parts.trigger.reasons.length > 0 ? `No suggest loop run: ${parts.trigger.reasons.join(", ")}.` : `No suggest loop run: the baseline extraction looks healthy (${parts.trigger.wordCount} words, no lost signal).`);
+	else lines.push(`Lost signals on the baseline extraction (${parts.trigger.wordCount} words): ${parts.trigger.reasons.join(", ")}.`);
+	if (state.calls > 0) lines.push(`Sampling: ${state.calls}/${state.budget} call(s)${state.exhausted ? " — budget exhausted" : ""}.`);
+	if (parts.verification) lines.push(`Verification with the preset stored: applied=${parts.verification.applied}, converged=${parts.verification.converged}, ${parts.verification.wordCountAfter} words, pages verified: ${parts.verification.verifiedPages}.`);
+	if (parts.secondVerification) lines.push(`Second-page verification: applied=${parts.secondVerification.applied}, converged=${parts.secondVerification.converged}, ${parts.secondVerification.wordCountAfter} words.`);
+	if (parts.preset) lines.push(`Accepted preset for ${parts.preset.site}: include=${parts.preset.scope.include ?? "(none)"}, exclude=${(parts.preset.scope.exclude ?? []).join(", ") || "(none)"}, detectors=${parts.preset.detectors.join(", ")}.`);
+	if (state.persistence) lines.push(state.persistence.persisted ? `Persisted to ${state.persistence.path}.` : `Not persisted: ${state.persistence.reason}.`);
+	return {
+		content: [{
+			text: lines.join("\n"),
+			type: "text"
+		}],
+		structuredContent: {
+			content: lines.join("\n"),
+			persistence: state.persistence,
+			preset: parts.preset,
+			sampling: {
+				budget: state.budget,
+				budgetExhausted: state.exhausted,
+				calls: state.calls
+			},
+			schemaVersion: 1,
+			secondVerification: parts.secondVerification,
+			trigger: parts.trigger,
+			verification: parts.verification
+		}
+	};
+}
+function coreProposalUserText(site, title, evidence, outline, rejection) {
+	return [
+		`SITE: ${site}`,
+		`PAGE: ${title || "(untitled)"}`,
+		`BASELINE: ${evidence.wordCount} words; debris probes: ${evidence.debrisProbes.join(", ") || "none"}; gating: ${evidence.gatedReason ?? "none"}. The extraction lost to page junk — propose a preset.`,
+		"",
+		"MATERIAL — ancestor chains of every node holding at least 200 chars of its own text, hop format tag#id.classes[attr=\"value\"] (own:X, all:Y):",
+		outline.text,
+		...outline.truncated ? ["(material truncated at the budget — the largest own-text chains come first)"] : [],
+		...rejection ? [
+			"",
+			"YOUR PREVIOUS PROPOSAL WAS REJECTED:",
+			rejection,
+			"Return corrected strict JSON."
+		] : [""],
+		"Return JSON: {\"detectors\": [\"...\"], \"scope\": {\"include\": \"...\", \"exclude\": [\"...\"]}}"
+	].join("\n");
+}
+async function proposeCore(html, baseUrl, site, baseline, evidence, state, server) {
+	const outline = buildChainOutline({
+		baseUrl,
+		cleanChrome: true,
+		html,
+		mode: "page"
+	});
+	let rejection;
+	while (state.calls < state.budget) {
+		state.calls += 1;
+		let reply;
+		try {
+			reply = await sampleJson(server, {
+				maxTokens: MAX_SAMPLING_TOKENS,
+				systemPrompt: SUGGEST_SYSTEM_PROMPT,
+				userText: coreProposalUserText(site, baseline.metadata.title ?? "", evidence, outline, rejection)
+			});
+		} catch (err) {
+			if (err instanceof SuggestParseError) {
+				rejection = err.message;
+				continue;
+			}
+			throw err;
+		}
+		const parsed = proposalSchema.safeParse(reply);
+		if (!parsed.success) {
+			rejection = `the reply must parse as {"detectors": [...], "scope": {"include": "...", "exclude": [...]}} — ${parsed.error.issues[0]?.message}`;
+			continue;
+		}
+		const violations = lintProposal({
+			detectors: parsed.data.detectors,
+			document: normalizedDocument(html, baseUrl),
+			scope: parsed.data.scope
+		});
+		if (violations.length > 0) {
+			rejection = renderViolations(violations);
+			continue;
+		}
+		return {
+			detectors: parsed.data.detectors,
+			scope: {
+				exclude: parsed.data.scope.exclude,
+				include: parsed.data.scope.include
+			}
+		};
+	}
+	state.exhausted = true;
+}
+async function proposeExcludes(html, baseUrl, core, state, server) {
+	if (state.calls >= state.budget) return core.scope.exclude ?? [];
+	const outline = buildChainOutline({
+		baseUrl,
+		cleanChrome: true,
+		html,
+		mode: { scope: { include: core.scope.include } }
+	});
+	let rejection;
+	while (state.calls < state.budget) {
+		state.calls += 1;
+		let reply;
+		try {
+			reply = await sampleJson(server, {
+				maxTokens: MAX_SAMPLING_TOKENS,
+				systemPrompt: SUGGEST_SYSTEM_PROMPT,
+				userText: [
+					`ACCEPTED SO FAR: {"detectors": ${JSON.stringify(core.detectors)}, "scope": {"include": ${JSON.stringify(core.scope.include)}}}`,
+					"",
+					"MATERIAL — text blocks remaining inside the included subtree after the include was applied, grouped by chain, smallest own text first, each with a text sample:",
+					outline.text,
+					...rejection ? [
+						"",
+						"YOUR PREVIOUS PROPOSAL WAS REJECTED:",
+						rejection,
+						"Return corrected strict JSON."
+					] : [""],
+					"Propose excludes for the debris groups (video players, carousels, caption figures, comment blocks, promos) — never for prose paragraphs. Return [] if none. Return JSON: {\"exclude\": [\"...\"]}"
+				].join("\n")
+			});
+		} catch (err) {
+			if (err instanceof SuggestParseError) {
+				rejection = err.message;
+				continue;
+			}
+			throw err;
+		}
+		const parsed = excludeProposalSchema.safeParse(reply);
+		if (!parsed.success) {
+			rejection = `the reply must parse as {"exclude": ["..."]} — ${parsed.error.issues[0]?.message}`;
+			continue;
+		}
+		const violations = lintProposal({
+			detectors: core.detectors,
+			document: normalizedDocument(html, baseUrl),
+			scope: {
+				exclude: parsed.data.exclude,
+				include: core.scope.include
+			}
+		});
+		if (violations.length > 0) {
+			rejection = renderViolations(violations);
+			continue;
+		}
+		const merged = [...core.scope.exclude ?? []];
+		for (const selector of parsed.data.exclude) if (!merged.includes(selector)) merged.push(selector);
+		return merged;
+	}
+	state.exhausted = true;
+	return core.scope.exclude ?? [];
+}
+function renderViolations(violations) {
+	return violations.map((violation) => `- ${violation.kind}: ${violation.selector} — ${violation.detail}`).join("\n");
+}
+function normalizedDocument(html, baseUrl) {
+	const { document } = buildDocument(html, baseUrl);
+	normalizeDocument(document, { cleanChrome: true });
+	resolveLazyImages(document);
+	return document;
+}
+function extractText(html, baseUrl) {
+	const result = extractArticleFromHtml({
+		baseUrl,
+		cache: false,
+		format: "text",
+		html
+	});
+	if (result.isError || !result.structuredContent) throw new Error("extraction failed inside the suggest loop");
+	const structured = result.structuredContent;
+	return {
+		content: structured.content,
+		diagnostics: {
+			fallbackUsed: structured.diagnostics.fallbackUsed,
+			gated: structured.diagnostics.gated
+		},
+		metadata: structured.metadata,
+		presetSignal: structured.diagnostics.preset
+	};
+}
+//#endregion
 //#region src/sampling.ts
 var SUMMARIZE_SYSTEM_PROMPT = "Summarize the user-supplied text concisely while preserving its key points, entities, and any decisive conclusions. Output only the summary prose — no preamble, no headings unless the source had them.";
 var summarizeInputShape = {
@@ -13,19 +871,11 @@ var summarizeInputShape = {
 var summarizeInputSchema = z.object(summarizeInputShape);
 var SUMMARIZE_TOOL_DESCRIPTION = `Summarize text using the HOST's model via MCP \`sampling/createMessage\` — the server embeds no model and calls no provider directly. Hand it the output of \`extract\`, \`extract_section\`, \`html_to_markdown\`, or any markdown/text string; the host picks the model and may ask the user to approve the sampling request (human-in-the-loop per MCP). The tool is only listed when the connected client advertises the sampling capability.`;
 async function summarizeWithHost(server, args) {
-	const result = await server.server.createMessage({
-		messages: [{
-			role: "user",
-			content: {
-				type: "text",
-				text: args.text
-			}
-		}],
+	return sampleText$1(server, {
+		maxTokens: args.maxTokens,
 		systemPrompt: SUMMARIZE_SYSTEM_PROMPT,
-		maxTokens: args.maxTokens
+		userText: args.text
 	});
-	if (result.content.type !== "text") throw new Error(`host sampling returned non-text content (${result.content.type}); summarize expects a text response`);
-	return result.content.text;
 }
 function registerSummarizeTool(server) {
 	return server.registerTool("summarize", {
@@ -46,7 +896,7 @@ function registerSummarizeTool(server) {
 	});
 }
 function registerSamplingTools(server) {
-	return [registerSummarizeTool(server)];
+	return [registerSummarizeTool(server), registerSuggestPresetTool(server)];
 }
 //#endregion
 //#region src/tools/chunk_text.ts
@@ -1078,7 +1928,8 @@ function extractSectionFromHtml(input) {
 	if (selector !== void 0) return extractArticleFromHtml({
 		html,
 		baseUrl,
-		selectors: { include: selector }
+		selectors: { include: selector },
+		resolvePreset: false
 	});
 	if (heading === void 0) throw new ExtractionError("Provide exactly one of `selector` or `heading`.");
 	const { document } = buildDocument(html, baseUrl);
@@ -1088,7 +1939,8 @@ function extractSectionFromHtml(input) {
 	return extractArticleFromHtml({
 		html: scoped,
 		baseUrl,
-		selectors: { include: SECTION_SCOPE_SELECTOR }
+		selectors: { include: SECTION_SCOPE_SELECTOR },
+		resolvePreset: false
 	});
 }
 var EXTRACT_SECTION_TOOL_DESCRIPTION = `Extract one section of an already-rendered (post-JavaScript) HTML document and return its Markdown + metadata + diagnostics — a thin resolver over extract’s \`selectors.include\` path, not a new extractor. Pick the section by CSS \`selector\` (passed straight through) OR by \`heading\` text (case-insensitive, first match wins; the section spans from the matched heading to the next same-or-higher-level heading). Exactly one of \`selector\`/\`heading\` is required. The server fetches nothing: \`localPath\` is the only source, and \`baseUrl\` (optional) is origin context only (never fetched).`;
@@ -1392,6 +2244,7 @@ function registerCapabilityGatedTools(server) {
 }
 function createServer() {
 	const server = createMcpServer();
+	loadPresets();
 	registerTools(server);
 	registerResources(server);
 	server.server.oninitialized = () => {
@@ -1401,7 +2254,7 @@ function createServer() {
 }
 //#endregion
 //#region src/index.ts
-if (process.argv[2] === "extract") import("./assets/cli-C4RkP1lV.js").then((m) => m.runCli(process.argv.slice(2))).then((code) => {
+if (process.argv[2] === "extract") import("./assets/cli-CQl4_iKO.js").then((m) => m.runCli(process.argv.slice(2))).then((code) => {
 	process.exit(code);
 }).catch((err) => {
 	process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);