@v1nvn/readability 0.45.0 → 0.45.1

package/src/tools/extract.js

@@ -0,0 +1,263 @@
+import { ExtractionError } from "../errors.js";
+import { tool } from "../handler.js";
+import { logger } from "../logger.js";
+import { formatPayload } from "../output/format.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { applySelectors, canonicalizeCodeBlocks, normalizeDocument, resolveLazyImages, } from "../pipeline/normalize.js";
+import { isReaderable, parseArticle } from "../pipeline/readability.js";
+import { resolveReadabilityOptions } from "../pipeline/resolver.js";
+import { sanitizeHtml } from "../pipeline/sanitize.js";
+import { toMarkdown } from "../pipeline/turndown.js";
+import { chunkMarkdown } from "../policy/chunk.js";
+import { assembleDiagnostics, TraceCollector } from "../policy/diagnostics.js";
+import { extractViaFallback } from "../policy/fallback.js";
+import { detectGating } from "../policy/gating.js";
+import { collectImageInventory } from "../policy/images.js";
+import { resolveMetadata } from "../policy/metadata.js";
+import { detectPagination } from "../policy/pagination.js";
+import { resolvePreset } from "../policy/presets.js";
+import { computeTextMetrics } from "../policy/text.js";
+import { truncateMarkdown } from "../policy/truncate.js";
+import * as cache from "../resources.js";
+import { fromLocalPath, withSchemaDefaults } from "./html-source.js";
+import { outputSchemaShape } from "./output-schema.js";
+import { extractInputSchema, extractInputShape, } from "./schemas.js";
+// Names the extraction path, not a DOM tag — Readability doesn't expose the source node.
+const EXTRACTED_NODE = 'readability';
+export function extractArticle(rawArgs) {
+    return extractArticleFromHtml(fromLocalPath(extractInputSchema.parse(rawArgs)));
+}
+export function extractArticleFromHtml(input) {
+    const merged = withSchemaDefaults(extractInputSchema, input);
+    const { html, baseUrl, cache: useCache, selectors, extraction, minArticleLength, maxNodes, keepClasses, readabilityOverrides, format, metadataMode, gfm, headingStyle, codeBlockStyle, images, sanitize: shouldSanitize, maxChars, wordsPerMinute, cleanChrome, tables, chunk, imageInventory, debug, resolvePreset: presetsEnabled = true, } = merged;
+    // Cache hit short-circuits the pipeline. A clone is returned so the cache
+    // field can be overwritten to reflect *this* call's hashes (normalizedHash is
+    // stable across re-renders, but originalHash differs by nonce/CSP/…).
+    if (useCache) {
+        const hit = cache.lookup(html, merged);
+        if (hit) {
+            const cloned = JSON.parse(JSON.stringify(hit.entry.structuredContent));
+            const structuredContent = {
+                ...cloned,
+                diagnostics: {
+                    ...cloned.diagnostics,
+                    cache: {
+                        hit: true,
+                        normalizedHash: hit.normalizedHash,
+                        originalHash: hit.originalHash,
+                    },
+                },
+            };
+            return {
+                content: [{ text: hit.entry.contentText, type: 'text' }],
+                structuredContent,
+            };
+        }
+    }
+    // Stages are timed at the orchestrator boundary so they stay non-overlapping
+    // and sum to the pipeline's wall-clock — stripConsent/absolutize live inside
+    // normalize/turndown respectively and aren't carved out as their own stages.
+    const trace = new TraceCollector(debug);
+    const { document, window } = buildDocument(html, baseUrl);
+    // Paywall overlays are stripped by normalizeDocument's stripChrome (a Piano
+    // modal is role="dialog" + full-viewport fixed), so gating must be detected
+    // before normalization. Pagination chrome survives stripChrome and is detected after.
+    const { gating, documentElementCount, normalizeCounts, imagesResolved, pagination, preset, } = trace.run('normalize', () => {
+        const gating = detectGating(document);
+        const documentElementCount = document.querySelectorAll('*').length;
+        const normalizeCounts = normalizeDocument(document, { cleanChrome });
+        const imagesResolved = resolveLazyImages(document);
+        // Detect before applySelectors: a caller's selectors.include could scope the
+        // body and hide pagination chrome, but "more content exists" is still true.
+        const pagination = detectPagination(document, baseUrl);
+        const resolution = presetsEnabled
+            ? resolvePreset(document, baseUrl, selectors !== undefined)
+            : undefined;
+        applySelectors(document, resolution?.scope ?? selectors);
+        const codeBlocksCanonicalized = canonicalizeCodeBlocks(document);
+        if (codeBlocksCanonicalized > 0) {
+            logger.debug(`canonicalized ${codeBlocksCanonicalized} code-block language tag(s)`);
+        }
+        return {
+            documentElementCount,
+            gating,
+            imagesResolved,
+            normalizeCounts,
+            pagination,
+            preset: resolution?.signal,
+        };
+    });
+    const { readerable, article } = trace.run('readability', () => {
+        const readerable = isReaderable(document);
+        const readabilityOptions = resolveReadabilityOptions({
+            extraction,
+            keepClasses,
+            maxNodes,
+            minArticleLength,
+            readabilityOverrides,
+        });
+        const article = parseArticle(document, readabilityOptions);
+        return { article, readerable };
+    });
+    let markdown;
+    let sanitizedHtml;
+    let textContent;
+    let extractedNode;
+    let fallbackUsed;
+    let sanitizeCounts;
+    if (article?.content) {
+        extractedNode = EXTRACTED_NODE;
+        fallbackUsed = false;
+        textContent = article.textContent ?? '';
+        const articleHtml = article.content;
+        const sanitized = trace.run('sanitize', () => {
+            if (!shouldSanitize) {
+                return { counts: { iframes: 0, scripts: 0 }, html: articleHtml };
+            }
+            const res = sanitizeHtml(articleHtml, window);
+            return {
+                counts: { iframes: res.iframesRemoved, scripts: res.scriptsRemoved },
+                html: res.html,
+            };
+        });
+        sanitizedHtml = sanitized.html;
+        sanitizeCounts = sanitized.counts;
+        markdown = trace.run('turndown', () => toMarkdown(sanitizedHtml, {
+            codeBlockStyle,
+            gfm,
+            headingStyle,
+            images,
+            tables,
+            baseUrl,
+        }));
+    }
+    else {
+        // Cascade only on parse failure, not on isProbablyReaderable.
+        // Fallback owns sanitize + turndown internally, so the two stages collapse
+        // into one timed block here — keeping the trace non-overlapping.
+        const fallback = trace.run('fallback', () => extractViaFallback(document, {
+            codeBlockStyle,
+            gfm,
+            headingStyle,
+            images,
+            sanitize: shouldSanitize,
+            tables,
+            baseUrl,
+            window,
+        }));
+        if (!fallback) {
+            throw new ExtractionError('Readability returned no article and the selector cascade yielded no usable content.');
+        }
+        extractedNode = fallback.rootSelector;
+        fallbackUsed = true;
+        markdown = fallback.markdown;
+        sanitizedHtml = fallback.sanitizedHtml;
+        textContent = fallback.textContent;
+        sanitizeCounts = fallback.sanitization;
+    }
+    const { metadata } = trace.run('metadata', () => {
+        const { wordCount, readingTimeMin } = computeTextMetrics(textContent, wordsPerMinute);
+        const metadata = resolveMetadata({
+            document,
+            readability: article,
+            readingTimeMin,
+            textContent,
+            baseUrl,
+            wordCount,
+        });
+        return { metadata };
+    });
+    const sanitization = {
+        iframes: normalizeCounts.iframes + sanitizeCounts.iframes,
+        scripts: normalizeCounts.scripts + sanitizeCounts.scripts,
+    };
+    const baseDiagnostics = assembleDiagnostics({
+        articleHtml: sanitizedHtml,
+        boilerplateRemoved: normalizeCounts.boilerplateRemoved,
+        chromeRemoved: normalizeCounts.chromeRemoved,
+        documentElementCount,
+        extractedNode,
+        fallbackUsed,
+        gated: gating,
+        imagesResolved,
+        pagination,
+        preset,
+        readerable,
+        sanitization,
+        trace: trace.collect(),
+        truncated: false,
+        window,
+    });
+    let payload = formatPayload({
+        diagnostics: baseDiagnostics,
+        format,
+        markdown,
+        metadata,
+        metadataMode,
+        sanitizedHtml,
+        textContent,
+    });
+    let truncated = false;
+    if (maxChars !== undefined && (format === 'markdown' || format === 'text')) {
+        const res = truncateMarkdown(payload, maxChars);
+        payload = res.text;
+        truncated = res.truncated;
+    }
+    const diagnostics = truncated
+        ? { ...baseDiagnostics, truncated }
+        : baseDiagnostics;
+    // Chunk the final payload (post-format, post-truncation) so token counts
+    // reflect what the host sees in content[0].text. HTML/JSON formats carry no
+    // markdown body to slice, so `chunks` stays unset for them.
+    const chunks = chunk && (format === 'markdown' || format === 'text')
+        ? chunkMarkdown(payload, chunk)
+        : undefined;
+    // Runs against sanitizedHtml so the inventory reflects exactly what the host
+    // sees in content[0].text — post-sanitization, post-lazy-resolution.
+    const imageInventoryEntries = imageInventory
+        ? collectImageInventory(sanitizedHtml, window, baseUrl)
+        : undefined;
+    const baseStructuredContent = {
+        schemaVersion: 1,
+        content: payload,
+        metadata,
+        diagnostics,
+        ...(chunks ? { chunks } : {}),
+        ...(imageInventoryEntries ? { images: imageInventoryEntries } : {}),
+    };
+    // On cache miss (when cache:true), persist a cache-agnostic copy so the
+    // stored entry never carries a stale hit/miss verdict, then surface the
+    // signal on the returned object only.
+    let structuredContent = baseStructuredContent;
+    if (useCache) {
+        const stored = cache.storeResult(html, merged, {
+            contentText: payload,
+            structuredContent: baseStructuredContent,
+        });
+        structuredContent = {
+            ...baseStructuredContent,
+            diagnostics: {
+                ...diagnostics,
+                cache: {
+                    hit: false,
+                    normalizedHash: stored.normalizedHash,
+                    originalHash: stored.originalHash,
+                },
+            },
+        };
+    }
+    return {
+        content: [{ text: payload, type: 'text' }],
+        structuredContent,
+    };
+}
+export const EXTRACT_TOOL_DESCRIPTION = `Extract the main article from already-rendered (post-JavaScript) HTML and return clean Markdown plus metadata and diagnostics. The server fetches nothing: \`localPath\` (a file holding the rendered HTML, e.g. \`document.documentElement.outerHTML\` written to disk by a browser/devtools capture) is the only source, and \`baseUrl\` (optional) is used solely to absolutize relative links.`;
+export const extractHandler = tool('extract', extractArticle);
+export function registerExtractTool(server) {
+    return server.registerTool('extract', {
+        title: 'Extract article to Markdown',
+        description: EXTRACT_TOOL_DESCRIPTION,
+        inputSchema: extractInputShape,
+        outputSchema: outputSchemaShape,
+    }, extractHandler);
+}

