gongmu-kit
by qihong-jin
README.md
# gongmu-kit
**공무(관급공사 행정서류) 에이전트를 위한 MCP 서버 + Claude 스킬 모음**
*An MCP server and Claude skills for Korean public-works paperwork agents — HWP reader, answer-key comparison, PII guard, multi-AI handoff.*
관급공사 서류 자동화를 AI 도구 여러 개로 개발하며 반복해서 부딪힌 문제 12가지([docs/pain-points.md](docs/pain-points.md))를 도구로 풀었습니다.
모든 처리는 **로컬**에서 이루어지고 외부 서비스로 문서를 보내지 않습니다.
## 무엇이 들어 있나
| 도구 (MCP) | 하는 일 |
|---|---|
| `hwp_read` | `.hwp`(5.x) / `.hwpx` 본문·표(행·열·병합·캡션) 읽기 — **한글 프로그램 불필요** |
| `read_document` | xlsx / xls / csv / txt / json 도 같은 방식으로 읽기 (`Sheet1!B3`, `표2!R3C2` 위치 표기) |
| `compare_documents` | 생성본 vs 최종 제출본(정답지) 비교 — 셀 위치·값 기준 일치율 + 차이 목록 |
| `consistency_check` | 여러 서류에서 같은 사실(예: 준공금액)이 일치하는지 라벨 기준으로 대조 |
| `pii_scan` / `pii_redact` | 주민·외국인등록번호, 계좌, 카드, 휴대전화, 이메일 탐지 — 값 없이 건수·위치·마스킹만 |
| `find_docs` | 여러 폴더(NAS 동기화·카카오톡 받은 파일·다운로드)를 함께 검색, 검색한 곳/접근 불가한 곳 보고 |
| `resolve_site` | 메일 제목·파일명·카톡방 이름 → 현장 코드 |
| `handoff_check` / `clear_stale_locks` | 다음 AI 도구에 넘길 준비(깨끗한 작업트리·락·커밋 태그·작업표) 점검과 잔재 락 정리 |
| `run_selftest` | 프로젝트 `.venv` 로 selftest 실행(UTF-8 강제) + 환경 지문 |
| `make_handoff_prompt` | Codex/Antigravity용 지시문(고정 N줄 보고 형식, 새 창/기존 창 안내) |
| `make_decision_request` | 권장안·근거 등급·확신도·문의문을 갖춘 "확인필요" 형식 |
| 스킬 | 언제 |
|---|---|
| `gongmu-handoff` | 여러 AI 도구가 한 저장소를 번갈아 작업할 때 |
| `gongmu-decision-request` | 사용자 판단이 필요한 사안을 정리할 때 |
| `gongmu-real-doc-first` | 서류 생성 도구를 만들고 검증할 때 (실제 구조 먼저, 정답지 대조) |
## 설치
Python 3.9+ (3.13에서 테스트). 윈도우에서는 `python` 이 스토어 스텁일 수 있으니 가상환경의 인터프리터를 직접 지정하세요.
```bat
git clone https://github.com/qihong-jin/gongmu-kit.git C:\tools\gongmu-kit
cd C:\tools\gongmu-kit
py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -e .[xls]
```
### Claude Desktop
`claude_desktop_config.json` 에 추가 ([예시](examples/claude_desktop_config.example.json)):
```json
{
"mcpServers": {
"gongmu-kit": {
"command": "C:\\tools\\gongmu-kit\\.venv\\Scripts\\python.exe",
"args": ["-m", "gongmu_kit.server"],
"env": { "PYTHONUTF8": "1", "GONGMU_ALLOWED_ROOTS": "C:\\Work;C:\\Users\\me\\Downloads" }
}
}
}
```
### Claude Code
```bash
claude mcp add gongmu-kit -- /path/to/.venv/bin/python -m gongmu_kit.server
```
### 스킬
`skills/*` 폴더를 Claude의 스킬 폴더(예: `~/.claude/skills/`)에 복사하세요.
(저장소에는 실험적으로 `.claude-plugin/plugin.json` 과 `.mcp.json` 도 들어 있습니다.)
### CLI
같은 기능을 터미널에서도 쓸 수 있습니다 (JSON 출력, 항상 UTF-8):
```bash
gongmu-kit hwp-read 준공검사원.hwp
gongmu-kit compare 생성본.xlsx 정답지.hwp
gongmu-kit xcheck 착공계.xlsx 준공계.hwp -f "준공금액|준공 금액" -f 공사명
gongmu-kit pii-scan 기술자명단.xlsx
gongmu-kit find "○○초 계약서" --ext pdf
gongmu-kit handoff-check . --expect-tag Claude --task-id 107
```
## 설정
| 환경변수 | 의미 |
|---|---|
| `GONGMU_ALLOWED_ROOTS` | 파일 도구가 읽을 수 있는 폴더 제한 (`;` 윈도우 / `:` 리눅스로 구분). **설정을 권장합니다** |
| `GONGMU_SEARCH_ROOTS` | `find_docs` 기본 검색 폴더 |
| `GONGMU_SITES` | 현장 목록 JSON 경로 ([예시](examples/sites.example.json)) — 저장소 밖에 두세요 |
| `GONGMU_CONFIG` | `~/.gongmu-kit/config.json` 대신 쓸 설정 파일 ([예시](examples/config.example.json)) |
## 개인정보·안전 원칙
- 문서는 로컬에서만 처리하며 네트워크를 쓰지 않습니다.
- 출력은 **기본적으로 마스킹**됩니다 (`redact_pii=false` 로만 해제). `pii_scan` 은 값을 돌려주지 않습니다.
- 탐지는 패턴 기반이라 완전하지 않습니다. 중요한 서류는 사람이 최종 확인하세요.
- `clear_stale_locks` 는 `.git` 안의 `*.lock`·`stale-*` 중 오래된 것만 건드리고 기본이 `dry_run` 입니다.
- `run_selftest` 는 저장소 안의 `.py` 파일만 실행합니다 (임의 명령 실행 없음).
## 한계
- **배포용 문서**(본문 암호화)와 **암호 문서** 는 읽지 못하고 오류로 알립니다 (한글에서 해제 후 저장하거나 PDF 변환).
- PDF·스캔본 OCR·DWG 는 포함하지 않습니다.
- `consistency_check` 는 불일치를 알려 줄 뿐 어느 쪽이 맞는지 판단하지 않습니다.
- 법률·세무 조언이 아닙니다.
- 구버전 한글(2005 등)에서 쓰인 일부 옛 글자가 사용자 영역 문자로 읽힐 수 있습니다.
## 개발·검증
```bash
pip install -e .[dev]
pytest # 합성 HWP(실제 OLE 컨테이너)·MCP 서버 end-to-end 포함
GONGMU_REAL_HWP_DIR=/path/to/real_hwp_samples pytest tests/test_hwp.py # 실제 한글 파일로 스모크 테스트
```
`hwp_read` 는 합성 파일뿐 아니라 한글이 직접 저장한 공개 샘플 36개(표·캡션·텍스트박스·머리말 포함)로도 확인했고,
MCP SDK 1.x 와 2.x 양쪽에서 테스트합니다.
## English summary
`gongmu-kit` is an MCP server (stdio, MCP SDK 1.x/2.x) plus three Claude skills for Korean public-works paperwork agents:
a dependency-light **HWP/HWPX reader** (no Hangul needed; tables with cell addresses and merges), **answer-key comparison**
and **cross-document consistency checks** with date/amount normalisation, a **PII scanner/redactor** that never returns raw values,
a **multi-root document finder** that reports unreachable roots, a **site registry resolver**, and helpers for
**multi-AI handoff** (git cleanliness/lock checks, copy-paste prompts with a fixed report format, UTF-8-safe self-test runner)
and **structured decision requests**. Everything runs locally. MIT licensed.
## 라이선스
MIT — [LICENSE](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues