file-toolkit-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 File Toolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# file-toolkit-mcp
+
+为 WorkBuddy 连接器「**文件工具箱**」提供能力的 MCP 服务，包含 15 个确定性的文件处理工具。
+
+**完全在本机运行**：不联网、不上传文件、不需要 API Key、不依赖任何付费服务。
+
+## 工具清单
+
+| 工具 | 作用 |
+|---|---|
+| `image_compress` | 压缩 jpg / png / webp，可按目标体积自动逼近画质 |
+| `image_convert` | jpg / png / webp 互转，png 透明背景转 jpg 时自动铺白底 |
+| `image_resize` | 按宽高或百分比缩放，支持只缩不放 |
+| `pdf_split` | 逐页拆分 / 按页码提取 / 每 N 页一组 |
+| `pdf_merge` | 按指定顺序合并多个 PDF |
+| `pdf_to_image` | PDF 页面渲染成 png / jpg，可指定页码和 dpi |
+| `image_to_pdf` | 一张或多张图片合成 PDF |
+| `json_format` | JSON 美化 / 压缩 / 校验（报错会指出行列位置） |
+| `csv_to_json` | CSV / TSV 转 JSON，自动识别 UTF-8 / GBK |
+| `json_to_csv` | JSON 转 CSV，输出带 BOM（Excel 打开中文不乱码） |
+| `markdown_to_html` | Markdown 转 HTML，可选完整网页或片段 |
+| `html_to_markdown` | HTML 转 Markdown，保留表格与代码块 |
+| `batch_rename` | 批量重命名，默认只预览，支持序号模板 |
+| `rename_undo` | 撤销上一次批量重命名 |
+| `file_info` | 文件大小、类型、时间、图片尺寸、PDF 页数 |
+
+## 使用方式
+
+由 WorkBuddy 连接器自动拉起，用户无需手动执行：
+
+```bash
+npx -y file-toolkit-mcp@1.0.0
+```
+
+也可以在任何支持 MCP 的客户端里手动配置（stdio 传输）：
+
+```json
+{
+  "mcpServers": {
+    "file-toolkit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "file-toolkit-mcp@1.0.0"]
+    }
+  }
+}
+```
+
+## 输出规则
+
+所有工具遵循同一套输出策略：
+
+- 结果写到「第一个输入文件所在目录」下的 `file-toolkit-output/` 文件夹
+- **绝不覆盖原文件**，同名时自动加序号
+- 可以传文件夹，会自动收集里面的文件批量处理
+- 批量处理时单个文件失败不会中断整批，结果里分别列出成功与失败
+
+## 隐私
+
+所有处理都在调用方的机器上完成。本服务不发起任何网络请求，
+不读取处理目标以外的文件，也不写入 `file-toolkit-output/` 以外的位置
+（批量重命名会在原地改名，但会写一份可回滚的记录）。
+
+## 依赖
+
+运行时由 WorkBuddy 托管的 Node.js（>= 18.17）提供，用户端无需预装环境。
+
+- `sharp`（Apache-2.0）图片编解码
+- `pdf-lib`（MIT）PDF 读写
+- `pdfjs-dist`（Apache-2.0）+ `@napi-rs/canvas`（MIT）PDF 光栅化
+- `marked`（MIT）、`turndown`（MIT）文本格式转换
+- `iconv-lite`（MIT）中文编码识别
+- `@modelcontextprotocol/sdk`（MIT）
+
+不含任何 AGPL / GPL 组件。
+
+## 许可证
+
+MIT

package/bin/file-toolkit-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * File Toolkit MCP Server 的可执行入口。
+ * WorkBuddy 通过 `npx -y file-toolkit-mcp` 拉起的就是这个文件。
+ */
+import '../src/server.js';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "file-toolkit-mcp",
+  "version": "1.0.0",
+  "description": "Local file toolkit MCP server for WorkBuddy. Compress, convert and resize images; split, merge and rasterize PDFs; convert CSV/JSON/Markdown; batch rename and inspect files. 100% local processing, no uploads, no paid APIs.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "bin": {
+    "file-toolkit-mcp": "bin/file-toolkit-mcp.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "workbuddy",
+    "file",
+    "image",
+    "pdf",
+    "convert",
+    "compress",
+    "local"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "@napi-rs/canvas": "^1.0.9",
+    "iconv-lite": "^0.7.3",
+    "marked": "^18.0.14",
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^6.3.289",
+    "sharp": "^0.35.5",
+    "turndown": "^7.2.4",
+    "zod": "^4.6.5"
+  }
+}

