GongMun Doctor MCP

AI가 공문서를 로컬에서 안전하게 교정합니다 AI-powered Korean official document proofreading -- 100% local, no cloud required

---

소개 | Introduction

GongMun Doctor MCP는 한국 공문서(.hwpx/.hwp)를 로컬 PC에서 자동 교정하는 MCP 서버입니다. Claude, Codex 등 AI 에이전트에게 "이 문서 교정해줘"라고 말하면, 파일이 외부로 나가지 않고 내 PC 안에서 교정이 완료됩니다.

GongMun Doctor MCP is a local MCP server that proofreads Korean official documents (.hwpx/.hwp) entirely on your PC. When you ask an AI agent like Claude or Codex to "proofread this document," the file never leaves your machine.

보안 원칙 | Security First: 문서는 밖으로 나가지 않습니다. 네트워크 호출 없음. 클라우드 API 키 불필요. Documents stay local. No network calls. No cloud API keys needed.

---

이런 분들에게 유용합니다 | Who Is This For?

대상	활용 예시
공무원	기안 작성 후 맞춤법/공문서체 자동 교정, 보고 전 최종 검수
공공기관 직원	업무협조 요청, 민원회신 등 공문 템플릿 자동 생성
행정사/법무사	대량 문서 일괄 교정, 교정 보고서 자동 생성
공문 작성이 처음인 분	50종 행정문서 템플릿으로 올바른 양식 학습

Who	Use Case
Government officials	Auto-proofread drafts before submission
Public institution staff	Generate official document templates (cooperation requests, civil responses, etc.)
Administrative professionals	Batch-correct large volumes of documents with reports
Beginners	Learn proper official document formatting with 50 built-in templates

---

주요 기능 | Key Features

3단계 교정 규칙 | 3-Layer Correction Rules

레이어 Layer	내용 Description	예시 Example
L1 맞춤법	띄어쓰기, 맞춤법 교정	"시행알림" -> "시행 알림"
L2 문법	조사 오류, 병기 제거	"을/를" -> "을" (공문서는 조사 병기 금지)
L3 공문서체	행정업무운영편람 기준 서식 교정	"관련하여," -> "관련하여" (접속표현 뒤 쉼표 생략)

10개 MCP 도구 | 10 MCP Tools

#	도구 Tool	설명 Description
1	correct_document	단일 문서 교정 / Correct one document
2	correct_documents_in_folder	폴더 내 문서 일괄 교정 / Batch correct all documents in a folder
3	list_rules	교정 규칙 목록 조회 / List correction rules
4	get_correction_report	교정 보고서 조회 / Read correction report
5	preview_text_corrections	텍스트 교정 미리보기 / Preview corrections without touching files
6	list_document_templates	행정문서 템플릿 목록 / List document templates
7	match_document_templates	키워드로 템플릿 검색 / Search templates by keyword
8	get_template_variables	템플릿 입력 변수 조회 / Show required template variables
9	render_document_template	템플릿 렌더링 (문서 생성) / Render template with values
10	get_server_info	서버 정보 조회 / Server info

50종 행정문서 템플릿 | 50 Administrative Templates

6개 분야에 걸쳐 실무에서 바로 쓸 수 있는 템플릿을 제공합니다:

분야 Category	템플릿 수	예시 Examples
일반행정 (gen)	15종	업무협조요청, 알림통보, 회신, 업무보고, 자료요청, 회의개최알림 등
감사 (audit)	5종	감사결과통보, 시정조치요구, 지도점검알림 등
민원 (civil)	5종	민원회신, 처리기간연장통보, 이첩통보, 질의회신 등
건설공사 (con)	10종	착공알림, 준공알림, 설계변경요청, 하자보수통보 등
인사 (hr)	5종	출장결과보고, 휴가사용보고, 겸직허가신청, 직위해제통보 등
계약조달 (proc)	10종	입찰공고, 낙찰자결정통보, 계약체결요청, 보조금교부신청 등

---

빠른 시작 가이드 | Quick Start Guide

1단계: 설치 | Step 1: Install

Python 3.12 또는 3.13을 권장합니다. 3.14에서는 lxml 빌드 문제가 발생할 수 있습니다. Python 3.12 or 3.13 recommended. 3.14 may have lxml build issues.