package/src/tools/extract_grid.js

@@ -0,0 +1,56 @@
+import { tool } from "../handler.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { applySelectors } from "../pipeline/normalize.js";
+import { renderTable } from "../pipeline/tables.js";
+import { detectGrid } from "../policy/grid-detector.js";
+import { fromLocalPath, withSchemaDefaults } from "./html-source.js";
+import { extractGridOutputShape } from "./output-schema.js";
+import { extractGridInputSchema, extractGridInputShape, } from "./schemas.js";
+const NO_GRID = '(no repeating grid found)';
+export function extractGridFromHtml(input) {
+    const { html, baseUrl, format, selectors, rowSelector, cellSelector } = withSchemaDefaults(extractGridInputSchema, input);
+    // Same raw-DOM rationale as extract_tables/extract_list: the repeating grid
+    // lives in statically-rendered divs that Readability/normalize would discard
+    // (nav/aside/boilerplate), and grid shape is unaffected by unsanitized
+    // scripts/styles. Chrome stripping lives inside detectGrid (auto mode only)
+    // so selector mode sees the page as captured.
+    const { document } = buildDocument(html, baseUrl);
+    applySelectors(document, selectors);
+    const result = detectGrid(document, { rowSelector, cellSelector });
+    let content = NO_GRID;
+    let grid = { rows: 0, cols: 0, markdown: '' };
+    if (result.detected && result.rows.length > 0) {
+        const matrix = result.rows.map(row => [...row.cells]);
+        const markdown = renderTable(matrix, format);
+        content = markdown;
+        grid = { rows: result.rowCount, cols: result.colCount, markdown };
+    }
+    return {
+        content: [{ text: content, type: 'text' }],
+        structuredContent: {
+            schemaVersion: 1,
+            content,
+            grid,
+            diagnostics: {
+                confidence: result.confidence,
+                containerSelector: result.containerSelector,
+                detected: result.detected,
+                rowCount: result.rowCount,
+                colCount: result.colCount,
+                rowTag: result.rowTag,
+                note: result.note,
+            },
+            metadata: { baseUrl, format, detected: result.detected },
+        },
+    };
+}
+export const EXTRACT_GRID_TOOL_DESCRIPTION = `Detect and extract a CSS-grid / div "table" from already-rendered (post-JavaScript) HTML — the div equivalent of \`extract_tables\` for SPAs that render data into repeating \`<div>\` rows instead of \`<table>\`. Supports auto-detect (find the container whose direct children form the largest same-shape sibling group of ≥3 rows, each row a set of ≥2 direct element-children) and explicit \`rowSelector\` + \`cellSelector\` selector mode (cells scoped to each row subtree). Renders the matrix through the SAME gfm/csv/json renderer as \`extract_tables\`. Runs no Readability, no Turndown, no sanitization — the server fetches nothing: \`localPath\` is the only source, and \`baseUrl\` (optional) is origin context only.`;
+export const extractGridHandler = tool('extract_grid', input => extractGridFromHtml(fromLocalPath(input)), extractGridInputSchema);
+export function registerExtractGridTool(server) {
+    return server.registerTool('extract_grid', {
+        title: 'Extract a CSS-grid / div table (the div equivalent of extract_tables)',
+        description: EXTRACT_GRID_TOOL_DESCRIPTION,
+        inputSchema: extractGridInputShape,
+        outputSchema: extractGridOutputShape,
+    }, extractGridHandler);
+}