package/src/lib/batch.js

@@ -0,0 +1,53 @@
+/**
+ * 逐文件批处理：单个文件失败不影响其余文件。
+ * 「批量处理时一个坏文件不应该毁掉整批任务」是这个连接器的核心价值之一。
+ */
+
+import { ToolError, describeError } from './errors.js';
+
+/**
+ * @param {string[]} files
+ * @param {(file: string, index: number) => Promise<object>} worker
+ */
+export async function runBatch(files, worker, { onProgress = null } = {}) {
+  const results = [];
+  for (let i = 0; i < files.length; i += 1) {
+    const file = files[i];
+    try {
+      const value = await worker(file, i);
+      results.push({ ok: true, file, ...value });
+    } catch (error) {
+      results.push({ ok: false, file, error });
+    }
+    if (onProgress) onProgress(i + 1, files.length);
+  }
+
+  assertNotAllFailed(results);
+  return results;
+}
+
+/**
+ * 一个文件都没成功时，把错误抛出去。
+ *
+ * 为什么必须这样做：批量处理时我们把「单文件失败」降级成表格里的一行，
+ * 但如果全部失败（通常是路径写错、页码越界、格式不支持这类用户侧问题），
+ * 继续返回一个「看起来正常」的结果，会让模型误以为任务已经完成了。
+ * 这种情况必须明确报错，模型才能自我纠正。
+ */
+function assertNotAllFailed(results) {
+  if (results.length === 0) return;
+  if (results.some((r) => r.ok)) return;
+
+  const first = results[0].error;
+
+  // 用户侧的问题（参数不合法、页码越界等）本身就是 ToolError，原样抛出，保留修复建议
+  if (first instanceof ToolError) throw first;
+
+  const message = describeError(first, {});
+  throw new ToolError(
+    results.length === 1
+      ? message
+      : `${results.length} 个文件全部处理失败。第一个错误：${message}`,
+    { hint: '请检查文件路径、文件格式和参数是否正确。' },
+  );
+}

package/src/lib/csv.js

