Skip to main content
Glama

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)를 도구로 풀었습니다. 모든 처리는 로컬에서 이루어지고 외부 서비스로 문서를 보내지 않습니다.

무엇이 들어 있나

도구 (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

서류 생성 도구를 만들고 검증할 때 (실제 구조 먼저, 정답지 대조)

Related MCP server: artifact-intelligence

설치

Python 3.9+ (3.13에서 테스트). 윈도우에서는 python 이 스토어 스텁일 수 있으니 가상환경의 인터프리터를 직접 지정하세요.

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 에 추가 (예시):

{
  "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

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):

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 경로 (예시) — 저장소 밖에 두세요

GONGMU_CONFIG

~/.gongmu-kit/config.json 대신 쓸 설정 파일 (예시)

개인정보·안전 원칙

  • 문서는 로컬에서만 처리하며 네트워크를 쓰지 않습니다.

  • 출력은 기본적으로 마스킹됩니다 (redact_pii=false 로만 해제). pii_scan 은 값을 돌려주지 않습니다.

  • 탐지는 패턴 기반이라 완전하지 않습니다. 중요한 서류는 사람이 최종 확인하세요.

  • clear_stale_locks 는 .git 안의 *.lock·stale-* 중 오래된 것만 건드리고 기본이 dry_run 입니다.

  • run_selftest 는 저장소 안의 .py 파일만 실행합니다 (임의 명령 실행 없음).

한계

  • 배포용 문서(본문 암호화)와 암호 문서 는 읽지 못하고 오류로 알립니다 (한글에서 해제 후 저장하거나 PDF 변환).

  • PDF·스캔본 OCR·DWG 는 포함하지 않습니다.

  • consistency_check 는 불일치를 알려 줄 뿐 어느 쪽이 맞는지 판단하지 않습니다.

  • 법률·세무 조언이 아닙니다.

  • 구버전 한글(2005 등)에서 쓰인 일부 옛 글자가 사용자 영역 문자로 읽힐 수 있습니다.

개발·검증

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables secure local proofreading of Korean official documents (.hwpx/.hwp) using 3-layer AI correction for spelling, grammar, and official document style. Provides 50 administrative document templates for generating standardized official correspondence without cloud dependencies or API keys.
      24
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Turns your intent and source facts into approval-ready Korean public-sector documents — reports, official letters, regulations, press releases, and slides — as HTML, PDF, HWPX, and PPTX. Everything runs locally so your documents never leave your machine; only formatting-rule fragments are fetched from a policy server.
      3
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables reading and extracting text from local documents (PDF, Word, Excel, PowerPoint, HWP, Markdown, CSV, etc.) without network access, and provides approval-gated summary saving and file organization.
      11
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI apps to compare Korean public notice HWP/HWPX files from consecutive years, extracting changed application requirements and required documents with cited original text locations.
      4
      44 npm
      MIT