Skip to content

Commit 8e7d41c

Browse files
lapioggaclaude
lapiogga
and
claude
committed
docs(readme): v0.11.0 전체 정합화 — 상태·배지·MCP Tools 52종·로드맵
오랫동안 v0.7.0~v0.9.0 시점에서 부분 갱신만 되어 있던 README 를 v0.11.0 현재 상태와 일치하도록 전체 정합화. Updated: - 배지: tests 267→352, MCP tools 44→52, outputs 신규 (search/draft/predict) - 상태 라인: v0.9.0 Multi-Client → v0.11.0 Outcome Prediction - 한 줄 요약 3 트랙 (변호사·일반인·외국인) 시나리오 * 변호사: 검색 → 예측 → 작성 한 줄 워크플로 강조 - pytest 주석 91 passed → 352 passed - MCP Tools 한눈에: 20종 단일 표 → 3 트랙 분류 * 변호사 트랙 35종 (검색 27 + 분석 helper 3 + 첨부 2 + drafting 4 + prediction 4) * 일반인 트랙 12종 (mode/disclaimer/triage/limitation/cost/interview/strength/pro_bono/kit) * 외국인 트랙 5종 (locale 3 + foreigner_resources) - 자연어 사용 예시 4 카테고리 (검색·예측·작성·일반인) - 디렉토리 구조 갱신: * citizen_data/ + prediction_data/ 추가 * tools/citizen + tools/drafting + tools/prediction 추가 * docs/ 추가 (INSTALL_GEMINI/INSTALL_CHATGPT/CITIZEN_MODE/시각가이드 등) * scripts/ 4 파일 (설치하기.bat + ps1 3개) * .github/workflows/ ci.yml + publish.yml - 로드맵: Phase 0~14 + 버전 컬럼 추가 (v0.1.0~v0.11.0 매핑) - 라이선스 안내 갱신 (LICENSE 파일 포함) Why now: v0.11.0 부터 변호사 트랙이 검색을 넘어 예측·작성까지 도달. README 가 옛날 (20 tool / 91 PASS / Phase 5 백로그 시점) 정보로 남아 있던 불일치를 한 번에 해소. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent ecb6eb5 commit 8e7d41c

1 file changed

Lines changed: 141 additions & 45 deletions

File tree

‎README.md‎

