nodebench-mcp 2.6.0 → 2.8.1

package/dist/tools/localFileTools.js

@@ -10,6 +10,7 @@
  * - xlsx: XLSX parsing
  * - papaparse: CSV parsing
  * - pdf-parse: PDF text extraction (page-aware)
+ * - yauzl: ZIP/DOCX/PPTX parsing
  */
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -50,6 +51,117 @@ function truncateCell(value, maxChars) {
         return s;
     return s.slice(0, maxChars) + "...";
 }
+function toText(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
+function toNumberOrNull(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    const s = toText(value).trim();
+    if (!s)
+        return null;
+    // Strip common formatting (currency, thousands separators, %). Keep digits/sign/decimal/exponent.
+    const cleaned = s.replace(/[, $£€¥%]/g, "").replace(/[^\d.+\-eE]/g, "");
+    const n = Number.parseFloat(cleaned);
+    return Number.isFinite(n) ? n : null;
+}
+function resolveColumnIndex(headers, column) {
+    if (typeof column === "number" && Number.isFinite(column)) {
+        const idx = Math.trunc(column);
+        return idx >= 0 && idx < headers.length ? idx : -1;
+    }
+    const name = String(column ?? "").trim();
+    if (!name)
+        return -1;
+    const needle = name.toLowerCase();
+    return headers.findIndex((h) => String(h ?? "").trim().toLowerCase() === needle);
+}
+function compileWhere(headers, whereRaw) {
+    if (!Array.isArray(whereRaw))
+        return [];
+    const out = [];
+    for (const raw of whereRaw) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const obj = raw;
+        const column = obj.column;
+        const op = String(obj.op ?? "").trim();
+        if (!op)
+            continue;
+        const columnIndex = resolveColumnIndex(headers, column);
+        if (columnIndex < 0)
+            continue;
+        out.push({
+            columnIndex,
+            op,
+            value: obj.value ?? null,
+            caseSensitive: obj.caseSensitive === true,
+        });
+    }
+    return out;
+}
+function rowMatchesWhere(row, where) {
+    if (where.length === 0)
+        return true;
+    for (const clause of where) {
+        const cell = row[clause.columnIndex];
+        if (clause.op === "is_empty") {
+            const s = toText(cell).trim();
+            if (s.length !== 0)
+                return false;
+            continue;
+        }
+        if (clause.op === "not_empty") {
+            const s = toText(cell).trim();
+            if (s.length === 0)
+                return false;
+            continue;
+        }
+        if (clause.op === "contains") {
+            const hay = clause.caseSensitive ? toText(cell) : toText(cell).toLowerCase();
+            const needle = clause.caseSensitive ? toText(clause.value) : toText(clause.value).toLowerCase();
+            if (!hay.includes(needle))
+                return false;
+            continue;
+        }
+        if (clause.op === "eq" || clause.op === "ne") {
+            const a = clause.caseSensitive ? toText(cell).trim() : toText(cell).trim().toLowerCase();
+            const b = clause.caseSensitive
+                ? toText(clause.value).trim()
+                : toText(clause.value).trim().toLowerCase();
+            const ok = a === b;
+            if (clause.op === "eq" && !ok)
+                return false;
+            if (clause.op === "ne" && ok)
+                return false;
+            continue;
+        }
+        // Numeric comparisons.
+        const n = toNumberOrNull(cell);
+        const v = toNumberOrNull(clause.value);
+        if (n === null || v === null)
+            return false;
+        if (clause.op === "gt" && !(n > v))
+            return false;
+        if (clause.op === "gte" && !(n >= v))
+            return false;
+        if (clause.op === "lt" && !(n < v))
+            return false;
+        if (clause.op === "lte" && !(n <= v))
+            return false;
+    }
+    return true;
+}
 async function getXlsx() {
     try {
         const mod = await import("xlsx");
@@ -76,6 +188,389 @@ async function getPdfParseModule() {
         throw new Error("Missing optional dependency: pdf-parse. Install it (or run npm install in packages/mcp-local) to use PDF parsing.");
     }
 }
+async function getYauzl() {
+    try {
+        const mod = await import("yauzl");
+        return mod.default ?? mod;
+    }
+    catch {
+        throw new Error("Missing optional dependency: yauzl. Install it (or run npm install in packages/mcp-local) to use ZIP/DOCX/PPTX parsing.");
+    }
+}
+function decodeXmlEntities(text) {
+    return text
+        .replace(/&quot;/g, "\"")
+        .replace(/&apos;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&")
+        .replace(/&#(x?[0-9a-fA-F]+);/g, (_m, raw) => {
+        const isHex = String(raw).toLowerCase().startsWith("x");
+        const n = Number.parseInt(isHex ? String(raw).slice(1) : String(raw), isHex ? 16 : 10);
+        if (!Number.isFinite(n))
+            return _m;
+        try {
+            return String.fromCodePoint(n);
+        }
+        catch {
+            return _m;
+        }
+    });
+}
+function safeJoinInsideDir(baseDir, unsafeRelative) {
+    const rel = String(unsafeRelative ?? "")
+        .replace(/\\/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/^\/+/, "");
+    const normalized = path.posix.normalize(rel);
+    if (normalized === "." || normalized === "") {
+        throw new Error("innerPath resolved to empty path");
+    }
+    if (normalized.startsWith("../") || normalized === "..") {
+        throw new Error(`Refusing zip-slip path: ${unsafeRelative}`);
+    }
+    if (/[A-Za-z]:/.test(normalized)) {
+        throw new Error(`Refusing drive-qualified path: ${unsafeRelative}`);
+    }
+    const out = path.resolve(baseDir, normalized.replace(/\//g, path.sep));
+    const baseResolved = path.resolve(baseDir);
+    if (!out.startsWith(baseResolved + path.sep) && out !== baseResolved) {
+        throw new Error("Resolved path escapes outputDir");
+    }
+    return out;
+}
+async function zipListEntries(zipPath, maxEntries) {
+    const yauzl = await getYauzl();
+    return await new Promise((resolve, reject) => {
+        yauzl.open(zipPath, { lazyEntries: true, autoClose: true }, (err, zipfile) => {
+            if (err || !zipfile)
+                return reject(err ?? new Error("Failed to open zip"));
+            const entries = [];
+            let done = false;
+            let truncated = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                try {
+                    zipfile.close();
+                }
+                catch {
+                    // ignore
+                }
+                resolve({ entries, truncated });
+            };
+            zipfile.on("error", (e) => {
+                if (done)
+                    return;
+                done = true;
+                reject(e);
+            });
+            zipfile.on("end", finish);
+            zipfile.readEntry();
+            zipfile.on("entry", (entry) => {
+                if (done)
+                    return;
+                if (entries.length >= maxEntries) {
+                    truncated = true;
+                    finish();
+                    return;
+                }
+                const name = String(entry.fileName ?? "");
+                const isDirectory = name.endsWith("/");
+                entries.push({
+                    fileName: name,
+                    uncompressedSize: Number(entry.uncompressedSize ?? 0),
+                    compressedSize: Number(entry.compressedSize ?? 0),
+                    isDirectory,
+                    crc32: typeof entry.crc32 === "number" ? entry.crc32 : undefined,
+                    compressionMethod: typeof entry.compressionMethod === "number" ? entry.compressionMethod : undefined,
+                });
+                zipfile.readEntry();
+            });
+        });
+    });
+}
+async function zipReadEntryBuffer(zipPath, innerPath, opts) {
+    const yauzl = await getYauzl();
+    const target = String(innerPath ?? "").replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!target)
+        throw new Error("innerPath is required");
+    return await new Promise((resolve, reject) => {
+        yauzl.open(zipPath, { lazyEntries: true, autoClose: true }, (err, zipfile) => {
+            if (err || !zipfile)
+                return reject(err ?? new Error("Failed to open zip"));
+            let done = false;
+            const finishError = (e) => {
+                if (done)
+                    return;
+                done = true;
+                try {
+                    zipfile.close();
+                }
+                catch {
+                    // ignore
+                }
+                reject(e);
+            };
+            zipfile.on("error", finishError);
+            const want = opts.caseSensitive ? target : target.toLowerCase();
+            zipfile.readEntry();
+            zipfile.on("entry", (entry) => {
+                if (done)
+                    return;
+                const nameRaw = String(entry.fileName ?? "");
+                const name = opts.caseSensitive ? nameRaw : nameRaw.toLowerCase();
+                if (name !== want) {
+                    zipfile.readEntry();
+                    return;
+                }
+                if (nameRaw.endsWith("/")) {
+                    finishError(new Error(`zip entry is a directory: ${nameRaw}`));
+                    return;
+                }
+                const uncompressedSize = Number(entry.uncompressedSize ?? 0);
+                if (Number.isFinite(uncompressedSize) && uncompressedSize > opts.maxBytes) {
+                    finishError(new Error(`zip entry too large (${uncompressedSize} bytes) for maxBytes=${opts.maxBytes}: ${nameRaw}`));
+                    return;
+                }
+                zipfile.openReadStream(entry, (streamErr, readStream) => {
+                    if (streamErr || !readStream) {
+                        finishError(streamErr ?? new Error("Failed to open zip entry stream"));
+                        return;
+                    }
+                    const chunks = [];
+                    let total = 0;
+                    readStream.on("data", (chunk) => {
+                        if (done)
+                            return;
+                        total += chunk.length;
+                        if (total > opts.maxBytes) {
+                            try {
+                                readStream.destroy();
+                            }
+                            catch {
+                                // ignore
+                            }
+                            finishError(new Error(`zip entry exceeded maxBytes=${opts.maxBytes}: ${nameRaw}`));
+                            return;
+                        }
+                        chunks.push(chunk);
+                    });
+                    readStream.on("error", finishError);
+                    readStream.on("end", () => {
+                        if (done)
+                            return;
+                        done = true;
+                        const buffer = Buffer.concat(chunks);
+                        const info = {
+                            fileName: nameRaw,
+                            uncompressedSize: Number(entry.uncompressedSize ?? buffer.length),
+                            compressedSize: Number(entry.compressedSize ?? buffer.length),
+                            isDirectory: false,
+                            crc32: typeof entry.crc32 === "number" ? entry.crc32 : undefined,
+                            compressionMethod: typeof entry.compressionMethod === "number" ? entry.compressionMethod : undefined,
+                        };
+                        try {
+                            zipfile.close();
+                        }
+                        catch {
+                            // ignore
+                        }
+                        resolve({ buffer, entry: info });
+                    });
+                });
+            });
+            zipfile.on("end", () => {
+                if (done)
+                    return;
+                finishError(new Error(`zip entry not found: ${target}`));
+            });
+        });
+    });
+}
+function pruneJsonForPreview(value, opts, state, depth = 0) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string") {
+        if (value.length > opts.maxStringChars) {
+            state.truncated = true;
+            return value.slice(0, opts.maxStringChars) + "...";
+        }
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (depth >= opts.maxDepth) {
+        state.truncated = true;
+        return "[Truncated:maxDepth]";
+    }
+    if (Array.isArray(value)) {
+        const out = [];
+        const take = Math.min(value.length, opts.maxItems);
+        if (value.length > take)
+            state.truncated = true;
+        for (let i = 0; i < take; i++) {
+            out.push(pruneJsonForPreview(value[i], opts, state, depth + 1));
+        }
+        return out;
+    }
+    if (typeof value === "object") {
+        const keys = Object.keys(value);
+        const take = Math.min(keys.length, opts.maxItems);
+        if (keys.length > take)
+            state.truncated = true;
+        const out = {};
+        for (let i = 0; i < take; i++) {
+            const k = keys[i];
+            out[k] = pruneJsonForPreview(value[k], opts, state, depth + 1);
+        }
+        return out;
+    }
+    return String(value);
+}
+function jsonPointerGet(root, pointerRaw) {
+    const pointer = String(pointerRaw ?? "").trim();
+    if (pointer === "" || pointer === "/")
+        return { found: true, value: root };
+    if (!pointer.startsWith("/")) {
+        throw new Error("pointer must start with '/' or be empty");
+    }
+    const parts = pointer
+        .split("/")
+        .slice(1)
+        .map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+    let cur = root;
+    for (const part of parts) {
+        if (cur === null || cur === undefined)
+            return { found: false, value: null };
+        if (Array.isArray(cur)) {
+            const idx = Number.parseInt(part, 10);
+            if (!Number.isFinite(idx) || idx < 0 || idx >= cur.length)
+                return { found: false, value: null };
+            cur = cur[idx];
+            continue;
+        }
+        if (typeof cur === "object") {
+            if (!Object.prototype.hasOwnProperty.call(cur, part))
+                return { found: false, value: null };
+            cur = cur[part];
+            continue;
+        }
+        return { found: false, value: null };
+    }
+    return { found: true, value: cur };
+}
+function docxXmlToText(xmlRaw) {
+    let s = String(xmlRaw ?? "");
+    s = s.replace(/<w:tab[^>]*\/>/gi, "\t");
+    s = s.replace(/<(w:br|w:cr)[^>]*\/>/gi, "\n");
+    s = s.replace(/<\/w:p>/gi, "\n");
+    s = s.replace(/<w:t\b[^>]*>/gi, "");
+    s = s.replace(/<\/w:t>/gi, "");
+    s = s.replace(/<[^>]+>/g, "");
+    s = decodeXmlEntities(s);
+    s = s.replace(/\r/g, "");
+    s = s.replace(/[ \t]+\n/g, "\n");
+    s = s.replace(/\n{3,}/g, "\n\n");
+    return s.trim();
+}
+function pptxSlideXmlToText(xmlRaw) {
+    let s = String(xmlRaw ?? "");
+    s = s.replace(/<a:br[^>]*\/>/gi, "\n");
+    s = s.replace(/<\/a:p>/gi, "\n");
+    s = s.replace(/<a:t\b[^>]*>/gi, "");
+    s = s.replace(/<\/a:t>/gi, "");
+    s = s.replace(/<[^>]+>/g, "");
+    s = decodeXmlEntities(s);
+    s = s.replace(/\r/g, "");
+    s = s.replace(/[ \t]+\n/g, "\n");
+    s = s.replace(/\n{3,}/g, "\n\n");
+    return s.trim();
+}
+async function loadCsvTable(args, opts) {
+    const encoding = String(args?.encoding ?? "utf8");
+    const text = await readFile(opts.filePath, { encoding });
+    const hasHeader = args?.hasHeader !== false;
+    const delimiter = typeof args?.delimiter === "string" ? args.delimiter : undefined;
+    const papa = await getPapaParse();
+    let rows = [];
+    let parseErrors = [];
+    if (papa?.parse) {
+        const result = papa.parse(text, {
+            ...(delimiter ? { delimiter } : {}),
+            skipEmptyLines: true,
+            dynamicTyping: false,
+        });
+        rows = Array.isArray(result?.data) ? result.data : [];
+        parseErrors = Array.isArray(result?.errors) ? result.errors : [];
+    }
+    else {
+        // Minimal fallback parser: split by newlines and delimiter (no quote handling).
+        const lines = String(text).split(/\r?\n/).filter((l) => l.trim().length > 0);
+        rows = lines.map((l) => l.split(delimiter ?? ","));
+    }
+    const normalizedAll = rows
+        .filter((r) => Array.isArray(r))
+        .map((r) => r.slice(0, opts.maxCols).map((c) => truncateCell(c, opts.maxCellChars)));
+    const headerRow = hasHeader ? normalizedAll[0] : undefined;
+    const dataRowsAll = hasHeader ? normalizedAll.slice(1) : normalizedAll;
+    const dataRows = dataRowsAll.slice(0, opts.maxScanRows);
+    const colCount = Math.max(headerRow ? headerRow.length : 0, ...dataRows.map((r) => r.length));
+    const headers = headerRow
+        ? headerRow.map((h) => String(h ?? "").trim())
+        : Array.from({ length: colCount }, (_, i) => `col_${i + 1}`);
+    return {
+        encoding,
+        hasHeader,
+        delimiter: delimiter ?? null,
+        parseErrors,
+        headers,
+        dataRows,
+    };
+}
+async function loadXlsxTable(args, opts) {
+    const XLSX = await getXlsx();
+    const wb = XLSX.readFile(opts.filePath, { cellDates: true, dense: true });
+    const sheets = Array.isArray(wb?.SheetNames) ? wb.SheetNames : [];
+    if (sheets.length === 0)
+        throw new Error(`No sheets found in workbook: ${opts.filePath}`);
+    const requestedSheet = typeof args?.sheetName === "string" ? args.sheetName.trim() : "";
+    const sheetName = requestedSheet || sheets[0];
+    const sheet = wb.Sheets?.[sheetName];
+    if (!sheet) {
+        throw new Error(`Sheet not found: \"${sheetName}\". Available sheets: ${sheets.join(", ")}`);
+    }
+    const headerRow = clampInt(args?.headerRow, 1, 0, 1000);
+    const rangeA1 = typeof args?.rangeA1 === "string" ? args.rangeA1.trim() : "";
+    const table = XLSX.utils.sheet_to_json(sheet, {
+        header: 1,
+        blankrows: false,
+        defval: "",
+        ...(rangeA1 ? { range: rangeA1 } : {}),
+    });
+    const normalizedAll = table
+        .filter((r) => Array.isArray(r))
+        .map((r) => r.slice(0, opts.maxCols).map((c) => truncateCell(c, opts.maxCellChars)));
+    const headerIdx = headerRow > 0 ? headerRow - 1 : -1;
+    const header = headerIdx >= 0 ? normalizedAll[headerIdx] : undefined;
+    const dataRowsAll = headerIdx >= 0 ? normalizedAll.slice(headerIdx + 1) : normalizedAll;
+    const dataRows = dataRowsAll.slice(0, opts.maxScanRows);
+    const colCount = Math.max(header ? header.length : 0, ...dataRows.map((r) => r.length));
+    const headers = header
+        ? header.map((h) => String(h ?? "").trim())
+        : Array.from({ length: colCount }, (_, i) => `col_${i + 1}`);
+    return {
+        sheets,
+        sheetName,
+        headerRow,
+        rangeA1: rangeA1 || null,
+        headers,
+        dataRows,
+    };
+}
 export const localFileTools = [
     {
         name: "read_csv_file",
@@ -176,6 +671,347 @@ export const localFileTools = [
             };
         },
     },
