hwpctl — 한/글 라이브 코파일럿 브리지

열린 한글 2022 창을 채팅 클라이언트가 고치게 하는 단일 작성기입니다.
Grok Build, Cursor, Codex, Gemini CLI, Claude Code는 설정을 갈아끼우기만 하면 됩니다. 한/글 전용 로직은 클라이언트에 두지 않습니다.

• 엔진은 hwpctl 하나뿐입니다.

• 글자를 타이핑하지 않습니다. pyhwpx / win32com HWPFrame.HwpObject 로 문단·표·셀을 조작합니다.

• 문단·표·셀 명령은 Undo 한 덩어리입니다.

• 자동저장 없음. 원본은 덮어쓰지 않고 save_as 로 새 파일에 저장합니다.

• 작성기는 한 번에 하나만. 잠금 파일이 두 클라이언트의 동시 쓰기를 막습니다.

대상/실측 기준: Windows + 한글 2022 12.0.0.850 + pyhwpx 1.7.2. 한글 2024 전용 GSG / GetCtrlInstID / SelectCtrl 은 쓰지 않습니다.

flowchart LR
    U["사용자"] --> A["Codex · Claude Code · Cursor<br/>Gemini CLI · Grok Build"]
    A -->|"로컬 MCP stdio"| B["hwpctl<br/>단일 작성기 · 명령 잠금"]
    B -->|"pyhwpx / Windows COM"| H["사용자가 열어 둔<br/>한글 2022 문서"]
    H -->|"화면에서 즉시 확인"| U

AI 클라이언트와 hwpctl이 같은 PC에서 실행되면 기본 연결은 로컬 stdio입니다. HTTP는 별도 프로세스나 원격 클라이언트가 명시적으로 필요로 할 때만 선택합니다.

설치 (Windows + 한글 2022)

1. 한글 2022가 설치되어 있는지 확인합니다.

2. Python 3.10+ 을 설치합니다. 설치 시 Add Python to PATH 를 켭니다.

3. 이 저장소를 받은 뒤:

py -3.12 -m pip install -e ".[windows]"

개발·테스트만 할 때(한/글 없는 머신):

pip install -e ".[dev]"
pytest

4. 한글을 한 창 열어 둡니다. hwpctl 은 지금 열린 창(캔버스) 에 붙습니다.

5. 처음 파일 열기/저장 때 보안 모듈(FilePathChecker) 대화 상자가 뜨면 허용합니다. pyhwpx 가 모듈을 등록합니다.

연결 확인:

hwpctl status

한/글이 없거나 Windows 가 아니면 스택 없이 한국어로 실패합니다.

한/글(한글 오피스)을 찾을 수 없습니다. 이 컴퓨터에 한글 2022가 설치되어 있고 Windows에서 실행 중인지 확인하세요. ...

선택: 한글 없이 .hwpx 준비

복잡한 공고문을 COM 으로 처음부터 재현하지 않고, .hwpx XML 을 조립하는 준비 계층입니다. 재현 자체는 다음 단계입니다. 계획: docs/hwpx-upgrade-plan.md · 조사: docs/research-hwp-without-hangul.md

pip install -e ".[hwpx]"
hwpctl hwpx_status
hwpctl hwpx_inspect 샘플.hwpx

한/글·COM·작성 잠금은 필요 없습니다. 기존 status / insert_title 등 COM 명령은 그대로입니다.

Related MCP server: HWP-MCP

클라이언트 바꾸기

서버는 같고, 설정만 다릅니다. 한/글 코드를 클라이언트마다 넣지 마세요.

stdio 예 (Cursor·Codex·Claude·Gemini·Grok Build 공통):

{
  "mcpServers": {
    "hwpctl": {
      "command": "hwpctl",
      "args": ["mcp"],
      "env": { "HWPCTL_CLIENT": "cursor" }
    }
  }
}

• Cursor: 프로젝트 .cursor/mcp.json 또는 사용자 MCP 설정에 위 내용을 넣습니다.

• Codex: ~/.codex/config.toml 에 examples/codex/config.toml 을 복사합니다.