# 저장소 클론 | Clone the repository
git clone https://github.com/sinmb79/GongMun-Doctor-MCP.git
cd GongMun-Doctor-MCP

# MCP 라이브러리 설치 | Install MCP library
python -m pip install "mcp[cli]>=1.0,<2"

# GongMun Doctor 설치 (개발 모드) | Install in dev mode
python -m pip install -e . --no-deps

2단계: 서버 실행 확인 | Step 2: Verify Server

# 서버 직접 실행 | Run server directly
python -m gongmun_doctor.mcp.server

# MCP Inspector로 도구 목록 확인 (선택) | Inspect tools visually (optional)
npx -y @modelcontextprotocol/inspector python -m gongmun_doctor.mcp.server

3단계: AI 클라이언트 연결 | Step 3: Connect Your AI Client

Codex (가장 간단 | Simplest)

codex mcp add gongmun-doctor -- python -m gongmun_doctor.mcp.server

확인:

codex mcp list

Claude Code

claude mcp add --transport stdio gongmun-doctor -- python -m gongmun_doctor.mcp.server

프로젝트 단위로 설정하려면 .mcp.json을 사용하세요. 자세한 내용은 docs/client-setup-ko.md를 참고하세요.

Claude Desktop

수동 stdio 연결 예시는 examples/claude_desktop_config.json을 참고하세요.

---

실전 사용 예시 | Real-World Usage Examples

AI 에이전트에 연결한 후, 자연어로 요청하면 됩니다. 도구 이름을 외울 필요가 없습니다.

After connecting to your AI agent, just ask in natural language. No need to memorize tool names.

예시 1: 단일 문서 교정 | Example 1: Correct One Document

이렇게 말하세요 | Say this:

D:\문서\공문.hwpx를 dry_run으로 먼저 검사해줘

AI가 수행하는 작업 | What happens:

correct_document(file_path="D:\\문서\\공문.hwpx", dry_run=True) 호출

{
  "status": "dry_run_complete",
  "file_path": "D:\\문서\\공문.hwpx",
  "corrections": [
    {"rule": "SP-001", "layer": "L1_spelling", "before": "시행알림", "after": "시행 알림"},
    {"rule": "GR-001", "layer": "L2_grammar", "before": "을/를", "after": "을"},
    {"rule": "OS-002", "layer": "L3_official_style", "before": "관련 :", "after": "관련:"}
  ],
  "total_corrections": 3
}

교정 내용을 확인한 뒤 실제 적용:

확인했어. 실제로 교정해줘.

예시 2: 폴더 일괄 교정 | Example 2: Batch Correct a Folder

D:\문서\주간보고 폴더 안의 .hwpx를 전부 교정하고 보고서도 만들어줘

correct_documents_in_folder(folder_path="D:\\문서\\주간보고", report=True) 호출 -- 폴더 내 모든 .hwpx 파일을 교정하고 각각의 교정 보고서(Markdown)를 생성합니다.

예시 3: 교정 규칙 확인 | Example 3: Check Rules

맞춤법 레이어 규칙만 보여줘

list_rules(layer="L1_spelling") 호출:

[
  {"id": "SP-001", "search": "시행알림", "replace": "시행 알림", "desc": "합성어가 아닌 경우 띄어쓰기"},
  {"id": "SP-002", "search": "참고 하시기", "replace": "참고하시기", "desc": "'참고하다'는 한 단어이므로 붙여 씀"},
  {"id": "SP-003", "search": "보수 공사", "replace": "보수공사", "desc": "'보수공사'는 한 단어이므로 붙여 씀"}
]

예시 4: 공문 템플릿으로 문서 작성 | Example 4: Generate Document from Template

업무 협조 요청 공문을 만들어줘

AI가 자동으로 적절한 템플릿을 찾고, 필요한 정보를 물어본 뒤 문서를 생성합니다:

수신기관: ○○시 도시건설국장
제목: 도시계획 변경 관련 업무 협조 요청
관련문서: 도시계획과-1234(2026.03.10.)
협조사항: 도시계획 변경안 검토
기한: 2026. 4. 10.

생성 결과 | Output:

수신 ○○시 도시건설국장
(경유)
제목 도시계획 변경 관련 업무 협조 요청

1. 관련: 도시계획과-1234(2026.03.10.)

2. 위 호와 관련하여 도시계획 변경안 검토에 대한 귀 기관의
   적극적인 협조를 요청합니다.