+    {
+        name: "csv_select_rows",
+        description: "Select rows from a local CSV using deterministic filters. Returns bounded results (selected columns + matching rows). No network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .csv file (absolute or relative to current working directory).",
+                },
+                hasHeader: {
+                    type: "boolean",
+                    description: "If true, treats the first row as headers.",
+                    default: true,
+                },
+                delimiter: {
+                    type: "string",
+                    description: "Optional delimiter override, e.g. ',' or '\\t'. If omitted, parser default is used.",
+                },
+                encoding: {
+                    type: "string",
+                    description: "File encoding (default: utf8).",
+                    default: "utf8",
+                },
+                where: {
+                    type: "array",
+                    description: "Optional filters combined with AND. Column can be a header name or 0-based index. Ops: eq, ne, contains, gt, gte, lt, lte, is_empty, not_empty.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            column: { type: ["string", "number"] },
+                            op: {
+                                type: "string",
+                                enum: ["eq", "ne", "contains", "gt", "gte", "lt", "lte", "is_empty", "not_empty"],
+                            },
+                            value: { type: ["string", "number", "boolean", "null"] },
+                            caseSensitive: { type: "boolean" },
+                        },
+                        required: ["column", "op"],
+                    },
+                },
+                returnColumns: {
+                    type: "array",
+                    description: "Optional list of columns to return (header name or 0-based index). If omitted, returns all columns (bounded by maxCols).",
+                    items: { type: ["string", "number"] },
+                },
+                offset: {
+                    type: "number",
+                    description: "Number of matching rows to skip before returning results.",
+                    default: 0,
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of matching rows to return.",
+                    default: 50,
+                },
+                maxScanRows: {
+                    type: "number",
+                    description: "Maximum number of data rows to scan (excluding header).",
+                    default: 50000,
+                },
+                maxCols: {
+                    type: "number",
+                    description: "Maximum number of columns to scan/return.",
+                    default: 80,
+                },
+                maxCellChars: {
+                    type: "number",
+                    description: "Maximum characters to return per cell (long cells are truncated).",
+                    default: 2000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxScanRows = clampInt(args?.maxScanRows, 50000, 1, 200000);
+            const maxCols = clampInt(args?.maxCols, 80, 1, 500);
+            const maxCellChars = clampInt(args?.maxCellChars, 2000, 20, 20000);
+            const offset = clampInt(args?.offset, 0, 0, 1_000_000_000);
+            const limit = clampInt(args?.limit, 50, 1, 5000);
+            const table = await loadCsvTable(args, { filePath, maxScanRows, maxCols, maxCellChars });
+            const where = compileWhere(table.headers, args?.where);
+            const returnColumnsRaw = Array.isArray(args?.returnColumns)
+                ? args.returnColumns.slice(0, 200)
+                : null;
+            const returnIndices = returnColumnsRaw && returnColumnsRaw.length > 0
+                ? returnColumnsRaw
+                    .map((c) => resolveColumnIndex(table.headers, c))
+                    .filter((idx) => idx >= 0)
+                : Array.from({ length: Math.min(table.headers.length, maxCols) }, (_, i) => i);
+            const selectedHeaders = returnIndices.map((i) => table.headers[i] ?? `col_${i + 1}`);
+            const outRows = [];
+            let matched = 0;
+            for (let i = 0; i < table.dataRows.length; i++) {
+                const row = table.dataRows[i];
+                if (!rowMatchesWhere(row, where))
+                    continue;
+                if (matched >= offset && outRows.length < limit) {
+                    outRows.push({
+                        rowIndex: i + 1,
+                        row: returnIndices.map((idx) => row[idx]),
+                    });
+                }
+                matched++;
+                if (outRows.length >= limit && matched >= offset + limit)
+                    break;
+            }
+            return {
+                path: filePath,
+                encoding: table.encoding,
+                hasHeader: table.hasHeader,
+                delimiter: table.delimiter,
+                parseErrors: table.parseErrors.length > 0 ? table.parseErrors.slice(0, 5) : [],
+                scannedRows: table.dataRows.length,
+                matchedRows: matched,
+                returnedRows: outRows.length,
+                offset,
+                limit,
+                headers: selectedHeaders,
+                rows: outRows,
+            };
+        },
+    },
+    {
+        name: "csv_aggregate",
+        description: "Aggregate values from a local CSV (count/sum/avg/min/max) with optional filters. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .csv file (absolute or relative to current working directory).",
+                },
+                hasHeader: {
+                    type: "boolean",
+                    description: "If true, treats the first row as headers.",
+                    default: true,
+                },
+                delimiter: {
+                    type: "string",
+                    description: "Optional delimiter override, e.g. ',' or '\\t'. If omitted, parser default is used.",
+                },
+                encoding: {
+                    type: "string",
+                    description: "File encoding (default: utf8).",
+                    default: "utf8",
+                },
+                where: {
+                    type: "array",
+                    description: "Optional filters combined with AND. Column can be a header name or 0-based index. Ops: eq, ne, contains, gt, gte, lt, lte, is_empty, not_empty.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            column: { type: ["string", "number"] },
+                            op: {
+                                type: "string",
+                                enum: ["eq", "ne", "contains", "gt", "gte", "lt", "lte", "is_empty", "not_empty"],
+                            },
+                            value: { type: ["string", "number", "boolean", "null"] },
+                            caseSensitive: { type: "boolean" },
+                        },
+                        required: ["column", "op"],
+                    },
+                },
+                operation: {
+                    type: "string",
+                    enum: ["count", "sum", "avg", "min", "max"],
+                    description: "Aggregation to compute.",
+                },
+                value: {
+                    type: "object",
+                    description: "Value definition. Use {type:'column',column:'ColName'} or {type:'ratio',numeratorColumn:'A',denominatorColumn:'B'}.",
+                    properties: {
+                        type: { type: "string", enum: ["column", "ratio"] },
+                        column: { type: ["string", "number"] },
+                        numeratorColumn: { type: ["string", "number"] },
+                        denominatorColumn: { type: ["string", "number"] },
+                    },
+                    required: ["type"],
+                },
+                ignoreNonNumeric: {
+                    type: "boolean",
+                    description: "If true, skips rows where the value can't be parsed as a number (default true).",
+                    default: true,
+                },
+                returnRow: {
+                    type: "boolean",
+                    description: "If true (and operation is min/max), includes the best row.",
+                    default: true,
+                },
+                returnColumns: {
+                    type: "array",
+                    description: "If returnRow is true, optionally choose which columns to include from the best row (header name or 0-based index).",
+                    items: { type: ["string", "number"] },
+                },
+                maxScanRows: {
+                    type: "number",
+                    description: "Maximum number of data rows to scan (excluding header).",
+                    default: 50000,
+                },
+                maxCols: {
+                    type: "number",
+                    description: "Maximum number of columns to scan.",
+                    default: 200,
+                },
+                maxCellChars: {
+                    type: "number",
+                    description: "Maximum characters to return per cell in bestRow (long cells are truncated).",
+                    default: 2000,
+                },
+            },
+            required: ["path", "operation"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const operation = String(args?.operation ?? "").trim().toLowerCase();
+            if (!["count", "sum", "avg", "min", "max"].includes(operation)) {
+                throw new Error(`Unsupported operation: ${operation}`);
+            }
+            const maxScanRows = clampInt(args?.maxScanRows, 50000, 1, 200000);
+            const maxCols = clampInt(args?.maxCols, 200, 1, 500);
+            const maxCellChars = clampInt(args?.maxCellChars, 2000, 20, 20000);
+            const ignoreNonNumeric = args?.ignoreNonNumeric !== false;
+            const returnRow = args?.returnRow !== false;
+            const table = await loadCsvTable(args, { filePath, maxScanRows, maxCols, maxCellChars });
+            const where = compileWhere(table.headers, args?.where);
+            const valueSpec = (args?.value ?? null);
+            const getValue = (row) => {
+                if (!valueSpec || typeof valueSpec !== "object")
+                    return null;
+                const t = String(valueSpec.type ?? "").trim().toLowerCase();
+                if (t === "column") {
+                    const idx = resolveColumnIndex(table.headers, valueSpec.column);
+                    if (idx < 0)
+                        return null;
+                    return toNumberOrNull(row[idx]);
+                }
+                if (t === "ratio") {
+                    const nIdx = resolveColumnIndex(table.headers, valueSpec.numeratorColumn);
+                    const dIdx = resolveColumnIndex(table.headers, valueSpec.denominatorColumn);
+                    if (nIdx < 0 || dIdx < 0)
+                        return null;
+                    const n = toNumberOrNull(row[nIdx]);
+                    const d = toNumberOrNull(row[dIdx]);
+                    if (n === null || d === null || d === 0)
+                        return null;
+                    return n / d;
+                }
+                return null;
+            };
+            let matchedRows = 0;
+            let usedRows = 0;
+            let skippedRows = 0;
+            let sum = 0;
+            let bestVal = null;
+            let bestRowIndex = null;
+            let bestRow = null;
+            for (let i = 0; i < table.dataRows.length; i++) {
+                const row = table.dataRows[i];
+                if (!rowMatchesWhere(row, where))
+                    continue;
+                matchedRows++;
+                if (operation === "count" && !valueSpec)
+                    continue;
+                const value = valueSpec ? getValue(row) : null;
+                if (value === null) {
+                    skippedRows++;
+                    continue;
+                }
+                usedRows++;
+                sum += value;
+                if (operation === "min") {
+                    if (bestVal === null || value < bestVal) {
+                        bestVal = value;
+                        bestRowIndex = i + 1;
+                        bestRow = row;
+                    }
+                }
+                else if (operation === "max") {
+                    if (bestVal === null || value > bestVal) {
+                        bestVal = value;
+                        bestRowIndex = i + 1;
+                        bestRow = row;
+                    }
+                }
+            }
+            let resultValue = null;
+            if (operation === "count") {
+                resultValue = valueSpec ? usedRows : matchedRows;
+            }
+            else if (operation === "sum") {
+                resultValue = usedRows > 0 ? sum : null;
+            }
+            else if (operation === "avg") {
+                resultValue = usedRows > 0 ? sum / usedRows : null;
+            }
+            else if (operation === "min" || operation === "max") {
+                resultValue = bestVal;
+            }
+            let best = null;
+            if (returnRow && (operation === "min" || operation === "max") && bestRowIndex !== null && bestRow) {
+                const returnColumnsRaw = Array.isArray(args?.returnColumns)
+                    ? args.returnColumns.slice(0, 200)
+                    : null;
+                const returnIndices = returnColumnsRaw && returnColumnsRaw.length > 0
+                    ? returnColumnsRaw
+                        .map((c) => resolveColumnIndex(table.headers, c))
+                        .filter((idx) => idx >= 0)
+                    : Array.from({ length: Math.min(table.headers.length, 50) }, (_, i) => i);
+                best = {
+                    rowIndex: bestRowIndex,
+                    headers: returnIndices.map((i) => table.headers[i] ?? `col_${i + 1}`),
+                    row: returnIndices.map((i) => bestRow[i]),
+                };
+            }
+            if (!ignoreNonNumeric && (operation === "sum" || operation === "avg" || operation === "min" || operation === "max") && skippedRows > 0) {
+                // Caller can choose to treat non-numeric rows as a hard failure.
+                // We keep it non-throwing by default for robustness.
+            }
+            return {
+                path: filePath,
+                encoding: table.encoding,
+                hasHeader: table.hasHeader,
+                delimiter: table.delimiter,
+                parseErrors: table.parseErrors.length > 0 ? table.parseErrors.slice(0, 5) : [],
+                operation,
+                value: valueSpec ?? null,
+                scannedRows: table.dataRows.length,
+                matchedRows,
+                usedRows,
+                skippedRows,
+                result: resultValue,
+                bestRow: best,
+            };
+        },
+    },
     {
         name: "read_xlsx_file",
         description: "Read a local XLSX workbook and return a bounded sheet preview (headers + rows). Deterministic, no network.",
@@ -276,34 +1112,74 @@ export const localFileTools = [
         },
     },
     {
-        name: "read_pdf_text",
-        description: "Extract text from a local PDF file for selected pages. Returns bounded text with page markers. Deterministic, no network.",
+        name: "xlsx_select_rows",
+        description: "Select rows from a local XLSX using deterministic filters. Returns bounded results (selected columns + matching rows). No network.",
         inputSchema: {
             type: "object",
             properties: {
                 path: {
                     type: "string",
-                    description: "Path to a local .pdf file (absolute or relative to current working directory).",
+                    description: "Path to a local .xlsx file (absolute or relative to current working directory).",
                 },
-                pageStart: {
+                sheetName: {
+                    type: "string",
+                    description: "Sheet to read. If omitted, the first sheet is used.",
+                },
+                headerRow: {
                     type: "number",
-                    description: "1-based start page (inclusive). Defaults to 1.",
+                    description: "1-based header row index. Use 0 for no header row.",
                     default: 1,
                 },
-                pageEnd: {
-                    type: "number",
-                    description: "1-based end page (inclusive). Defaults to 3.",
-                    default: 3,
+                rangeA1: {
+                    type: "string",
+                    description: "Optional A1 range (e.g. A1:D5000) to limit scanning to a specific region.",
                 },
-                pageNumbers: {
+                where: {
                     type: "array",
-                    description: "Optional explicit list of 1-based pages to extract (overrides pageStart/pageEnd).",
-                    items: { type: "number" },
+                    description: "Optional filters combined with AND. Column can be a header name or 0-based index. Ops: eq, ne, contains, gt, gte, lt, lte, is_empty, not_empty.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            column: { type: ["string", "number"] },
+                            op: {
+                                type: "string",
+                                enum: ["eq", "ne", "contains", "gt", "gte", "lt", "lte", "is_empty", "not_empty"],
+                            },
+                            value: { type: ["string", "number", "boolean", "null"] },
+                            caseSensitive: { type: "boolean" },
+                        },
+                        required: ["column", "op"],
+                    },
                 },
-                maxChars: {
+                returnColumns: {
+                    type: "array",
+                    description: "Optional list of columns to return (header name or 0-based index). If omitted, returns all columns (bounded by maxCols).",
+                    items: { type: ["string", "number"] },
+                },
+                offset: {
                     type: "number",
-                    description: "Maximum characters to return across all extracted pages (text is truncated).",
-                    default: 12000,
+                    description: "Number of matching rows to skip before returning results.",
+                    default: 0,
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of matching rows to return.",
+                    default: 50,
+                },
+                maxScanRows: {
+                    type: "number",
+                    description: "Maximum number of data rows to scan (excluding header).",
+                    default: 50000,
+                },
+                maxCols: {
+                    type: "number",
+                    description: "Maximum number of columns to scan/return.",
+                    default: 80,
+                },
+                maxCellChars: {
+                    type: "number",
+                    description: "Maximum characters to return per cell (long cells are truncated).",
+                    default: 2000,
                 },
             },
             required: ["path"],
@@ -312,19 +1188,318 @@ export const localFileTools = [
             const filePath = resolveLocalPath(args?.path);
             if (!existsSync(filePath))
                 throw new Error(`File not found: ${filePath}`);
-            const maxChars = clampInt(args?.maxChars, 12000, 1000, 200000);
-            const pageNumbersRaw = Array.isArray(args?.pageNumbers) ? args.pageNumbers : null;
-            const explicitPages = pageNumbersRaw
-                ? pageNumbersRaw
-                    .map((n) => clampInt(n, 0, 0, 100000))
-                    .filter((n) => n > 0)
+            const maxScanRows = clampInt(args?.maxScanRows, 50000, 1, 200000);
+            const maxCols = clampInt(args?.maxCols, 80, 1, 500);
+            const maxCellChars = clampInt(args?.maxCellChars, 2000, 20, 20000);
+            const offset = clampInt(args?.offset, 0, 0, 1_000_000_000);
+            const limit = clampInt(args?.limit, 50, 1, 5000);
+            const table = await loadXlsxTable(args, { filePath, maxScanRows, maxCols, maxCellChars });
+            const where = compileWhere(table.headers, args?.where);
+            const returnColumnsRaw = Array.isArray(args?.returnColumns)
+                ? args.returnColumns.slice(0, 200)
                 : null;
-            const pageStart = clampInt(args?.pageStart, 1, 1, 100000);
-            const pageEnd = clampInt(args?.pageEnd, 3, 1, 100000);
-            const mod = await getPdfParseModule();
-            const PDFParse = mod?.PDFParse;
-            if (typeof PDFParse !== "function") {
-                throw new Error("pdf-parse module missing PDFParse export (unsupported version)");
+            const returnIndices = returnColumnsRaw && returnColumnsRaw.length > 0
+                ? returnColumnsRaw
+                    .map((c) => resolveColumnIndex(table.headers, c))
+                    .filter((idx) => idx >= 0)
+                : Array.from({ length: Math.min(table.headers.length, maxCols) }, (_, i) => i);
+            const selectedHeaders = returnIndices.map((i) => table.headers[i] ?? `col_${i + 1}`);
+            const outRows = [];
+            let matched = 0;
+            for (let i = 0; i < table.dataRows.length; i++) {
+                const row = table.dataRows[i];
+                if (!rowMatchesWhere(row, where))
+                    continue;
+                if (matched >= offset && outRows.length < limit) {
+                    outRows.push({
+                        rowIndex: i + 1,
+                        row: returnIndices.map((idx) => row[idx]),
+                    });
+                }
+                matched++;
+                if (outRows.length >= limit && matched >= offset + limit)
+                    break;
+            }
+            return {
+                path: filePath,
+                sheets: table.sheets,
+                sheetName: table.sheetName,
+                headerRow: table.headerRow,
+                rangeA1: table.rangeA1,
+                scannedRows: table.dataRows.length,
+                matchedRows: matched,
+                returnedRows: outRows.length,
+                offset,
+                limit,
+                headers: selectedHeaders,
+                rows: outRows,
+            };
+        },
+    },
+    {
+        name: "xlsx_aggregate",
+        description: "Aggregate values from a local XLSX (count/sum/avg/min/max) with optional filters. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .xlsx file (absolute or relative to current working directory).",
+                },
+                sheetName: {
+                    type: "string",
+                    description: "Sheet to read. If omitted, the first sheet is used.",
+                },
+                headerRow: {
+                    type: "number",
+                    description: "1-based header row index. Use 0 for no header row.",
+                    default: 1,
+                },
+                rangeA1: {
+                    type: "string",
+                    description: "Optional A1 range (e.g. A1:D5000) to limit scanning to a specific region.",
+                },
+                where: {
+                    type: "array",
+                    description: "Optional filters combined with AND. Column can be a header name or 0-based index. Ops: eq, ne, contains, gt, gte, lt, lte, is_empty, not_empty.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            column: { type: ["string", "number"] },
+                            op: {
+                                type: "string",
+                                enum: ["eq", "ne", "contains", "gt", "gte", "lt", "lte", "is_empty", "not_empty"],
+                            },
+                            value: { type: ["string", "number", "boolean", "null"] },
+                            caseSensitive: { type: "boolean" },
+                        },
+                        required: ["column", "op"],
+                    },
+                },
+                operation: {
+                    type: "string",
+                    enum: ["count", "sum", "avg", "min", "max"],
+                    description: "Aggregation to compute.",
+                },
+                value: {
+                    type: "object",
+                    description: "Value definition. Use {type:'column',column:'ColName'} or {type:'ratio',numeratorColumn:'A',denominatorColumn:'B'}.",
+                    properties: {
+                        type: { type: "string", enum: ["column", "ratio"] },
+                        column: { type: ["string", "number"] },
+                        numeratorColumn: { type: ["string", "number"] },
+                        denominatorColumn: { type: ["string", "number"] },
+                    },
+                    required: ["type"],
+                },
+                ignoreNonNumeric: {
+                    type: "boolean",
+                    description: "If true, skips rows where the value can't be parsed as a number (default true).",
+                    default: true,
+                },
+                returnRow: {
+                    type: "boolean",
+                    description: "If true (and operation is min/max), includes the best row.",
+                    default: true,
+                },
+                returnColumns: {
+                    type: "array",
+                    description: "If returnRow is true, optionally choose which columns to include from the best row (header name or 0-based index).",
+                    items: { type: ["string", "number"] },
+                },
+                maxScanRows: {
+                    type: "number",
+                    description: "Maximum number of data rows to scan (excluding header).",
+                    default: 50000,
+                },
+                maxCols: {
+                    type: "number",
+                    description: "Maximum number of columns to scan.",
+                    default: 200,
+                },
+                maxCellChars: {
+                    type: "number",
+                    description: "Maximum characters to return per cell in bestRow (long cells are truncated).",
+                    default: 2000,
+                },
+            },
+            required: ["path", "operation"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const operation = String(args?.operation ?? "").trim().toLowerCase();
+            if (!["count", "sum", "avg", "min", "max"].includes(operation)) {
+                throw new Error(`Unsupported operation: ${operation}`);
+            }
+            const maxScanRows = clampInt(args?.maxScanRows, 50000, 1, 200000);
+            const maxCols = clampInt(args?.maxCols, 200, 1, 500);
+            const maxCellChars = clampInt(args?.maxCellChars, 2000, 20, 20000);
+            const ignoreNonNumeric = args?.ignoreNonNumeric !== false;
+            const returnRow = args?.returnRow !== false;
+            const table = await loadXlsxTable(args, { filePath, maxScanRows, maxCols, maxCellChars });
+            const where = compileWhere(table.headers, args?.where);
+            const valueSpec = (args?.value ?? null);
+            const getValue = (row) => {
+                if (!valueSpec || typeof valueSpec !== "object")
+                    return null;
+                const t = String(valueSpec.type ?? "").trim().toLowerCase();
+                if (t === "column") {
+                    const idx = resolveColumnIndex(table.headers, valueSpec.column);
+                    if (idx < 0)
+                        return null;
+                    return toNumberOrNull(row[idx]);
+                }
+                if (t === "ratio") {
+                    const nIdx = resolveColumnIndex(table.headers, valueSpec.numeratorColumn);
+                    const dIdx = resolveColumnIndex(table.headers, valueSpec.denominatorColumn);
+                    if (nIdx < 0 || dIdx < 0)
+                        return null;
+                    const n = toNumberOrNull(row[nIdx]);
+                    const d = toNumberOrNull(row[dIdx]);
+                    if (n === null || d === null || d === 0)
+                        return null;
+                    return n / d;
+                }
+                return null;
+            };
+            let matchedRows = 0;
+            let usedRows = 0;
+            let skippedRows = 0;
+            let sum = 0;
+            let bestVal = null;
+            let bestRowIndex = null;
+            let bestRow = null;
+            for (let i = 0; i < table.dataRows.length; i++) {
+                const row = table.dataRows[i];
+                if (!rowMatchesWhere(row, where))
+                    continue;
+                matchedRows++;
+                if (operation === "count" && !valueSpec)
+                    continue;
+                const value = valueSpec ? getValue(row) : null;
+                if (value === null) {
+                    skippedRows++;
+                    continue;
+                }
+                usedRows++;
+                sum += value;
+                if (operation === "min") {
+                    if (bestVal === null || value < bestVal) {
+                        bestVal = value;
+                        bestRowIndex = i + 1;
+                        bestRow = row;
+                    }
+                }
+                else if (operation === "max") {
+                    if (bestVal === null || value > bestVal) {
+                        bestVal = value;
+                        bestRowIndex = i + 1;
+                        bestRow = row;
+                    }
+                }
+            }
+            let resultValue = null;
+            if (operation === "count") {
+                resultValue = valueSpec ? usedRows : matchedRows;
+            }
+            else if (operation === "sum") {
+                resultValue = usedRows > 0 ? sum : null;
+            }
+            else if (operation === "avg") {
+                resultValue = usedRows > 0 ? sum / usedRows : null;
+            }
+            else if (operation === "min" || operation === "max") {
+                resultValue = bestVal;
+            }
+            let best = null;
+            if (returnRow && (operation === "min" || operation === "max") && bestRowIndex !== null && bestRow) {
+                const returnColumnsRaw = Array.isArray(args?.returnColumns)
+                    ? args.returnColumns.slice(0, 200)
+                    : null;
+                const returnIndices = returnColumnsRaw && returnColumnsRaw.length > 0
+                    ? returnColumnsRaw
+                        .map((c) => resolveColumnIndex(table.headers, c))
+                        .filter((idx) => idx >= 0)
+                    : Array.from({ length: Math.min(table.headers.length, 50) }, (_, i) => i);
+                best = {
+                    rowIndex: bestRowIndex,
+                    headers: returnIndices.map((i) => table.headers[i] ?? `col_${i + 1}`),
+                    row: returnIndices.map((i) => bestRow[i]),
+                };
+            }
+            if (!ignoreNonNumeric && (operation === "sum" || operation === "avg" || operation === "min" || operation === "max") && skippedRows > 0) {
+                // Caller can choose to treat non-numeric rows as a hard failure.
+                // We keep it non-throwing by default for robustness.
+            }
+            return {
+                path: filePath,
+                sheets: table.sheets,
+                sheetName: table.sheetName,
+                headerRow: table.headerRow,
+                rangeA1: table.rangeA1,
+                operation,
+                value: valueSpec ?? null,
+                scannedRows: table.dataRows.length,
+                matchedRows,
+                usedRows,
+                skippedRows,
+                result: resultValue,
+                bestRow: best,
+            };
+        },
+    },
+    {
+        name: "read_pdf_text",
+        description: "Extract text from a local PDF file for selected pages. Returns bounded text with page markers. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .pdf file (absolute or relative to current working directory).",
+                },
+                pageStart: {
+                    type: "number",
+                    description: "1-based start page (inclusive). Defaults to 1.",
+                    default: 1,
+                },
+                pageEnd: {
+                    type: "number",
+                    description: "1-based end page (inclusive). Defaults to 3.",
+                    default: 3,
+                },
+                pageNumbers: {
+                    type: "array",
+                    description: "Optional explicit list of 1-based pages to extract (overrides pageStart/pageEnd).",
+                    items: { type: "number" },
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return across all extracted pages (text is truncated).",
+                    default: 12000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxChars = clampInt(args?.maxChars, 12000, 1000, 200000);
+            const pageNumbersRaw = Array.isArray(args?.pageNumbers) ? args.pageNumbers : null;
+            const explicitPages = pageNumbersRaw
+                ? pageNumbersRaw
+                    .map((n) => clampInt(n, 0, 0, 100000))
+                    .filter((n) => n > 0)
+                : null;
+            const pageStart = clampInt(args?.pageStart, 1, 1, 100000);
+            const pageEnd = clampInt(args?.pageEnd, 3, 1, 100000);
+            const mod = await getPdfParseModule();
+            const PDFParse = mod?.PDFParse;
+            if (typeof PDFParse !== "function") {
+                throw new Error("pdf-parse module missing PDFParse export (unsupported version)");
             }
             const buffer = await readFile(filePath);
             const parser = new PDFParse({ data: buffer });
@@ -382,5 +1557,729 @@ export const localFileTools = [
             };
         },
     },
