Gyeongguk — 한국 법률 추론 MCP 서버

한국 법률 작업을 위한 MCP 서버. 세 가지 흐름을 지원한다:

1. 기록형(사건기록 → 법률서면): PDF 파일을 주면 파싱 → 사실관계 → 청구추출 → 법리(쟁점·포섭격자) → 법령API 검증 → 작성 → 검토 파이프라인을 단계별 파일로 진행.

2. 사례형(사례 문제 → IRAC 답안): 문제 텍스트/파일을 주면 사실관계 → 청구추출 → 포섭격자 → IRAC 답안 → 검토.

3. 일반 법률 상담(질문 → 상담의견): 질문을 법령·판례로 검증해 IRAC 상담의견(면책 고지 포함).

공통 엔진: 법제처 OPEN API 검증 + 요건사실 카탈로그 + 포섭 여부 격자(요건×사실×증명책임) + IRAC + 날조 차단.

기존 '기록형풀이' 룰스킬(개인 옵시디언 볼트)을 독립 MCP 서버로 이식·확장한 것이다. 학습용 약점분석·카드·SRS는 의도적으로 제외한다(포섭 추론은 포함).

⚠ 이 저장소에는 코드만 포함된다. 사건기록·교재·산출 서면 등 민감/저작권 자료는 .gitignore로 제외된다.

파이프라인

Related MCP server: korean-law-alio-mcp

핵심 특징

• 청구추출: 명시적 청구가 없는 사건기록(형사·자문형)에서도 사실 신호 → 가능한 청구/항변/감경사유를 역추출한다. 요건사실 카탈로그(resources/claim_catalog.json)와 매치업 매트릭스(요건×사실×증명책임, 상태=충족/일부/다툼/공백/불명)로 갭을 식별하고, 당사자 입장 미정 시 양측 승소구조를 비교해 권고한다.

• 작성 양식 분석: analyze_format이 사용자가 준 양식/샘플 서면(docx·pdf·md·hwp 미리보기)을 역분석해 머리·말미·번호체계·인용형식을 추출하고, draft가 그 구조를 따른다. 양식 미제공 시 내장 서면 템플릿(brief_templates.json)으로 폴백.

• 법령·판례 검증 내장: 법제처(국가법령정보센터) OPEN API 직접 호출. 검증완료 판례만 본문 직접인용으로 승격하고, 미검증은 [검증필요]로 강등(날조 차단).

• 자세-스탬프 영속화: 각 단계 산출물 프론트매터에 확정한 결정(당사자 입장·다툼없음 전제 등)을 박아 회귀를 막는다.

설치

git clone https://github.com/kmjy98-sketch/Gyeongguk.git
cd Gyeongguk
pip install -e .            # 최소(mcp + PyMuPDF)
pip install -e ".[all]"     # opendataloader·docx·auto 전부

opendataloader-pdf(권장 OCR 엔진)는 Java 11+ 가 PATH에 있어야 한다 — 없으면 Adoptium에서 설치. Java가 없으면 자동으로 PyMuPDF(디지털 텍스트레이어)로 폴백한다. 스캔 PDF의 진짜 OCR은 opendataloader hybrid 모드가 필요하다:

pip install "opendataloader-pdf[hybrid]"
opendataloader-pdf-hybrid --port 5002 --ocr-lang "ko,en"
# .env: GIROK_ODL_HYBRID=http://localhost:5002  또는 hybrid 백엔드명

설정 (온보딩)

자세한 단계는 docs/SETUP.md. 요약:

python -m girokhyeong_mcp.setup --init     # .env 생성
# .env 에 LAW_API_KEY=<OC값> 입력  (open.law.go.kr OPEN API 신청 → 이메일 아이디가 OC 값)
python -m girokhyeong_mcp.setup --check    # 라이브 검증(법령 1건 실제 조회)
python -m girokhyeong_mcp.setup            # 전체 상태 점검 + 다음 할 일 안내

.env(cwd 또는 리포 루트)는 서버가 자동으로 읽는다. 환경변수로 직접 줘도 된다(환경변수 우선).

LAW_API_KEY=...          # 필수. open.law.go.kr OPEN API 신청 → 이메일 ID가 OC 값
ANTHROPIC_API_KEY=...    # 선택. solve_record auto 모드(서버 내부 자동 진행)에만

MCP 클라이언트 등록 후 check_setup 도구를 호출하면 키가 살아있는지 즉시 확인된다.

MCP 클라이언트(예: Claude Code) 등록:

{
  "mcpServers": {
    "girokhyeong": {
      "command": "girokhyeong-mcp",
      "env": { "LAW_API_KEY": "...", "GIROK_WORK_ROOT": "C:/work/기록형" }
    }
  }
}

또는 python -m girokhyeong_mcp.server.

사용

가장 간단한 흐름 — 사건기록 폴더를 주고 자동 진행:

solve_record(source="C:/cases/2025고합123", brief_type="형사변론요지서", party_side="변호인")