package/src/tools/extract_links.js

@@ -0,0 +1,98 @@
+import { tool } from "../handler.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { applySelectors } from "../pipeline/normalize.js";
+import { absolutize } from "../pipeline/urls.js";
+import { fromLocalPath, withSchemaDefaults } from "./html-source.js";
+import { extractLinksOutputShape } from "./output-schema.js";
+import { extractLinksInputSchema, extractLinksInputShape, } from "./schemas.js";
+const MAX_TEXT_LENGTH = 300;
+function clipText(raw) {
+    const collapsed = raw.replace(/\s+/g, ' ').trim();
+    return collapsed.length > MAX_TEXT_LENGTH
+        ? `${collapsed.slice(0, MAX_TEXT_LENGTH)}…`
+        : collapsed;
+}
+// Non-http(s) schemes (mailto/tel/javascript/data) have an opaque origin and
+// would otherwise compare as "different" — treat them as non-external so the
+// isExternal flag tracks real cross-origin navigation only.
+function isWebOrigin(parsed) {
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+}
+function resolveExternal(absolutizedHref, baseUrl) {
+    let parsedHref;
+    try {
+        parsedHref = new URL(absolutizedHref);
+    }
+    catch {
+        return false;
+    }
+    if (!isWebOrigin(parsedHref)) {
+        return false;
+    }
+    try {
+        return new URL(baseUrl).origin !== parsedHref.origin;
+    }
+    catch {
+        return false;
+    }
+}
+// Drop <script>/<template> for safety (templates never render, scripts carry no
+// crawl value), but keep nav/footer/main — crawl-relevant links live there.
+function pruneUnsafeRoots(document) {
+    for (const el of document.querySelectorAll('script, template')) {
+        el.remove();
+    }
+}
+export function extractLinksFromHtml(input) {
+    const { html, baseUrl, sameOriginOnly, selectors } = withSchemaDefaults(extractLinksInputSchema, input);
+    const { document } = buildDocument(html, baseUrl);
+    applySelectors(document, selectors);
+    pruneUnsafeRoots(document);
+    const links = [];
+    for (const anchor of document.querySelectorAll('a')) {
+        const rawHref = anchor.getAttribute('href');
+        if (!rawHref) {
+            continue;
+        }
+        const href = absolutize(rawHref, baseUrl);
+        const isExternal = baseUrl ? resolveExternal(href, baseUrl) : false;
+        if (sameOriginOnly && isExternal) {
+            continue;
+        }
+        links.push({
+            text: clipText(anchor.textContent),
+            href,
+            rel: anchor.getAttribute('rel') ?? '',
+            isExternal,
+        });
+    }
+    const content = renderLinksIndex(links);
+    return {
+        content: [{ text: content, type: 'text' }],
+        structuredContent: {
+            schemaVersion: 1,
+            content,
+            links,
+            metadata: { baseUrl },
+        },
+    };
+}
+// One `- [text](href)` line per link; never blank so content[0].text is scannable.
+function renderLinksIndex(links) {
+    if (links.length === 0) {
+        return '(no links found)';
+    }
+    return links
+        .map(link => `- [${link.text || '(no text)'}](${link.href})`)
+        .join('\n');
+}
+export const EXTRACT_LINKS_TOOL_DESCRIPTION = `Return a structured list of anchor links from already-rendered (post-JavaScript) HTML — \`[{text, href, rel, isExternal}]\` in document order, hrefs absolutized against \`baseUrl\`. No Readability scoring, Turndown, or sanitization — links are gathered from the raw parsed DOM so nav/footer/main links survive. Pairs with chrome-devtools for crawl/navigation decisions. The server fetches nothing: \`localPath\` is the only source, and \`baseUrl\` is origin context only (never fetched).`;
+export const extractLinksHandler = tool('extract_links', input => extractLinksFromHtml(fromLocalPath(input)), extractLinksInputSchema);
+export function registerExtractLinksTool(server) {
+    return server.registerTool('extract_links', {
+        title: 'Extract anchor links',
+        description: EXTRACT_LINKS_TOOL_DESCRIPTION,
+        inputSchema: extractLinksInputShape,
+        outputSchema: extractLinksOutputShape,
+    }, extractLinksHandler);
+}

