file-toolkit-mcp 1.0.0

package/src/tools/pdf-tools.js

@@ -0,0 +1,335 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { z } from 'zod';
+import { defineTool } from '../lib/registry.js';
+import { runBatch } from '../lib/batch.js';
+import {
+  expandInputs,
+  resolveOutputDir,
+  uniquePath,
+  assertNotOverwritingInput,
+  displayPath,
+} from '../lib/paths.js';
+import { mergePdfs, splitPdf, pdfToImages } from '../lib/pdf.js';
+import { imagesToPdf, IMAGE_EXTENSIONS } from '../lib/image.js';
+import { buildResult, mdTable, summarize, formatBytes } from '../lib/result.js';
+import { describeError, invalid } from '../lib/errors.js';
+
+const OUTPUT_DIRECTORY = z
+  .string()
+  .optional()
+  .describe('输出目录。不填则默认写到第一个文件所在目录下的 file-toolkit-output 文件夹，原文件不会被改动。');
+
+function safeName(name, fallback) {
+  const cleaned = String(name ?? '')
+    .replace(/[\\/:*?"<>|\u0000-\u001f]/g, '')
+    .trim();
+  return cleaned === '' ? fallback : cleaned;
+}
+
+export function registerPdfTools(server) {
+  defineTool(server, {
+    name: 'pdf_split',
+    title: '拆分 PDF',
+    action: '拆分 PDF',
+    description:
+      '把一个 PDF 拆成多个。three 种方式：each 逐页拆成单独的 PDF；range 只保留指定页码（例如 "1-3,5"）；chunk 每 N 页存成一个文件。支持一次处理多个 PDF。合并 PDF 请用 pdf_merge。',
+    inputSchema: {
+      input_files: z
+        .array(z.string())
+        .describe('要拆分的 PDF 路径，可以传文件或文件夹，支持一次多个。'),
+      mode: z
+        .enum(['each', 'range', 'chunk'])
+        .optional()
+        .describe(
+          '拆分方式。each=每一页拆成独立 PDF（用户说"每一页拆开"时用）；range=只取指定页码；chunk=每 N 页一组。默认 each。',
+        ),
+      pages: z
+        .string()
+        .optional()
+        .describe('mode=range 时必填。页码表达式，如 "1-3,5"、"2-"（第2页到末页）、"-3"（前3页）。'),
+      chunk_size: z.number().optional().describe('mode=chunk 时每份包含的页数，默认 1。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, mode = 'each', pages, chunk_size = 1, output_directory } = args;
+
+      if (mode === 'range' && (pages === undefined || String(pages).trim() === '')) {
+        throw invalid('按页码拆分时必须告诉我要哪些页', '例如 pages="1-3,5"。');
+      }
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['pdf'],
+        label: 'PDF',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const stem = safeName(path.basename(file, path.extname(file)), 'document');
+        const parts = await splitPdf(file, {
+          mode,
+          pages,
+          chunkSize: chunk_size,
+        });
+
+        const written = [];
+        for (const part of parts) {
+          const target = await uniquePath(outputDir, `${stem}-${part.name}.pdf`);
+          assertNotOverwritingInput(target, files);
+          await fs.writeFile(target, part.buffer);
+          written.push({
+            outPath: target,
+            bytes: part.buffer.length,
+            pageCount: part.pageCount,
+            fromPage: part.fromPage,
+            toPage: part.toPage,
+          });
+        }
+        return { parts: written, partCount: written.length };
+      });
+
+      const rows = [];
+      for (const r of results) {
+        if (!r.ok) {
+          rows.push([path.basename(r.file), '—', '—', describeError(r.error, { action: '拆分' })]);
+          continue;
+        }
+        rows.push([
+          path.basename(r.file),
+          `${r.partCount} 份`,
+          r.parts.map((p) => `第${p.fromPage}${p.fromPage === p.toPage ? '' : `-${p.toPage}`}页`).join('、').slice(0, 40),
+          displayPath(path.dirname(r.parts[0]?.outPath ?? outputDir)),
+        ]);
+      }
+
+      const notes = [];
+      if (mode === 'each') {
+        notes.push('已按每页一个文件拆分，文件名格式为「原名-page-页码.pdf」。');
+      } else if (mode === 'range') {
+        notes.push(`已按指定页码 ${pages} 提取。`);
+      } else {
+        notes.push(`已按每 ${chunk_size} 页一份拆分。`);
+      }
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      const totalParts = results.filter((r) => r.ok).reduce((sum, r) => sum + r.partCount, 0);
+
+      return buildResult({
+        title: `✂️ ${summarize('PDF 拆分', results)}共生成 ${totalParts} 个文件。`,
+        table: mdTable(['原文件', '拆出份数', '页码范围', '输出目录'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          sourceFiles: results.length,
+          generatedFiles: totalParts,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'pdf_merge',
+    title: '合并 PDF',
+    action: '合并 PDF',
+    description:
+      '把多个 PDF 按给定顺序合并成一个。input_files 的先后顺序就是要拼接的顺序，所以用户说"把 A 放在最前面"时，把 A 排在数组第一位。',
+    inputSchema: {
+      input_files: z
+        .array(z.string())
+        .describe('要合并的 PDF 路径列表，顺序即拼接顺序。至少 2 个。如果这里传的是文件夹，会按文件名顺序合并。'),
+      output_name: z
+        .string()
+        .optional()
+        .describe('输出的文件名，例如 "合同合集.pdf"。不填则叫 merged.pdf。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, output_name, output_directory } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['pdf'],
+        label: 'PDF',
+      });
+
+      if (files.length < 2) {
+        throw invalid(
+          `合并至少需要 2 个 PDF，现在只找到 ${files.length} 个`,
+          '请确认这些路径下都有 .pdf 文件。',
+        );
+      }
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const merged = await mergePdfs(files);
+
+      const requested = safeName(output_name, 'merged');
+      const fileName = requested.toLowerCase().endsWith('.pdf') ? requested : `${requested}.pdf`;
+      const target = await uniquePath(outputDir, fileName);
+      assertNotOverwritingInput(target, files);
+      await fs.writeFile(target, merged);
+
+      const totalBytes = files.reduce(async (accP, f) => {
+        const acc = await accP;
+        return acc + (await fs.stat(f)).size;
+      }, Promise.resolve(0));
+
+      const rows = files.map((f, i) => [String(i + 1), path.basename(f), displayPath(path.dirname(f))]);
+
+      const notes = [`合并顺序即上表顺序。合并后的文件：\`${displayPath(target)}\``];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `📎 合并完成：${files.length} 个 PDF 已合成 1 个文件（${formatBytes(merged.length)}）。`,
+        table: mdTable(['序号', '文件', '所在位置'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          sourceCount: files.length,
+          outputPath: target,
+          outputBytes: merged.length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'pdf_to_image',
+    title: 'PDF 转图片',
+    action: 'PDF 转图片',
+    description:
+      '把 PDF 的页面渲染成 png 或 jpg 图片。可以只转指定页（例如"第 1、3、5 页"），也可以指定分辨率 dpi（72 屏幕预览、150 普通、300 印刷）。支持一次处理多个 PDF。反向操作用 image_to_pdf。',
+    inputSchema: {
+      input_files: z.array(z.string()).describe('要转换的 PDF 路径，可以传文件或文件夹，支持多个。'),
+      pages: z
+        .string()
+        .optional()
+        .describe('只转这些页，例如 "1,3,5" 或 "1-3"。不填则转换全部页面。'),
+      dpi: z
+        .number()
+        .optional()
+        .describe('输出分辨率，默认 150。数值越大越清晰、文件越大（72 屏幕用、150 普通、300 印刷级）。'),
+      format: z.enum(['png', 'jpg']).optional().describe('输出图片格式，默认 png。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, pages, dpi = 150, format = 'png', output_directory } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['pdf'],
+        label: 'PDF',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+      const ext = format === 'jpg' ? 'jpg' : 'png';
+
+      const results = await runBatch(files, async (file) => {
+        const stem = safeName(path.basename(file, path.extname(file)), 'document');
+        const images = await pdfToImages(file, { pages: pages ?? null, dpi, format });
+        const written = [];
+        for (const image of images) {
+          const target = await uniquePath(outputDir, `${stem}-${image.name}.${ext}`);
+          assertNotOverwritingInput(target, files);
+          await fs.writeFile(target, image.buffer);
+          written.push({
+            outPath: target,
+            page: image.page,
+            width: image.width,
+            height: image.height,
+            bytes: image.buffer.length,
+          });
+        }
+        return { images: written };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', '—', describeError(r.error, { action: '转换' })];
+        }
+        const first = r.images[0];
+        return [
+          path.basename(r.file),
+          `${r.images.length} 张`,
+          first ? `${first.width}×${first.height}` : '—',
+          displayPath(outputDir),
+        ];
+      });
+
+      const totalImages = results.filter((r) => r.ok).reduce((s, r) => s + r.images.length, 0);
+      const notes = [`输出为 ${ext.toUpperCase()}，分辨率 ${dpi} dpi，文件名格式「原名-page-页码.${ext}」。`];
+      if (pages) notes.push(`只转换了指定页码：${pages}`);
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `🖼️ ${summarize('PDF 转图片', results)}共生成 ${totalImages} 张图片。`,
+        table: mdTable(['原文件', '生成张数', '首张尺寸', '输出目录'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          sourceFiles: results.length,
+          generatedImages: totalImages,
+          dpi,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'image_to_pdf',
+    title: '图片转 PDF',
+    action: '图片转 PDF',
+    description:
+      '把一张或多张图片合成 PDF。多张图片会按传入顺序依次成为 PDF 的每一页，所以用户说"按文件名顺序合并"时，把路径按顺序传进来。document 尺寸可选跟随图片或 A4。反向操作用 pdf_to_image。',
+    inputSchema: {
+      input_files: z
+        .array(z.string())
+        .describe('图片路径列表，顺序即 PDF 的页面顺序。可以传文件夹（会按文件名顺序排列）。'),
+      output_name: z.string().optional().describe('输出文件名，例如 "作品集.pdf"。单张图片时默认沿用图片名。'),
+      page_size: z
+        .enum(['fit', 'a4'])
+        .optional()
+        .describe('fit=页面大小跟随图片（默认）；a4=统一放到 A4 页面上居中。'),
+      margin: z.number().optional().describe('页边距，单位像素，默认 0。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, output_name, page_size = 'fit', margin = 0, output_directory } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: IMAGE_EXTENSIONS,
+        label: '图片',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const buffer = await imagesToPdf(files, { pageSize: page_size, margin });
+
+      const fallback = files.length === 1
+        ? safeName(path.basename(files[0], path.extname(files[0])), 'document')
+        : 'merged';
+      const requested = safeName(output_name, fallback);
+      const fileName = requested.toLowerCase().endsWith('.pdf') ? requested : `${requested}.pdf`;
+      const target = await uniquePath(outputDir, fileName);
+      assertNotOverwritingInput(target, files);
+      await fs.writeFile(target, buffer);
+
+      const rows = files.map((f, i) => [String(i + 1), path.basename(f)]);
+      const notes = [
+        `${files.length} 张图片已合成 PDF，共 ${files.length} 页。页面尺寸：${page_size === 'a4' ? 'A4' : '跟随图片'}。`,
+      ];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `📄 图片转 PDF 完成：${files.length} 张图 → 1 个文件（${formatBytes(buffer.length)}）。`,
+        table: mdTable(['页码', '来源图片'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          imageCount: files.length,
+          outputPath: target,
+          outputBytes: buffer.length,
+        },
+      });
+    },
+  });
+}