solve_record는 파싱(결정적)을 즉시 수행해 00_인벤토리.md를 만들고, 나머지 단계의 플레이북을 반환한다. 호스트 LLM(Claude Code)이 각 단계 가이드를 따라 수행하고 save_stage로 저장한다. auto=True + ANTHROPIC_API_KEY면 서버가 01~06 파일을 직접 생성한다.

양식을 따라야 하면:

solve_record(source="...", brief_type="형사의견서", format_sample="C:/양식/우수서면.pdf")

도구 목록

• 파싱: parse_record

• 법령 API(12): law_search · law_detail · law_toc · precedent_search · precedent_detail · admin_rule_search · verify_case · verify_article · verify_text · get_annexes · verify_annex · cite_check

law_toc — 조문 목차 탐색 (2026-07-03 신설)

조문번호를 모를 때 조문번호를 추측하지 말고 목차로 찾기 위한 도구.

law_toc("부정경쟁방지 및 영업비밀보호에 관한 법률", "영업비밀")

• 목차: 전 조문의 번호·제목(키워드를 주면 제목/내용 매칭 조문만, 매칭 위치 표시).

• 정의·총칙(우선참고): 머리 조문(목적·정의·적용범위·기본이념·해석)을 항상 함께 반환하고, 정의 조문은 정의어 목록까지 추출한다(예: 부정경쟁행위·영업비밀·영업비밀 침해행위·도메인이름).

• 권장 순서: 정의·총칙 먼저 확인 → 키워드 목차 — 특히 특별법은 §2 정의가 용어의 의미를 일반 용례와 다르게 규정하므로 정의 조문 확인이 필수다(기본법은 불요 시 생략 가능).

CLI: python -m girokhyeong_mcp.law_api law-toc "민법" 유치권

• 포섭·청구: list_claims(요건 카탈로그 색인) · subsumption_grid(요건×사실 포섭격자)

• 작성 지원: analyze_format · stage_guide · verify_brief · save_stage · export_docx

• 오케스트레이션: solve_record(기록형) · solve_case(사례형) · consult(상담) · server_info · check_setup

• 프롬프트: girok_facts · girok_claims · girok_issues · girok_authorities · girok_draft · girok_review · girok_subsume · girok_case · girok_consult

사용 예:

solve_case(problem="갑은 을에게 1억을 빌려줬으나 변제기 후에도 안 갚는다. 갑의 청구는?", party_side="원고")
consult(question="전세 보증금을 안 돌려주면?")
subsumption_grid(claim_keys=["tort", "unjust_enrichment"])   # 먼저 list_claims 로 key 확인

server_info로 환경(법령API 키·Java·opendataloader·리소스 배치)을 점검할 수 있다.

구조

src/girokhyeong_mcp/
  server.py            FastMCP 서버(도구·프롬프트 등록)
  law_api.py           법제처 OPEN API 클라이언트(stdlib만, 자체완결)
  config.py  resources.py
  pipeline/            parse·stages·orchestrator·verify·export·analyze_format·storage·auto_runner
  resources/           rules.md · claim_catalog.json · brief_templates.json · review_axes.json
  util/                hanja(한자→한글) · markdown(프론트매터·페이지마커)

자세한 설계는 docs/ARCHITECTURE.md, 이식 시 반영한 이전 연구 미반영분은 docs/UNREFLECTED_RESEARCH.md 참조.

원격 MCP (PlayMCP / OpenAI·Claude 커넥터)

로컬 stdio 외에 원격 Streamable HTTP 엔트리를 제공한다 — 카카오 PlayMCP in KC 및 OpenAI/Claude 커넥터에 등록 가능. 공개(무인증) 서버에는 읽기전용 법령·검증·포섭 도구(16) + 프롬프트(9)만 노출하고, 서버 디스크에 파일을 쓰는 사건기록 파이프라인은 제외한다(stdio 전용).

pip install -e ".[http]"
BIND_ADDR=0.0.0.0:8080 girokhyeong-mcp-http     # POST /mcp · GET /healthz · /readyz
python scripts/smoke_http.py                    # 원격 엔드투엔드 스모크
python scripts/export_listtools.py              # playmcp/listtools.json (콘솔 붙여넣기용) 재생성

• 배포 런북(컨테이너 → KC → Endpoint URL → PlayMCP): docs/PLAYMCP.md

• 등록 패킷(콘솔 복붙 필드·샘플 프롬프트·체크리스트): playmcp/submission.md

• 콘솔 listTools 붙여넣기 아티팩트: playmcp/listtools.json · 아이콘: assets/playmcp-icon.svg

Docker: docker build --platform linux/amd64 -t ghcr.io/<owner>/gyeongguk-mcp .(arm64는 KC 활성화 실패).

라이선스

MIT. 법제처 OPEN API·opendataloader-pdf(Apache-2.0)는 각자의 약관을 따른다.