package/src/tools/extract_list.js

@@ -0,0 +1,66 @@
+import { tool } from "../handler.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { applySelectors } from "../pipeline/normalize.js";
+import { detectList, } from "../policy/list-detector.js";
+import { fromLocalPath } from "./html-source.js";
+import { extractListOutputShape } from "./output-schema.js";
+import { extractListInputSchema, extractListInputShape, } from "./schemas.js";
+const NOT_A_LIST = 'not a list: no repeated item structure with links';
+function renderItems(result) {
+    if (!result.detected || result.items.length === 0) {
+        return result.note || NOT_A_LIST;
+    }
+    return result.items
+        .map((item, index) => {
+        const head = `${index + 1}. ${item.title} — ${item.url}`;
+        return item.snippet ? `${head}\n   ${item.snippet}` : head;
+    })
+        .join('\n');
+}
+function toStructuredItem(item) {
+    return {
+        score: item.score,
+        snippet: item.snippet,
+        title: item.title,
+        url: item.url,
+    };
+}
+export function extractListFromHtml(input) {
+    const { html, baseUrl, selectors } = input;
+    // No Readability/Turndown/normalize: list pages survive on raw DOM shape
+    // (sibling TR/LI/ARTICLE clusters), and the article normalizer would
+    // discard the very chrome-bearing structure the detector scores against.
+    // Chrome stripping (nav/header/footer/aside) lives inside detectList so
+    // this tool sees the page as captured.
+    const { document } = buildDocument(html, baseUrl);
+    applySelectors(document, selectors);
+    const result = detectList(document, baseUrl);
+    const content = renderItems(result);
+    return {
+        content: [{ text: content, type: 'text' }],
+        structuredContent: {
+            schemaVersion: 1,
+            content,
+            items: result.items.map(toStructuredItem),
+            diagnostics: {
+                confidence: result.confidence,
+                containerSelector: result.containerSelector,
+                detected: result.detected,
+                itemCount: result.itemCount,
+                itemTag: result.itemTag,
+                note: result.note,
+            },
+            metadata: { baseUrl },
+        },
+    };
+}
+export const EXTRACT_LIST_TOOL_DESCRIPTION = `Detect and extract a list/feed/index structure from already-rendered (post-JavaScript) HTML — for HN-style, search-result, and blog-index pages that Readability cannot turn into one article. Returns \`{items: [{title, url, snippet, score}], diagnostics}\` instead of one article. Strips nav/header/footer/aside + ARIA chrome roles first (the false-positive guard so an article's nav menu doesn't look like a 4-item feed), then finds the container whose direct children form a same-shape sibling cluster of ≥3 elements each carrying a navigation anchor, and the cluster with the most items wins. No Readability, no Turndown, no sanitization. The server fetches nothing: \`localPath\` is the only source, and \`baseUrl\` (optional) is origin context for absolutizing item hrefs.`;
+export const extractListHandler = tool('extract_list', input => extractListFromHtml(fromLocalPath(input)), extractListInputSchema);
+export function registerExtractListTool(server) {
+    return server.registerTool('extract_list', {
+        title: 'Extract a list/feed (HN/search/blog-index pages)',
+        description: EXTRACT_LIST_TOOL_DESCRIPTION,
+        inputSchema: extractListInputShape,
+        outputSchema: extractListOutputShape,
+    }, extractListHandler);
+}

