opencode-guide

[시니어 직장인의 AI 탐구기 #11] 한국 직장인 필수템! 깃허브에서 ‘kordoc’ 복사해 오픈코드에 HWP 파서 MCP 설치 및 실전 활용 가이드

“회사에서 받은 아래한글(HWP) 파일, AI에게 읽히려고 텍스트 복사하느라 고생하셨나요?”
공공기관과 기업에서 쏟아지는 HWP 문서를 한컴오피스 없이도 오픈코드가 알아서 척척 읽고, 마크다운(.md)으로 변환하며, 핵심만 3초 만에 요약해 주는 마법 같은 방법이 있습니다.

안녕하세요. 시니어 회사원의 시선에서 AI 실무 도구를 가장 쉽고 실용적으로 해설하는 블로그의 열한 번째 글입니다.

대한민국 직장인이라면 누구나 공감하겠지만, 공공기관 공문서, 입찰 제안서, 사내 규정집의 상당수가 여전히 아래한글(HWP / HWPX) 포맷으로 작성되어 있습니다. 하지만 해외에서 만들어진 대부분의 AI 도구들은 HWP 파일을 직접 읽지 못해 큰 불편을 겪어왔습니다.

오늘 소개해 드릴 kordoc (KorDoc, 개발자: 류주임)은 이 갈증을 완벽하게 해소한 국내 최고의 오픈소스 도구입니다.

이번 글에서는 깃허브(GitHub)에서 녹색 ‘Code’ 버튼을 눌러 레포지토리 주소를 복사한 뒤, 오픈코드 대화창에서 AI에게 설치를 지시하여 MCP(Model Context Protocol) 플러그인으로 등록하는 방법을 초보자도 따라 할 수 있게 단계별로 안내해 드립니다.

1. ‘kordoc’이란 무엇인가요?

kordoc은 현직 공무원 개발자가 공공 실무에서 쏟아지는 한글 문서를 AI가 처리하지 못하는 한계를 극복하기 위해 직접 개발한 한국형 문서 전용 오픈소스 파서이자 공식 MCP 서버입니다.

┌────────────────────────────────────────────────────────────────────────┐
│                          [ kordoc 핵심 강점 ]                          │
├────────────────────────────────────────────────────────────────────────┤
│ • 한컴오피스 프로그램 설치 불필요 (Mac, Windows, Linux 모두 독립 구동)   │
│ • 복잡한 공문서 다중 셀 표(Table), 개조식 글머리기호 완벽 보존            │
│ • HWP 구버전(3.x / 5.0)부터 최신 HWPX, HML, PDF, 오피스 문서까지 지원   │
│ • 오픈코드 에이전트가 HWP를 직접 읽고 쓰게 해주는 공식 MCP 서버 기본 내장  │
│ • 문서 비교(신구대조표) 및 서식 보존 텍스트 패치(Patch) 지원           │
└────────────────────────────────────────────────────────────────────────┘

[표] ‘kordoc’ 지원 포맷 및 주요 기능 요약

지원 파일 포맷	변환 형태	핵심 기능 및 실무 활용도
HWP (3.x, 5.0)	Markdown (`.md`), JSON	구버전 공문서 본문 및 복잡한 표 추출, 텍스트 요약
HWPX (최신 표준)	Markdown (`.md`), JSON	최신 한글 문서 구조 분석, 서식 보존 텍스트 교체 (Patch)
PDF / Office	Markdown (`.md`)	행정 보고서, 엑셀/워드 문서의 통합 AI 파싱
신구대조표 (Compare)	Markdown 비교 표	인사/회계 사내 규정 개정안 전/후 변경 조항 자동 비교

2. 깃허브 ‘Code’ 버튼 복사 → 오픈코드 안에서 MCP 설치 5단계

깃허브 웹사이트에서 레포지토리 주소를 복사한 뒤, 오픈코드 대화창에 주소를 붙여넣고 지시하면 AI가 알아서 오픈코드 전역 설정 파일(opencode.json)에 MCP 서버를 완벽하게 등록합니다.

설치 전체 흐름도

[1단계: 웹 브라우저]          [2단계: 초록색 Code 클릭]          [3단계: 오픈코드 대화창]
GitHub 메인에서 kordoc 검색  ──>  레포지토리 HTTPS 주소 복사  ──>  AI에게 "이 주소의 kordoc을
공식 저장소 이동               (초록색 Code 버튼 클릭)          전역 MCP로 등록해줘" 지시

[1단계] 깃허브 메인 접속 및 ‘kordoc’ 검색

웹 브라우저를 열고 GitHub 공식 사이트(https://github.com)에 접속합니다.
상단 검색창에 kordoc 또는 chrisryugj/kordoc을 입력하고 검색합니다.
검색 결과 목록에서 공식 저장소인 chrisryugj/kordoc을 클릭하여 이동합니다.
- 👉 저장소 직접 링크: https://github.com/chrisryugj/kordoc

[2단계] 녹색 ‘Code’ 버튼 클릭 후 레포지토리 주소 복사하기

저장소 메인 화면 우측 상단에 위치한 녹색 <> Code 버튼을 클릭합니다.
나타난 드롭다운 팝업에서 HTTPS 탭을 확인합니다.
표시된 주소(https://github.com/chrisryugj/kordoc.git) 옆의 ‘복사 아이콘(네모 두 개 겹친 모양)’을 클릭합니다.
- 주소가 내 컴퓨터 클립보드에 안전하게 복사되었습니다.

[3단계] 오픈코드 대화창에 주소 전달 및 MCP 설치 지시하기

오픈코드 데스크탑을 열고, 하단 프롬프트 입력창(Composer)에 복사한 주소와 함께 아래 추천 프롬프트를 입력합니다:

💬 초보자 추천 복사 프롬프트:
“깃허브에서 복사한 아래 레포지토리 주소의 kordoc을 내 오픈코드 전역 MCP 서버(~/.config/opencode/opencode.json)에 등록해줘.
레포지토리 주소: https://github.com/chrisryugj/kordoc.git
MCP 실행 명령어는 npx -y kordoc mcp 야.”

[4단계] AI의 자동 MCP 등록 및 설정 반영

지시를 받은 오픈코드 AI는 전역 설정 파일(~/.config/opencode/opencode.json)을 열어 다음과 같이 mcp 설정을 자동으로 등록합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "kordoc": {
        "type": "local",
        "command": ["npx", "-y", "kordoc", "mcp"]
      }
    }
  }
}