Lines changed: 141 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
> 법제처 국가법령정보 공동활용 OpenAPI(191종)를 **MCP(Model Context Protocol) 서버**로 표준화하여, 변호사·로펌이 **Claude Desktop · Gemini CLI · ChatGPT** 등 자연어 환경에서 한국 판례·법령·결정례를 검색·인용·요약할 수 있게 한다.
44
5-
[![PyPI](https://img.shields.io/pypi/v/caselaw-mcp)](https://pypi.org/project/caselaw-mcp/) [![CI](https://github.com/lapiogga/caseLaw/actions/workflows/ci.yml/badge.svg)](https://github.com/lapiogga/caseLaw/actions/workflows/ci.yml) [![Tests](https://img.shields.io/badge/tests-267%20passed-brightgreen)]() [![Tools](https://img.shields.io/badge/MCP%20tools-44-blue)]() [![Clients](https://img.shields.io/badge/clients-Claude%20%7C%20Gemini%20%7C%20ChatGPT-purple)]() [![Python](https://img.shields.io/badge/python-3.11%2B-blue)]() [![Languages](https://img.shields.io/badge/i18n-ko%2Fen%2Fzh%2Fvi%2Fja-orange)]() [![License](https://img.shields.io/badge/license-MIT-green)]()
5+
[![PyPI](https://img.shields.io/pypi/v/caselaw-mcp)](https://pypi.org/project/caselaw-mcp/) [![CI](https://github.com/lapiogga/caseLaw/actions/workflows/ci.yml/badge.svg)](https://github.com/lapiogga/caseLaw/actions/workflows/ci.yml) [![Tests](https://img.shields.io/badge/tests-352%20passed-brightgreen)]() [![Tools](https://img.shields.io/badge/MCP%20tools-52-blue)]() [![Clients](https://img.shields.io/badge/clients-Claude%20%7C%20Gemini%20%7C%20ChatGPT-purple)]() [![Outputs](https://img.shields.io/badge/outputs-search%20%7C%20draft%20%7C%20predict-brightgreen)]() [![Python](https://img.shields.io/badge/python-3.11%2B-blue)]() [![Languages](https://img.shields.io/badge/i18n-ko%2Fen%2Fzh%2Fvi%2Fja-orange)]() [![License](https://img.shields.io/badge/license-MIT-green)]()
66

7-
**상태**: v0.9.0 — Multi-Client Edition (Claude · Gemini · ChatGPT). 활성 MCP Tool **44종**, 단위 테스트 **267 PASS**.
7+
**상태**: v0.11.0 — Outcome Prediction. 활성 MCP Tool **52종**, 단위 테스트 **352 PASS**, 자동 생성 문서 4종 + 결과 예측 4종.
88

99
## 지원 클라이언트 매트릭스
1010

@@ -22,9 +22,11 @@
2222

2323
## 한 줄 요약
2424

25-
> 변호사가 채팅창에 *"음주운전 양형 5건, 사건번호·법원·판시사항 표로 정리"* 라고 입력하면, Claude 가 자동으로 본 MCP 의 `search_precedent` + `get_precedent` 를 호출하여 실제 대법원 판례를 회수·정리한다. 인용 사건번호는 100% 실재.
25+
> **변호사 (검색 → 예측 → 작성 한 줄 워크플로)**: *"음주운전 양형 분포 보여주고, 그 결과로 변호인 의견서 초안까지 만들어 줘"* 한 줄로 `predict_sentencing` → `draft_criminal_defense` 까지 자동 체이닝. 인용 사건번호 100% 실재.
2626
>
27-
> 일반인은 *"3년 전 친구한테 5천만원 빌려줬는데 안 갚아요. 어떻게 해야 하죠?"* 라고 입력하면 분쟁 분류·시효 점검·소송비용·무료자원·변호사 상담 키트까지 자동 생성된다.
27+
> **일반인**: *"3년 전 친구한테 5천만원 빌려줬는데 안 갚아요. 어떻게 해야 하죠?"* 라고 입력하면 분쟁 분류·시효 점검·소송비용·무료자원·변호사 상담 키트까지 자동 생성. 50종 분쟁 카테고리 + 6턴 인터뷰 + 30종 시효 + 인지법.
28+
>
29+
> **외국인 사용자**: 5언어(ko/en/zh/vi/ja) 면책·라벨·외국인 자원 (1345·1577-1366·1577-5432) 자동 매핑.
2830
2931
---
3032

@@ -118,7 +120,7 @@ copy .env.example .env
118120
# - 마이페이지 → API인증키관리에서 확인
119121
120122
# 4. 테스트
121-
uv run pytest -v # 91 passed
123+
uv run pytest -v # 352 passed
122124
123125
# 5. MCP Inspector (디버깅 UI)
124126
uv run mcp dev src\caselaw_mcp\server.py
@@ -128,28 +130,55 @@ uv run mcp dev src\caselaw_mcp\server.py
128130

129131
---
130132

131-
## MCP Tools 한눈에 (20종)
133+
## MCP Tools 한눈에 (52종)
134+
135+
### 변호사 트랙 (35종)
132136

133137
| 카테고리 | Tools | 비고 |
134138
|---|---|---|
135-
| 헬스 | `ping` | 서버·OC 키 상태 |
136-
| **판례** | `search_precedent` / `get_precedent` / `find_related_precedents` | 대법원·고등·지방. 참조판례 자동 추출 |
139+
| 헬스 | `ping` | 서버·OC 키 상태·phase·user_mode·user_locale |
140+
| **판례** | `search_precedent` / `get_precedent` / `find_related_precedents` / `find_precedent_by_citation` | 대법원·고등·지방. 참조판례·인용 역검색 |
137141
| **현행법령** | `search_statute` / `get_statute` | 시행일 기준 |
138142
| 헌재 | `search_constitutional_decision` / `get_constitutional_decision` | |
139143
| 법령해석례 | `search_law_interpretation` / `get_law_interpretation` | 법제처 해석 |
140144
| 행정심판례 | `search_admin_judgment` / `get_admin_judgment` | 국민권익위·각급 행심위 |
141-
| 위원회 결정문 | `search_committee_decision` / `get_committee_decision` | **12종 enum** (공정위·노동위·금융위 등) |
142-
| 특별행정심판 | `search_special_admin_judgment` / `get_special_admin_judgment` | **4종 enum** (조세·해양·소청 등) |
145+
| 위원회 결정문 | `search_committee_decision` / `get_committee_decision` | **12종 enum** |
146+
| 특별행정심판 | `search_special_admin_judgment` / `get_special_admin_judgment` | **4종 enum** |
143147
| 중앙부처 해석 | `search_central_dept_interpretation` / `get_central_dept_interpretation` | **39개 부처 enum** |
144148
| 법령용어 | `search_legal_term` / `get_legal_term` | 사전 |
145-
| 정적 | `lookup_case_codes` | 코드 매핑표 |
149+
| **분석 helper** | `analyze_precedent_trend` / `format_citation` / `compare_precedents` | 추세·인용·비교 |
150+
| 첨부 | `download_attachment` / `extract_attachment_links` | path traversal 방지 |
151+
| **문서 초안** (v0.10.0) | `draft_civil_complaint` / `draft_legal_opinion` / `draft_preparatory_brief` / `draft_criminal_defense` | 한국 표준 양식 마크다운 + 자동 면책 |
152+
| **결과 예측** (v0.11.0) | `predict_sentencing` / `predict_civil_outcome` / `estimate_case_duration` / `dispute_resolution_options` | 표본 N + 95% CI + 면책 |
153+
154+
### 일반인 트랙 (12종)
155+
156+
| 카테고리 | Tools | 비고 |
157+
|---|---|---|
158+
| 모드·면책 | `set_user_mode` / `get_user_mode` / `get_disclaimer` | 변호사·일반인 모드 분기 |
159+
| **분쟁 분류** | `triage_dispute` | **50종 카테고리** (민사 19 + 형사 8 + 가사 8 + 노동 5 + 행정 5 + 소비 5) |
160+
| **시효** | `list_limitation_categories` / `check_statute_of_limitations` | **30종 시효** + 중단 사유 |
161+
| **비용** | `estimate_litigation_cost` | 인지법 4구간 + 변호사비 9종 + 무료자원 7개 |
162+
| **인터뷰** | `get_interview_flow` / `interview_facts` | 6턴 사실관계 인터뷰 (stateless) |
163+
| **사건 강도** | `evaluate_case_strength` | 라벨 9종 |
164+
| **무료 상담** | `recommend_pro_bono` | 전국 14 + 지역 14 + KLAC 6 + 도메인 특화 |
165+
| **상담 키트** | `prepare_consultation_kit` | 13섹션 마크다운 + 변호사 질문 10개 |
166+
167+
### 외국인 사용자 트랙 (5종)
168+
169+
| Tools | 비고 |
170+
|---|---|
171+
| `set_user_locale` / `get_user_locale` / `get_disclaimer_localized` / `list_disclaimers_localized` / `get_foreigner_resources` | 5언어 (ko/en/zh/vi/ja) + 외국인종합안내 1345 등 |
146172

147173
자세한 입출력 스키마: [`docs/API_REFERENCE.md`](./docs/API_REFERENCE.md)
148174
전체 코드·별칭 사전: [`docs/CODES.md`](./docs/CODES.md)
175+
일반인 모드 가이드: [`docs/CITIZEN_MODE.md`](./docs/CITIZEN_MODE.md)
149176

150177
---
151178

152-
## 자연어 사용 예시 (Claude Desktop)
179+
## 자연어 사용 예시 (Claude Desktop · Gemini CLI · ChatGPT)
180+
181+
### 검색·인용 (변호사 기본 워크플로)
153182

154183
```
155184
음주운전 관련 최근 대법원 판례 5개 찾아서 사건명만 정리해줘.
@@ -163,6 +192,41 @@ uv run mcp dev src\caselaw_mcp\server.py
163192
법령용어 "공탁" 사전 검색.
164193
```
165194

195+
### 결과 예측 (v0.11.0 신규)
196+
197+
```
198+
음주운전 양형 분포 알려줘. 대법원 판례 30건 표본으로.
199+
→ predict_sentencing: 벌금 53% / 집유 32% / 실형 11% (가상 분포)
200+
201+
대여금 5천만원 청구 사건의 평균 인용률과 인정 금액 분포는?
202+
→ predict_civil_outcome: 인용 60% / 일부 25% / 기각 15%, 평균 인정 4,200만원
203+
204+
민사 1심 평균 소요 기간은? 단순 사건 기준.
205+
→ estimate_case_duration: 평균 4개월, 95% CI [2, 7]개월
206+
207+
5천만원 대여금. 6개월 안에 끝내고 관계 유지 우선.
208+
→ dispute_resolution_options: 화해(settlement) 추천 + 4-옵션 매트릭스
209+
```
210+
211+
### 문서 초안 자동 (v0.10.0 신규)
212+
213+
```
214+
대여금 5천만 원, 원고 박원고 (서울 강남구), 피고 김피고 (서울 송파구).
215+
2022. 3. 15. 대여, 변제기 2023. 3. 14., 미상환. 차용증·통장사본 첨부.
216+
→ draft_civil_complaint: 한국 표준 소장 마크다운 + 면책
217+
218+
음주운전 양형 자문 의견서. 혈중알코올농도 0.08, 사고 없음, 전과 없음.
219+
→ draft_legal_opinion: 쟁점·법리·결론 골격 + 유사 판례 인용
220+
```
221+
222+
### 일반인 트랙 (변호사 만나기 전 사전진단)
223+
224+
```
225+
3년 전 친구한테 5천만원 빌려줬는데 안 갚아요. 어떻게 해야 하죠?
226+
→ triage_dispute → check_statute_of_limitations → estimate_litigation_cost
227+
→ recommend_pro_bono → prepare_consultation_kit (13섹션 마크다운)
228+
```
229+
166230
전체 30종 시나리오: [`docs/EXAMPLES.md`](./docs/EXAMPLES.md)
167231

168232
---
@@ -171,58 +235,90 @@ uv run mcp dev src\caselaw_mcp\server.py
171235

172236
```
173237
CaseLaw/
174-
├── PLAN.md # 종합 계획서
175238
├── README.md
176-
├── CHANGELOG.md # 버전 히스토리
177-
├── pyproject.toml # uv 프로젝트
178-
├── .env.example # OC 키 템플릿
239+
├── CHANGELOG.md # 버전 히스토리 (v0.1.0 ~ v0.11.0)
240+
├── VERSION-STAMP.md # 마일스톤 인증 + 동결 코드 영역
241+
├── pyproject.toml # uv 프로젝트 (52 tool, hatchling sdist exclude)
242+
├── .env.example # OC 키 + Bearer 토큰 템플릿
179243
├── src/caselaw_mcp/
180-
│ ├── server.py # FastMCP 엔트리 (20 tool 등록)
244+
│ ├── server.py # FastMCP 엔트리 (52 tool 등록, --transport stdio|http)
245+
│ ├── auth.py # Bearer 토큰 ASGI 미들웨어 (CASELAW_AUTH_TOKEN)
181246
│ ├── client.py # 비동기 HTTP + 재시도 + URL 마스킹
182-
│ ├── parsers.py # XML/JSON → 영문 키 정규화 (60+ 키)
247+
│ ├── parsers.py # XML/JSON → 영문 키 정규화
183248
│ ├── cache.py # SQLite TTL 캐시
184-
│ ├── codes.py # 사건종류·법원·위원회·부처 코드 (105+ 별칭)
185-
│ ├── config.py # pydantic-settings 환경 로더
249+
│ ├── codes.py # 사건종류·법원·위원회·부처 코드 (200+ 별칭)
250+
│ ├── config.py # pydantic-settings (.env 자동 로드)
251+
│ ├── citizen_data/ # 시드 (categories 50 + limitations 30 + court_fees 등)
252+
│ ├── prediction_data/ # 사법연감 시드 (duration_baselines.json)
186253
│ └── tools/
187-
│ ├── precedent.py # 판례 + find_related
254+
│ ├── precedent.py # 판례 + find_related + find_by_citation
188255
│ ├── statute.py # 현행법령
189256
│ ├── constitution.py # 헌재결정례
190257
│ ├── interpretation.py # 법령해석례
191258
│ ├── admin_judg.py # 행정심판례
192-
│ ├── committee.py # 위원회 12종 통합
193-
│ ├── special_judg.py # 특별행정심판 4종 통합
194-
│ ├── dept_interpretation.py # 중앙부처 39종 통합
195-
│ └── terminology.py # 법령용어
259+
│ ├── committee.py # 위원회 12종 enum
260+
│ ├── special_judg.py # 특별행정심판 4종 enum
261+
│ ├── dept_interpretation.py # 중앙부처 39종 enum
262+
│ ├── terminology.py # 법령용어
263+
│ ├── analytics.py # analyze_trend / format_citation / compare
264+
│ ├── attachments.py # 별표·HWP/PDF 다운로드
265+
│ ├── citation_lookup.py # 인용 텍스트 → prec_id 역검색
266+
│ ├── citizen/ # 일반인 트랙 (mode/locale/disclaimer/triage 등 12 tool)
267+
│ ├── drafting/ # 변호사 문서 4종 (소장·의견서·준비서면·변호인의견서) v0.10.0
268+
│ └── prediction/ # 결과 예측 4종 (양형·민사결과·기간·해결옵션) v0.11.0
196269
├── tests/
197-
│ ├── unit/ # 91 단위 테스트
198-
│ └── integration/
199-
│ ├── smoke_live.py # Phase 1 시나리오 4종
200-
│ ├── smoke_phase2.py # Phase 2 시나리오 4종
201-
│ └── smoke_phase3.py # Phase 3 시나리오 4종
270+
│ ├── unit/ # 352 단위 테스트
271+
│ └── integration/ # smoke 시나리오 19종
202272
├── docs/
203-
│ ├── INSTALL.md # Claude Desktop / Cursor 등록
204-
│ ├── API_REFERENCE.md # 20 tool 입출력 스키마
273+
│ ├── INSTALL.md # 5-클라이언트 매트릭스
274+
│ ├── INSTALL_GEMINI.md # Gemini CLI 등록
275+
│ ├── INSTALL_CHATGPT.md # ChatGPT (HTTP + Cloudflare Tunnel)
276+
│ ├── API_REFERENCE.md # tool 입출력 스키마
205277
│ ├── CODES.md # 전체 코드·별칭 사전
278+
│ ├── CITIZEN_MODE.md # 일반인 트랙 가이드
279+
│ ├── OC_PERMISSIONS.md # OC 권한 확장
280+
│ ├── OC발급_가이드.md # OC 키 9단계 발급
206281
│ ├── EXAMPLES.md # 변호사 자연어 30종
207-
│ └── claude_desktop_config.example.json
282+
│ ├── 설치_시각가이드.md # 비기술자용 화면 캡처 11장
283+
│ ├── 소개자료_일반인.md # 1페이지 소개
284+
│ ├── 기술노트_MCP아키텍처.md # 14섹션 기술 노트
285+
│ └── promo/ # 영상·캡처 자료 (mp4 git ignore)
286+
├── scripts/
287+
│ ├── 설치하기.bat # 비기술자 더블클릭 진입점
288+
│ ├── setup-for-novice.ps1 # 자동 설치 (Python·uv·Claude Desktop)
289+
│ ├── install-caselaw-mcp.ps1 # Claude Desktop config 등록
290+
│ └── install-caselaw-gemini.ps1 # Gemini CLI settings.json 등록
291+
├── .github/workflows/
292+
│ ├── ci.yml # Python 3.11/12/13 매트릭스 + ruff + pytest
293+
│ └── publish.yml # Release published → PyPI Trusted OIDC 자동
208294
├── reference/ # 법제처 OpenAPI 가이드 원본
209-
└── .planning/ # GSD 플래닝 (PROJECT/ROADMAP/PROMPTS-LOG/phases/*)
295+
└── .planning/ # GSD 플래닝 (.gitignore — 로컬 메모)
210296
```
211297

212298
---
213299

214300
## 로드맵 진행
215301

216-
| Phase | 내용 | 상태 |
217-
|---|---|---|
218-
| 0 | Bootstrap (uv, ping tool, CI) | ✅ |
219-
| 1 | 판례 + 법령 MVP (5 tool) | ✅ |
220-
| 2 | 헌재·해석례·심판례 + 관련판례 추천 | ✅ |
221-
| 3 | 위원회 12 + 특별심판 4 + 중앙부처 39 + 법령용어 | ✅ |
222-
| **4** | **품질·배포 (API_REFERENCE / CODES / CHANGELOG / Release)** | ✅ |
223-
| 5+ | 외국 판례 연동 (CourtListener·Find Case Law) — 백로그 | ⏭ |
224-
225-
상세: [`PLAN.md`](./PLAN.md) · [`.planning/ROADMAP.md`](./.planning/ROADMAP.md)
302+
| Phase | 내용 | 버전 | 상태 |
303+
|---|---|---|---|
304+
| 0 | Bootstrap (uv, ping tool, CI) | — | ✅ |
305+
| 1 | 판례 + 법령 MVP (5 tool) | — | ✅ |
306+
| 2 | 헌재·해석례·심판례 + 관련판례 추천 | — | ✅ |
307+
| 3 | 위원회 12 + 특별심판 4 + 중앙부처 39 + 법령용어 | — | ✅ |
308+
| 4 | 품질·배포 (API_REFERENCE / CODES / CHANGELOG / Release) | v0.1.0 | ✅ |
309+
| 5 | Practitioner Helpers (analyze_trend / format_citation / compare) | v0.2.0 | ✅ |
310+
| 6 | Citation Lookup + Attachment Download | v0.3.0 | ✅ |
311+
| 7 | Citizen Mode MVP (mode / disclaimer / triage 30종) | v0.4.0 | ✅ |
312+
| 8 | Statute & Cost (시효 30 + 인지법) | v0.5.0 | ✅ |
313+
| 9 | Interview & Strength (6턴 인터뷰 + 사건 강도) | v0.6.0 | ✅ |
314+
| 10 | Pro Bono & Consultation Kit (50종 카테고리) | v0.7.0 | ✅ |
315+
| 11 | i18n MVP (5언어 + 외국인 자원) | v0.8.0 | ✅ |
316+
| 12 | **Multi-Client Edition** (Claude · Gemini · ChatGPT) | **v0.9.0** | ✅ |
317+
| 13 | **Practitioner Doc Drafting** (소장·의견서·준비서면·변호인 의견서) | **v0.10.0** | ✅ |
318+
| 14 | **Outcome Prediction** (양형·민사결과·기간·해결옵션) | **v0.11.0** | ✅ |
319+
| 15+ | Backlog: ChatGPT OAuth 2.1 / Vector DB / 외국 판례 / ML 라벨링 | — | ⏭ |
320+
321+
상세: [`.planning/ROADMAP.md`](./.planning/ROADMAP.md) · [`CHANGELOG.md`](./CHANGELOG.md) · [`VERSION-STAMP.md`](./VERSION-STAMP.md)
226322

227323
---
228324

@@ -254,7 +350,7 @@ CaseLaw/
254350

255351
## 라이선스
256352

257-
MIT (예정 — 정식 release 시 LICENSE 파일 추가)
353+
MIT (`LICENSE` 파일 포함, 무료 + 상업적 사용 가능)
258354

259355
---
260356

0 commit comments

Comments
 (0)