korean-report-hwpx — 한국 공문서 MCP (보고서·보도자료 HWPX)

· English

0.2.0부터 업스테이지 Solar Pro 4로 개발합니다. 간소화 모드·마크다운 출력·내부 결재 보고서는 Solar Pro 4(Solar Code CLI)가 코드를 작성하고, Claude가 결과를 검증했습니다.

공무원 공문서(보고서·보도자료)를 기관 서식 HWPX로. 쓰고 있는 AI(Claude·ChatGPT 등)가 메모·초안을 공문서 구조로 정리하면, 52개 중앙행정기관의 서식 규칙값으로 한글(HWPX) 파일을 그립니다.

외부 전송 없음 · API 키 불필요 — 모든 처리는 설치한 컴퓨터 안에서 끝납니다. 원고는 이 서버 밖으로 나가지 않습니다. → English README

"이 내용 공문서처럼 써 줘" 한마디로 개조식 보고서(□ → ㅇ → -) 또는 보도자료를 기관 서식대로 만듭니다. 서식은 정책브리핑 보도자료 2,670건 전수 조사로 정한 규칙값이며, 원본 문서·로고는 포함하지 않습니다.

이렇게 물어보세요

• "이 메모를 ○○부 보고서로 만들어 줘"
• "회의 내용 정리한 거야. 공문서처럼 정리해 줘" (기관을 말하지 않으면 공통 서식)
• "이 원고 국세청 보도자료로 만들어 줘 — 보도시점 2026. 10. 8.(목) 조간"
• "아까 만든 보고서 구조에서 Ⅲ장 □ 문장만 바꿔서 다시 만들어 줘"
• "산림청 보고서 서식 규칙(계층별 기호·글꼴·크기) 보여 줘"

설치 한 줄 — claude mcp add korean-report-hwpx -- uvx korean-report-hwpx

문서 종류

사용 흐름 — AI에게 "이 메모를 ○○부 보고서로 만들어 줘" → AI가 get_writing_guide로 작성 규칙 확인 → 원고를 구조 JSON으로 작성 → build_document → 결과의 warnings(고칠 점)가 있으면 AI가 고쳐 다시 생성.

문서 종류 판단 기준(가이드에 포함): 언론·국민 대상 발표·배포용이면 보도자료, 내부 보고·계획·검토면 보고서.

설치

uv가 있으면 설치 없이 바로 실행됩니다.

{
  "mcpServers": {
    "korean-report-hwpx": {
      "command": "uvx",
      "args": ["korean-report-hwpx"]
    }
  }
}

Claude Code: claude mcp add korean-report-hwpx -- uvx korean-report-hwpx

• API 키·환경변수 필요 없음.
• 만든 파일은 ~/korean-report-hwpx/에 저장됩니다(KOREAN_REPORT_HWPX_OUT_DIR로 변경, 이전 이름 KOREAN_GOV_DOCS_OUT_DIR도 인식).

도구

간소화 모드 (style="simplified")

AI가 읽기 쉬운 보고서 서식(번호 체계 표준화, 서술식 문장, 단순한 표). 항목 기호를 단계별 번호로 자동 부여하고, 제목 상자·표 머리 음영을 없앤 간결한 서식.

사용법: build_document(..., style="simplified") 또는 get_writing_guide(..., style="simplified")로 지정.

간소화 모드 특징:

