hwp-cowork

Claude와 함께 쓰는 한글(HWP) 동시편집 서버. Claude가 문서를 고치는 동안 사람도 같은 문서를 브라우저에서 보고 직접 고칩니다. 바뀐 내용은 모두 판(v1, v2 …)으로 남습니다.

Co-edit Korean HWP/HWPX documents with Claude (or any MCP client). Self-hosted with Docker, no Hancom Office required.

• 한컴오피스 없이 Linux 서버에서 .hwp와 .hwpx를 조사하고 편집합니다. 엔진은 rhwp입니다.

• 원본은 손대지 않습니다. 편집하면 서버가 사본을 만들어 판(v0 → v1 → v2 …)을 쌓고, 비교와 되돌리기를 지원합니다.

• 사람과 AI가 같이 고칩니다. 실시간 화면에서 Claude의 편집이 1초 안에 보이고, 사람이 고친 내용은 다음 호출 때 Claude에게 전달됩니다(human_edits). 동시에 고칠 때 생기는 충돌도 처리합니다.

• 채팅 안 미리보기. MCP Apps를 지원하는 클라이언트(claude.ai, Claude 데스크톱 등)에서는 도구 결과 아래에 쪽 미리보기가 뜹니다.

• 원하는 인증을 고릅니다. 인증 없음, Bearer 토큰, OIDC(Authentik·Keycloak·Zitadel …) 중에서 선택합니다.

• docker compose up 한 번으로 설치합니다.

혼자 로컬에서 Claude Code로만 쓴다면 rhwp에 내장된 MCP(rhwp mcp-serve)로도 충분합니다. hwp-cowork는 그 위에 판 관리, 실시간 공동 편집 화면, 원격 다중 사용자 서버를 얹은 것입니다.

빠른 시작

git clone https://github.com/pgc3344/hwp-cowork && cd hwp-cowork
mkdir -p docs && cp ~/내문서.hwp docs/
docker compose up -d --build

이제 MCP 주소는 http://localhost:8119/mcp입니다. 기본값은 인증 없음이고 127.0.0.1에서만 열립니다.

클라이언트 연결

Claude Code

claude mcp add --transport http hwp http://localhost:8119/mcp

Claude 데스크톱이나 다른 MCP 클라이언트: streamable HTTP 주소 http://localhost:8119/mcp를 등록합니다. token 모드라면 Authorization: Bearer <토큰> 헤더를 붙입니다.

claude.ai 커스텀 커넥터: 외부에서 닿는 HTTPS 주소가 필요합니다. 리버스 프록시나 터널 뒤에 두고, 인증은 oidc 모드를 씁니다(아래 참고).

연결한 뒤에는 이렇게 말하면 됩니다. "docs/내문서.hwp에서 표 3번째 행 금액을 고치고 실시간으로 보여줘."

Related MCP server: Hangeul-mcp

설정

cp .env.example .env로 복사한 뒤 고칩니다. 주요 항목은 다음과 같습니다.

인증

oidc 모드에서 지켜야 할 것:

• 제공자 쪽 클라이언트는 **public(PKCE)**이어야 합니다.

• redirect URI에 <PUBLIC_BASE>/sso/callback을 넣습니다.

• 서버가 동적 클라이언트 등록(DCR)을 대신 처리하므로, DCR이 없는 제공자도 claude.ai 커넥터에 주소만 넣으면 됩니다.

• 사람별 권한은 principals.example.json 형식으로 둡니다. 실시간 화면 링크는 링크 주인이 로그인한 브라우저에서만 열립니다.

none과 token 모드의 실시간 화면 링크는 링크 코드(12시간 유효)만으로 열립니다.

원본 폴더에 사본 저장

# docker-compose.yml
environment:
  HWPCOWORK_ROOTS: docs=/docs
  HWPCOWORK_WRITABLE_ROOTS: docs
volumes:
  - ./docs:/docs        # :ro 를 뗍니다

컨테이너는 uid 10003으로 돌기 때문에 sudo chown -R 10003 docs처럼 쓰기 권한을 줘야 합니다. 저장하면 원본 옆에 이름_vN.hwp가 생기고, 원본은 절대 덮어쓰지 않습니다.

도구

hwp_run의 기능 목록은 rhwp가 직접 내보냅니다(rhwp capabilities --mcp). 그래서 rhwp 버전을 올리면 코드를 고치지 않아도 기능이 늘어납니다.

실시간 화면

hwp_view_link나 편집 결과로 받은 링크를 열면 다음을 할 수 있습니다.

• 판 기록: 누가(Claude·사람·원본) 무엇을 바꿨는지, 판마다 바뀐 곳, 옛 판 보기와 되돌리기

• 직접 편집: 손을 멈추고 4초가 지나면 자동으로 새 판이 됩니다. Claude가 고치는 중이면 화면에 표시되고, 충돌이 나면 어느 쪽을 남길지 고릅니다

• 다운로드, 그리고 원본 폴더에 사본 저장(쓰기 허용 루트일 때)

보안 설계

• 원본 루트는 읽기 전용으로 마운트하는 것을 권장합니다. 편집은 /work 샌드박스 안에서만 일어납니다.

• rhwp에 넘기는 경로 인자는 모두 서버가 바꿔 넣습니다. 분류되지 않은 경로 인자는 막고(fail-closed), 응답에 실제 경로가 나가지 않습니다.

• 짧은 링크 코드를 무작위로 대입하면 IP마다 막습니다(10분에 20회).

• 컨테이너는 read_only, cap_drop: ALL, no-new-privileges, 비root 사용자로 돕니다.

개발

python3 -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/python -m pytest -q tests --ignore=tests/test_e2e.py
PYTHONPATH=src .venv/bin/python tests/test_apps.py
# rhwp 바이너리와 표가 있는 샘플 문서로 종단 테스트
HWPCOWORK_RHWP_BIN=/path/to/rhwp HWPCOWORK_TEST_HWP=sample.hwp .venv/bin/python tests/test_e2e.py

rhwp 버전은 Dockerfile의 RHWP_VERSION 한 곳에서 정합니다. 그 값 하나로 CLI, studio, editor가 함께 맞춰집니다.

라이선스

MIT. rhwp(MIT, © Edward Kim)를 사용하며, 자세한 내용은 NOTICE.md에 있습니다. "한글"과 "HWP"는 한글과컴퓨터의 상표이고, "Claude"는 Anthropic의 상표입니다. 이 프로젝트는 두 회사와 관계가 없습니다.