file-toolkit-mcp 1.0.0

package/src/tools/data-tools.js

@@ -0,0 +1,497 @@
+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 { decodeBuffer, detectDelimiter } from '../lib/encoding.js';
+import {
+  parseCsv,
+  serializeCsv,
+  rowsToRecords,
+  recordsToRows,
+  collectHeaders,
+} from '../lib/csv.js';
+import { processJson } from '../lib/dataops.js';
+import { markdownToHtml, htmlToMarkdown, guessTitle } from '../lib/text.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 文件夹，原文件不会被改动。');
+
+/**
+ * 把任意 JSON 结构整理成「表头 + 记录」的形式，供转 CSV 使用。
+ */
+function jsonToTabular(parsed) {
+  if (Array.isArray(parsed)) {
+    if (parsed.length === 0) return { headers: [], records: [] };
+
+    const allObjects = parsed.every(
+      (item) => item !== null && typeof item === 'object' && !Array.isArray(item),
+    );
+    if (allObjects) {
+      return { headers: collectHeaders(parsed), records: parsed };
+    }
+
+    const allArrays = parsed.every((item) => Array.isArray(item));
+    if (allArrays) {
+      const width = Math.max(...parsed.map((row) => row.length));
+      const headers = Array.from({ length: width }, (_, i) => `column_${i + 1}`);
+      const records = parsed.map((row) =>
+        Object.fromEntries(headers.map((key, i) => [key, row[i] ?? ''])),
+      );
+      return { headers, records };
+    }
+
+    return { headers: ['value'], records: parsed.map((value) => ({ value })) };
+  }
+
+  if (parsed !== null && typeof parsed === 'object') {
+    const keys = Object.keys(parsed);
+    const isColumnar = keys.length > 0 && keys.every((key) => Array.isArray(parsed[key]));
+    if (isColumnar) {
+      // 列式结构 {"name":["a","b"],"age":[1,2]} -> 行式
+      const length = Math.max(...keys.map((key) => parsed[key].length));
+      const records = [];
+      for (let i = 0; i < length; i += 1) {
+        const record = {};
+        for (const key of keys) record[key] = parsed[key][i] ?? '';
+        records.push(record);
+      }
+      return { headers: keys, records };
+    }
+    return { headers: keys, records: [parsed] };
+  }
+
+  throw invalid(
+    '这个 JSON 不是能转成表格的结构',
+    '需要是对象数组，例如 [{"名称":"A","数量":1},{"名称":"B","数量":2}]。',
+  );
+}
+
+/** 把对象里的值拍平成 CSV 单元格可用的字符串 */
+function flattenValue(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return value;
+}
+
+export function registerDataTools(server) {
+  defineTool(server, {
+    name: 'json_format',
+    title: '格式化 / 压缩 / 校验 JSON',
+    action: '处理 JSON',
+    description:
+      '美化（缩进）、压缩（去掉空白）或校验 JSON。输入可以是文件，也可以直接把 JSON 文本放进 json_text 参数里。校验失败会指出具体是第几行第几个字符出错。',
+    inputSchema: {
+      input_files: z.array(z.string()).optional().describe('JSON 文件路径，可以传文件或文件夹。'),
+      json_text: z
+        .string()
+        .optional()
+        .describe('直接要处理的 JSON 文本。用户在对话里贴了一段 JSON 而不是给文件时用这个。'),
+      mode: z
+        .enum(['pretty', 'minify', 'validate'])
+        .optional()
+        .describe('pretty=美化缩进（默认）；minify=压缩成一行；validate=只检查合法性不输出内容。'),
+      indent: z.number().optional().describe('美化时的缩进空格数，默认 2。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, json_text, mode = 'pretty', indent = 2, output_directory } = args;
+      const hasFiles = Array.isArray(input_files) && input_files.length > 0;
+
+      // 情况一：直接给了一段 JSON 文本，结果就地返回，不落盘
+      if (!hasFiles) {
+        if (!json_text || String(json_text).trim() === '') {
+          throw invalid(
+            '没有提供要处理的 JSON',
+            '可以给我一个 .json 文件的路径，或者直接把 JSON 内容贴给我。',
+          );
+        }
+        const result = processJson(json_text, { mode, indent });
+        if (!result.ok) {
+          throw invalid(result.error, '请检查引号、逗号和括号是否配对。');
+        }
+
+        const shape = result.stats;
+        if (mode === 'validate') {
+          const detail = shape.type === '数组'
+            ? `数组，共 ${shape.length} 项`
+            : shape.type === '对象'
+              ? `对象，共 ${shape.keys} 个键`
+              : shape.type;
+          return `✅ JSON 校验通过：${detail}。`;
+        }
+
+        return [
+          `✅ JSON 处理完成（${mode === 'minify' ? '已压缩' : '已美化'}）。`,
+          '',
+          '```json',
+          result.output,
+          '```',
+        ].join('\n');
+      }
+
+      // 情况二：给的是文件，结果写入输出目录
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['json'],
+        label: 'JSON 文件',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const raw = await fs.readFile(file);
+        const { text, encoding } = decodeBuffer(raw);
+        const result = processJson(text, { mode, indent });
+        if (!result.ok) throw invalid(result.error);
+
+        if (mode === 'validate') {
+          return { validated: true, encoding, stats: result.stats };
+        }
+
+        const target = await uniquePath(outputDir, path.basename(file));
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, result.output, 'utf8');
+        return {
+          outPath: target,
+          bytes: Buffer.byteLength(result.output, 'utf8'),
+          encoding,
+          stats: result.stats,
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '失败', describeError(r.error, { action: '处理' })];
+        }
+        if (r.validated) {
+          return [path.basename(r.file), '格式正确', '—'];
+        }
+        return [path.basename(r.file), formatBytes(r.bytes), displayPath(r.outPath)];
+      });
+
+      const notes = [];
+      if (mode === 'validate') notes.push('只做了校验，没有写出新文件。');
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `🧩 ${summarize('JSON 处理', results)}`,
+        table: mdTable(['文件', '结果', '输出'], rows),
+        notes,
+        outputDir: mode === 'validate' ? null : displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'csv_to_json',
+    title: 'CSV 转 JSON',
+    action: '转换 CSV',
+    description:
+      '把 CSV / TSV 转成 JSON 数组（第一行当表头）。自动识别 UTF-8 与 GBK 编码，中文不会乱码；引号包裹的逗号、换行、双引号都能正确处理。支持批量。反向操作用 json_to_csv。',
+    inputSchema: {
+      input_files: z.array(z.string()).describe('CSV 文件路径，可以传文件或文件夹，支持多个。'),
+      delimiter: z
+        .string()
+        .optional()
+        .describe('分隔符，默认自动识别（逗号 / 制表符 / 分号 / 竖线）。'),
+      encoding: z
+        .string()
+        .optional()
+        .describe('文件编码，默认自动识别（UTF-8 或 GBK）。乱码时可以明确指定 utf-8 或 gbk。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, delimiter, encoding, output_directory } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['csv', 'tsv'],
+        label: 'CSV 文件',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const raw = await fs.readFile(file);
+        const decoded = decodeBuffer(raw, encoding ?? null);
+        const sep = delimiter || (path.extname(file).toLowerCase() === '.tsv'
+          ? '\t'
+          : detectDelimiter(decoded.text));
+
+        const rows = parseCsv(decoded.text, { delimiter: sep });
+        const { headers, records } = rowsToRecords(rows);
+        if (headers.length === 0) {
+          throw invalid('这个文件里没有可读取的内容');
+        }
+
+        const json = JSON.stringify(records, null, 2);
+        const stem = path.basename(file, path.extname(file));
+        const target = await uniquePath(outputDir, `${stem}.json`);
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, json, 'utf8');
+
+        return {
+          outPath: target,
+          rows: records.length,
+          columns: headers.length,
+          encoding: decoded.encoding,
+          delimiter: sep === '\t' ? '制表符' : sep,
+          bytes: Buffer.byteLength(json, 'utf8'),
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', '—', describeError(r.error, { action: '转换' })];
+        }
+        return [
+          path.basename(r.file),
+          `${r.rows} 行 × ${r.columns} 列`,
+          `${r.encoding} / ${r.delimiter}`,
+          displayPath(r.outPath),
+        ];
+      });
+
+      const notes = ['第一行被当作表头，转换结果是对象数组。'];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `📊 ${summarize('CSV 转 JSON', results)}`,
+        table: mdTable(['文件', '规模', '识别到的编码 / 分隔符', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'json_to_csv',
+    title: 'JSON 转 CSV',
+    action: '转换 JSON',
+    description:
+      '把 JSON 对象数组转成 CSV 表格。输出的 CSV 带 UTF-8 BOM，Excel / WPS 直接双击打开中文不乱码。支持对象数组、二维数组、列式对象。反向操作用 csv_to_json。',
+    inputSchema: {
+      input_files: z.array(z.string()).optional().describe('JSON 文件路径，可以传文件或文件夹。'),
+      json_text: z.string().optional().describe('直接要转换的 JSON 文本。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, json_text, output_directory } = args;
+      const hasFiles = Array.isArray(input_files) && input_files.length > 0;
+
+      if (!hasFiles) {
+        if (!json_text || String(json_text).trim() === '') {
+          throw invalid('没有提供要转换的 JSON', '可以给 .json 文件路径，或直接贴 JSON 内容。');
+        }
+        const parsed = processJson(json_text, { mode: 'validate' });
+        if (!parsed.ok) throw invalid(parsed.error);
+
+        const { headers, records } = jsonToTabular(parsed.parsed);
+        if (headers.length === 0) throw invalid('这个 JSON 里没有可转成表格的数据');
+
+        const csv = serializeCsv(headers, recordsToRows(records, headers).map((row) => row.map(flattenValue)));
+        return [
+          `✅ 已转换：${records.length} 行 × ${headers.length} 列。`,
+          '',
+          '```csv',
+          csv.trimEnd(),
+          '```',
+        ].join('\n');
+      }
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['json'],
+        label: 'JSON 文件',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const raw = await fs.readFile(file);
+        const { text } = decodeBuffer(raw);
+        const parsed = processJson(text, { mode: 'validate' });
+        if (!parsed.ok) throw invalid(parsed.error);
+
+        const { headers, records } = jsonToTabular(parsed.parsed);
+        if (headers.length === 0) throw invalid('这个 JSON 里没有可转成表格的数据');
+
+        const csv = serializeCsv(headers, recordsToRows(records, headers).map((row) => row.map(flattenValue)));
+        const stem = path.basename(file, path.extname(file));
+        const target = await uniquePath(outputDir, `${stem}.csv`);
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, csv, 'utf8');
+
+        return {
+          outPath: target,
+          rows: records.length,
+          columns: headers.length,
+          bytes: Buffer.byteLength(csv, 'utf8'),
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', describeError(r.error, { action: '转换' }), '—'];
+        }
+        return [
+          path.basename(r.file),
+          `${r.rows} 行 × ${r.columns} 列`,
+          formatBytes(r.bytes),
+          displayPath(r.outPath),
+        ];
+      });
+
+      const notes = ['输出的 CSV 带 UTF-8 BOM，Excel / WPS 双击打开不会乱码。'];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `📊 ${summarize('JSON 转 CSV', results)}`,
+        table: mdTable(['文件', '规模', '大小', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'markdown_to_html',
+    title: 'Markdown 转 HTML',
+    action: '转换 Markdown',
+    description:
+      '把 .md 文件转成 HTML。默认输出带样式、可直接在浏览器打开的完整网页；把 full_page 设为 false 则只输出 HTML 片段（方便嵌到别的页面里）。反向操作用 html_to_markdown。',
+    inputSchema: {
+      input_files: z.array(z.string()).describe('Markdown 文件路径，可以传文件或文件夹，支持多个。'),
+      full_page: z
+        .boolean()
+        .optional()
+        .describe('true=输出完整网页（默认，带样式和标题）；false=只输出 HTML 片段。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, full_page = true, output_directory } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['md', 'markdown', 'mdown', 'mkd'],
+        label: 'Markdown 文件',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const raw = await fs.readFile(file);
+        const { text } = decodeBuffer(raw);
+        const html = markdownToHtml(text, { fullPage: full_page, title: guessTitle(text) });
+        const stem = path.basename(file, path.extname(file));
+        const target = await uniquePath(outputDir, `${stem}.html`);
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, html, 'utf8');
+        return {
+          outPath: target,
+          bytes: Buffer.byteLength(html, 'utf8'),
+          title: guessTitle(text),
+        };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', describeError(r.error, { action: '转换' })];
+        }
+        return [path.basename(r.file), formatBytes(r.bytes), displayPath(r.outPath)];
+      });
+
+      const notes = [
+        full_page
+          ? '输出的是完整网页，可直接用浏览器打开，已内置基础排版样式。'
+          : '只输出了 HTML 片段。',
+      ];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `🌐 ${summarize('Markdown 转 HTML', results)}`,
+        table: mdTable(['文件', '大小', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+
+  defineTool(server, {
+    name: 'html_to_markdown',
+    title: 'HTML 转 Markdown',
+    action: '转换 HTML',
+    description:
+      '把 .html 文件转成 Markdown 文本。表格、代码块、列表、标题都会被保留。反向操作用 markdown_to_html。',
+    inputSchema: {
+      input_files: z.array(z.string()).describe('HTML 文件路径，可以传文件或文件夹，支持多个。'),
+      output_directory: OUTPUT_DIRECTORY,
+    },
+    handler: async (args) => {
+      const { input_files, output_directory } = args;
+
+      const { files, warnings } = await expandInputs(input_files, {
+        extensions: ['html', 'htm'],
+        label: 'HTML 文件',
+      });
+
+      const outputDir = await resolveOutputDir({ inputs: files, outputDirectory: output_directory });
+
+      const results = await runBatch(files, async (file) => {
+        const raw = await fs.readFile(file);
+        const { text } = decodeBuffer(raw);
+        const markdown = htmlToMarkdown(text);
+        const stem = path.basename(file, path.extname(file));
+        const target = await uniquePath(outputDir, `${stem}.md`);
+        assertNotOverwritingInput(target, files);
+        await fs.writeFile(target, markdown, 'utf8');
+        return { outPath: target, bytes: Buffer.byteLength(markdown, 'utf8') };
+      });
+
+      const rows = results.map((r) => {
+        if (!r.ok) {
+          return [path.basename(r.file), '—', describeError(r.error, { action: '转换' })];
+        }
+        return [path.basename(r.file), formatBytes(r.bytes), displayPath(r.outPath)];
+      });
+
+      const notes = ['表格和代码块会保留为 Markdown 语法。'];
+      for (const w of warnings) notes.push(`· ${w}`);
+
+      return buildResult({
+        title: `📝 ${summarize('HTML 转 Markdown', results)}`,
+        table: mdTable(['文件', '大小', '输出'], rows),
+        notes,
+        outputDir: displayPath(outputDir),
+        data: {
+          succeeded: results.filter((r) => r.ok).length,
+          failed: results.filter((r) => !r.ok).length,
+        },
+      });
+    },
+  });
+}