package/src/tools/extract_metadata.js

@@ -0,0 +1,67 @@
+import { tool } from "../handler.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { normalizeDocument } from "../pipeline/normalize.js";
+import { resolveMetadata } from "../policy/metadata.js";
+import { fromLocalPath } from "./html-source.js";
+import { extractMetadataOutputShape } from "./output-schema.js";
+import { extractMetadataInputSchema, extractMetadataInputShape, } from "./schemas.js";
+// Bibliographic fields only — wordCount/readingTimeMin/tokenEstimate are
+// meaningless without the extracted body, so a metadata-only caller never
+// sees wordCount: 0.
+const BIBLIOGRAPHIC_KEYS = [
+    'title',
+    'byline',
+    'siteName',
+    'lang',
+    'publishedTime',
+    'excerpt',
+    'canonical',
+    'baseUrl',
+];
+function pickBibliographic(metadata) {
+    const out = {};
+    for (const key of BIBLIOGRAPHIC_KEYS) {
+        const value = metadata[key];
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+// One line per present field; never blank so content[0].text is always scannable.
+function renderMetadataLines(metadata) {
+    const lines = Object.entries(metadata).map(([key, value]) => `${key}: ${value}`);
+    return lines.length > 0 ? lines.join('\n') : '(no metadata found)';
+}
+export function extractMetadataDocumentFromHtml(input) {
+    const { html, baseUrl } = input;
+    const { document } = buildDocument(html, baseUrl);
+    normalizeDocument(document);
+    const resolved = resolveMetadata({
+        document,
+        textContent: '',
+        wordCount: 0,
+        readingTimeMin: 0,
+        baseUrl,
+    });
+    const metadata = pickBibliographic(resolved);
+    const content = renderMetadataLines(metadata);
+    return {
+        content: [{ text: content, type: 'text' }],
+        structuredContent: {
+            schemaVersion: 1,
+            content,
+            metadata,
+        },
+    };
+}
+export const EXTRACT_METADATA_TOOL_DESCRIPTION = `Return only the bibliographic metadata (title, byline, siteName, lang, publishedTime, excerpt, canonical, baseUrl) of already-rendered (post-JavaScript) HTML without running Readability/Turndown — a fast pre-check for crawlers and citation. Resolves the same metadata cascade as \`extract\` (JSON-LD → OpenGraph → Twitter → <meta> → <time> → <title>), plus <link rel="canonical"> → og:url. The server fetches nothing: \`localPath\` is the only source, and \`baseUrl\` is origin context only (never fetched).`;
+export const extractMetadataHandler = tool('extract_metadata', input => extractMetadataDocumentFromHtml(fromLocalPath(input)), extractMetadataInputSchema);
+export function registerExtractMetadataTool(server) {
+    return server.registerTool('extract_metadata', {
+        title: 'Extract metadata only (no Readability)',
+        description: EXTRACT_METADATA_TOOL_DESCRIPTION,
+        inputSchema: extractMetadataInputShape,
+        outputSchema: extractMetadataOutputShape,
+    }, extractMetadataHandler);
+}

package/src/tools/extract_section.js

@@ -0,0 +1,56 @@
+import { ExtractionError } from "../errors.js";
+import { tool } from "../handler.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { normalizeDocument } from "../pipeline/normalize.js";
+import { scopeToHeading } from "../policy/section.js";
+import { extractArticleFromHtml } from "./extract.js";
+import { fromLocalPath } from "./html-source.js";
+import { outputSchemaShape } from "./output-schema.js";
+import { extractSectionInputSchema, extractSectionInputShape, } from "./schemas.js";
+const SECTION_SCOPE_SELECTOR = '[data-rdrm-section-scope]';
+export function extractSectionFromHtml(input) {
+    const { html, baseUrl, selector, heading } = input;
+    if (selector !== undefined) {
+        return extractArticleFromHtml({
+            html,
+            baseUrl,
+            selectors: { include: selector },
+            resolvePreset: false,
+        });
+    }
+    // The superRefine on the schema enforces selector/heading XOR, so reaching
+    // here means heading is set — but its declared type is still optional, so
+    // narrow explicitly rather than asserting.
+    if (heading === undefined) {
+        throw new ExtractionError('Provide exactly one of `selector` or `heading`.');
+    }
+    // Heading mode: wrap the matched subtree, re-serialize, and route through
+    // extractArticleFromHtml's selectors.include so this tool stays a thin
+    // resolver over the existing extraction pipeline — no forked extraction logic.
+    // The DOM is parsed+normalized twice: here to scope against a normalized
+    // DOM, and again inside the extract worker — which owns detectGating-before-
+    // normalize, resolveLazyImages, and applySelectors. Folding scoping into
+    // that pipeline would breach its invariants for a non-hot path; accepted.
+    const { document } = buildDocument(html, baseUrl);
+    normalizeDocument(document);
+    if (!scopeToHeading(document, heading)) {
+        throw new ExtractionError(`no heading matched: ${heading}`);
+    }
+    const scoped = `<!DOCTYPE html><html><head></head><body>${document.body.innerHTML}</body></html>`;
+    return extractArticleFromHtml({
+        html: scoped,
+        baseUrl,
+        selectors: { include: SECTION_SCOPE_SELECTOR },
+        resolvePreset: false,
+    });
+}
+export const 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).`;
+export const extractSectionHandler = tool('extract_section', input => extractSectionFromHtml(fromLocalPath(input)), extractSectionInputSchema);
+export function registerExtractSectionTool(server) {
+    return server.registerTool('extract_section', {
+        title: 'Extract one section by selector or heading',
+        description: EXTRACT_SECTION_TOOL_DESCRIPTION,
+        inputSchema: extractSectionInputShape,
+        outputSchema: outputSchemaShape,
+    }, extractSectionHandler);
+}

package/src/tools/extract_tables.js

@@ -0,0 +1,59 @@
+import { tool } from "../handler.js";
+import { buildDocument } from "../pipeline/dom.js";
+import { applySelectors } from "../pipeline/normalize.js";
+import { parseTableMatrix, renderTable, resolveHeaderKeys, } from "../pipeline/tables.js";
+import { fromLocalPath, withSchemaDefaults } from "./html-source.js";
+import { extractTablesOutputShape } from "./output-schema.js";
+import { extractTablesInputSchema, extractTablesInputShape, } from "./schemas.js";
+const NO_TABLES = '(no tables found)';
+export function extractTables(rawArgs) {
+    return extractTablesFromHtml(fromLocalPath(extractTablesInputSchema.parse(rawArgs)));
+}
+export function extractTablesFromHtml(input) {
+    const { html, baseUrl, format, selectors } = withSchemaDefaults(extractTablesInputSchema, input);
+    // Skip normalizeDocument/Readability on purpose: this tool exists to reach
+    // tables that live outside the scored article (nav, aside, boilerplate), which
+    // those stages would discard. Table structure is static HTML, so the matrix
+    // walk is unaffected by unsanitized scripts/styles.
+    const { document } = buildDocument(html, baseUrl);
+    applySelectors(document, selectors);
+    const tables = [];
+    let index = 0;
+    for (const table of document.querySelectorAll('table')) {
+        const matrix = parseTableMatrix(table);
+        if (matrix.length === 0) {
+            continue;
+        }
+        const keys = format === 'json' ? resolveHeaderKeys(table, matrix) : undefined;
+        const markdown = renderTable(matrix, format, keys);
+        tables.push({
+            index,
+            rows: matrix.length,
+            cols: matrix[0]?.length ?? 0,
+            markdown,
+        });
+        index++;
+    }
+    const content = tables.length > 0
+        ? tables.map(entry => entry.markdown).join('\n\n')
+        : NO_TABLES;
+    return {
+        content: [{ text: content, type: 'text' }],
+        structuredContent: {
+            schemaVersion: 1,
+            content,
+            tables,
+            metadata: { baseUrl, format, tableCount: tables.length },
+        },
+    };
+}
+export const EXTRACT_TABLES_TOOL_DESCRIPTION = `Extract every <table> on the page from already-rendered (post-JavaScript) HTML and return each as GFM / CSV / JSON (caller picks). Runs no Readability, Turndown, or sanitization — a page-wide \`querySelectorAll('table')\` walk in front of the same rowspan/colspan-aware matrix serializer used by the \`tables\` option on \`extract\`. Captures tables outside the article body (nav, aside, boilerplate) that the \`tables\` option never sees. The server fetches nothing: \`localPath\` is the only source, and \`baseUrl\` (optional) is origin context only (never fetched).`;
+export const extractTablesHandler = tool('extract_tables', extractTables);
+export function registerExtractTablesTool(server) {
+    return server.registerTool('extract_tables', {
+        title: 'Extract every table on the page',
+        description: EXTRACT_TABLES_TOOL_DESCRIPTION,
+        inputSchema: extractTablesInputShape,
+        outputSchema: extractTablesOutputShape,
+    }, extractTablesHandler);
+}