file-toolkit-mcp 1.0.0

package/src/lib/pdf.js

@@ -0,0 +1,328 @@
+/**
+ * PDF 处理：拆分、合并、转图片。
+ *
+ * 拆分 / 合并用 pdf-lib（纯 JS，MIT，零系统依赖）。
+ * 转图片用 pdfjs-dist + @napi-rs/canvas（均为 Apache-2.0 / MIT，带预编译二进制）。
+ *
+ * 刻意不用 ghostscript / poppler / ImageMagick：
+ * 用户机器上不一定装了它们，而且它们在不同平台上名字和参数都不一样。
+ */
+
+import fs from 'node:fs/promises';
+import { PDFDocument } from 'pdf-lib';
+import { ToolError, invalid } from './errors.js';
+
+/**
+ * 解析页码范围表达式。
+ * 支持 "1-3,5,7-9"、"2-"（第 2 页到末页）、"-3"（前 3 页）。
+ *
+ * @param {string|number[]} spec
+ * @param {number} totalPages
+ * @returns {number[]} 从 1 开始的页号数组，已去重并升序
+ */
+export function parsePageRanges(spec, totalPages) {
+  if (Array.isArray(spec)) {
+    const pages = spec
+      .map((n) => Number(n))
+      .filter((n) => Number.isInteger(n) && n >= 1 && n <= totalPages);
+    return [...new Set(pages)].sort((a, b) => a - b);
+  }
+
+  const text = String(spec ?? '').trim();
+  if (text === '') {
+    throw invalid('页码范围是空的', '例如 "1-3,5" 表示第 1 到 3 页和第 5 页。');
+  }
+
+  const pages = new Set();
+  for (const chunk of text.split(/[,，、\s]+/).filter(Boolean)) {
+    const match = chunk.match(/^(\d*)\s*[-~至]\s*(\d*)$/);
+    if (match) {
+      const start = match[1] === '' ? 1 : Number(match[1]);
+      const end = match[2] === '' ? totalPages : Number(match[2]);
+      if (!Number.isInteger(start) || !Number.isInteger(end) || start > end) {
+        throw invalid(`页码范围写错了：${chunk}`, '正确写法如 "1-3" 或 "5"。');
+      }
+      for (let i = start; i <= end; i += 1) {
+        if (i >= 1 && i <= totalPages) pages.add(i);
+      }
+      continue;
+    }
+    const single = Number(chunk);
+    if (Number.isInteger(single) && single >= 1 && single <= totalPages) {
+      pages.add(single);
+      continue;
+    }
+    throw invalid(
+      `页码 "${chunk}" 超出范围`,
+      `这个 PDF 一共 ${totalPages} 页，页码必须在 1 到 ${totalPages} 之间。`,
+    );
+  }
+
+  if (pages.size === 0) {
+    throw invalid('没有解析出任何有效页码', `这个 PDF 一共 ${totalPages} 页。`);
+  }
+  return [...pages].sort((a, b) => a - b);
+}
+
+/** 读取 PDF 页数等信息 */
+export async function readPdfMeta(file) {
+  const bytes = await fs.readFile(file);
+  let doc;
+  try {
+    doc = await PDFDocument.load(bytes, { updateMetadata: false });
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (/encrypt/i.test(message)) {
+      throw new ToolError('这个 PDF 有密码保护，无法直接处理', {
+        hint: '请先用 PDF 阅读器解除密码，再重新尝试。',
+      });
+    }
+    throw new ToolError('无法读取这个 PDF', {
+      hint: '文件可能已损坏，或者它并不是标准 PDF 文件。',
+    });
+  }
+  return {
+    pages: doc.getPageCount(),
+    title: doc.getTitle() ?? null,
+    author: doc.getAuthor() ?? null,
+  };
+}
+
+/**
+ * 合并多个 PDF，按传入顺序拼装。
+ * @returns {Promise<Buffer>}
+ */
+export async function mergePdfs(files) {
+  if (files.length < 2) {
+    throw invalid('合并至少需要 2 个 PDF 文件', '请再选一个 PDF 一起合并。');
+  }
+
+  const merged = await PDFDocument.create();
+
+  for (const file of files) {
+    const bytes = await fs.readFile(file);
+    let doc;
+    try {
+      doc = await PDFDocument.load(bytes, { updateMetadata: false });
+    } catch (error) {
+      const message = String(error?.message ?? error);
+      if (/encrypt/i.test(message)) {
+        throw new ToolError(`${file} 有密码保护，无法合并`, {
+          hint: '请先解除这个文件的密码。',
+        });
+      }
+      throw new ToolError(`${file} 无法读取`, {
+        hint: '文件可能已损坏，或者它不是标准 PDF。',
+      });
+    }
+    const pages = await merged.copyPages(doc, doc.getPageIndices());
+    for (const page of pages) merged.addPage(page);
+  }
+
+  return Buffer.from(await merged.save());
+}
+
+/**
+ * 拆分 PDF。
+ *
+ * @param {string} file
+ * @param {{ mode: 'each'|'range'|'chunk', pages?: string, chunkSize?: number }} options
+ * @returns {Promise<Array<{ name: string, buffer: Buffer, pageCount: number }>>}
+ */
+export async function splitPdf(file, options = {}) {
+  const { mode = 'each', pages: pagesSpec, chunkSize = 1 } = options;
+
+  const bytes = await fs.readFile(file);
+  let src;
+  try {
+    src = await PDFDocument.load(bytes, { updateMetadata: false });
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (/encrypt/i.test(message)) {
+      throw new ToolError('这个 PDF 有密码保护，无法拆分', {
+        hint: '请先解除密码再试。',
+      });
+    }
+    throw new ToolError('无法读取这个 PDF', {
+      hint: '文件可能已损坏，或者它不是标准 PDF 文件。',
+    });
+  }
+
+  const total = src.getPageCount();
+  const outputs = [];
+
+  if (mode === 'each') {
+    for (let i = 0; i < total; i += 1) {
+      const doc = await PDFDocument.create();
+      const [page] = await doc.copyPages(src, [i]);
+      doc.addPage(page);
+      outputs.push({
+        name: `page-${String(i + 1).padStart(3, '0')}`,
+        buffer: Buffer.from(await doc.save()),
+        pageCount: 1,
+        fromPage: i + 1,
+        toPage: i + 1,
+      });
+    }
+    return outputs;
+  }
+
+  if (mode === 'range') {
+    const wanted = parsePageRanges(pagesSpec, total);
+    const doc = await PDFDocument.create();
+    const copied = await doc.copyPages(src, wanted.map((p) => p - 1));
+    for (const page of copied) doc.addPage(page);
+    outputs.push({
+      name: `range-${wanted[0]}-${wanted[wanted.length - 1]}`,
+      buffer: Buffer.from(await doc.save()),
+      pageCount: wanted.length,
+      fromPage: wanted[0],
+      toPage: wanted[wanted.length - 1],
+      pages: wanted,
+    });
+    return outputs;
+  }
+
+  if (mode === 'chunk') {
+    const size = Number(chunkSize);
+    if (!Number.isInteger(size) || size < 1) {
+      throw invalid('每组页数必须是大于 0 的整数', '例如 5 表示每 5 页存成一个 PDF。');
+    }
+    let index = 0;
+    for (let start = 0; start < total; start += size) {
+      const indices = [];
+      for (let i = start; i < Math.min(start + size, total); i += 1) indices.push(i);
+      const doc = await PDFDocument.create();
+      const copied = await doc.copyPages(src, indices);
+      for (const page of copied) doc.addPage(page);
+      index += 1;
+      outputs.push({
+        name: `part-${String(index).padStart(3, '0')}`,
+        buffer: Buffer.from(await doc.save()),
+        pageCount: indices.length,
+        fromPage: indices[0] + 1,
+        toPage: indices[indices.length - 1] + 1,
+      });
+    }
+    return outputs;
+  }
+
+  throw invalid(`不支持的拆分方式：${mode}`, '可选 each（逐页）、range（指定页码）、chunk（每 N 页）。');
+}
+
+let pdfjsPromise = null;
+
+/**
+ * 惰性加载 pdfjs 与 canvas。
+ * 这两者只有在真正需要把 PDF 转成图片时才加载，避免拖慢服务启动。
+ */
+async function loadPdfJs() {
+  if (!pdfjsPromise) {
+    pdfjsPromise = (async () => {
+      const canvas = await import('@napi-rs/canvas');
+      // pdfjs 在 Node 环境里会用到这些浏览器全局对象
+      globalThis.DOMMatrix ??= canvas.DOMMatrix;
+      globalThis.ImageData ??= canvas.ImageData;
+      globalThis.Path2D ??= canvas.Path2D;
+      const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+      return { pdfjs, canvas };
+    })();
+  }
+  return pdfjsPromise;
+}
+
+/**
+ * 把 PDF 的指定页面渲染成图片。
+ *
+ * @param {string} file
+ * @param {{ pages?: string|number[], dpi?: number, format?: 'png'|'jpg' }} options
+ * @returns {Promise<Array<{ name: string, buffer: Buffer, width: number, height: number, page: number }>>}
+ */
+export async function pdfToImages(file, options = {}) {
+  const { pages: pagesSpec = null, dpi = 150, format = 'png' } = options;
+
+  const targetFormat = String(format).toLowerCase().replace(/^\./, '');
+  if (!['png', 'jpg', 'jpeg'].includes(targetFormat)) {
+    throw invalid(`PDF 只能转成 png 或 jpg，收到的是：${format}`);
+  }
+  const wanted = targetFormat === 'png' ? 'png' : 'jpeg';
+
+  const dpiNum = Number(dpi);
+  if (!Number.isFinite(dpiNum) || dpiNum < 36 || dpiNum > 600) {
+    throw invalid('分辨率（dpi）需要在 36 到 600 之间', '常用值是 72（屏幕）、150（普通）、300（印刷）。');
+  }
+
+  const { pdfjs, canvas } = await loadPdfJs();
+  const data = new Uint8Array(await fs.readFile(file));
+
+  let loadingTask;
+  let doc;
+  try {
+    loadingTask = pdfjs.getDocument({
+      data,
+      useSystemFonts: true,
+      isEvalSupported: false,
+      disableFontFace: true,
+    });
+    doc = await loadingTask.promise;
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (/password/i.test(message)) {
+      throw new ToolError('这个 PDF 有密码保护，无法转成图片', {
+        hint: '请先解除密码再试。',
+      });
+    }
+    throw new ToolError('无法读取这个 PDF', {
+      hint: '文件可能已损坏，或者它不是标准 PDF 文件。',
+    });
+  }
+
+  try {
+    const total = doc.numPages;
+    const pageNumbers = pagesSpec
+      ? parsePageRanges(pagesSpec, total)
+      : Array.from({ length: total }, (_, i) => i + 1);
+
+    const scale = dpiNum / 72;
+    const results = [];
+
+    for (const pageNumber of pageNumbers) {
+      const page = await doc.getPage(pageNumber);
+      const viewport = page.getViewport({ scale });
+      const target = canvas.createCanvas(
+        Math.max(1, Math.ceil(viewport.width)),
+        Math.max(1, Math.ceil(viewport.height)),
+      );
+      const ctx = target.getContext('2d');
+      ctx.fillStyle = '#ffffff';
+      ctx.fillRect(0, 0, target.width, target.height);
+
+      await page.render({ canvasContext: ctx, viewport }).promise;
+
+      const buffer = wanted === 'png'
+        ? target.toBuffer('image/png')
+        : target.toBuffer('image/jpeg', 92);
+
+      results.push({
+        name: `page-${String(pageNumber).padStart(3, '0')}`,
+        buffer,
+        width: target.width,
+        height: target.height,
+        page: pageNumber,
+      });
+
+      page.cleanup();
+    }
+
+    return results;
+  } finally {
+    // pdfjs 各版本清理接口不一致，逐个尝试，清理失败不能影响已经拿到的结果
+    try {
+      if (typeof loadingTask?.destroy === 'function') await loadingTask.destroy();
+      else if (typeof doc?.destroy === 'function') await doc.destroy();
+      else if (typeof doc?.cleanup === 'function') await doc.cleanup();
+    } catch {
+      // 忽略清理阶段的异常
+    }
+  }
+}