• Claude Code: 프로젝트 .mcp.json 또는 claude mcp add.

• Gemini CLI: ~/.gemini/settings.json 의 mcpServers.

• Grok Build: 프로젝트 .mcp.json에 examples/grok-build/.mcp.json을 병합합니다.

바꾼 뒤 클라이언트를 재시작하면 같은 status / insert_title / create_table 도구가 보입니다.

선택 사항: HTTP 연결

같은 PC에서 명령줄을 실행하는 Grok Build를 포함한 로컬 클라이언트는 위의 stdio 설정을 사용하면 됩니다. HTTP 모드는 별도 프로세스가 필요하거나, 원격 서비스에 대해 사용자가 보안 영향을 검토하고 명시적으로 연결을 구성할 때만 사용하세요. 이 저장소는 외부 공개나 터널을 기본값으로 가정하지 않습니다.

set HWPCTL_TOKEN=긴무작위문자열
hwpctl mcp --http --host 127.0.0.1 --port 18765 --token %HWPCTL_TOKEN%

• MCP 엔드포인트: http://127.0.0.1:18765/mcp

• 헤더: Authorization: Bearer <토큰> 또는 X-Hwpctl-Token: <토큰>

• 토큰 없으면 401. 127.0.0.1 / localhost 만 허용합니다.

명령 / MCP 도구

CLI 와 MCP 는 같은 함수를 부릅니다. 성공 시 JSON, 실패 시 stderr 한국어.

도구 목록만 (한/글 불필요):

hwpctl mcp --list-tools

모델이 「사업계획서, 4열 8행 표, 첫 행 회색」을 이렇게 매핑하면 됩니다.

hwpctl insert_title 사업계획서
hwpctl create_table --rows 8 --cols 4 --header-fill gray
hwpctl fill_cells --table 0 --cells "[[\"항목\",\"내용\",\"담당\",\"기한\"]]"
hwpctl layout_review
hwpctl save_as "%USERPROFILE%\Documents\사업계획서-초안.hwpx"

서브커맨드 이름은 밑줄입니다 (insert_title, fill_cells).

표 편집 뒤 항상 레이아웃 검토

create_table, fill_cells, set_format, set_cell_margin, insert_chart 등으로 표를 만들거나 채운 뒤에는 항상 layout_review를 한 번 실행합니다. 편집 명령과 자동으로 묶지는 않습니다. 한/글 잠금과 Undo 단위를 섞지 않기 위해 별도 명령으로 호출해야 합니다.

hwpctl layout_review                         :: 문서의 모든 표를 검토하고 기본적으로 수정
hwpctl layout_review --table 0               :: 0번 표만 검토하고 수정
hwpctl layout_review --table 0 --dry-run     :: 수정하지 않고 JSON 계획만 출력

셀의 조판 줄 수는 한글 2022의 MoveLineEnd 위치 진행과 KeyIndicator 셀 주소를 함께 확인해 실측합니다. 명시적 줄바꿈보다 조판 줄 수가 많을 때만 열 너비로 인한 줄바꿈으로 판정합니다. 한글 2022 Automation에는 문자열 조판 폭을 직접 재는 API가 없으므로 필요한 목표 열 너비는 글자 크기와 유니코드 문자 폭으로 추정하며, 열 하나가 본문 폭의 45% 또는 기존 너비의 1.6배를 넘지 않게 제한합니다. 표 폭은 용지 폭에서 좌우·제본·표 바깥 여백을 뺀 범위를 넘기지 않습니다.

표 칸 안쪽 여백 (셀 안 여백)

글자가 칸 테두리에 붙는 문제는 표 바깥 여백이 아니라 셀 안쪽 여백 문제입니다.

• create_table 은 새 표의 모든 칸에 기본 안여백 좌우 3.5mm / 상하 2.0mm 를 적용합니다. 한/글 기본값(1.8/0.5mm)보다 넉넉합니다. --cell-padding "3.0,1.5" 로 바꾸거나 --cell-padding none 으로 끌 수 있습니다.

