# us-law-mcp

미국 연방법(U.S. Code · CFR · Federal Register · 판례 · 법안)을 LLM에서 바로 조회하고, **인용을 원문과 교차검증해 환각을 차단하는** MCP 서버 + CLI.

Claude Desktop, Claude Code, Cursor, Windsurf, Kiro, VS Code, Zed에서 바로 사용할 수 있습니다.

> MCP server for U.S. federal law — search the U.S. Code, CFR, Federal Register,
> case law and bills, and verify citations against primary sources.

---

## 왜 만들었나

LLM에 미국법을 물으면 세 가지를 자신 있게 틀립니다.

| 실패 유형 | 예시 | 이 서버의 대응 |
|---|---|---|
| **없는 조문을 만들어냄** | "17 U.S.C. § 9999에 따라 3배 배상" | `verify_citations` → `[NOT_FOUND]` |
| **있는 조문에 엉뚱한 내용을 붙임** | "17 U.S.C. § 107(양형 하한 규정)" | `verify_citations` → `[MISMATCH]` |
| **폐기된 판례를 살아있는 것처럼 인용** | "Roe v. Wade, 410 U.S. 113" | `cite_check` → Dobbs 감지 |
| **과거 행위에 현행법을 적용** | 2019년 위반에 2026년 규정 인용 | `applicable_law` → 시점 본문 |

미국법 원문은 govinfo, eCFR, federalregister.gov, CourtListener, Congress.gov에
전부 공개돼 있지만 서로 다른 5개 시스템에 흩어져 있고, 인용 문법·법원 위계·소급효
법리까지 알아야 연결됩니다. 이 서버가 그 연결을 담당합니다.

**모든 데이터 소스가 무료이고, API 키 없이도 동작합니다.**

---

## 30초 확인

```bash
git clone https://github.com/seelpeed-debug/us-law-mcp.git
cd us-law-mcp
npm install && npm run build

node dist/cli.js verify "Under 17 U.S.C. 107 courts weigh four fair use factors, \
and 42 U.S.C. 1983 creates a cause of action. See Roe v. Wade, 410 U.S. 113 (1973). \
But 17 U.S.C. 9999 imposes treble damages, and 40 CFR 261.9999 governs listing."
```

실제 출력 (라이브 API 호출 결과):

```
[HALLUCINATION_DETECTED] 5 citation(s) checked
  verified: 3
  content mismatch: 0
  not found: 2
  could not be checked: 0

Failed — cited authority does not exist (2)
  [NOT_FOUND] 17 U.S.C. § 9999
      note: no § 9999 in title 17 (Copyrights)
  [NOT_FOUND] 40 C.F.R. § 261.9999
      note: part 261 exists but has no § 261.9999
            (it contains § 261.1, 261.2, 261.3, 261.4, ...)

Verified (3)
  [OK] 17 U.S.C. § 107      actual: Limitations on exclusive rights: Fair use
  [OK] 42 U.S.C. § 1983     actual: Civil action for deprivation of rights
  [OK] Roe v. Wade, 410 U.S. 113 (1973)
       Supreme Court of the United States, filed 1973-01-22, cited by 5585
```

종료 코드는 `1`입니다. 파이프라인 게이트로 바로 걸 수 있습니다.

---

## 설치

### 방법 1 — 설정 마법사 (권장)

```bash
npm run build
node dist/index.js setup
```

API 키를 물어보고(전부 Enter로 건너뛰기 가능), 클라이언트를 고르면 설정 파일에
**병합**해 넣습니다. 기존 MCP 서버 설정은 건드리지 않고, 쓰기 전에 백업을 남깁니다.

### 방법 2 — 설정 파일 직접 수정

Claude Desktop / Claude Code / Cursor / Windsurf / Kiro:

```json
{
  "mcpServers": {
    "us-law": {
      "command": "node",
      "args": ["D:/ai/US law MCP/dist/index.js"],
      "env": {
        "GOVINFO_API_KEY": "your-key",
        "COURTLISTENER_TOKEN": "your-token",
        "CONGRESS_API_KEY": "your-key"
      }
    }
  }
}
```