+    {
+        name: "pdf_search_text",
+        description: "Search text inside a local PDF over selected pages. Returns page numbers and bounded snippets around matches. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .pdf file (absolute or relative to current working directory).",
+                },
+                query: {
+                    type: "string",
+                    description: "Text to search for.",
+                },
+                caseSensitive: {
+                    type: "boolean",
+                    description: "If true, match case-sensitively (default false).",
+                    default: false,
+                },
+                pageStart: {
+                    type: "number",
+                    description: "1-based start page (inclusive). Defaults to 1.",
+                    default: 1,
+                },
+                pageEnd: {
+                    type: "number",
+                    description: "1-based end page (inclusive). Defaults to 25.",
+                    default: 25,
+                },
+                pageNumbers: {
+                    type: "array",
+                    description: "Optional explicit list of 1-based pages to search (overrides pageStart/pageEnd).",
+                    items: { type: "number" },
+                },
+                maxMatches: {
+                    type: "number",
+                    description: "Maximum matches to return across all pages.",
+                    default: 25,
+                },
+                snippetChars: {
+                    type: "number",
+                    description: "Snippet size (characters) around each match.",
+                    default: 180,
+                },
+            },
+            required: ["path", "query"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const queryRaw = String(args?.query ?? "");
+            const query = queryRaw.trim();
+            if (!query)
+                throw new Error("query is required");
+            const caseSensitive = args?.caseSensitive === true;
+            const maxMatches = clampInt(args?.maxMatches, 25, 1, 200);
+            const snippetChars = clampInt(args?.snippetChars, 180, 40, 1000);
+            const pageNumbersRaw = Array.isArray(args?.pageNumbers) ? args.pageNumbers : null;
+            const explicitPages = pageNumbersRaw
+                ? pageNumbersRaw
+                    .map((n) => clampInt(n, 0, 0, 100000))
+                    .filter((n) => n > 0)
+                : null;
+            const pageStart = clampInt(args?.pageStart, 1, 1, 100000);
+            const pageEnd = clampInt(args?.pageEnd, 25, 1, 100000);
+            const mod = await getPdfParseModule();
+            const PDFParse = mod?.PDFParse;
+            if (typeof PDFParse !== "function") {
+                throw new Error("pdf-parse module missing PDFParse export (unsupported version)");
+            }
+            const buffer = await readFile(filePath);
+            const parser = new PDFParse({ data: buffer });
+            let numPages = 0;
+            let extractedPages = [];
+            let pages = [];
+            try {
+                const parseParams = {
+                    lineEnforce: true,
+                    pageJoiner: "",
+                    parseHyperlinks: false,
+                };
+                if (explicitPages && explicitPages.length > 0) {
+                    parseParams.partial = explicitPages.slice(0, 200);
+                }
+                else {
+                    const start = Math.min(pageStart, pageEnd);
+                    const end = Math.max(pageStart, pageEnd);
+                    parseParams.first = start;
+                    parseParams.last = end;
+                }
+                const result = await parser.getText(parseParams);
+                numPages = Number(result?.total ?? 0);
+                const parsedPages = Array.isArray(result?.pages) ? result.pages : [];
+                extractedPages = parsedPages
+                    .map((p) => Number(p?.num ?? 0))
+                    .filter((n) => Number.isFinite(n) && n > 0);
+                pages = parsedPages.map((p) => ({
+                    num: Number(p?.num ?? 0),
+                    text: String(p?.text ?? ""),
+                }));
+            }
+            finally {
+                try {
+                    await parser.destroy();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            const needle = caseSensitive ? query : query.toLowerCase();
+            const matches = [];
+            for (const p of pages) {
+                const haystackRaw = String(p.text ?? "");
+                const haystack = caseSensitive ? haystackRaw : haystackRaw.toLowerCase();
+                let from = 0;
+                while (matches.length < maxMatches) {
+                    const idx = haystack.indexOf(needle, from);
+                    if (idx === -1)
+                        break;
+                    const start = Math.max(0, idx - Math.floor(snippetChars / 2));
+                    const end = Math.min(haystackRaw.length, start + snippetChars);
+                    const snippet = haystackRaw.slice(start, end).replace(/\s+/g, " ").trim();
+                    matches.push({ page: p.num, index: idx, snippet });
+                    from = idx + Math.max(1, needle.length);
+                }
+                if (matches.length >= maxMatches)
+                    break;
+            }
+            return {
+                path: filePath,
+                query,
+                caseSensitive,
+                numPages,
+                pagesIncluded: extractedPages,
+                maxMatches,
+                matchCount: matches.length,
+                matches,
+            };
+        },
+    },
+    {
+        name: "read_text_file",
+        description: "Read a local text file (txt/md/xml/json/etc) and return a bounded text slice. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local text file (absolute or relative to current working directory).",
+                },
+                encoding: {
+                    type: "string",
+                    description: "File encoding (default: utf8).",
+                    default: "utf8",
+                },
+                startChar: {
+                    type: "number",
+                    description: "0-based character offset to start reading from (default: 0).",
+                    default: 0,
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return (text is truncated).",
+                    default: 12000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const encoding = String(args?.encoding ?? "utf8");
+            const startChar = clampInt(args?.startChar, 0, 0, 50_000_000);
+            const maxChars = clampInt(args?.maxChars, 12000, 1, 200000);
+            const all = await readFile(filePath, { encoding });
+            const sliced = all.slice(startChar);
+            const truncated = sliced.length > maxChars;
+            const text = truncated ? sliced.slice(0, maxChars) : sliced;
+            return {
+                path: filePath,
+                encoding,
+                startChar,
+                maxChars,
+                truncated,
+                text,
+            };
+        },
+    },
+    {
+        name: "read_json_file",
+        description: "Read a local JSON file and return a bounded JSON preview (depth/item/string truncation). Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .json file (absolute or relative to current working directory).",
+                },
+                maxDepth: {
+                    type: "number",
+                    description: "Maximum depth to include (default: 8).",
+                    default: 8,
+                },
+                maxItems: {
+                    type: "number",
+                    description: "Maximum items (array elements or object keys) per container (default: 200).",
+                    default: 200,
+                },
+                maxStringChars: {
+                    type: "number",
+                    description: "Maximum characters per string value (default: 2000).",
+                    default: 2000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxDepth = clampInt(args?.maxDepth, 8, 1, 30);
+            const maxItems = clampInt(args?.maxItems, 200, 1, 2000);
+            const maxStringChars = clampInt(args?.maxStringChars, 2000, 20, 20000);
+            const raw = await readFile(filePath, { encoding: "utf8" });
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                throw new Error(`Invalid JSON: ${err?.message ?? String(err)}`);
+            }
+            const state = { truncated: false };
+            const value = pruneJsonForPreview(parsed, { maxDepth, maxItems, maxStringChars }, state);
+            return {
+                path: filePath,
+                maxDepth,
+                maxItems,
+                maxStringChars,
+                truncated: state.truncated,
+                rootType: Array.isArray(parsed) ? "array" : typeof parsed,
+                value,
+            };
+        },
+    },
+    {
+        name: "json_select",
+        description: "Select a sub-value from a local JSON file using a JSON Pointer (RFC 6901) and return a bounded preview. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .json file (absolute or relative to current working directory).",
+                },
+                pointer: {
+                    type: "string",
+                    description: "JSON Pointer (RFC 6901). Example: '/a/b/0/name'. Use '' or '/' for the root value.",
+                    default: "",
+                },
+                maxDepth: {
+                    type: "number",
+                    description: "Maximum depth to include (default: 8).",
+                    default: 8,
+                },
+                maxItems: {
+                    type: "number",
+                    description: "Maximum items (array elements or object keys) per container (default: 200).",
+                    default: 200,
+                },
+                maxStringChars: {
+                    type: "number",
+                    description: "Maximum characters per string value (default: 2000).",
+                    default: 2000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const pointer = String(args?.pointer ?? "");
+            const maxDepth = clampInt(args?.maxDepth, 8, 1, 30);
+            const maxItems = clampInt(args?.maxItems, 200, 1, 2000);
+            const maxStringChars = clampInt(args?.maxStringChars, 2000, 20, 20000);
+            const raw = await readFile(filePath, { encoding: "utf8" });
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                throw new Error(`Invalid JSON: ${err?.message ?? String(err)}`);
+            }
+            const selected = jsonPointerGet(parsed, pointer);
+            if (!selected.found) {
+                return {
+                    path: filePath,
+                    pointer,
+                    found: false,
+                    truncated: false,
+                    value: null,
+                };
+            }
+            const state = { truncated: false };
+            const value = pruneJsonForPreview(selected.value, { maxDepth, maxItems, maxStringChars }, state);
+            return {
+                path: filePath,
+                pointer,
+                found: true,
+                maxDepth,
+                maxItems,
+                maxStringChars,
+                truncated: state.truncated,
+                value,
+            };
+        },
+    },
+    {
+        name: "read_jsonl_file",
+        description: "Read a local JSONL file and return bounded parsed rows. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .jsonl file (absolute or relative to current working directory).",
+                },
+                encoding: {
+                    type: "string",
+                    description: "File encoding (default: utf8).",
+                    default: "utf8",
+                },
+                offsetLines: {
+                    type: "number",
+                    description: "Number of lines to skip before returning results.",
+                    default: 0,
+                },
+                limitLines: {
+                    type: "number",
+                    description: "Maximum number of non-empty lines to return.",
+                    default: 200,
+                },
+                parseJson: {
+                    type: "boolean",
+                    description: "If true, parses each line as JSON (default true). If false, returns raw text lines.",
+                    default: true,
+                },
+                maxLineChars: {
+                    type: "number",
+                    description: "Maximum characters per returned raw line (default 4000).",
+                    default: 4000,
+                },
+                maxDepth: {
+                    type: "number",
+                    description: "Maximum depth to include for parsed JSON lines (default: 6).",
+                    default: 6,
+                },
+                maxItems: {
+                    type: "number",
+                    description: "Maximum items per container for parsed JSON lines (default: 100).",
+                    default: 100,
+                },
+                maxStringChars: {
+                    type: "number",
+                    description: "Maximum characters per string for parsed JSON lines (default: 1000).",
+                    default: 1000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const encoding = String(args?.encoding ?? "utf8");
+            const offsetLines = clampInt(args?.offsetLines, 0, 0, 5_000_000);
+            const limitLines = clampInt(args?.limitLines, 200, 1, 5000);
+            const parseJson = args?.parseJson !== false;
+            const maxLineChars = clampInt(args?.maxLineChars, 4000, 200, 50000);
+            const maxDepth = clampInt(args?.maxDepth, 6, 1, 30);
+            const maxItems = clampInt(args?.maxItems, 100, 1, 2000);
+            const maxStringChars = clampInt(args?.maxStringChars, 1000, 20, 20000);
+            const text = await readFile(filePath, { encoding });
+            const linesAll = String(text).split(/\r?\n/);
+            const out = [];
+            const errors = [];
+            let seenNonEmpty = 0;
+            for (let i = 0; i < linesAll.length; i++) {
+                const raw = String(linesAll[i] ?? "");
+                if (raw.trim().length === 0)
+                    continue;
+                if (seenNonEmpty < offsetLines) {
+                    seenNonEmpty++;
+                    continue;
+                }
+                if (out.length >= limitLines)
+                    break;
+                const lineNumber = i + 1;
+                if (!parseJson) {
+                    const truncated = raw.length > maxLineChars ? raw.slice(0, maxLineChars) + "..." : raw;
+                    out.push({ lineNumber, value: truncated, raw: undefined });
+                    continue;
+                }
+                try {
+                    const parsed = JSON.parse(raw);
+                    const state = { truncated: false };
+                    const pruned = pruneJsonForPreview(parsed, { maxDepth, maxItems, maxStringChars }, state);
+                    out.push({ lineNumber, value: pruned });
+                }
+                catch (err) {
+                    errors.push({ lineNumber, error: err?.message ?? String(err) });
+                }
+            }
+            return {
+                path: filePath,
+                encoding,
+                offsetLines,
+                limitLines,
+                parseJson,
+                returnedLines: out.length,
+                errorCount: errors.length,
+                errors: errors.slice(0, 10),
+                lines: out,
+            };
+        },
+    },
+    {
+        name: "zip_list_files",
+        description: "List entries in a local ZIP file. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .zip file (absolute or relative to current working directory).",
+                },
+                maxEntries: {
+                    type: "number",
+                    description: "Maximum entries to return.",
+                    default: 200,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxEntries = clampInt(args?.maxEntries, 200, 1, 5000);
+            const result = await zipListEntries(filePath, maxEntries);
+            return {
+                path: filePath,
+                maxEntries,
+                returnedEntries: result.entries.length,
+                truncated: result.truncated,
+                entries: result.entries,
+            };
+        },
+    },
+    {
+        name: "zip_read_text_file",
+        description: "Read a text file inside a local ZIP archive and return bounded text. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .zip file (absolute or relative to current working directory).",
+                },
+                innerPath: {
+                    type: "string",
+                    description: "Path of the entry inside the ZIP (use zip_list_files to discover names).",
+                },
+                caseSensitive: {
+                    type: "boolean",
+                    description: "If true, entry match is case-sensitive (default true).",
+                    default: true,
+                },
+                encoding: {
+                    type: "string",
+                    description: "Text encoding for the entry (default: utf8).",
+                    default: "utf8",
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return.",
+                    default: 12000,
+                },
+                maxBytes: {
+                    type: "number",
+                    description: "Maximum uncompressed bytes to read (safety cap).",
+                    default: 5000000,
+                },
+            },
+            required: ["path", "innerPath"],
+        },
+        handler: async (args) => {
+            const zipPath = resolveLocalPath(args?.path);
+            if (!existsSync(zipPath))
+                throw new Error(`File not found: ${zipPath}`);
+            const innerPath = String(args?.innerPath ?? "").trim();
+            if (!innerPath)
+                throw new Error("innerPath is required");
+            const caseSensitive = args?.caseSensitive !== false;
+            const encoding = String(args?.encoding ?? "utf8");
+            const maxChars = clampInt(args?.maxChars, 12000, 200, 200000);
+            const maxBytes = clampInt(args?.maxBytes, 5000000, 1000, 50_000_000);
+            const { buffer, entry } = await zipReadEntryBuffer(zipPath, innerPath, {
+                maxBytes,
+                caseSensitive,
+            });
+            const all = buffer.toString(encoding);
+            const truncated = all.length > maxChars;
+            const text = truncated ? all.slice(0, maxChars) : all;
+            return {
+                path: zipPath,
+                innerPath: entry.fileName,
+                encoding,
+                sizeBytes: buffer.length,
+                maxChars,
+                truncated,
+                text,
+            };
+        },
+    },
+    {
+        name: "zip_extract_file",
+        description: "Extract a single file from a local ZIP archive to a local output directory (zip-slip safe). Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .zip file (absolute or relative to current working directory).",
+                },
+                innerPath: {
+                    type: "string",
+                    description: "Path of the entry inside the ZIP (use zip_list_files to discover names).",
+                },
+                caseSensitive: {
+                    type: "boolean",
+                    description: "If true, entry match is case-sensitive (default true).",
+                    default: true,
+                },
+                outputDir: {
+                    type: "string",
+                    description: "Directory to extract into (absolute or relative). Default: .tmp/nodebench_zip_extract",
+                    default: ".tmp/nodebench_zip_extract",
+                },
+                overwrite: {
+                    type: "boolean",
+                    description: "If true, overwrites an existing output file (default false).",
+                    default: false,
+                },
+                maxBytes: {
+                    type: "number",
+                    description: "Maximum uncompressed bytes to extract (safety cap).",
+                    default: 25000000,
+                },
+            },
+            required: ["path", "innerPath"],
+        },
+        handler: async (args) => {
+            const zipPath = resolveLocalPath(args?.path);
+            if (!existsSync(zipPath))
+                throw new Error(`File not found: ${zipPath}`);
+            const innerPath = String(args?.innerPath ?? "").trim();
+            if (!innerPath)
+                throw new Error("innerPath is required");
+            const outputDir = resolveLocalPath(args?.outputDir ?? ".tmp/nodebench_zip_extract");
+            const overwrite = args?.overwrite === true;
+            const caseSensitive = args?.caseSensitive !== false;
+            const maxBytes = clampInt(args?.maxBytes, 25000000, 1000, 200_000_000);
+            const { buffer, entry } = await zipReadEntryBuffer(zipPath, innerPath, {
+                maxBytes,
+                caseSensitive,
+            });
+            const extractedPath = safeJoinInsideDir(outputDir, entry.fileName);
+            await (await import("node:fs/promises")).mkdir(path.dirname(extractedPath), { recursive: true });
+            const alreadyExists = existsSync(extractedPath);
+            if (alreadyExists && !overwrite) {
+                return {
+                    path: zipPath,
+                    innerPath: entry.fileName,
+                    outputDir,
+                    extractedPath,
+                    sizeBytes: buffer.length,
+                    existed: true,
+                    overwritten: false,
+                };
+            }
+            await (await import("node:fs/promises")).writeFile(extractedPath, buffer);
+            return {
+                path: zipPath,
+                innerPath: entry.fileName,
+                outputDir,
+                extractedPath,
+                sizeBytes: buffer.length,
+                existed: alreadyExists,
+                overwritten: alreadyExists ? overwrite : false,
+            };
+        },
+    },
+    {
+        name: "read_docx_text",
+        description: "Extract text from a local DOCX (Office OpenXML) file. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .docx file (absolute or relative to current working directory).",
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return (text is truncated).",
+                    default: 12000,
+                },
+                maxBytes: {
+                    type: "number",
+                    description: "Maximum uncompressed bytes to read from word/document.xml (safety cap).",
+                    default: 20000000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxChars = clampInt(args?.maxChars, 12000, 1000, 200000);
+            const maxBytes = clampInt(args?.maxBytes, 20000000, 1000, 200_000_000);
+            const { buffer } = await zipReadEntryBuffer(filePath, "word/document.xml", {
+                maxBytes,
+                caseSensitive: true,
+            });
+            const xml = buffer.toString("utf8");
+            let text = docxXmlToText(xml);
+            const truncated = text.length > maxChars;
+            if (truncated)
+                text = text.slice(0, maxChars);
+            return {
+                path: filePath,
+                source: "word/document.xml",
+                maxChars,
+                truncated,
+                text,
+            };
+        },
+    },
+    {
+        name: "read_pptx_text",
+        description: "Extract text from a local PPTX (Office OpenXML) file. Deterministic, no network.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to a local .pptx file (absolute or relative to current working directory).",
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return (text is truncated).",
+                    default: 12000,
+                },
+                maxSlides: {
+                    type: "number",
+                    description: "Maximum slides to process (default: 60).",
+                    default: 60,
+                },
+                maxBytesPerSlide: {
+                    type: "number",
+                    description: "Maximum uncompressed bytes to read per slide XML (safety cap).",
+                    default: 10000000,
+                },
+            },
+            required: ["path"],
+        },
+        handler: async (args) => {
+            const filePath = resolveLocalPath(args?.path);
+            if (!existsSync(filePath))
+                throw new Error(`File not found: ${filePath}`);
+            const maxChars = clampInt(args?.maxChars, 12000, 1000, 200000);
+            const maxSlides = clampInt(args?.maxSlides, 60, 1, 500);
+            const maxBytesPerSlide = clampInt(args?.maxBytesPerSlide, 10000000, 1000, 200_000_000);
+            const listing = await zipListEntries(filePath, 5000);
+            const slides = listing.entries
+                .map((e) => e.fileName)
+                .filter((n) => /^ppt\/slides\/slide\d+\.xml$/i.test(n))
+                .map((n) => {
+                const m = n.match(/slide(\d+)\.xml$/i);
+                return { name: n, index: m ? Number.parseInt(m[1], 10) : 0 };
+            })
+                .filter((s) => Number.isFinite(s.index) && s.index > 0)
+                .sort((a, b) => a.index - b.index)
+                .slice(0, maxSlides);
+            let text = "";
+            for (const slide of slides) {
+                const { buffer } = await zipReadEntryBuffer(filePath, slide.name, {
+                    maxBytes: maxBytesPerSlide,
+                    caseSensitive: true,
+                });
+                const xml = buffer.toString("utf8");
+                const slideText = pptxSlideXmlToText(xml);
+                text += `\n\n[SLIDE ${slide.index}]\n${slideText}\n`;
+                if (text.length > maxChars)
+                    break;
+            }
+            text = text.trim();
+            const truncated = text.length > maxChars;
+            if (truncated)
+                text = text.slice(0, maxChars);
+            return {
+                path: filePath,
+                slideCount: slides.length,
+                slidesIncluded: slides.map((s) => s.index),
+                maxChars,
+                truncated,
+                text,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=localFileTools.js.map