설정 파일이 저장되면 오픈코드가 백그라운드에서 설정을 즉시 리로드하며, AI 비서에게 HWP 문서를 직접 열고 파싱할 수 있는 전문 도구가 부여됩니다.

[5단계] 정상 등록 여부 3초 만에 확인하기

오픈코드 우측 Terminal 창(단축키: Control + Option + T)을 엽니다.
아래 명령어를 입력합니다:
```
opencode mcp list
```
목록에 kordoc이 출력되면 모든 설치와 연동이 100% 성공한 것입니다!

3. 실전! HWP 문서 처리 초간단 사용 예제 3가지

kordoc MCP가 등록되면, 사용자는 별도의 변환 프로그램을 실행할 필요 없이 평소처럼 대화창에서 HWP 파일 처리를 말로 부탁하면 됩니다.

📌 예제 1: HWP 기획서 읽고 핵심 3대 과제 요약 표 만들기

복잡한 수십 페이지짜리 사업계획서나 업무 보고서의 핵심만 빠르게 뽑아낼 때 사용합니다.

프롬프트 입력:

“현재 폴더에 있는 2026_신규사업계획서.hwp 파일을 읽어서, 사업 추진 배경과 핵심 추진 과제 3가지를 마크다운 표준 표 형식으로 깔끔하게 요약해줘.”
AI의 실제 반응 및 결과:
1. AI가 kordoc 도구를 호출하여 HWP 바이너리 파일을 순식간에 텍스트와 표로 파싱합니다.
2. 파싱된 데이터를 분석하여 배경, 목표, 담당 부서, 일정 등이 잘 정돈된 요약 보고서를 대화창에 출력합니다.

📌 예제 2: HWP 공문서를 마크다운(`.md`) 파일로 일괄 변환하기

팀원들과 웹/노션(Notion)에서 공유하거나 깃허브에 아카이빙하기 위해 HWP를 마크다운 파일로 영구 저장할 때 유용합니다.

