# Gyeongguk — 한국 법률 추론 MCP 서버

한국 법률 작업을 위한 [MCP](https://modelcontextprotocol.io) 서버. 세 가지 흐름을 지원한다:

1. **기록형**(사건기록 → 법률서면): PDF 파일을 주면 **파싱 → 사실관계 → 청구추출 → 법리(쟁점·포섭격자) → 법령API 검증 → 작성 → 검토** 파이프라인을 단계별 파일로 진행.
2. **사례형**(사례 문제 → IRAC 답안): 문제 텍스트/파일을 주면 사실관계 → 청구추출 → **포섭격자** → IRAC 답안 → 검토.
3. **일반 법률 상담**(질문 → 상담의견): 질문을 법령·판례로 검증해 IRAC 상담의견(면책 고지 포함).

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

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

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

---

## 파이프라인

| 단계 | 도구/프롬프트 | 산출 파일 |
|---|---|---|
| 파싱 (OCR) | `parse_record` — opendataloader-pdf(로컬) + pymupdf 폴백 | `00_인벤토리.md`, `_추출/*.md` |
| 사실관계 | `girok_facts` — 타임라인·다툼없는사실·주장대비표·증거분류·불일치·사실관계도 | `01_사실관계.md` |
| **청구추출** | `girok_claims` — 요건사실 카탈로그 역매칭 → 가능 청구/항변 도출, 매치업 매트릭스·갭 목록 | `02_청구추출.md` |
| 법리 | `girok_issues` — 쟁점 도출 + 포섭격자(요건×사실×증명책임 + 셀상태) | `03_쟁점법리.md` |
| 법령API | `precedent_search`·`verify_case`·`verify_article`·`verify_brief` (법제처 OPEN API) | `04_조문판례.md` |
| 작성 | `girok_draft` — 서면유형별 골격 + 양식 역분석 + 검증완료만 직접인용 | `05_답안.md` |
| 검토 | `girok_review` — 논리·포섭 5축 + 정확성 게이트 | `06_검토.md` |
| **자동 진행** | `solve_record` — 파일 주면 위 전부 순차 진행, 단계별 파일 생성 | 전체 |

## 핵심 특징

- **청구추출**: 명시적 청구가 없는 사건기록(형사·자문형)에서도 **사실 신호 → 가능한 청구/항변/감경사유**를 역추출한다. 요건사실 카탈로그(`resources/claim_catalog.json`)와 매치업 매트릭스(요건×사실×증명책임, 상태=충족/일부/다툼/공백/불명)로 갭을 식별하고, 당사자 입장 미정 시 양측 승소구조를 비교해 권고한다.
- **작성 양식 분석**: `analyze_format`이 사용자가 준 양식/샘플 서면(docx·pdf·md·hwp 미리보기)을 역분석해 머리·말미·번호체계·인용형식을 추출하고, draft가 그 구조를 따른다. 양식 미제공 시 내장 서면 템플릿(`brief_templates.json`)으로 폴백.
- **법령·판례 검증 내장**: 법제처(국가법령정보센터) OPEN API 직접 호출. 검증완료 판례만 본문 직접인용으로 승격하고, 미검증은 `[검증필요]`로 강등(날조 차단).
- **자세-스탬프 영속화**: 각 단계 산출물 프론트매터에 확정한 결정(당사자 입장·다툼없음 전제 등)을 박아 회귀를 막는다.

## 설치

```bash
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](https://adoptium.net/)에서 설치. Java가 없으면 자동으로 PyMuPDF(디지털 텍스트레이어)로 폴백한다. 스캔 PDF의 진짜 OCR은 opendataloader hybrid 모드가 필요하다:

```bash
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`](docs/SETUP.md)**. 요약:

```bash
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) 등록:

```json
{
  "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/ARCHITECTURE.md), 이식 시 반영한 이전 연구 미반영분은 [`docs/UNREFLECTED_RESEARCH.md`](docs/UNREFLECTED_RESEARCH.md) 참조.

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

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

```bash
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`](docs/PLAYMCP.md)**
- 등록 패킷(콘솔 복붙 필드·샘플 프롬프트·체크리스트): **[`playmcp/submission.md`](playmcp/submission.md)**
- 콘솔 listTools 붙여넣기 아티팩트: **[`playmcp/listtools.json`](playmcp/listtools.json)** · 아이콘: [`assets/playmcp-icon.svg`](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)는 각자의 약관을 따른다.