@v1nvn/readability 0.44.0 → 0.45.1

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.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_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,
+  );
+}

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_metadata.ts

@@ -0,0 +1,102 @@
+import type { Metadata } from '../pipeline/context.ts';
+import type { ToolHandle } from '../server.ts';
+
+import { tool } from '../handler.ts';
+import { buildDocument } from '../pipeline/dom.ts';
+import { normalizeDocument } from '../pipeline/normalize.ts';
+import { resolveMetadata } from '../policy/metadata.ts';
+import { fromLocalPath } from './html-source.ts';
+import { extractMetadataOutputShape } from './output-schema.ts';
+import {
+  type ExtractMetadataFromHtmlInput,
+  extractMetadataInputSchema,
+  extractMetadataInputShape,
+} from './schemas.ts';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.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',
+] as const satisfies readonly (keyof Metadata)[];
+
+function pickBibliographic(
+  metadata: Readonly<Metadata>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  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: Readonly<Record<string, string>>,
+): string {
+  const lines = Object.entries(metadata).map(
+    ([key, value]) => `${key}: ${value}`,
+  );
+  return lines.length > 0 ? lines.join('\n') : '(no metadata found)';
+}
+
+export function extractMetadataDocumentFromHtml(
+  input: Readonly<ExtractMetadataFromHtmlInput>,
+): CallToolResult {
+  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: McpServer): ToolHandle {
+  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_section.ts

@@ -0,0 +1,84 @@
+import type { ToolHandle } from '../server.ts';
+
+import { ExtractionError } from '../errors.ts';
+import { tool } from '../handler.ts';
+import { buildDocument } from '../pipeline/dom.ts';
+import { normalizeDocument } from '../pipeline/normalize.ts';
+import { scopeToHeading } from '../policy/section.ts';
+import { extractArticleFromHtml } from './extract.ts';
+import { fromLocalPath } from './html-source.ts';
+import { outputSchemaShape } from './output-schema.ts';
+import {
+  type ExtractSectionFromHtmlInput,
+  extractSectionInputSchema,
+  extractSectionInputShape,
+} from './schemas.ts';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+const SECTION_SCOPE_SELECTOR = '[data-rdrm-section-scope]';
+
+export function extractSectionFromHtml(
+  input: Readonly<ExtractSectionFromHtmlInput>,
+): CallToolResult {
+  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: McpServer): ToolHandle {
+  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);
+}