프롬프트 입력:

“우리 팀 사내보안업무규정.hwp 파일의 본문과 표 서식을 그대로 유지해서 사내보안업무규정.md 파일로 변환하여 저장해줘.”
AI의 실제 반응 및 결과:
- kordoc의 마크다운 변환 엔진이 HWP의 표와 글머리기호를 완벽한 GFM 마크다운 파이프 표 형태로 번역합니다.
- 내 프로젝트 폴더 안에 깨끗한 마크다운 문서가 생성되어 오픈코드 우측 Open file 창에서 바로 확인 가능합니다.

📌 예제 3: 두 HWP 문서 간 신구대조표(개정 변경 내역) 자동 작성

회사 규정이나 계약서가 개정되었을 때, 어떤 조항이 어떻게 바뀌었는지 하나하나 눈으로 대조하는 고통을 덜어줍니다.

프롬프트 입력:

“지난달 버전인 취업규칙_v1.hwp와 이번 개정안 취업규칙_v2.hwp를 비교하여, 신구대조표(조항 번호, 개정 전 내용, 개정 후 내용, 변경 사유) 표를 만들어줘.”
AI의 실제 반응 및 결과:
- 두 파일의 텍스트 차이점을 자동으로 교차 분석하여, 삭제되거나 추가된 단어와 조항을 명확한 신구대조표 형태로 일목요연하게 보고합니다.

4. 실무 활용을 위한 프롬프트 명령어 요약표

업무 목적	추천 프롬프트 형태	기대 산출물
HWP 본문 요약	”`[파일명.hwp]` 읽어서 주요 안건 3줄 요약해줘”	대화창 내 핵심 요약 브리핑 및 마크다운 표
MD 파일 변환	”`[파일명.hwp]`를 같은 이름의 `.md` 파일로 변환해줘”	프로젝트 폴더 내 표준 마크다운(`.md`) 파일 생성
규정 신구대조	”`[구버전.hwp]`와 `[신버전.hwp]` 비교해서 신구대조표 작성해줘”	조항별 개정 전/후 비교 분석 마크다운 표
MCP 연결 확인	터미널에 `opencode mcp list` 입력	등록된 `kordoc` MCP 서버 연결 상태 확인

5. 시니어 안심 Q&A

Q1. Mac(맥북)을 쓰는데 한컴오피스가 없어도 정말 잘 작동하나요?

네, 100% 독립 구동됩니다.
kordoc은 한컴오피스 프로그램에 의존하지 않고, HWP 파일의 바이너리 구조를 직접 해석하는 독립 엔진으로 동작합니다. 따라서 윈도우는 물론 맥북, 리눅스 환경에서도 한컴오피스 설치 없이 완벽하게 구동됩니다.

Q2. 10년 전 작성된 옛날 HWP 파일도 읽을 수 있나요?

네, 완벽히 지원합니다.
최신 한글 표준인 HWPX 뿐만 아니라 과거 공공기관에서 널리 쓰이던 HWP 5.0 및 HWP 3.x 바이너리 포맷까지 모두 지원하므로 오래된 사내 문서도 안심하고 넘겨줄 수 있습니다.

6. 에필로그

이제 여러분의 오픈코드는 구글 제미나이의 두뇌와 아키파이(archify)의 시각화 능력에 더해, ‘대한민국 모든 아래한글(HWP) 문서를 자유자재로 해독하고 분석하는 한국형 무적 AI 비서’로 거듭났습니다.

깃허브에서 주소를 복사해 오픈코드에 던져주는 이 간단한 패턴만 익혀두시면, 앞으로 등장할 어떤 최신 AI 플러그인도 단 1분 만에 내 것으로 만들 수 있습니다.

오늘 안내해 드린 순서대로 차근차근 설치해 보시고, 내 컴퓨터에 잠들어 있던 복잡한 HWP 파일들을 오픈코드에게 시원하게 맡겨보세요!

작성일: 2026년 10월 31일
태그: #오픈코드 #OpenCode #MCP #kordoc #한글파일 #HWP #HWPX #마크다운변환 #신구대조표 #공문서요약 #직장인생산성 #시니어AI