`env` 블록은 통째로 생략해도 동작합니다.

설정 파일 위치:

| 클라이언트 | 경로 |
|---|---|
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Code | `~/.claude.json` |
| Cursor | `<project>/.cursor/mcp.json` |
| Windsurf | `<project>/.windsurf/mcp.json` |
| Kiro | `<project>/.kiro/settings/mcp.json` |
| VS Code | `<project>/.vscode/mcp.json` (키 이름은 `servers`) |

### 방법 3 — HTTP 서버 (원격/공유)

```bash
node dist/index.js --http --port 8787
```

```json
{ "mcpServers": { "us-law": { "url": "http://localhost:8787/mcp?govinfo_key=YOUR_KEY" } } }
```

무상태(stateless) 방식입니다. 요청마다 서버·트랜스포트를 새로 만들고 끝나면
해제하므로, 프로세스가 재시작되거나 인스턴스가 늘어나도 세션이 깨지지 않습니다.
`GET /health`로 상태를 확인할 수 있습니다.

### 방법 4 — 터미널 CLI

```bash
node dist/cli.js "17 USC 107"          # 자동 라우팅
node dist/cli.js "40 CFR 261.11"
node dist/cli.js "Section 230"
node dist/cli.js "Roe v. Wade"
node dist/cli.js verify "<검증할 텍스트>"
node dist/cli.js list                  # 도구 목록
node dist/cli.js help legal_analysis   # 파라미터 설명
```

---

## API 키 (전부 무료, 전부 선택)

