set_hwp_field_value

Instructions

Implementation Reference

• src/tools/edit.ts:143-156 (handler)

  Tool handler function for 'set_hwp_field_value'. Calls setHwpxFieldValue from core/hwpx-mutate.ts after preflight check.

  export async function setHwpFieldValue(args: SetFieldArgs): Promise<string> {
    const err = preflight(args.file_path);
    if (err) return err;
    const out = args.output_path && args.output_path.length > 0
      ? args.output_path
      : defaultOutput(args.file_path, "field-set");
    try {
      const r = await setHwpxFieldValue(args.file_path, out, args.name, args.value);
      if (r.replaced === 0) return `필드를 찾지 못했습니다 (field not found): ${args.name}`;
      return `필드 '${args.name}' = '${args.value}' (replaced ${r.replaced})\n저장 (saved): ${out}`;
    } catch (e) {
      return `필드 설정 오류 (set field error): ${(e as Error).message}`;
    }
  }

• src/tools/edit.ts:136-141 (schema)

  TypeScript interface SetFieldArgs defining the input schema: file_path, name, value, optional output_path.

  export interface SetFieldArgs {
    file_path: string;
    name: string;
    value: string;
    output_path?: string;
  }

• src/server.ts:307-320 (schema)

  MCP tool registration with input schema for set_hwp_field_value. Required: file_path, name, value.

  {
    name: "set_hwp_field_value",
    description:
      "Set a Hancom field's value by name in an .hwpx (writes the new text between the matching `<hp:fldBegin name=...>` and `<hp:fldEnd>`). Use list_hwp_fields first to discover names. Args: file_path, name, value, output_path (optional).",
    inputSchema: {
      type: "object",
      properties: {
        file_path: { type: "string" },
        name: { type: "string" },
        value: { type: "string" },
        output_path: { type: "string" },
      },
      required: ["file_path", "name", "value"],
    },

• src/server.ts:540-543 (registration)

  Handler registration mapping 'set_hwp_field_value' → setHwpFieldValue (from edit.ts).

  set_hwp_field_value: setHwpFieldValue,
  delete_hwp_image: deleteHwpImage,
  render_hwp_html: renderHwpHtml,
  render_hwp_equation_svg: renderHwpEquationSvg,

• src/core/hwpx-mutate.ts:293-331 (helper)

  Core implementation: loads .hwpx ZIP, finds <hp:fldBegin name='...'> / <hp:fldEnd> pairs, replaces <hp:t> text content with new value.

  export async function setHwpxFieldValue(
    inputPath: string,
    outputPath: string,
    fieldName: string,
    value: string
  ): Promise<{ replaced: number }> {
    const { zip, sectionName, xml } = await loadSection(inputPath);
    // OWPML field markers: <hp:fldBegin name="..." .../> ... text ... <hp:fldEnd .../>
    // Or as attribute on <hp:run>. Strategy: find each fldBegin/fldEnd pair where name matches,
    // then replace any <hp:t>...</hp:t> between them with new value (in the *first* such pair).
    // This is best-effort; full schema support comes in v0.3.
    const fldBeginRegex = new RegExp(
      `<hp:fldBegin[^/>]*name="${escapeRegex(fieldName)}"[^/>]*/?>`,
      "g"
    );
    const beginMatches = [...xml.matchAll(fldBeginRegex)];
    if (beginMatches.length === 0) {
      return { replaced: 0 };
    }
    // Take the first occurrence; find the next <hp:fldEnd .../> after it
    const begin = beginMatches[0];
    const startIdx = (begin.index ?? 0) + begin[0].length;
    const fldEndRegex = /<hp:fldEnd[^/>]*\/?>/g;
    fldEndRegex.lastIndex = startIdx;
    const endMatch = fldEndRegex.exec(xml);
    if (!endMatch) {
      return { replaced: 0 };
    }
    const before = xml.slice(0, startIdx);
    const between = xml.slice(startIdx, endMatch.index);
    const after = xml.slice(endMatch.index);
    const newBetween = between.replace(
      /<hp:t>[^<]*<\/hp:t>/g,
      `<hp:t>${xmlEscape(value)}</hp:t>`
    );
    const newXml = before + newBetween + after;
    await writeSection(zip, sectionName, newXml, outputPath);
    return { replaced: 1 };
  }