• 항목 기호(□ ㅇ ○ - * ※) 대신 단계별 번호 자동 부여: Ⅰ. Ⅱ. Ⅲ. (소제목) → 1. 2. 3. (대항목) → 가. 나. 다. (중항목) → 1) 2) 3) (소항목) → 가) 나) 다) (세항목)
• 번호는 서버가 구조 JSON의 계층 수준(level)에서 계산하므로 사용자가 직접 번호를 쓰지 않음
• 단계별 들여쓰기 유지
• 서술식 문장 허용 (~합니다·~했다 등 동사형 종결 가능, 명사형 종결 경고 없음)
• 제목 상자(테두리·음영) 없이 일반 제목 문단
• 표 머리 음영 없음
• 표 제목 자동 번호: 〈표 1〉 제목 형식 (caption에는 제목만 작성)
• 표 셀 병합 금지: 구조에 병합이 있으면 같은 값이 행마다 반복되도록 풀어 씀
• export_markdown=True: 같은 구조로 .md 파일 동시 저장 (GFM 표, #, ##, ### 제목 위계)
• 줄 간격 150%, 문단 위 10pt(1수준)·5pt(그 외), 빈 줄 없이 문단 간격으로 구분
• 번호는 글자로 넣음. 한글 '개요' 번호 연동은 다음 버전 예정

내부 결재 보고서 (report_kind="internal")

정보공개포털 내부 결재 보고서 실물 표본 측정값 반영: 라벨 칸 없는 제목, 작성일·부서 줄 '26. 10. 9.(금) / 과·팀명, 줄 간격 150%, 문단 위 10pt(□)·5pt(ㅇ·-).

예시:

{
  "title": "○○ 추진계획(안)", "date": "2026. 10. 7.", "dept": "○○과",
  "body": [
    {"type": "h", "text": "추진 배경"},
    {"type": "l1", "text": "민원 대기 시간 감소를 위해 AI 안내 도입 필요"},
    {"type": "l2", "text": "하루 평균 창구 민원 약 400건"},
    {"type": "caption", "text": "소요 예산"},
    {"type": "table", "rows": [["구분", "금액"], ["시스템 구축", "2억"]]}
  ]
}

→ 간소화 모드로 생성 시: Ⅰ. 추진 배경, 1. 민원 대기 시간 감소를 위해 AI 안내 도입 필요, 가. 하루 평균 창구 민원 약 400건, 〈표 1〉 소요 예산 형식으로 표시.

보고서 구조 JSON 예:

{
  "title": "○○ 서비스 도입 추진계획(안)", "date": "2026. 10. 7.", "dept": "○○과",
  "body": [{"type": "h", "text": "Ⅰ. 추진 배경"},
           {"type": "l1", "text": "핵심 결론 한 문장임"}, {"type": "l2", "text": "근거·세부"}, {"type": "l3", "text": "소항목"},
           {"type": "note", "text": "각주"}, {"type": "ref", "text": "참고 사항"},
           {"type": "caption", "text": "소요 예산"}, {"type": "table", "rows": [["구분", "금액"], ["가", "100"]]}],
  "appendix": [{"title": "붙임 1", "heading": "세부 내용", "body": [{"type": "l1", "text": "..."}]}]
}

보도자료 구조는 {release, distribute, title, subtitles, body, appendix, contact}입니다(블록 종류는 같고 문단 p·강조 상자 box·그림 image 추가). 원고에 담당자가 없으면 담당 표를 ○○과 / 김○○ / 044-000-0000 자리표시로 채웁니다(placeholder_contact).

지원 기관 (52곳)

보고서: 기관 규칙 = 그 기관 보도자료 참고·붙임 구간 실측값(42곳), 공통 규칙 = 기관 간 최빈값(기관을 지정하지 않으면 기관명 칸은 비움). 보도자료: 문단식 = 기호 없는 기사체 문단 위주, □식 = □ → ㅇ → - 개조식.

기관 로고

정부상징·기관 로고는 사용 규정상 이 패키지에 포함하지 않습니다. 소속 기관 담당자가 자기 기관 로고 파일을 지정하세요.

• logo_path로 로고 그림 파일을 지정하면 보도자료는 표지의 로고 자리(기관별 크기)에, 보고서는 제목 상자 위에 들어갑니다. 보도자료 슬로건 그림은 slogan_path.
• 지정하지 않으면 보도자료 표지에 같은 크기의 「기관 로고」 자리표시가 들어갑니다. 한글에서 글을 지우고 그림을 넣으면 됩니다.

데이터 전송 안내

• 모든 처리는 로컬입니다. 이 서버는 외부 API를 부르지 않고, 원고·결과 파일을 어디로도 보내지 않습니다.
• 원고를 구조로 정리하는 일은 사용자가 쓰는 AI가 합니다. 그 AI 서비스의 데이터 정책은 별도로 확인하세요.

근거

• 정책브리핑(korea.kr) 보도자료 HWPX 2,670건(52개 중앙행정기관) 전수 파싱. 보도자료 본문 서식은 2,016건의 문단 35,465개·빈 줄 35,434개·표 칸 32,392개 실측.
• 보고서 서식은 같은 자료 중 「참고·붙임」 보고서형 구간이 있는 1,326건(문단 13,757개)에서 기관별로 산출(42개 기관, 3건 이상). 공통 골격(□·-·*·※ 기호, 기호 뒤 1타, 1행 제목 상자, 표 머리 맑은 고딕·가운데·굵게)은 기관 간 90% 이상 일치.
• 공식 기준: 「행정업무의 운영 및 혁신에 관한 규정 시행규칙」의 항목 구분(1. → 가. → 1) → 가) …), 경기도교육청 「한 곳에 정리한 공문서 작성법」(둘째 줄은 항목 첫 글자에 맞춤, 기호 뒤 1타, 하위 항목 2타 들여쓰기 등).
• 실측: 정책브리핑 보도자료 2,670건·52개 기관(보고서 구간 1,326건)에서 기관별 기호·글꼴·빈 줄·표지 표 수치를 산출.
• 규칙 문서: 보도자료 서식 규칙, 보고서 서식 규칙. 규칙값: rules/, rules_report/, 보도자료 표지·담당 표 수치: templates/.
• 원자료는 정책브리핑에 공공누리로 공개된 보도자료이며, 이 저장소에는 원본 파일·본문·그림을 포함하지 않고 서식 수치만 담았습니다.

유의

• 결과물은 초안입니다. 보고·배포 전 한글에서 확인하세요.
• 줄 끝(마지막 줄 한두 글자 등)은 글자 폭 추정으로 맞추므로 일부 남을 수 있습니다. macOS + 한컴오피스 한글이 있으면 polish=True로 실제 줄 배치를 받아 문단별 자간을 다시 고릅니다(한글 창이 여러 번 열리고 수 분 걸림).
• 글꼴은 사용하는 컴퓨터에 설치된 글꼴로 표시됩니다(휴먼명조·HY헤드라인M 등 미설치 시 대체 글꼴).
• 기안문은 다음 버전에서 지원할 예정입니다.

라이선스

MIT © 2026 Upstage

Created by Mia(윤승미)