package/src/lib/registry.js

@@ -0,0 +1,53 @@
+/**
+ * 工具注册器。
+ *
+ * 所有工具共用一套外壳，保证：
+ *   - 成功时统一返回 Markdown 文本
+ *   - 失败时统一把异常翻译成自然语言，并且带上 isError 标记
+ *   - 工具都声明 openWorldHint: false（明确告诉客户端：这个连接器不访问外网）
+ */
+
+import { describeError } from './errors.js';
+
+export function defineTool(server, config) {
+  const {
+    name,
+    title,
+    description,
+    inputSchema,
+    annotations = {},
+    action,
+    handler,
+  } = config;
+
+  server.registerTool(
+    name,
+    {
+      title,
+      description,
+      inputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+        ...annotations,
+      },
+    },
+    async (args) => {
+      try {
+        const text = await handler(args ?? {});
+        return { content: [{ type: 'text', text }] };
+      } catch (error) {
+        if (process.env.FILE_TOOLKIT_DEBUG) {
+          console.error(`[${name}]`, error);
+        }
+        const message = describeError(error, { action });
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `⚠️ ${message}` }],
+        };
+      }
+    },
+  );
+}

package/src/lib/rename.js

@@ -0,0 +1,285 @@
+/**
+ * 批量重命名。
+ *
+ * 安全设计（这是本工具和「让模型自己写脚本」最大的区别）：
+ *   1. 默认只预览，不执行。必须显式传 confirm=true 才真的改名。
+ *   2. 预览阶段就检测冲突：目标重名、目标已存在、与本次其他文件撞车。
+ *   3. 执行采用两阶段（先改临时名、再改目标名），避免 a→b、b→a 这类互换死锁。
+ *   4. 全过程写日志，可用 rename_undo 一键回滚。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { invalid } from './errors.js';
+
+export const RENAME_LOG_PREFIX = 'rename-log-';
+
+const TEMP_PREFIX = '.file-toolkit-tmp-';
+
+/** 把 pattern 里的占位符替换掉：{n}、{n:3}、{name}、{ext} */
+function renderPattern(pattern, { index, name, ext }) {
+  return String(pattern)
+    .replace(/\{n(?::(\d+))?\}/gi, (_, pad) =>
+      String(index).padStart(pad ? Number(pad) : 1, '0'),
+    )
+    .replace(/\{name\}/gi, name)
+    .replace(/\{ext\}/gi, ext);
+}
+
+/**
+ * 计算单个文件的新文件名。
+ *
+ * 处理顺序：
+ *   原始基础名 -> find/replace 替换 -> pattern 重写基础名 -> 加前后缀 -> 换扩展名
+ */
+export function buildNewName(filePath, options, index) {
+  const {
+    pattern = null,
+    prefix = '',
+    suffix = '',
+    find = null,
+    replace = '',
+    newExtension = null,
+  } = options;
+
+  const ext = path.extname(filePath);
+  const extName = ext.replace(/^\./, '');
+  const baseName = path.basename(filePath, ext);
+
+  let nextBase = baseName;
+  if (find !== null && find !== undefined && String(find) !== '') {
+    nextBase = nextBase.split(String(find)).join(String(replace ?? ''));
+  }
+  if (pattern) {
+    nextBase = renderPattern(pattern, { index, name: nextBase, ext: extName });
+  }
+  nextBase = `${prefix ?? ''}${nextBase}${suffix ?? ''}`;
+
+  const finalExt = newExtension
+    ? `.${String(newExtension).replace(/^\./, '')}`
+    : ext;
+
+  const nextName = `${nextBase}${finalExt}`;
+
+  return {
+    from: path.basename(filePath),
+    to: nextName,
+    directory: path.dirname(filePath),
+    fromPath: path.resolve(filePath),
+    toPath: path.join(path.dirname(filePath), nextName),
+  };
+}
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 生成重命名方案，并标注每个文件的状态。
+ *
+ * status:
+ *   ready     可以执行
+ *   unchanged 新名字和原名一样，跳过
+ *   conflict  有冲突，会被跳过（conflictReason 说明原因）
+ */
+export async function planRename(files, options = {}) {
+  const startNumber = Number.isFinite(options.startNumber) ? Number(options.startNumber) : 1;
+  const sourceSet = new Set(files.map((f) => path.resolve(f)));
+  const plannedTargets = new Map();
+
+  const items = [];
+  let index = startNumber;
+
+  for (const file of files) {
+    const item = buildNewName(file, options, index);
+    index += 1;
+
+    let status = 'ready';
+    let conflictReason = '';
+
+    if (item.toPath === item.fromPath) {
+      status = 'unchanged';
+    } else if (plannedTargets.has(item.toPath)) {
+      status = 'conflict';
+      conflictReason = '和本次的另一个文件重名';
+    } else if (sourceSet.has(item.toPath)) {
+      // 目标正好是本次要改名的另一个文件 —— 靠两阶段执行可以安全处理
+      status = 'ready';
+    } else if (await exists(item.toPath)) {
+      status = 'conflict';
+      conflictReason = '同名文件已存在';
+    }
+
+    if (status === 'ready') plannedTargets.set(item.toPath, item.fromPath);
+
+    items.push({ ...item, status, conflictReason });
+  }
+
+  return items;
+}
+
+/**
+ * 执行重命名。
+ *
+ * @returns {Promise<{ done: object[], skipped: object[], logPath: string|null }>}
+ */
+export async function executeRename(items, { logDirectory }) {
+  const runnable = items.filter((i) => i.status === 'ready');
+  const skipped = items.filter((i) => i.status !== 'ready');
+
+  if (runnable.length === 0) {
+    return { done: [], skipped, logPath: null };
+  }
+
+  const stamp = Date.now();
+  const moved = [];
+
+  // 阶段一：全部改成临时名，彻底消除命名冲突
+  try {
+    for (let i = 0; i < runnable.length; i += 1) {
+      const item = runnable[i];
+      const tmpPath = path.join(item.directory, `${TEMP_PREFIX}${stamp}-${i}`);
+      await fs.rename(item.fromPath, tmpPath);
+      moved.push({ ...item, tmpPath });
+    }
+  } catch (error) {
+    // 阶段一失败：把已经改名的还原回去
+    for (const m of moved.reverse()) {
+      try {
+        await fs.rename(m.tmpPath, m.fromPath);
+      } catch {
+        // 还原失败只能跳过，继续还原其余的
+      }
+    }
+    throw error;
+  }
+
+  // 阶段二：临时名 -> 目标名
+  const done = [];
+  try {
+    for (const item of moved) {
+      await fs.rename(item.tmpPath, item.toPath);
+      done.push(item);
+    }
+  } catch (error) {
+    // 阶段二失败：尽力还原
+    for (const item of done) {
+      try {
+        await fs.rename(item.toPath, item.fromPath);
+      } catch {
+        // 忽略
+      }
+    }
+    for (const item of moved) {
+      try {
+        await fs.rename(item.tmpPath, item.fromPath);
+      } catch {
+        // 忽略
+      }
+    }
+    throw error;
+  }
+
+  // 写回滚日志
+  await fs.mkdir(logDirectory, { recursive: true });
+  const logPath = path.join(logDirectory, `${RENAME_LOG_PREFIX}${stamp}.json`);
+  await fs.writeFile(
+    logPath,
+    JSON.stringify(
+      {
+        createdAt: new Date().toISOString(),
+        entries: done.map((d) => ({ from: d.fromPath, to: d.toPath })),
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+
+  return { done, skipped, logPath };
+}
+
+/**
+ * 找到最近一次的改名日志。
+ */
+export async function findLatestLog(logDirectory, explicitPath = null) {
+  if (explicitPath) {
+    return path.resolve(explicitPath);
+  }
+  let entries = [];
+  try {
+    entries = await fs.readdir(logDirectory);
+  } catch {
+    return null;
+  }
+  const logs = entries
+    .filter((name) => name.startsWith(RENAME_LOG_PREFIX) && name.endsWith('.json'))
+    .sort();
+  if (logs.length === 0) return null;
+  return path.join(logDirectory, logs[logs.length - 1]);
+}
+
+/**
+ * 回滚一次重命名。
+ */
+export async function undoRename(logPath) {
+  const raw = await fs.readFile(logPath, 'utf8');
+  let log;
+  try {
+    log = JSON.parse(raw);
+  } catch {
+    throw invalid('这个回滚记录文件已损坏，无法解析', `路径：${logPath}`);
+  }
+
+  const entries = Array.isArray(log?.entries) ? log.entries : [];
+  if (entries.length === 0) {
+    return { restored: [], missing: [] };
+  }
+
+  const restored = [];
+  const missing = [];
+  const moved = [];
+
+  // 同样两阶段，避免反向也出现互换冲突
+  const usable = [];
+  for (const entry of entries) {
+    if (await exists(entry.to)) {
+      usable.push(entry);
+    } else {
+      missing.push(entry);
+    }
+  }
+
+  for (let i = 0; i < usable.length; i += 1) {
+    const entry = usable[i];
+    const dir = path.dirname(entry.to);
+    const tmpPath = path.join(dir, `${TEMP_PREFIX}undo-${Date.now()}-${i}`);
+    await fs.rename(entry.to, tmpPath);
+    moved.push({ entry, tmpPath });
+  }
+
+  for (const m of moved) {
+    const target = m.entry.from;
+    // 原名字已经被占用时，退让为一个带后缀的备份名，绝不覆盖
+    let finalTarget = target;
+    if (await exists(target)) {
+      const ext = path.extname(target);
+      const base = path.basename(target, ext);
+      finalTarget = path.join(path.dirname(target), `${base}.restored${ext}`);
+      let counter = 1;
+      while (await exists(finalTarget)) {
+        counter += 1;
+        finalTarget = path.join(path.dirname(target), `${base}.restored-${counter}${ext}`);
+      }
+    }
+    await fs.rename(m.tmpPath, finalTarget);
+    restored.push({ from: m.entry.to, to: finalTarget });
+  }
+
+  return { restored, missing };
+}