replace_hwp_image

Instructions

Implementation Reference

• src/tools/replace-image.ts:22-59 (handler)

  Main handler function for replace_hwp_image tool. Validates inputs (file existence, .hwpx format), calls replaceHwpxImages from the core module, and returns a user-facing result message.

  export async function replaceHwpImage(args: ReplaceImageArgs): Promise<string> {
    if (!existsSync(args.file_path)) {
      return `파일을 찾을 수 없습니다 (file not found): ${args.file_path}`;
    }
    if (!existsSync(args.source_path)) {
      return `대체 이미지 파일을 찾을 수 없습니다 (replacement file not found): ${args.source_path}`;
    }
    let fmt;
    try {
      fmt = getFormatFromPath(args.file_path);
    } catch (e) {
      return (e as Error).message;
    }
    if (fmt !== "hwpx") {
      return "v0.2은 .hwpx 이미지 교체만 지원합니다 (image replace supports .hwpx only in v0.2).";
    }
    const outputPath =
      args.output_path && args.output_path.length > 0
        ? args.output_path
        : defaultOutputPath(args.file_path, "img");
    try {
      const r = await replaceHwpxImages(args.file_path, outputPath, {
        [args.target]: args.source_path,
      });
      if (r.total === 0) {
        const entries = await listHwpxBinDataEntries(args.file_path);
        return [
          `대상 이미지를 찾지 못했습니다 (target not found): ${args.target}`,
          `사용 가능한 BinData 엔트리:`,
          ...entries.map((e) => `  - ${e}`),
        ].join("\n");
      }
      const rep = r.replaced[0];
      return `이미지 교체 완료 (replaced): ${rep.entry} ← ${rep.from} (${rep.bytes} bytes)\n저장 (saved): ${outputPath}`;
    } catch (e) {
      return `이미지 교체 오류 (image replace error): ${(e as Error).message}`;
    }
  }

• src/tools/replace-image.ts:9-14 (schema)

  ReplaceImageArgs interface defining input schema: file_path (target .hwpx), target (BinData entry name), source_path (replacement file), and optional output_path.

  export interface ReplaceImageArgs {
    file_path: string;
    target: string;
    source_path: string;
    output_path?: string;
  }

• src/server.ts:175-188 (registration)

  Tool registration entry in the TOOLS array: defines name 'replace_hwp_image', description, and inputSchema with required properties (file_path, target, source_path) and optional output_path.

    name: "replace_hwp_image",
    description:
      "Replace an embedded image inside an .hwpx by overwriting its BinData/ ZIP entry with new file contents. `target` accepts either basename ('image1.bmp') or full entry path ('BinData/image1.bmp'). Args: file_path, target, source_path, output_path (optional).",
    inputSchema: {
      type: "object",
      properties: {
        file_path: { type: "string" },
        target: { type: "string" },
        source_path: { type: "string" },
        output_path: { type: "string" },
      },
      required: ["file_path", "target", "source_path"],
    },
  },

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

  Handler mapping: maps the tool name 'replace_hwp_image' to the imported replaceHwpImage function in the HANDLERS record.

  replace_hwp_image: replaceHwpImage,

• src/core/hwpx-mutate.ts:110-147 (helper)

  Core helper function replaceHwpxImages that performs the actual image replacement inside the .hwpx ZIP archive by overwriting BinData entries with new file bytes and writing the modified ZIP.

  export async function replaceHwpxImages(
    inputPath: string,
    outputPath: string,
    replacements: ImageReplaceMap
  ): Promise<ImageReplaceResult> {
    const bytes = await readFile(inputPath);
    const zip = await JSZip.loadAsync(bytes);
  
    const entryNames = Object.keys(zip.files).filter((n) => n.startsWith("BinData/"));
    const result: ImageReplaceResult = { total: 0, replaced: [], skipped: [] };
  
    for (const [target, sourcePath] of Object.entries(replacements)) {
      const fullEntry = target.includes("/") ? target : `BinData/${target}`;
      const match = entryNames.find(
        (n) => n === fullEntry || n.endsWith("/" + target) || n === target
      );
      if (!match) {
        result.skipped.push(target);
        continue;
      }
      const newBytes = await readFile(sourcePath);
      zip.file(match, newBytes);
      result.replaced.push({ entry: match, from: sourcePath, bytes: newBytes.byteLength });
      result.total += 1;
    }
  
    if (zip.files["mimetype"]) {
      const mt = await zip.files["mimetype"].async("string");
      zip.file("mimetype", mt, { compression: "STORE" });
    }
    const out = await zip.generateAsync({
      type: "uint8array",
      compression: "DEFLATE",
      compressionOptions: { level: 6 },
    });
    await writeFile(outputPath, out);
    return result;
  }