• 이미 있는 표는 set_cell_margin 으로:

hwpctl set_cell_margin --table 0                        :: 0번 표 전체 칸, 기본 3.5/2.0mm
hwpctl set_cell_margin --table 0 --left 4 --right 4 --top 2 --bottom 2
hwpctl set_cell_margin --table 0 --range A1:D4          :: 해당 칸들만

한글 2022에서 set_table_inside_margin은 True를 반환해도 실제 값이 바뀌지 않았습니다. 따라서 create_table의 기본 여백과 set_cell_margin --table N은 모두 표의 실제 셀 주소를 순회하며 각 셀에 set_cell_margin을 한 번씩 적용합니다. Undo 기록에도 적용한 셀 수가 그대로 들어갑니다.

한글 2022 실측 서식 명령

MCP/Engine 시그니처(같은 이름의 CLI도 제공):

set_col_width(widths, table=None, column=None, unit="mm")  # unit: mm | ratio
get_col_width(table=None, column=None)                     # 결과 단위: mm
set_row_height(height, table=None, row=None)               # mm, row는 1부터
get_row_height(table=None, row=None)                       # 결과 단위: mm
merge_cells(cell_range, table=None)
set_valign(align, table=None, cell_range="")               # top | center | bottom
set_cell_border(sides="all", line_type="Solid", width="0.12mm",
                color="#000000", table=None, cell_range="")
set_style(style)                                           # 예: "개요 1"
set_pagedef(paper_width=None, paper_height=None, left=None, right=None,
            top=None, bottom=None, header=None, footer=None, gutter=None,
            landscape=None, apply="current")
page(goto=None, break_page=False)

• 열·행 치수는 GetCellWidth 없이 TablePropertyDialog의 ShapeTableCell.Width/Height를 읽고, 설정할 때 ShapeCellSize=1을 씁니다. ratio는 현재 표 전체 폭을 유지하며 모든 열의 비율을 지정합니다.

• 병합은 TableCellBlock → TableCellBlockExtend → 셀 이동 → TableMergeCell 순서입니다. TableMergeCell 단독 호출은 하지 않습니다.

• 세로 정렬은 TableVAlignTop/Center/Bottom이며 결과의 vert_align은 각각 0/1/2입니다.

• 테두리는 CellBorderFill을 사용합니다. 왼쪽 색 항목은 한글 2022의 실제 철자인 BorderCorlorLeft를 사용합니다. 내부 가로선 TypeHorz는 오류로 거부합니다.

• 쪽 나누기는 BreakPage, 쪽 수는 PageCount입니다.

• set_style("개요 1")은 pyhwpx의 set_style을 사용합니다. 한글 2022에서 COM 예외가 나는 HwpOutlineType/HwpOutlineStyle 직접 호출은 하지 않습니다.

• 편집 전후에 한/글 대화상자를 확인하며, 떠 있으면 대신 누르지 않고 한국어 오류로 중단합니다. SendKeys와 자동저장은 사용하지 않습니다.

CLI 예:

hwpctl set_col_width --table 0 --widths 1,2,1 --unit ratio
hwpctl get_col_width --table 0
hwpctl set_row_height --table 0 --row 2 --height 12
hwpctl merge_cells --table 0 --range A1:B1
hwpctl set_valign center --table 0 --range A1:C2
hwpctl set_cell_border --table 0 --range A1:C2 --sides all --color #333333
hwpctl set_style "개요 1"
hwpctl set_pagedef --paper-width 210 --paper-height 297 --left 20 --right 20
hwpctl page --break

저장 없이 시험하려면 빈 문서에서 다음처럼 실행하고, 결과 확인 뒤 undo로 직전 명령을 되돌립니다. save/save_as를 호출하지 않는 한 자동으로 저장되지 않습니다.

hwpctl open --new
hwpctl create_table --rows 2 --cols 3
hwpctl set_col_width --widths 1,2,1 --unit ratio
hwpctl set_valign center --table 0
hwpctl layout_review --table 0
hwpctl page
hwpctl undo