3. 협조 요청 사항은 다음과 같습니다.
   가. 협조 내용: 도시계획 변경안 검토
   나. 회신 기한: 2026. 4. 10.까지
   다. 담당자: 도시계획과 담당자 홍길동

붙임 협조 요청 자료 1부.  끝.

예시 5: 텍스트 미리보기 | Example 5: Preview Text Corrections

"관련하여, 을/를 첨부 합니다" 이 문장 교정해줘

preview_text_corrections(text="관련하여, 을/를 첨부 합니다") 호출 -- 파일 없이 텍스트만으로 교정 결과를 미리 확인할 수 있습니다.

---

프로젝트 구조 | Project Structure

GongMun-Doctor-MCP/
|-- src/gongmun_doctor/
|   |-- mcp/                   # MCP 서버 | MCP server
|   |   |-- server.py           #   서버 정의 (10개 도구)
|   |   |-- services.py         #   비즈니스 로직
|   |   +-- models.py           #   데이터 모델
|   |-- rules/                  # 교정 규칙 | Correction rules
|   |   |-- L1_spelling.json    #   맞춤법/띄어쓰기
|   |   |-- L2_grammar.json     #   문법 (조사 오류 등)
|   |   +-- L3_official_style.json  #   공문서체
|   |-- agents/administrative/  # 행정문서 템플릿 | Templates
|   |   +-- templates/          #   50종 JSON 템플릿
|   |-- parser/                 # HWPX/HWP 파서 | Document parser
|   |-- engine.py               # 교정 엔진 | Correction engine
|   +-- report/                 # 보고서 생성 | Report generator
|-- docs/                       # 설정 가이드 | Setup guides
|-- examples/                   # 클라이언트 설정 예시 | Client config examples
+-- tests/                      # 테스트 | Tests

---

자주 묻는 질문 | FAQ

서버는 뜨는데 문서 교정이 안 돼요

MCP 서버 실행과 문서 교정은 별개입니다. 실제 .hwpx 문서 교정에는 python-hwpx 런타임이 필요합니다:

python -m pip install "python-hwpx>=2.8.0"

Windows에서 명령어를 못 찾아요

python, codex, claude 명령이 PATH에 없는 경우입니다. 전체 경로를 사용하세요:

# 예시: Python 전체 경로
C:\Users\사용자\AppData\Local\Programs\Python\Python312\python.exe -m gongmun_doctor.mcp.server

Claude Code에서 승인 팝업이 떠요

정상 동작입니다. .mcp.json 기반 프로젝트 서버는 처음 사용 시 승인 과정을 거칩니다.

Claude Desktop에서 연결이 안 돼요

현재 주력 지원 대상은 Codex와 Claude Code입니다. Claude Desktop은 수동 stdio 연결로 가능하지만 환경에 따라 차이가 있을 수 있습니다.

---

테스트 실행 | Running Tests

pytest tests -q

실제 HWPX 파일이 필요한 통합 테스트는 별도 마커로 관리합니다:

# 통합 테스트 제외 | Skip integration tests
pytest tests -q -m "not integration"

---

보안 설계 원칙 | Security Design Principles

원칙 Principle	설명 Description
로컬 우선	모든 파일 처리는 사용자 PC 내에서 완료
네트워크 없음	기본 동작에 네트워크 호출 없음
API 키 불필요	클라우드 API 키 없이 시작 가능
경계 명확	로컬 처리와 외부 통신의 경계를 명확히 구분

클라우드 LLM 분석, 한글 COM 자동조작 등 확장 기능은 선택적(opt-in)이며 기본 범위에 포함되지 않습니다. Cloud LLM analysis and HWP COM automation are opt-in extensions, not included in the default scope.

---

참고 문서 | References

• 클라이언트 연결 가이드 (한글)
• MCP 준비 메모
• Claude Desktop 설정 예시
• Claude Code .mcp.json 예시
• Codex 설정 예시

---

라이선스 | License

MIT License -- 자유롭게 사용, 수정, 배포할 수 있습니다.

MIT License -- Free to use, modify, and distribute.

---

만든 사람 | Author

22B Labs (sinmb79) -- The 4th Path

문의사항이나 기여는 Issues를 이용해 주세요.

For questions or contributions, please use Issues.