@@ -0,0 +1,178 @@
+/**
+ * CSV 编解码（RFC 4180），针对中文场景做了处理：
+ *   - 自动识别并剥掉 UTF-8 BOM
+ *   - 写出时默认带 BOM，保证 Excel 直接双击打开中文不乱码
+ *   - 正确处理引号包裹的逗号、换行、双引号转义
+ *   - CRLF / LF 两种换行都能读
+ *
+ * 刻意不引入第三方 CSV 库：这里的行为需要完全可预期，
+ * 而且少一个依赖就少一份 npx 首次安装的体积和失败概率。
+ */
+
+const BOM = '\uFEFF';
+
+/**
+ * 解析 CSV 文本。
+ * @param {string} text
+ * @param {{ delimiter?: string }} [options]
+ * @returns {string[][]} 二维数组，行 × 列
+ */
+export function parseCsv(text, options = {}) {
+  const { delimiter = ',' } = options;
+  let source = String(text ?? '');
+  if (source.charCodeAt(0) === 0xfeff) source = source.slice(1);
+
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  let i = 0;
+
+  while (i < source.length) {
+    const ch = source[i];
+
+    if (inQuotes) {
+      if (ch === '"') {
+        if (source[i + 1] === '"') {
+          field += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i += 1;
+        continue;
+      }
+      field += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      inQuotes = true;
+      i += 1;
+      continue;
+    }
+    if (ch === delimiter) {
+      row.push(field);
+      field = '';
+      i += 1;
+      continue;
+    }
+    if (ch === '\r') {
+      if (source[i + 1] === '\n') i += 1;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+      i += 1;
+      continue;
+    }
+    if (ch === '\n') {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+      i += 1;
+      continue;
+    }
+    field += ch;
+    i += 1;
+  }
+
+  if (field !== '' || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+
+  return rows;
+}
+
+/**
+ * 把二维数组还原成 CSV 文本。
+ * @param {string[]} headers
+ * @param {Array<Array<unknown>>} rows
+ * @param {{ delimiter?: string, bom?: boolean, eol?: string }} [options]
+ */
+export function serializeCsv(headers, rows, options = {}) {
+  const { delimiter = ',', bom = true, eol = '\n' } = options;
+
+  const escape = (value) => {
+    if (value === null || value === undefined) return '';
+    const s = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    if (s.includes('"') || s.includes(delimiter) || s.includes('\n') || s.includes('\r')) {
+      return `"${s.replace(/"/g, '""')}"`;
+    }
+    return s;
+  };
+
+  const lines = [];
+  if (Array.isArray(headers) && headers.length > 0) {
+    lines.push(headers.map(escape).join(delimiter));
+  }
+  for (const row of rows) {
+    lines.push(row.map(escape).join(delimiter));
+  }
+
+  return (bom ? BOM : '') + lines.join(eol) + eol;
+}
+
+/**
+ * CSV 行 -> 对象数组。
+ * @param {string[][]} rows
+ * @param {{ headers?: string[] }} [options] 不传则把第一行当表头
+ */
+export function rowsToRecords(rows, options = {}) {
+  const meaningful = rows.filter(
+    (r) => !(r.length === 1 && String(r[0] ?? '').trim() === ''),
+  );
+  if (meaningful.length === 0) return { headers: [], records: [] };
+
+  const explicit = options.headers;
+  const headers = explicit && explicit.length
+    ? explicit.map(String)
+    : meaningful[0].map((h, idx) => {
+        const name = String(h ?? '').trim();
+        return name === '' ? `column_${idx + 1}` : name;
+      });
+
+  const body = explicit && explicit.length ? meaningful : meaningful.slice(1);
+  const records = body.map((row) => {
+    const obj = {};
+    headers.forEach((key, idx) => {
+      obj[key] = row[idx] === undefined ? '' : String(row[idx]);
+    });
+    return obj;
+  });
+
+  return { headers, records };
+}
+
+/**
+ * 对象数组 -> 二维数组（按表头顺序取列，缺失的补空字符串）。
+ */
+export function recordsToRows(records, headers) {
+  return records.map((rec) =>
+    headers.map((key) => {
+      const v = rec?.[key];
+      return v === null || v === undefined ? '' : v;
+    }),
+  );
+}
+
+/**
+ * 从对象数组里收集表头：保持出现顺序，并补齐各对象键的并集。
+ */
+export function collectHeaders(records) {
+  const headers = [];
+  const seen = new Set();
+  for (const rec of records) {
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) continue;
+    for (const key of Object.keys(rec)) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        headers.push(key);
+      }
+    }
+  }
+  return headers;
+}

package/src/lib/dataops.js

