[![MCP Badge](https://lobehub.com/badge/mcp/seonaru-lexguard-mcp)](https://lobehub.com/mcp/seonaru-lexguard-mcp)
![Python](https://img.shields.io/badge/Python-3.11%2B-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-green)
![License](https://img.shields.io/badge/License-MIT-yellow)
![CI](https://github.com/SeoNaRu/lexguard-mcp/actions/workflows/ci.yml/badge.svg)

# ⚖️ LexGuard MCP (법실마리)

> **한국 법령·판례·법령해석을 AI가 이해하기 쉬운 형태로 연결하는 MCP 서버**
>
> 국가법령정보센터(Open Law) 공식 데이터를 기반으로, 법령·조문·판례·법령해석·행정심판·헌재결정을 **하나의 질문 흐름**으로 제공합니다.

- **실행 방식**: 본인의 국가법령정보센터 API 키로 직접 실행하는 **self-host** MCP 서버 (별도 호스팅 서비스 없음)
- **GitHub**: [https://github.com/SeoNaRu/lexguard-mcp](https://github.com/SeoNaRu/lexguard-mcp)

### 빠른 시작 (5분)

1. **API 키 발급** — [open.law.go.kr](https://open.law.go.kr)에서 무료 발급. 신청 시 **본인 IP 등록** 필수 (아래 [API Key 발급](#api-key-발급-필수) 참고)
2. **서버 실행**

   ```bash
   git clone https://github.com/SeoNaRu/lexguard-mcp
   cd lexguard-mcp
   cp .env.example .env        # LAW_API_KEY=발급키 설정
   docker compose up --build   # 또는: pip install -r requirements.txt && python -m src.main
   ```

3. **클라이언트 연결** — MCP URL: `http://localhost:9099/mcp`
   - Cursor: [`examples/cursor-mcp.local.json`](examples/cursor-mcp.local.json) 내용을 `.cursor/mcp.json`에 병합
   - Claude Desktop: [`examples/claude-desktop-mcp.local.json`](examples/claude-desktop-mcp.local.json) → `claude_desktop_config.json`의 `mcpServers`에 병합 (Node.js 필요)

마켓플레이스·크롤러용 정적 메타: [`mcp/manifest.json`](mcp/manifest.json) · 프롬프트 색인 [`prompts/`](prompts/) · 리소스 URI 안내 [`resources/README.md`](resources/README.md) · Cursor 개발 스킬 [`.cursor/skills/lexguard-mcp-dev/SKILL.md`](.cursor/skills/lexguard-mcp-dev/SKILL.md)

---

## Why LexGuard?

법은 필요할 때마다 멀고 어렵게 느껴집니다.
높은 비용, 낯선 용어, 어디서부터 찾아야 할지 모르는 구조.

**LexGuard MCP(법실마리)** 는 이 문제에서 출발했습니다.

- 사용자는 **사람의 말**로 질문하고
- AI는 질문 의도를 분석한 뒤
- **공식 법령·판례 데이터**를 근거로 실마리를 제공합니다.

> 판단이나 법률 자문을 대신하지 않습니다.
> 다만, _법을 처음 마주하는 순간을 덜 어렵게_ 만드는 것을 목표로 합니다.

---

## Core Features

| 기능 | 설명 |
|------|------|
| **18개 MCP 도구** | 통합 QA부터 부처별 해석·법령이력·별표서식·연계 조회까지 전 영역 커버 |
| **통합 법률 QA** | 법령·판례·법령해석·행정심판·헌재결정 병렬 종합 탐색 |
| **조문 정밀 조회** | 법령명 + 조문번호로 특정 조항 직접 조회 |
| **문서·계약서 분석** | 계약서·약관 붙여넣기만으로 조항별 법적 이슈 자동 감지 |
| **판례 번호 직접 감지** | `2023다12345`, `2021헌마123` 형식 자동 인식 후 즉시 검색 |
| **도메인 자동 분류** | 노동·개인정보·부동산·소비자·세금·금융 등 10개 법률 도메인 |
| **자연어 시간 조건** | "최근 3년", "2023년 이후" 등 자연어 시간 표현 자동 파싱 |
| **Reranker 파이프라인** | 검색 결과를 쿼리 적합도(BM25 + Keyword Hybrid) 기준으로 재정렬 |
| **병렬 검색** | `asyncio.gather` 기반 멀티 API 동시 호출로 응답 속도 최소화 |
| **Rate Limiting** | IP당 600 req/min 제한 (기본값, `LEXGUARD_MCP_RATE_LIMIT`로 조정) |

---

## MCP Tools

### `legal_qa_tool` — 범용 법률 QA

모든 법률 질문의 단일 진입점입니다. 질문 하나로 법령·판례·해석·위원회 결정례를 병렬 탐색하고 종합합니다. 출처가 한정된 검색(판례만, 해석만 등)은 각 전용 툴을 검토할 수 있습니다.

**Capabilities**

- 10개 도메인 자동 분류
- 질문 의도(Intent) 다중 감지 및 우선순위 정렬
- 법령 → 판례 → 해석 → 위원회 병렬 탐색
- 자연어 시간 조건 필터링 (`date_from` / `date_to` 자동 변환)

**Input Schema**

| 파라미터 | 타입 | 필수 | 설명 |
|---------|------|------|------|
| `query` | string | ✅ | 사용자의 법률 질문 |
| `max_results_per_type` | integer | — | 타입당 최대 결과 수 (기본값: 3, 최대: 10) |

**Example Prompts**

```
프리랜서인데 근로자성 인정된 판례 있나요?
최근 3년 부당해고 판례 알려줘
개인정보 유출됐는데 법적으로 어떻게 되나요?
2023다12345 판례 찾아줘
```

---

### `law_article_tool` — 법령 조문 정밀 조회

법령명과 조문번호를 알고 있을 때 특정 조항을 직접 조회합니다. `legal_qa_tool`이 "탐색"이라면, 이 툴은 "정확한 조회"입니다.

**Input Schema**

| 파라미터 | 타입 | 필수 | 설명 |
|---------|------|------|------|
| `law_name` | string | ✅ | 법령명 (예: 근로기준법, 민법) |
| `article_number` | string | — | 조문 번호 (예: `50`, `2`). 생략 시 법령 개요 반환 |
| `hang` | string | — | 항 번호 (예: `1`, `2`) |
| `ho` | string | — | 호 번호 (예: `1`, `2`) |
| `mok` | string | — | 목 번호 (예: `가`, `나`) |

**Example Prompts**

```
근로기준법 제50조 내용 알려줘
민법 제750조 3항이 뭐야?
개인정보보호법 제17조
```

---

### `law_comparison_tool` — 법령 신구·연혁·3단 비교

법령명을 기준으로 신구법 대비, 연혁, 3단 비교 결과를 조회합니다. 조문 원문 조회는 `law_article_tool`, 일반 질문은 `legal_qa_tool`을 사용하세요.

**Input Schema**

| 파라미터 | 타입 | 필수 | 설명 |
|---------|------|------|------|
| `law_name` | string | ✅ | 법령명 (예: 형법, 민법) |
| `compare_type` | string | — | `신구법` · `연혁` · `3단비교` (기본값: `신구법`, 질문에 연혁/3단비교/신구법이 있으면 해당 값 사용) |

**Example Prompts**

```
근로기준법 신구법 비교 보여줘
민법 연혁 조회
```

---

### `document_issue_tool` — 계약서·약관 분석

문서를 붙여넣으면 조항 단위로 법적 이슈를 추출하고, 관련 법령·판례를 자동 검색합니다.

**Input Schema**

| 파라미터 | 타입 | 필수 | 설명 |
|---------|------|------|------|
| `document_text` | string | ✅ | 계약서·약관 전문 |
| `auto_search` | boolean | — | 조항별 자동 법령 검색 여부 (기본값: true) |
| `max_clauses` | integer | — | 분석할 최대 조항 수 (기본값: 3) |
| `max_results_per_type` | integer | — | 타입당 최대 결과 수 (기본값: 3) |

**Supported Document Types**

- `labor` — 근로계약서 / 용역계약서
- `lease` — 임대차 계약서
- `terms` — 이용약관

**Example Prompts**

```
이 프리랜서 계약서 문제 있는지 봐줘
아래 임대차 계약서에서 불리한 조항 찾아줘
```

---

### `health` — 서버 상태 확인

MCP 서버 동작 여부, API Key 설정 상태, 환경 변수를 확인합니다.

---

### 전용 검색 툴 (출처 한정)

통합 검색(`legal_qa_tool`) 대신 **특정 데이터만** 찾을 때 사용합니다.

| 툴 이름 | 용도 | 주요 입력 |
|---------|------|-----------|
| `precedent_lookup_tool` | 판례만 | `keyword` 또는 `case_number` |
| `interpretation_tool` | 법령해석·유권해석 등 | `query`, 선택 `agency` |
| `administrative_appeal_tool` | 행정심판 재결만 | `query`, 선택 기간 |
| `constitutional_decision_tool` | 헌법재판소 결정만 | `query`, 선택 기간 |
| `committee_decision_tool` | 독립위원회 등 결정문 | `committee_type`, `query` |
| `special_administrative_appeal_tool` | 특별행정심판원 재결 | `tribunal_type`, `query` |
| `local_ordinance_tool` | 자치법규(조례 등)만 | `query` 또는 `local_government` 중 하나 이상 |
| `administrative_rule_tool` | 행정규칙만 | `query` 또는 `agency` 중 하나 이상 |

---

### 확장 조회 툴

법령 부가 정보, 이력, 서식, 연계 등 심화 조회가 필요할 때 사용합니다.

#### `ministry_interpretation_tool` — 부처별 법령해석

39개 부처 전용 법령해석(질의회신) 데이터베이스를 검색합니다. `interpretation_tool`이 통합 검색이라면, 이 툴은 **특정 부처 해석만** 직접 조회합니다.

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `query` | string | 검색 키워드 |
| `agency` | string | 부처명 (예: `고용노동부`, `국세청`, `보건복지부`) |
| `page` / `per_page` | integer | 페이지 설정 |

지원 부처: 고용노동부, 국토교통부, 기획재정부, 국세청, 관세청, 교육부, 보건복지부, 법무부, 법제처, 식품의약품안전처, 경찰청, 소방청, 해양경찰청 외 39개 기관

---

#### `law_history_tool` — 법령·조문 변경이력

법령이 언제 어떻게 개정되었는지 추적합니다.

| `search_type` 값 | 설명 |
|-----------------|------|
| `law_change` | 법령 변경이력 목록 |
| `article_change` | 일자별 조문 개정이력 목록 |
| `article_detail` | 특정 조문의 개정이력 상세 (`law_id` 필수) |

**Example Prompts**

```
근로기준법 개정 이력 알려줘
개인정보보호법 제17조 조문 개정 내역
```

---

#### `law_info_tool` — 법령 부가 정보

영문법령, 국제조약, 법령 체계도, 한눈보기, 약칭 등 부가 정보를 조회합니다.

| `info_type` 값 | 설명 |
|--------------|------|
| `english_law` | 영문법령 |
| `treaty` | 국제조약 |
| `structure` | 법령 체계도 |
| `oneview` | 한눈보기(법령 요약) |
| `abbreviation` | 법령명 약칭 |
| `deleted` | 삭제된 법령·조문 이력 |

---

#### `law_form_tool` — 별표서식 검색

법령·행정규칙·자치법규의 별표서식을 서식명 또는 관련 법령명으로 검색합니다.

| `form_type` 값 | 설명 |
|--------------|------|
| `law` | 법령 별표서식 |
| `admin_rule` | 행정규칙 별표서식 |
| `ordinance` | 자치법규 별표서식 |

---

#### `law_link_tool` — 법령-자치법규 연계 조회

특정 법령에 연계된 조례 목록, 소관부처별·지자체별 연계 현황을 확인합니다.

| `link_type` 값 | 설명 |
|--------------|------|
| `law_to_ordinance` | 법령-자치법규 연계 목록 |
| `ordinance_articles` | 연계 법령별 조례 조문 목록 |
| `by_department` | 연계 법령 소관부처별 목록 |
| `linked_ordinance` | 연계 조례 목록 |
| `law_linked_ordinance` | 연계 법령별 조례 목록 |
| `by_region` | 연계 조례 지자체별 목록 |

---

## MCP Prompts

`prompts/list` 및 `prompts/get` 엔드포인트를 지원합니다.

| Prompt 이름 | 설명 |
|-------------|------|
| `legal_basis_answer` | 관련 법령 조문 번호와 판례 요지를 포함한 답변 요청 |
| `precedent_summary` | 판례를 사실관계 / 쟁점 / 판단요지로 요약 |
| `contract_risk_check` | 범용 계약·약관 위험 조항 점검. **근로·용역 전용 고밀도 검토**는 `labor_contract_review` 또는 `document_issue_tool`(문서가 labor로 분류될 때)을 사용하세요. |
| `labor_contract_review` | 근로·용역 계약서 조항별 조문·위험도·수정방향 검토(B 타입) |
| `legal_qa` | 특정 상황에 대한 법률적 관점 설명 |

---

## MCP Resources

`resources/list` 및 `resources/read` 엔드포인트를 지원합니다.

### URI Scheme

| 형식 | 설명 | 예시 |
|------|------|------|
| `law://{법령명}` | 법령 본문 조회 | `law://근로기준법` |
| `case://{검색어}` | 판례 검색 (상위 5건) | `case://부당해고` |
| `interpret://{검색어}` | 법령해석 검색 (상위 5건) | `interpret://근로자성` |

### Featured Resources (기본 제공)

근로기준법, 민법, 형법, 개인정보보호법, 상법, 국가공무원법, 행정소송법 등 주요 법령을 즉시 조회할 수 있습니다.

---

## Installation

### Method 1. Local (Python)

```bash
git clone https://github.com/SeoNaRu/lexguard-mcp
cd lexguard-mcp
pip install -r requirements.txt
cp .env.example .env   # LAW_API_KEY 설정
python -m src.main
```

### Method 2. Docker Compose (권장 · 한 줄에 가깝게)

```bash
git clone https://github.com/SeoNaRu/lexguard-mcp
cd lexguard-mcp
cp .env.example .env   # LAW_API_KEY 편집
docker compose up --build
```

브라우저/클라이언트 MCP URL: `http://localhost:9099/mcp` · 헬스: `http://localhost:9099/health`

### Method 3. Docker (run만)

```bash
docker build -t lexguard-mcp .
docker run -p 9099:9099 -e LAW_API_KEY=your_key lexguard-mcp
```

### 클라이언트 연결

서버가 로컬에서 실행 중일 때 MCP URL은 `http://localhost:9099/mcp` 입니다.

**Cursor** (`.cursor/mcp.json`) — [`examples/cursor-mcp.local.json`](examples/cursor-mcp.local.json) 파일과 동일:

```json
{
  "mcpServers": {
    "lexguard-mcp": {
      "url": "http://localhost:9099/mcp"
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`) — [`examples/claude-desktop-mcp.local.json`](examples/claude-desktop-mcp.local.json) 파일과 동일. Claude Desktop은 로컬 HTTP URL을 직접 지원하지 않으므로 `mcp-remote` 브리지를 사용합니다 (Node.js 필요):

```json
{
  "mcpServers": {
    "lexguard-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9099/mcp"]
    }
  }
}
```

> **claude.ai 웹 커넥터 안내**: 웹 커넥터는 공개 HTTPS URL이 필요하므로 로컬 실행 서버에는 연결할 수 없습니다. Claude Desktop 또는 Cursor 사용을 권장합니다. 웹에서 꼭 사용해야 한다면 본인 소유 서버(고정 IP + HTTPS)에 직접 배포한 뒤 그 IP를 open.law.go.kr에 등록하세요.

### API Key 발급 (필수)

국가법령정보센터 Open API 키가 필요합니다. 발급과 사용 모두 무료입니다.

1. [https://open.law.go.kr](https://open.law.go.kr) 회원가입
2. OPEN API 활용 신청 — 이때 **요청을 보낼 서버(본인 PC)의 IP 또는 도메인을 등록**해야 합니다. law.go.kr는 등록된 IP에서 온 요청만 허용합니다.
3. `.env`에 `LAW_API_KEY=발급받은키` 설정

> **유동 IP 주의**: 일반 가정 회선은 IP가 바뀔 수 있습니다. `"사용자 정보 검증에 실패하였습니다"` 오류가 나오면 [open.law.go.kr → API인증키관리]에서 현재 IP로 재등록하세요.

### DRF scheme 선택

`lexguard-mcp`는 국가법령정보센터 DRF URL의 host/path를 고정한 채, scheme만 `.env`로 선택할 수 있습니다.

```env
LAW_GO_KR_DRF_SCHEME=https
```

- 허용값: `http`, `https`
- 기본값: `https`
- 제한된 기업망/방화벽 환경에서는 공식 가이드 예시에 맞춘 `http://www.law.go.kr/DRF/...` 경로가 필요할 수 있습니다.

이 설정은 `https` 하드코딩이 일반 환경에서 우연히 가려질 수 있었던 잠복 URL-generation 문제를 운영환경별로 조정하기 위한 옵션입니다.

---

## Architecture

```
Client (Cursor / Claude)
    │ JSON-RPC 2.0 over SSE
    ▼
FastAPI  (/mcp POST)
    │ Rate Limiting (slowapi, 600 req/min/IP 기본값)
    ▼
MCP Routes  (tools/call · prompts/get · resources/read)
    │
    ▼
Services  (SmartSearchService · SituationGuidanceService)
    │ asyncio.gather (병렬 멀티 API 호출)
    ▼
Repositories  (Law · Precedent · Interpretation · Appeal · Constitutional …)
    │ httpx (동기/비동기 HTTP 클라이언트)
    │ TTLCache (검색 결과 30분 / 실패 5분)
    │ Exponential Backoff Retry
    ▼
국가법령정보센터 DRF API  (159개 엔트리 / 88개 unique target)
```

**검색 파이프라인**

```
질문 입력
    → 판례 번호 패턴 조기 감지 (2023다12345 / 2021헌마123)
    → 도메인 분류 + 의도(Intent) 분석
    → 시간 조건 파싱
    → asyncio.gather 병렬 API 호출
    → Reranker (BM25 + Keyword Hybrid 재정렬)
    → 응답 포매팅
```

**주요 기술 스택**

| 구분 | 사용 기술 |
|------|-----------|
| Web Framework | FastAPI + Uvicorn |
| MCP Transport | Streamable HTTP (SSE) |
| HTTP Client | httpx (sync + async) |
| Cache | cachetools TTLCache |
| Rate Limiting | slowapi |
| Search Ranking | BM25 + Keyword Hybrid Reranker |
| CI/CD | GitHub Actions (Python 3.11 / 3.12) |
| Testing | pytest + pytest-asyncio |

---

## Development

```bash
# 테스트 실행
pytest tests/ -v

# 린트
ruff check src/

# 로컬 서버 (자동 재로드)
RELOAD=true python -m src.main
```

---

## License

전문은 저장소 루트의 [`LICENSE`](LICENSE) 파일을 따릅니다.

- **사용:** MIT와 동일하게 연구·개인·상업적 이용, 수정·배포·재판매까지 허용됩니다.
- **판매·유료 제공 시:** 이 소프트웨어를 단독으로 판매하거나, 제품·서비스에 포함해 판매하는 경우 **저작권 표시와 본 라이선스 문구**를 최종 이용자에게 전달되는 자료(문서, 크레딧·라이선스 화면, 패키지 메타데이터 등)에 포함해야 합니다.

본 안내는 요약이며 법적 효력은 `LICENSE` 원문이 우선합니다.

---

## Contribution

Issues & PRs are always welcome.
법률 도메인 데이터, 검색 품질 개선, 새로운 MCP 툴 아이디어 모두 환영합니다.

---

> **LexGuard MCP — 법률 정보의 실마리를 찾아드립니다.**
> 법은 어렵지만, 첫 실마리는 쉬워질 수 있습니다.