extract_hwp_images

Instructions

Implementation Reference

• src/tools/images.ts:39-71 (handler)

  Main handler function that extracts all embedded images from an HWP/HWPX file and saves them to disk. Opens the document, walks images via walkImages(), creates the output directory, writes each image as a file, and returns a summary.

  export async function extractHwpImages(args: ExtractImagesArgs): Promise<string> {
    let doc;
    try {
      doc = await openDocument(args.file_path);
    } catch (e) {
      return (e as Error).message;
    }
    try {
      const imgs = walkImages(doc);
      if (imgs.length === 0) return "(추출할 이미지가 없습니다 / no images to extract)";
      const baseName = basename(args.file_path, extname(args.file_path));
      const outDir = args.output_dir
        ? resolve(args.output_dir)
        : resolve(dirname(args.file_path), `${baseName}_images`);
      mkdirSync(outDir, { recursive: true });
      const saved: string[] = [];
      imgs.forEach((img, i) => {
        const bytes = getImageBytes(doc, img);
        const fname = `image_${String(i + 1).padStart(3, "0")}.${img.ext}`;
        const fpath = join(outDir, fname);
        writeFileSync(fpath, bytes);
        saved.push(fname);
      });
      return [
        `이미지 ${saved.length}개를 추출했습니다 (extracted ${saved.length} images):`,
        `저장 위치 (output): ${outDir}`,
        "",
        ...saved.map((s) => `  - ${s}`),
      ].join("\n");
    } finally {
      closeDocument(doc);
    }
  }

• src/tools/images.ts:13-16 (schema)

  TypeScript interface ExtractImagesArgs defining the input schema for extractHwpImages: file_path (required) and output_dir (optional).

  export interface ExtractImagesArgs {
    file_path: string;
    output_dir?: string;
  }

• src/server.ts:80-90 (registration)

  Tool registration: defines the name 'extract_hwp_images', its description, and inputSchema (object with file_path required, output_dir optional).

  name: "extract_hwp_images",
  description:
    "Save every embedded image to disk. Args: file_path, output_dir (optional; defaults to <file>_images/).",
  inputSchema: {
    type: "object",
    properties: {
      file_path: { type: "string" },
      output_dir: { type: "string" },
    },
    required: ["file_path"],
  },

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

  Registration of extractHwpImages handler function in the HANDLERS record mapping tool names to handler functions.

  extract_hwp_images: extractHwpImages,

• src/core/document.ts:393-426 (helper)

  Helper walkImages() that iterates over all sections/paragraphs/controls in an HWP document, collecting image metadata (mime, byte length, ext) into ImageRef array.

  export function walkImages(doc: HwpDocument): ImageRef[] {
    const out: ImageRef[] = [];
    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 mime: string;
          try {
            mime = doc.getControlImageMime(s, p, ci);
          } catch {
            continue;
          }
          if (!mime) continue;
          let bytes: Uint8Array;
          try {
            bytes = doc.getControlImageData(s, p, ci);
          } catch {
            continue;
          }
          out.push({
            section: s,
            paragraph: p,
            controlIdx: ci,
            mime,
            byteLength: bytes.byteLength,
            ext: extFromMime(mime),
          });
        }
      }
    }
    return out;
  }

• src/core/document.ts:428-430 (helper)

  Helper getImageBytes() that retrieves raw image byte data from the document given an ImageRef.

  export function getImageBytes(doc: HwpDocument, ref: ImageRef): Uint8Array {
    return doc.getControlImageData(ref.section, ref.paragraph, ref.controlIdx);
  }

• src/core/document.ts:371-378 (schema)

  ImageRef interface defining the structure for referencing an embedded image: section, paragraph, controlIdx, mime, byteLength, ext.

  export interface ImageRef {
    section: number;
    paragraph: number;
    controlIdx: number;
    mime: string;
    byteLength: number;
    ext: string;
  }