한/글 네이티브 차트 (insert_chart)

insert_chart 는 한/글 입력 > 차트 개체를 넣습니다. PNG 그림 삽입이 아닙니다.

흐름: 데이터 표를 만들고(create_table + fill_cells) → insert_chart --table N. 표(또는 --range 범위)의 셀을 선택한 뒤 InsertChart 액션을 ChartGroup / ChartIndex / ChartDataDialogDisable=1 파라미터로 실행합니다 (한컴 포럼에서 확인된, 노출된 파라미터 전부입니다 — 생성 후 차트 수정 API 는 없습니다).

hwpctl insert_chart --table 1 --type line      :: 인생 그래프 = 꺾은선
hwpctl insert_chart --table 0 --type column --range A1:B10

• 종류: line(꺾은선) / column(세로막대) / bar(가로막대) / pie(원형). 0=가로막대·1=세로막대·3=원형은 한컴 포럼에서 확인된 값이고, line=2 는 추론값이라 실기에서 종류가 다르게 나오면 --type 대신 --index 와 함께 조정하세요.

• 한글 2022 이상 전용. 2020 이하에는 ChartDataDialogDisable 이 없어 데이터 편집 대화상자가 뜹니다. 대화상자가 뜨면 자동화 실패입니다 — hwpctl 은 한국어 오류를 내며, 화면의 창을 대신 눌러 주지 않습니다.

파괴적 작업

아래는 명시 플래그 없이 거부합니다.

큰 범위 삭제, 표·쪽·그림 구조 변경 API 는 넣지 않았습니다. 넣게 되면 같은 방식으로 플래그를 요구합니다.

잠금

%LOCALAPPDATA%\hwpctl\hwpctl.lock (Windows) 또는 $XDG_RUNTIME_DIR/hwpctl/hwpctl.lock.
경로 재정의: HWPCTL_LOCK, HWPCTL_STATE.
클라이언트 이름: HWPCTL_CLIENT (오류 메시지에 표시).

MCP 서버가 떠 있어도 잠금은 명령 단위입니다. 서버 프로세스가 잠금을 붙잡고 있지 않습니다.

undo 는 hwpctl 이 기록한 명령만 되돌립니다. hwpctl 명령 사이에 한/글에서 직접 편집했다면 그 편집이 먼저 되돌아갈 수 있으니, 수동 편집은 한/글의 Ctrl+Z 를 쓰세요.

개발 (한/글 없이)

파서와 잠금은 Linux 에서도 테스트합니다.

pip install -e ".[dev]"
pytest
hwpctl status
# → 한국어 오류, 종료 코드 2

레이아웃:

hwpctl/           엔진·CLI·MCP
hwpctl/hwpx/      한글 없는 .hwpx 준비 (python-hwpx)
examples/         클라이언트 설정만 (한/글 코드 없음)
tests/            파서·잠금·한/글 없음·HWPX XML

라이브 편집은 Windows + 한글 2022 + pip install -e ".[windows]" 가 필요합니다. .hwpx 읽기 준비는 pip install -e ".[hwpx]" 로 Linux 에서도 됩니다.

공개 문서와 프로젝트 범위

• HWPX 업그레이드 계획: 한글 없이 조립하는 단계 (준비만 완료)

• 한글 없이 HWP 조사: python-hwpx 1순위 근거

• 알려진 한계: 열린 창, Undo, 표·차트와 실기 검증 상태

• 보안 정책: 로컬 MCP의 신뢰 경계와 비공개 취약점 신고

• 기여 안내: 테스트 자료와 PR 원칙

• 변경 기록 · 릴리스 체크리스트

• 제3자 구성요소 고지

hwpctl은 독립적인 오픈 소스 프로젝트이며 한글과컴퓨터가 제공·보증·후원하는 공식 제품이 아닙니다. 사용자는 유효한 한글 라이선스와 해당 자동화 사용 조건을 직접 확인해야 합니다. 이 저장소의 코드는 MIT 라이선스로 배포되며, 한글 및 제3자 패키지는 각자의 라이선스를 따릅니다.