@v1nvn/readability 0.43.0 → 0.45.0

package/src/tools/extract.ts

@@ -0,0 +1,368 @@
+import type { SanitizationDiagnostics } from '../pipeline/context.ts';
+import type { ToolHandle } from '../server.ts';
+
+import { ExtractionError } from '../errors.ts';
+import { tool } from '../handler.ts';
+import { logger } from '../logger.ts';
+import { formatPayload } from '../output/format.ts';
+import { buildDocument } from '../pipeline/dom.ts';
+import {
+  applySelectors,
+  canonicalizeCodeBlocks,
+  normalizeDocument,
+  resolveLazyImages,
+} from '../pipeline/normalize.ts';
+import { isReaderable, parseArticle } from '../pipeline/readability.ts';
+import { resolveReadabilityOptions } from '../pipeline/resolver.ts';
+import { sanitizeHtml } from '../pipeline/sanitize.ts';
+import { toMarkdown } from '../pipeline/turndown.ts';
+import { chunkMarkdown } from '../policy/chunk.ts';
+import { assembleDiagnostics, TraceCollector } from '../policy/diagnostics.ts';
+import { extractViaFallback } from '../policy/fallback.ts';
+import { detectGating } from '../policy/gating.ts';
+import { collectImageInventory } from '../policy/images.ts';
+import { resolveMetadata } from '../policy/metadata.ts';
+import { detectPagination } from '../policy/pagination.ts';
+import { resolvePreset } from '../policy/presets.ts';
+import { computeTextMetrics } from '../policy/text.ts';
+import { truncateMarkdown } from '../policy/truncate.ts';
+import * as cache from '../resources.ts';
+import { fromLocalPath, withSchemaDefaults } from './html-source.ts';
+import { outputSchemaShape } from './output-schema.ts';
+import {
+  type ExtractFromHtmlInput,
+  extractInputSchema,
+  extractInputShape,
+} from './schemas.ts';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+// Names the extraction path, not a DOM tag — Readability doesn't expose the source node.
+const EXTRACTED_NODE = 'readability';
+
+export function extractArticle(rawArgs: unknown): CallToolResult {
+  return extractArticleFromHtml(
+    fromLocalPath(extractInputSchema.parse(rawArgs)),
+  );
+}
+
+// Internal worker option, never in the zod schema: the only caller that turns
+// preset resolution off is extract_section, whose re-serialized subtree document
+// carries none of the site fingerprints a preset validates against.
+export interface ExtractWorkerInput extends ExtractFromHtmlInput {
+  readonly resolvePreset?: boolean;
+}
+
+export function extractArticleFromHtml(
+  input: Readonly<ExtractWorkerInput>,
+): CallToolResult {
+  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),
+      ) as {
+        [key: string]: unknown;
+        diagnostics: Record<string, unknown>;
+      };
+      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: string;
+  let sanitizedHtml: string;
+  let textContent: string;
+  let extractedNode: string;
+  let fallbackUsed: boolean;
+  let sanitizeCounts: SanitizationDiagnostics;
+
+  if (article?.content) {
+    extractedNode = EXTRACTED_NODE;
+    fallbackUsed = false;
+    textContent = article.textContent ?? '';
+    const articleHtml = article.content;
+    const sanitized = trace.run(
+      'sanitize',
+      (): {
+        counts: SanitizationDiagnostics;
+        html: string;
+      } => {
+        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: SanitizationDiagnostics = {
+    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 as const,
+    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: McpServer): ToolHandle {
+  return server.registerTool(
+    'extract',
+    {
+      title: 'Extract article to Markdown',
+      description: EXTRACT_TOOL_DESCRIPTION,
+      inputSchema: extractInputShape,
+      outputSchema: outputSchemaShape,
+    },
+    extractHandler,
+  );
+}

package/src/tools/extract_grid.ts

@@ -0,0 +1,90 @@
+import type { ToolHandle } from '../server.ts';
+
+import { tool } from '../handler.ts';
+import { buildDocument } from '../pipeline/dom.ts';
+import { applySelectors } from '../pipeline/normalize.ts';
+import { renderTable } from '../pipeline/tables.ts';
+import { detectGrid } from '../policy/grid-detector.ts';
+import { fromLocalPath, withSchemaDefaults } from './html-source.ts';
+import { extractGridOutputShape } from './output-schema.ts';
+import {
+  type ExtractGridFromHtmlInput,
+  extractGridInputSchema,
+  extractGridInputShape,
+} from './schemas.ts';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+interface GridEntry {
+  readonly cols: number;
+  readonly markdown: string;
+  readonly rows: number;
+}
+
+const NO_GRID = '(no repeating grid found)';
+
+export function extractGridFromHtml(
+  input: Readonly<ExtractGridFromHtmlInput>,
+): CallToolResult {
+  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: GridEntry = { 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: McpServer): ToolHandle {
+  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.ts

@@ -0,0 +1,138 @@
+import type { ToolHandle } from '../server.ts';
+
+import { tool } from '../handler.ts';
+import { buildDocument } from '../pipeline/dom.ts';
+import { applySelectors } from '../pipeline/normalize.ts';
+import { absolutize } from '../pipeline/urls.ts';
+import { fromLocalPath, withSchemaDefaults } from './html-source.ts';
+import { extractLinksOutputShape } from './output-schema.ts';
+import {
+  type ExtractLinksFromHtmlInput,
+  extractLinksInputSchema,
+  extractLinksInputShape,
+} from './schemas.ts';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+export interface ExtractedLink {
+  readonly href: string;
+  readonly isExternal: boolean;
+  readonly rel: string;
+  readonly text: string;
+}
+
+const MAX_TEXT_LENGTH = 300;
+
+function clipText(raw: string): string {
+  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: URL): boolean {
+  return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+}
+
+function resolveExternal(absolutizedHref: string, baseUrl: string): boolean {
+  let parsedHref: URL;
+  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: Document): void {
+  for (const el of document.querySelectorAll('script, template')) {
+    el.remove();
+  }
+}
+
+export function extractLinksFromHtml(
+  input: Readonly<ExtractLinksFromHtmlInput>,
+): CallToolResult {
+  const { html, baseUrl, sameOriginOnly, selectors } = withSchemaDefaults(
+    extractLinksInputSchema,
+    input,
+  );
+
+  const { document } = buildDocument(html, baseUrl);
+  applySelectors(document, selectors);
+  pruneUnsafeRoots(document);
+
+  const links: ExtractedLink[] = [];
+  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: readonly ExtractedLink[]): string {
+  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: McpServer): ToolHandle {
+  return server.registerTool(
+    'extract_links',
+    {
+      title: 'Extract anchor links',
+      description: EXTRACT_LINKS_TOOL_DESCRIPTION,
+      inputSchema: extractLinksInputShape,
+      outputSchema: extractLinksOutputShape,
+    },
+    extractLinksHandler,
+  );
+}

package/src/tools/extract_list.ts

@@ -0,0 +1,97 @@
+import type { ToolHandle } from '../server.ts';
+
+import { tool } from '../handler.ts';
+import { buildDocument } from '../pipeline/dom.ts';
+import { applySelectors } from '../pipeline/normalize.ts';
+import {
+  detectList,
+  type ListDetectionResult,
+  type ListItem,
+} from '../policy/list-detector.ts';
+import { fromLocalPath } from './html-source.ts';
+import { extractListOutputShape } from './output-schema.ts';
+import {
+  type ExtractListFromHtmlInput,
+  extractListInputSchema,
+  extractListInputShape,
+} from './schemas.ts';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+const NOT_A_LIST = 'not a list: no repeated item structure with links';
+
+function renderItems(result: ListDetectionResult): string {
+  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: ListItem) {
+  return {
+    score: item.score,
+    snippet: item.snippet,
+    title: item.title,
+    url: item.url,
+  };
+}
+
+export function extractListFromHtml(
+  input: Readonly<ExtractListFromHtmlInput>,
+): CallToolResult {
+  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: McpServer): ToolHandle {
+  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,
+  );
+}