| 환경변수 | 없으면 어떻게 되나 | 발급 |
|---|---|---|
| `GOVINFO_API_KEY` | U.S. Code 조회가 Cornell LII 폴백으로 전환 (느리고 비공식) | [api.data.gov/signup](https://api.data.gov/signup/) |
| `COURTLISTENER_TOKEN` | 판례 검색·인용검증·시테이터는 정상 동작. 최신 판례 **전문**만 불가 | [courtlistener.com](https://www.courtlistener.com/help/api/rest/) |
| `CONGRESS_API_KEY` | 법안·공법 조회 제한 | [api.congress.gov/sign-up](https://api.congress.gov/sign-up/) |

**eCFR · Federal Register · Caselaw Access Project는 키가 필요 없습니다.**
그래서 키를 하나도 넣지 않아도 규정 조회, 판례 검색, 인용 검증이 전부 동작합니다.
환각 게이트를 회원가입 뒤에 두지 않으려는 의도적 설계입니다.

키 전달 방법은 우선순위 순으로 네 가지입니다: 도구 파라미터 → HTTP 헤더/쿼리스트링
→ 환경변수 → 내장 기본값. HTTP 모드에서는 요청별 키가 `AsyncLocalStorage`에
격리되므로 동시 요청끼리 키가 섞이지 않습니다.

---

## 도구 구조 — 광고 11개 / 전체 21개

`tools/list` 페이로드를 **14.5 KB**로 유지합니다. 도구 목록이 커지면 모델의 도구
선택 정확도가 눈에 띄게 떨어지므로, 자주 쓰지 않는 전문 도구 10개는 목록에서 빼고
`discover_tools` → `execute_tool`로 접근합니다.

### 광고되는 도구 (11)

| 구분 | 도구 | 설명 |
|---|---|---|
| 리서치 | `legal_research` | 다단계 체인 — `task` 7종 |
| 분석 | `legal_analysis` | 검증·분석 — `mode` 4종 |
| 법률 | `search_law` | U.S. Code 검색 (인용/통칭/키워드) |
| | `get_law_text` | 조문 전문 + 판본 최신성 표시 |
| 규정 | `search_regulations` | CFR 검색 + 관련 Federal Register 동향 |
| | `get_regulation_text` | CFR 본문, **임의 과거 시점 조회 가능** |
| | `regulatory_radar` | 규정 vs 근거 법률 개정 시점 대조 |
| 판례 | `search_decisions` | 12개 법원 계층 통합 검색 |
| | `get_decision_text` | 판결 전문 (다수·별개·반대의견 분리) |
| 메타 | `discover_tools` | 숨은 전문 도구 탐색 |
| | `execute_tool` | 전문 도구 프록시 실행 |

### `legal_analysis` mode 4종

| mode | 하는 일 | 필수 |
|---|---|---|
| `verify_citations` | 텍스트의 모든 인용을 원문 대조 — 존재 + 내용 + 항번호 | `text` |
| `cite_check` | 판례 생사 확인 (미국형 Shepard's) | `citation` / `caseName` / `opinionId` |
| `applicable_law` | 특정 날짜에 시행 중이던 본문 + 이후 변경 diff + 소급효 법리 | `date` + 조문 |
| `impact_map` | 이 조문을 인용한 판례·규정·행정입법 역방향 탐색 + mermaid | 조문 |

### `legal_research` task 7종

`full_research` · `statutory_scheme` · `agency_action` · `litigation_prep` ·
`amendment_track` · `compliance_check` · `document_review`

체인은 하위 도구를 그대로 호출해 이어붙이므로 조회 경로가 하나로 유지됩니다.
실패한 단계는 **숨기지 않고** `[INCOMPLETE]` / `[SKIPPED]`로 표시합니다.
빈칸이 있는 리포트를 매끈하게 내보내면 읽는 쪽이 그 빈칸을 알 수 없습니다.

### 숨은 전문 도구 (10)

`get_public_law` · `get_bill` · `search_bills` · `compare_cfr_versions` ·
`get_cfr_structure` · `list_agencies` · `get_federal_register_document` ·
`get_statute_history` · `list_usc_editions` · `list_popular_names`

```
discover_tools(query="compare a regulation across dates")
execute_tool(tool="compare_cfr_versions", args={title:"40", section:"261.11", fromDate:"2019-01-01"})
```

---

## 핵심 기능

### 1. 인용 검증 — 환각 게이트

존재 확인만으로는 부족합니다. 세 층으로 검사합니다.

```
17 U.S.C. § 9999                      → [NOT_FOUND]  없는 조문
17 U.S.C. § 107 (양형 하한)            → [MISMATCH]   조문은 있지만 내용이 다름
42 U.S.C. § 1983(z)(9)                → [MISMATCH]   (z)항이 존재하지 않음
Brown v. Board of Education, 410 U.S. 113 → [MISMATCH] 그 인용은 Roe v. Wade
12 F.4th 1234                          → [UNVERIFIED] 확인 불가 (CAP 수록 범위 밖)
```

설계 원칙 세 가지입니다.

1. **검사하지 않은 것을 "검증됨"으로 보고하지 않습니다.** 파서가 인식하지 못한
   인용 형태와 소스 장애는 `[UNVERIFIED]`로 요약 카운트에 드러납니다. 게이트에서
   가장 위험한 실패는 오판이 아니라, **검사되지 않은 텍스트에 대해 깨끗한 리포트가
   나오는 것**입니다. 읽는 쪽은 그것을 통과로 읽습니다.
2. **수록 범위 부재를 위조로 보고하지 않습니다.** CAP는 2020년경까지만 다루고,
   Federal Register API는 면 단위 색인이 없습니다. 이런 경우는 `[UNVERIFIED]`이지
   `[NOT_FOUND]`가 아닙니다. 진짜 판례를 위조로 낙인찍는 검증기는 결국 꺼집니다.
3. **문제가 하나라도 있으면 `isError: true`** 를 설정합니다.

지원 인용 형식: U.S.C. (`17 U.S.C. § 107`, `17 USC 107`, `section 107 of title 17`,
`Title 17, Section 107`) · CFR (`40 C.F.R. § 261.11`, `40 CFR part 261`) ·
판례 (401개 리포터 약어) · `Pub. L. No. 117-108` · `135 Stat. 4` · `88 Fed. Reg. 12,345`

### 2. 판례 생사 확인 (`cite_check`)

CourtListener 인용 그래프 + 판시 문구 스캔으로 파기·변경 신호를 찾습니다.

```
legal_analysis(mode="cite_check", citation="410 U.S. 113")

→ [NEGATIVE_SIGNAL] 10 citing decision(s) contain displacement language,
                    10 of them from a court that could overrule this one.

   Dobbs v. Jackson Women's Health Organization
       Supreme Court of the United States · 2022-06-24
       can overrule; names the target case; found via name search
```

**스캔을 두 갈래로 돌립니다.** 인용 그래프만 쓰면 Dobbs를 놓칩니다 — CourtListener에서
Dobbs의 `cites` 배열이 비어 있어 `cites:(108713)` 검색에 걸리지 않습니다.
그래서 사건명 + 파기 문구를 **파기 권한이 있는 법원으로 한정**해 검색하는 2차 스캔을
함께 돌립니다. 개발 중 실측으로 확인한 구멍이고, 이걸 놓치면 시테이터는 무의미합니다.

판정은 **신호**로만 보고합니다. 법원 위계를 계산해 "파기 가능한 법원인지"를 함께
표시하고, 근거 문구를 인용해 판단을 사용자에게 넘깁니다. 상용 시테이터가 아니며
묵시적 파기는 잡지 못한다는 한계를 매 응답에 명시합니다.

### 3. 행위시법 판단 (`applicable_law`)

```
legal_analysis(mode="applicable_law", citation="40 CFR 261.11", date="2019-06-01")

→ TEXT IN FORCE ON 2019-06-01 — use this one
   (그 시점 본문 전문)

→ Changes since then (then → now)
   [~ changed] (a)(3)  before: ... / after: ...

→ Amendment events after 2019-06-01 (n)
   각 Final Rule의 시행일 + Federal Register 링크

→ Which version actually applies
   - 행정규칙은 원칙적으로 장래효. 소급 규칙은 의회가 명시적으로 권한을 준
     경우에만 — Bowen v. Georgetown Univ. Hospital, 488 U.S. 204 (1988)
   - 제재는 행위 시점 기준이 원칙. 채택 문서의 경과규정을 확인할 것
```

CFR은 eCFR이 실제로 시점 버전을 제공하므로 정확한 과거 본문을 가져옵니다.
U.S. Code는 연 1회 판본만 있으므로 "그 날짜에 시행 중이던 판본"을 특정하고,
연중 개정이 반영되지 않는다는 한계를 명시합니다.

법리 안내도 함께 붙습니다: 형사는 소급입법금지(U.S. Const. art. I §§ 9-10),
민사는 Landgraf v. USI Film Products, 511 U.S. 244 (1994), 일반유보조항
1 U.S.C. § 109, 양형은 Peugh v. United States, 569 U.S. 530 (2013).

### 4. 조문 영향 그래프 (`impact_map`)

```
legal_analysis(mode="impact_map", citation="17 U.S.C. 107")

  Citing court decisions: 669
  Implementing / referencing CFR provisions: 20
  Federal Register documents invoking it: 23

  Harper & Row, Publishers, Inc. v. Nation Enterprises
      471 U.S. 539 · SCOTUS · 1985-05-20 · cited by 1198
  Sony Corp. of America v. Universal City Studios, Inc.
      464 U.S. 417 · SCOTUS · 1984-01-17 · cited by 983
  Campbell v. Acuff-Rose Music, Inc.
      510 U.S. 569 · SCOTUS · 1994-03-07 · cited by 633
```

인용 표기 편차가 실제 난점입니다. 법원은 `17 U.S.C. § 107`, CFR은 `17 U.S.C. 107`,
서면은 `17 USC 107`로 씁니다. 한 형태만 검색하면 코퍼스의 일부만 잡히므로 모든
질의를 변형들로 펼칩니다. 인용 수는 **하한**이며 census가 아닙니다.

### 5. 규제 레이더 (`regulatory_radar`)

CFR 각 part는 Authority note에 근거 법률을 선언합니다. 의회가 그 법률을 개정했는데
기관이 규정을 손대지 않았다면, 규정이 자기 근거와 어긋날 수 있습니다. 자동으로
알려주는 곳이 없어서 날짜를 나란히 놓지 않으면 보이지 않습니다.

```
regulatory_radar(title="40", part="261")

  Rule last revised: 2025-09-11
  Authority note: 42 U.S.C. 6905, 6912(a), 6921, 6922, 6924(y) and 6938.

  [NO_DRIFT] None of the 6 authority statutes checked was amended after
             the rule's last revision (2025-09-11).

  42 U.S.C. § 6921  [in step]
      Identification and listing of hazardous waste
      last touched: 2006 (Pub. L. 109-177)  [from Amendments note]
```

법률의 "마지막 개정"은 U.S. Code 편집주(Amendments note)를 파싱해 구합니다.
U.S. Code에는 버전 API가 없어 이 주석이 유일한 기록입니다. 주석이 없으면
source credit으로 폴백합니다 — 폐지·재제정된 조문은 Amendments note가 아예 없어서
(`31 U.S.C. § 5311`은 2021년 Pub. L. 116-283으로 전면 재제정) "개정 이력 없음"으로
보고하면 정면으로 틀립니다.

판정은 **검토 트리거**이지 법적 결론이 아닙니다. 어느 기록에서 날짜를 얻었는지
(`[from Amendments note]` / `[from source credit]`) 항상 함께 표시합니다.

---

## 데이터 소스

| 소스 | 담당 | 키 |
|---|---|---|
| [govinfo](https://api.govinfo.gov/) (GPO) | U.S. Code, 공법, Statutes at Large, 연방법원 문서 | 필요 |
| [eCFR](https://www.ecfr.gov/developers/documentation/api/v1) | CFR + 시점 조회 + 구조 + 기관 목록 | 불필요 |
| [federalregister.gov](https://www.federalregister.gov/developers/api/v1) | 규칙·규칙안·공고 | 불필요 |
| [CourtListener](https://www.courtlistener.com/help/api/rest/v4/) (Free Law Project) | 판례, 인용 그래프 | 검색은 불필요 |
| [Caselaw Access Project](https://static.case.law/) (Harvard) | 판결 전문 (~2020) | 불필요 |
| [Congress.gov](https://api.congress.gov/) (LoC) | 법안, 입법 이력 | 필요 |
| [Cornell LII](https://www.law.cornell.edu/uscode/) | U.S. Code 폴백 전용 | 불필요 |

Cornell LII는 govinfo가 없거나 불가할 때만 쓰고, robots.txt의 Crawl-delay를 지켜
직렬화하며 `/uscode/text/` 경로만 호출합니다. `US_LAW_ENABLE_LII_FALLBACK=false`로
완전히 끌 수 있습니다.

법적 효력이 필요한 판단은 각 응답에 붙은 URL의 원문을 반드시 확인하세요.
이 도구는 조회 결과를 가공·요약합니다. 법률 조언이 아닙니다.

---

## 개발

```bash
npm install
npm run build            # tsc
npm test                 # 오프라인 단위 테스트 52개
npm run smoke            # 라이브 API 통합 검증 21개
npm run probe:stdio      # MCP 프로토콜 레벨 검증
npm run gen:reporters    # 리포터 약어 표 재생성
npm run typecheck
```

### 현재 검증 상태

```
npm test              52 passed, 0 failed
npm run smoke         21 passed, 0 failed   (라이브 govinfo/eCFR/FR/CL/CAP 호출)
npm run probe:stdio   stdio transport OK    (11 tools, 14.5 KB tools/list)
```

`smoke`는 서드파티 API를 직접 호출하므로 빌드 게이트가 아닙니다. 실패가 레이트
리밋이나 상류 장애일 수 있으니 회귀로 단정하기 전에 다시 실행하세요.

문서: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) ·
[`docs/API.md`](docs/API.md) · [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)

---

## 라이선스

MIT. 데이터 출처와 제3자 고지는 [NOTICE](NOTICE)를 참조하세요.

도구 아키텍처는 [chrisryugj/korean-law-mcp](https://github.com/chrisryugj/korean-law-mcp)의
설계 패턴(작은 광고 표면 + discover/execute, 환각 게이트, 행위시법 판단, 영향 그래프,
정비 레이더)을 미국법 체계에 옮긴 것입니다. 코드는 복사하지 않았고, 데이터 소스·인용
문법·법원 위계·소급효 법리는 전부 다릅니다.