@@ -0,0 +1,78 @@
+/**
+ * 数据格式处理：JSON 美化 / 压缩 / 校验。
+ *
+ * 刻意保留键的原始顺序（JSON.parse 本身保序），
+ * 并且不做任何数值精度上的自作主张（大整数用 JSON.rawJSON 思路规避不了，
+ * 所以这里只保证不做多余转换，原样输出）。
+ */
+
+/**
+ * @param {string} text 原始 JSON 文本
+ * @param {{ mode?: 'pretty'|'minify'|'validate', indent?: number }} [options]
+ */
+export function processJson(text, options = {}) {
+  const { mode = 'pretty', indent = 2 } = options;
+  const source = String(text ?? '').replace(/^\uFEFF/, '').trim();
+
+  if (source === '') {
+    return { ok: false, error: '内容是空的，没有可以解析的 JSON' };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    return { ok: false, error: describeJsonError(error, source) };
+  }
+
+  const stats = describeShape(parsed);
+
+  if (mode === 'validate') {
+    return { ok: true, parsed, stats, output: null };
+  }
+
+  if (mode === 'minify') {
+    return { ok: true, parsed, stats, output: JSON.stringify(parsed) };
+  }
+
+  const space = Number.isFinite(indent) ? Math.min(8, Math.max(0, Number(indent))) : 2;
+  return { ok: true, parsed, stats, output: JSON.stringify(parsed, null, space) };
+}
+
+/**
+ * 把 JSON.parse 的报错翻译成带行列号的中文提示。
+ */
+function describeJsonError(error, source) {
+  const message = String(error?.message ?? error);
+  const positionMatch = message.match(/position\s+(\d+)/i);
+
+  if (positionMatch) {
+    const position = Number(positionMatch[1]);
+    const before = source.slice(0, position);
+    const line = before.split('\n').length;
+    const column = position - before.lastIndexOf('\n');
+    return `JSON 有语法错误：第 ${line} 行第 ${column} 个字符附近（${message}）`;
+  }
+
+  return `JSON 有语法错误：${message}`;
+}
+
+/** 描述 JSON 结构，方便用户确认"解析对了没有" */
+export function describeShape(value) {
+  if (Array.isArray(value)) {
+    return {
+      type: '数组',
+      length: value.length,
+      firstItemType: value.length > 0 ? typeof value[0] : null,
+    };
+  }
+  if (value === null) return { type: 'null' };
+  if (typeof value === 'object') {
+    return {
+      type: '对象',
+      keys: Object.keys(value).length,
+      keyNames: Object.keys(value).slice(0, 20),
+    };
+  }
+  return { type: typeof value };
+}

package/src/lib/encoding.js

@@ -0,0 +1,66 @@
+/**
+ * 文本解码。
+ *
+ * 中文用户从 Excel / WPS 导出的 CSV 经常是 GBK 而不是 UTF-8，
+ * 直接按 UTF-8 读会整片乱码。这里按 BOM -> 严格 UTF-8 -> GBK 的顺序自动判断。
+ */
+
+import iconv from 'iconv-lite';
+
+/**
+ * @param {Buffer} buffer
+ * @param {string|null} [explicitEncoding] 用户明确指定的编码，如 'utf-8'、'gbk'、'big5'
+ * @returns {{ text: string, encoding: string, guessed: boolean }}
+ */
+export function decodeBuffer(buffer, explicitEncoding = null) {
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+
+  if (explicitEncoding) {
+    const normalized = String(explicitEncoding).toLowerCase().replace(/[-_]/g, '');
+    return {
+      text: iconv.decode(buf, normalized),
+      encoding: explicitEncoding,
+      guessed: false,
+    };
+  }
+
+  // 1) BOM 优先
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+    return { text: buf.subarray(3).toString('utf8'), encoding: 'utf-8 (BOM)', guessed: true };
+  }
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+    return { text: iconv.decode(buf, 'utf16le'), encoding: 'utf-16le', guessed: true };
+  }
+  if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+    return { text: iconv.decode(buf, 'utf16be'), encoding: 'utf-16be', guessed: true };
+  }
+
+  // 2) 严格 UTF-8 校验：能过就是 UTF-8
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    return { text, encoding: 'utf-8', guessed: true };
+  } catch {
+    // 继续往下猜
+  }
+
+  // 3) 退到 GBK —— 中文 Windows 环境导出 CSV 的默认编码
+  return { text: iconv.decode(buf, 'gbk'), encoding: 'gbk', guessed: true };
+}
+
+/**
+ * 猜测 CSV 分隔符：看第一行里哪个候选出现得最多。
+ */
+export function detectDelimiter(text) {
+  const firstLine = String(text ?? '').split(/\r?\n/)[0] ?? '';
+  const candidates = [',', '\t', ';', '|'];
+  let best = ',';
+  let bestCount = 0;
+  for (const candidate of candidates) {
+    const count = firstLine.split(candidate).length - 1;
+    if (count > bestCount) {
+      best = candidate;
+      bestCount = count;
+    }
+  }
+  return best;
+}

package/src/lib/errors.js

