read_hwp_tables

Instructions

Implementation Reference

• src/server.ts:59-68 (registration)

  Tool 'read_hwp_tables' is registered in the TOOLS array with name, description, and inputSchema requiring file_path.

  {
    name: "read_hwp_tables",
    description:
      "Extract every table from an HWP/HWPX file as GitHub-flavored markdown. Args: file_path.",
    inputSchema: {
      type: "object",
      properties: { file_path: { type: "string" } },
      required: ["file_path"],
    },
  },

• src/server.ts:512-512 (registration)

  Handler mapping: tool name 'read_hwp_tables' is mapped to the readHwpTables handler function.

  read_hwp_tables: readHwpTables,

• src/tools/read.ts:32-54 (handler)

  The readHwpTables handler function: opens a document, walks tables via walkTables(), formats each as markdown with tableToMarkdown(), and returns the result.

  export async function readHwpTables(args: ReadHwpArgs): Promise<string> {
    let doc;
    try {
      doc = await openDocument(args.file_path);
    } catch (e) {
      return (e as Error).message;
    }
    try {
      const tables = walkTables(doc);
      if (tables.length === 0) return "(표가 없습니다 / no tables)";
      const out: string[] = [];
      tables.forEach((t, i) => {
        out.push(`### 표 ${i + 1} (${t.rows}행 x ${t.cols}열)`);
        out.push(tableToMarkdown(t));
        out.push("");
      });
      return out.join("\n");
    } catch (e) {
      return `표 추출 오류 (table extraction error): ${(e as Error).message}`;
    } finally {
      closeDocument(doc);
    }
  }

• src/tools/read.ts:11-13 (schema)

  ReadHwpArgs interface defining the input schema with a file_path string property.

  export interface ReadHwpArgs {
    file_path: string;
  }

• src/core/document.ts:318-365 (helper)

  walkTables() helper function that iterates sections/paragraphs/controls, reads table dimensions and cell text, and returns an array of TableData objects.

  export function walkTables(doc: HwpDocument): TableData[] {
    const out: TableData[] = [];
    const sectionCount = doc.getSectionCount();
    for (let s = 0; s < sectionCount; s++) {
      const paraCount = doc.getParagraphCount(s);
      for (let p = 0; p < paraCount; p++) {
        const n = controlCount(doc, s, p);
        for (let ci = 0; ci < n; ci++) {
          let dimsJson: string;
          try {
            dimsJson = doc.getTableDimensions(s, p, ci);
          } catch {
            continue;
          }
          if (!dimsJson || dimsJson === "null") continue;
          let dims: TableDims;
          try {
            dims = JSON.parse(dimsJson);
          } catch {
            continue;
          }
          const rows = Number(dims.rowCount ?? dims.rows ?? dims.row_count ?? 0);
          const cols = Number(dims.colCount ?? dims.cols ?? dims.col_count ?? 0);
          const cellCount = Number(dims.cellCount ?? dims.cell_count ?? rows * cols);
          if (rows === 0 || cols === 0) continue;
          // Tables with merged cells report cellCount < rows*cols. Walk by
          // cellCount instead of grid; place by getCellInfo (row, col, span).
          const cells: string[][] = Array.from({ length: rows }, () => Array(cols).fill(""));
          for (let cellIdx = 0; cellIdx < cellCount; cellIdx++) {
            let row = 0,
              col = 0;
            try {
              const info = JSON.parse(doc.getCellInfo(s, p, ci, cellIdx));
              row = Number(info.row ?? info.r ?? 0);
              col = Number(info.col ?? info.c ?? 0);
            } catch {
              row = Math.floor(cellIdx / cols);
              col = cellIdx % cols;
            }
            if (row >= rows || col >= cols) continue;
            cells[row][col] = readCellText(doc, s, p, ci, cellIdx);
          }
          out.push({ rows, cols, cells });
        }
      }
    }
    return out;
  }