@@ -0,0 +1,98 @@
+/**
+ * 统一错误处理。
+ *
+ * 核心原则：绝不把底层异常（Traceback、libvips 报错、spawn ENOENT……）直接抛给用户，
+ * 一律转换成可读的自然语言说明，并尽量给出下一步该怎么做。
+ */
+
+export class ToolError extends Error {
+  constructor(message, { hint = '', cause = null } = {}) {
+    super(message);
+    this.name = 'ToolError';
+    this.hint = hint;
+    this.cause = cause;
+  }
+}
+
+const SYSTEM_MESSAGES = {
+  ENOENT: '找不到这个文件或目录，请确认路径是否正确（路径里有空格或中文时不需要额外加引号）',
+  EACCES: '没有权限访问这个文件，请检查文件权限，或换一个可写的目录再试',
+  EPERM: '系统拒绝了这个操作，文件可能是只读的，或所在目录受保护',
+  EISDIR: '这是一个目录，但这个操作需要的是文件',
+  ENOTDIR: '路径中有一段不是目录，请检查路径是否写错',
+  ENOSPC: '磁盘空间不足，请清理一些空间后重试',
+  EBUSY: '文件正被其他程序占用，请先关闭该程序再试',
+  EMFILE: '同时打开的文件过多，请减少一次处理的文件数量',
+  EROFS: '目标位置是只读的，无法写入',
+  EEXIST: '目标文件已存在，为避免覆盖已中止操作',
+};
+
+const PATTERN_MESSAGES = [
+  [/unsupported image format|Input file contains unsupported|VipsForeignLoad/i,
+    '这个文件不是能识别的图片格式，或者图片已损坏'],
+  [/invalid pdf structure|failed to parse pdf|no pdf header|InvalidPDFException/i,
+    '无法读取这个 PDF，文件可能已损坏，或者它并不是一个标准 PDF'],
+  [/password|encrypted|EncryptedPDF/i,
+    '这个 PDF 带有密码保护，请先解除密码再处理'],
+  [/premature end|corrupt|truncated|unexpected end/i,
+    '文件内容不完整，可能在传输或保存过程中损坏了'],
+  [/unexpected token|json\.parse|Unexpected non-whitespace/i,
+    'JSON 内容有语法错误，无法解析'],
+  [/out of memory|heap out of memory|allocation failed/i,
+    '内存不足，请减少一次处理的文件数量，或降低输出分辨率'],
+  [/ENOTFOUND|EAI_AGAIN|ECONNREFUSED|fetch failed/i,
+    '网络请求失败（本工具不依赖网络，通常说明环境异常）'],
+];
+
+/**
+ * 把任意异常描述成一句用户能看懂的话。
+ *
+ * @param {unknown} error 原始异常
+ * @param {{ action?: string, target?: string }} [context] 正在做的事情和目标，用于补全句子
+ * @returns {string}
+ */
+export function describeError(error, context = {}) {
+  const { action, target } = context;
+  const prefix = action ? `${action}失败` : '操作失败';
+  const where = target ? `（${target}）` : '';
+
+  if (error instanceof ToolError) {
+    const hint = error.hint ? ` ${error.hint}` : '';
+    return `${prefix}${where}：${error.message}${hint}`;
+  }
+
+  const raw = error && typeof error === 'object' && 'message' in error
+    ? String(error.message)
+    : String(error ?? '未知错误');
+
+  // 1) 系统错误码优先：Node 的异常对象上带 code
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  if (code && SYSTEM_MESSAGES[code]) {
+    return `${prefix}${where}：${SYSTEM_MESSAGES[code]}`;
+  }
+
+  // 2) 第三方库的报错按特征匹配
+  for (const [pattern, message] of PATTERN_MESSAGES) {
+    if (pattern.test(raw)) {
+      return `${prefix}${where}：${message}`;
+    }
+  }
+
+  // 3) 兜底：截断原始信息，避免把大段堆栈甩给用户
+  const brief = raw.split('\n')[0].slice(0, 160);
+  return `${prefix}${where}：${brief}`;
+}
+
+/**
+ * 校验类错误。参数不合法时用它，比通用异常更容易生成清晰的提示。
+ */
+export function invalid(message, hint = '') {
+  return new ToolError(message, { hint });
+}
+
+/**
+ * 断言辅助：条件不满足就抛出参数错误。
+ */
+export function assertThat(condition, message, hint = '') {
+  if (!condition) throw invalid(message, hint);
+}