Keep korean-law-search available during upstream outages (#45)

Issue #44 adds Beopmang as the documented fallback when the primary korean-law-mcp path is unavailable, and locks the new routing into the doc regression suite so future edits do not silently revert the policy. Constraint: Existing guidance must still prefer korean-law-mcp and keep LAW_OC scoped to the local CLI/MCP path Rejected: Add a repo-local Beopmang client package | issue only requires fallback registration, not a new implementation surface Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep the primary-first rule intact; Beopmang is an outage fallback, not the default path Tested: node --test scripts/skill-docs.test.js; npm run ci; korean-law list; python3 live Beopmang search smoke for 관세법 Not-tested: Live Beopmang MCP handshake from a GUI MCP client
2026-06-24 02:04:11 +00:00 · 2026-04-02 23:33:12 +09:00 · 2026-04-02 23:33:12 +09:00 · 8a2a1565fc
commit 8a2a1565fc
parent 07c498669d
8 changed files with 84 additions and 18 deletions
--- a/README.md
+++ b/README.md
@ -23,7 +23,7 @@ Claude Code, Codex, OpenCode, OpenClaw/ClawHub 등 각종 코딩 에이전트
 | 카카오톡 Mac CLI | macOS에서 kakaocli로 대화 조회, 검색, 테스트 전송, 확인 후 실제 전송 | 불필요 | [카카오톡 Mac CLI 가이드](docs/features/kakaotalk-mac.md) |
 | 서울 지하철 도착정보 조회 | self-host 또는 배포 확인이 끝난 `k-skill-proxy` 경유로 역 기준 실시간 도착 예정 열차 확인 | 프록시 URL 필요 | [서울 지하철 도착정보 가이드](docs/features/seoul-subway-arrival.md) |
 | 사용자 위치 미세먼지 조회 | `k-skill-proxy` 로 현재 위치 또는 지역 fallback 기준 PM10/PM2.5 확인 | 불필요 | [사용자 위치 미세먼지 조회 가이드](docs/features/fine-dust-location.md) |
-| 한국 법령 검색 | `korean-law-mcp` 기반 법령/조문/판례/유권해석 조회 | 로컬 CLI/MCP면 `LAW_OC` 필요, remote endpoint면 불필요 | [한국 법령 검색 가이드](docs/features/korean-law-search.md) |
+| 한국 법령 검색 | `korean-law-mcp` 우선 + 장애 시 `법망` fallback으로 법령/조문/판례/유권해석 조회 | 로컬 CLI/MCP면 `LAW_OC` 필요, remote endpoint/법망 fallback은 불필요 | [한국 법령 검색 가이드](docs/features/korean-law-search.md) |
 | KBO 경기 결과 조회 | 날짜별 경기 일정, 결과, 팀별 필터링 | 불필요 | [KBO 결과 가이드](docs/features/kbo-results.md) |
 | K리그 경기 결과 조회 | 날짜별 K리그1/K리그2 경기 결과, 팀별 필터링, 현재 순위 확인 | 불필요 | [K리그 결과 가이드](docs/features/kleague-results.md) |
 | 토스증권 조회 | `tossctl` 기반 계좌 요약, 포트폴리오, 시세, 주문내역, 관심종목 조회 | 필요 | [토스증권 조회 가이드](docs/features/toss-securities.md) |
--- a/docs/features/korean-law-search.md
+++ b/docs/features/korean-law-search.md
@ -6,10 +6,12 @@
 - 특정 법령의 조문 본문 조회
 - 판례 / 유권해석 / 자치법규 검색
 - MCP 또는 CLI 경로 중 현재 환경에 맞는 방식 선택
+- 기존 경로 장애 시 `법망` fallback으로 이어가기

 ## 가장 중요한 규칙

-한국 법령 관련 검색/조회가 필요할 때는 **반드시 `korean-law-mcp`를 사용**합니다.
+한국 법령 관련 검색/조회가 필요할 때는 **`korean-law-mcp`를 먼저 사용**합니다.
+기존 서비스가 동작하지 않을 때만 승인된 fallback 표면인 **`법망`(`https://api.beopmang.org`)** 으로 전환합니다.
 별도 repo package, 별도 python package, 임의 크롤러를 새로 만들지 않습니다.

 ## 먼저 필요한 것
@ -18,6 +20,7 @@
 - `node` 18+
 - `npm install -g korean-law-mcp` (로컬 CLI/로컬 MCP server 경로일 때)
 - remote MCP endpoint를 쓸 MCP 클라이언트
+- `법망` fallback (`https://api.beopmang.org`) 에 접근할 수 있는 네트워크

 무료 API key 발급처: `https://open.law.go.kr`

@ -32,7 +35,7 @@ korean-law list
 korean-law help search_law
 ```

-로컬 설치가 막히면 `https://korean-law-mcp.fly.dev/mcp` remote endpoint를 사용해도 된다. 다만 이 경우에도 **`korean-law-mcp` 경로만** 사용한다.
+로컬 설치가 막히면 먼저 `https://korean-law-mcp.fly.dev/mcp` remote endpoint를 사용한다. 그 경로도 응답하지 않거나 서비스 장애가 나면 `법망`(`https://api.beopmang.org`) MCP/REST를 fallback으로 사용한다.

 ## MCP 연결 예시

@ -63,6 +66,30 @@ remote endpoint 예시:

 위 remote 예시는 upstream 문서 기준으로 사용자 `LAW_OC` 를 따로 넣지 않는다. 사용자 쪽에서 준비할 것은 `url` 등록뿐이다.

+## fallback: 법망
+
+기존 `korean-law-mcp` 경로가 동작하지 않을 때만 `법망`을 사용한다.
+
+### MCP fallback
+
+```json
+{
+  "mcpServers": {
+    "beopmang": {
+      "url": "https://api.beopmang.org/mcp"
+    }
+  }
+}
+```
+
+### REST fallback 예시
+
+```bash
+curl "https://api.beopmang.org/api/v4/law?action=search&q=관세법"
+curl "https://api.beopmang.org/api/v4/tools?action=overview&law_id=001706"
+curl "https://api.beopmang.org/api/v4/law?action=get&law_id=001706&article=제750조"
+```
+
 ## 기본 흐름

 1. 질의가 법령/판례/행정해석/자치법규 중 어디에 가까운지 분류한다.
@ -70,7 +97,8 @@ remote endpoint 예시:
 3. 특정 조문이 필요하면 `search_law` 또는 `search_all` 로 식별자(`mst`)를 확인한 뒤 `get_law_text` 를 호출한다.
 4. 판례는 `search_precedents`, 유권해석은 `search_interpretations`, 자치법규는 `search_ordinance` 를 우선 사용한다.
 5. 범주가 애매하면 `search_all` 로 시작한다.
-6. 한국 법령 검색은 항상 `korean-law-mcp` 로 끝까지 처리한다.
+6. `korean-law-mcp` 경로가 설치/네트워크/서비스 장애로 막히면 `법망` fallback으로 전환한다.
+7. fallback 검색 결과가 0건이어도 바로 "관련 규범이 없다"고 단정하지 말고 검색어와 범주를 다시 확인한다.

 ## CLI 예시

@ -84,8 +112,9 @@ korean-law search_precedents --query "부당해고"

 - `화관법` 같은 약칭은 `search_law` / `search_all` 로 정식 법령명을 먼저 확인한다.
 - 조문 번호가 헷갈리면 `get_law_text` 전에 법령 식별자부터 다시 확인한다.
- 로컬 CLI/MCP 경로를 쓰는데 `LAW_OC` 가 없으면 credential resolution order에 따라 확보를 안내하고, 다른 검색 경로로 우회하지 않는다.
+- 로컬 CLI/MCP 경로를 쓰는데 `LAW_OC` 가 없으면 credential resolution order에 따라 확보를 안내한다.
 - remote MCP endpoint를 쓰면 사용자 `LAW_OC` 없이 `url` 등록 상태만 확인한다.
+- 기존 `korean-law-mcp` 경로가 실패하면 `https://api.beopmang.org/mcp` 또는 `/api/v4/law?action=search` 경로를 fallback으로 쓴다.
 - 요약은 할 수 있지만 법률 자문처럼 단정적으로 결론을 내리지는 않는다.

 ## 라이브 확인 메모
@ -95,4 +124,4 @@ korean-law search_precedents --query "부당해고"
 - `korean-law list`
 - `korean-law help search_law`

-즉, `korean-law-mcp` CLI 설치와 기본 명령 진입은 검증했다. 실제 법령 검색은 로컬 CLI/MCP 경로라면 `LAW_OC` 가 준비된 환경에서 바로 이어서 사용할 수 있고, remote MCP endpoint는 사용자 `LAW_OC` 없이 URL 등록만으로 붙일 수 있다.
+즉, `korean-law-mcp` CLI 설치와 기본 명령 진입은 검증했다. 실제 법령 검색은 로컬 CLI/MCP 경로라면 `LAW_OC` 가 준비된 환경에서 바로 이어서 사용할 수 있고, remote MCP endpoint는 사용자 `LAW_OC` 없이 URL 등록만으로 붙일 수 있다. 기존 경로 장애 시에는 `법망` fallback을 사용할 수 있다.
--- a/docs/install.md
+++ b/docs/install.md
@ -77,6 +77,7 @@ npx --yes skills add <owner/repo> \

 - 로컬 CLI/MCP 경로는 `LAW_OC` 를 채운다.
 - remote endpoint는 `LAW_OC` 없이 `url`만 등록한다.
+- 기존 `korean-law-mcp` 경로가 실패하면 `법망`(`https://api.beopmang.org`) fallback을 사용한다.

 ```bash
 npm install -g korean-law-mcp
@ -84,7 +85,7 @@ export LAW_OC=your-api-key
 korean-law list
 ```

-로컬 설치가 막히면 `https://korean-law-mcp.fly.dev/mcp` remote endpoint를 MCP 클라이언트에 등록한다. 이 경우에도 한국 법령 조회는 `korean-law-mcp`만 사용한다.
+로컬 설치가 막히면 `https://korean-law-mcp.fly.dev/mcp` remote endpoint를 MCP 클라이언트에 등록한다. 그 경로도 응답하지 않거나 서비스 장애가 나면 `https://api.beopmang.org/mcp` 또는 `https://api.beopmang.org/api/v4/law?action=search` 를 fallback으로 사용한다.

 로컬 저장소에서 바로 전체 설치 테스트:

--- a/docs/setup.md
+++ b/docs/setup.md
@ -37,7 +37,7 @@ chmod 0600 ~/.config/k-skill/secrets.env

 한국 법령 검색의 로컬 CLI/MCP 경로용 `LAW_OC` 는 `korean-law-mcp` 로컬 실행에 쓴다. 로컬 CLI/MCP 경로는 `LAW_OC` 를 채운 뒤 `npm install -g korean-law-mcp` 와 `korean-law list` 로 설치 상태를 확인한다.

-remote MCP endpoint는 사용자 `LAW_OC` 없이 `url`만으로 연결한다. 이 경우에도 다른 구현으로 우회하지 않고 `korean-law-mcp` endpoint만 사용한다.
+remote MCP endpoint는 사용자 `LAW_OC` 없이 `url`만으로 연결한다. 다만 기존 `korean-law-mcp` 경로가 서비스 장애로 막히면 `법망`(`https://api.beopmang.org`) MCP/REST를 fallback으로 사용할 수 있다.

 ## 확인

@ -59,7 +59,7 @@ bash scripts/check-setup.sh
 | SRT 예매 | `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` |
 | KTX 예매 | `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD` |
 | 한국 법령 검색 (로컬 CLI/MCP) | `LAW_OC` |
-| 한국 법령 검색 (remote MCP endpoint) | 사용자 시크릿 불필요 (`url`만 등록) |
+| 한국 법령 검색 (remote MCP endpoint) | 사용자 시크릿 불필요 (`url`만 등록, 장애 시 `법망` fallback 가능) |
 | 서울 지하철 도착정보 조회 | self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL` |
 | 사용자 위치 미세먼지 조회 | `KSKILL_PROXY_BASE_URL` 또는 `AIR_KOREA_OPEN_API_KEY` |

--- a/docs/sources.md
+++ b/docs/sources.md
@ -13,6 +13,7 @@
 - `@ohah/hwpjs`: https://github.com/ohah/hwpjs
 - `hwp-mcp`: https://github.com/jkf87/hwp-mcp
 - korean-law-mcp: https://github.com/chrisryugj/korean-law-mcp
+- beopmang: https://api.beopmang.org
 - `silver-flight-group/kakaocli`: https://github.com/silver-flight-group/kakaocli
 - KakaoTalk Mac 설치 참고(`mas`): https://velog.io/@bonjugi/%EB%A7%A5%EB%B6%81-M1%EC%97%90-homebrew%EB%A1%9C-node-vscode-%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%86%A1-%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0
 - 동행복권 로또 결과 페이지: https://www.dhlottery.co.kr/lt645/result
--- a/k-skill-setup/SKILL.md
+++ b/k-skill-setup/SKILL.md
@ -78,7 +78,7 @@ chmod 0600 ~/.config/k-skill/secrets.env

 서울 지하철 도착정보는 hosted public route rollout 이 끝나기 전까지 `KSKILL_PROXY_BASE_URL` 을 self-host 또는 배포 확인이 끝난 proxy URL 로 채운다. 미세먼지만 hosted proxy 로 쓸 때는 이 값을 비워 둘 수 있다.

-한국 법령 검색은 로컬 `korean-law-mcp` 경로를 쓸 때만 `LAW_OC` 를 채운다. remote endpoint는 사용자 `LAW_OC` 없이 `url`만 등록하면 된다.
+한국 법령 검색은 로컬 `korean-law-mcp` 경로를 쓸 때만 `LAW_OC` 를 채운다. remote endpoint는 사용자 `LAW_OC` 없이 `url`만 등록하면 되고, 기존 경로 장애 시에는 `법망`(`https://api.beopmang.org`)을 fallback으로 안내한다.

 ### Missing secret response template

@ -89,7 +89,7 @@ chmod 0600 ~/.config/k-skill/secrets.env
 - SRT: `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD`
 - KTX: `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD`
 - 로컬 한국 법령 검색: `LAW_OC` + `korean-law-mcp`
- 한국 법령 검색 remote endpoint: 사용자 `LAW_OC` 없이 `url`만 등록
+- 한국 법령 검색 remote endpoint: 사용자 `LAW_OC` 없이 `url`만 등록, 장애 시 `법망` fallback
 - 서울 지하철: self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL`
 - 사용자 위치 미세먼지 조회: `KSKILL_PROXY_BASE_URL` 또는 `AIR_KOREA_OPEN_API_KEY`

--- a/korean-law-search/SKILL.md
+++ b/korean-law-search/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: korean-law-search
-description: Use korean-law-mcp for Korean law, precedent, ordinance, and interpretation lookups. Always use korean-law-mcp when the user needs Korean legal search or retrieval.
+description: Use korean-law-mcp first for Korean law lookups, and fall back to Beopmang when the primary service is unavailable.
 license: MIT
 metadata:
  category: legal
@ -12,7 +12,7 @@ metadata:

 ## What this skill does

-한국 법령/조문/판례/유권해석/자치법규 조회가 필요할 때 **반드시 `korean-law-mcp`를 사용**한다.
+한국 법령/조문/판례/유권해석/자치법규 조회가 필요할 때 기본 경로로 **`korean-law-mcp`를 먼저 사용**하고, 기존 서비스가 동작하지 않을 때는 승인된 fallback 표면인 **`법망`(`https://api.beopmang.org`)** 으로 이어간다.

 - 법령명 검색: `search_law`
 - 조문 본문 조회: `get_law_text`
@ -21,7 +21,7 @@ metadata:
 - 자치법규 검색: `search_ordinance`
 - 여러 카테고리가 섞인 검색: `search_all`

-이 스킬은 자체 npm/python 패키지를 만들지 않는다. 한국 법령 관련 조회는 로컬 설치든 remote endpoint든 **항상 `korean-law-mcp` 경로로만 처리**한다.
+이 스킬은 자체 npm/python 패키지를 만들지 않는다. 한국 법령 관련 조회는 기본적으로 `korean-law-mcp` 로 처리하고, 해당 경로가 막히거나 실패가 반복될 때만 승인된 fallback 표면인 `법망`을 사용한다.

 ## When to use

@ -43,6 +43,7 @@ metadata:
 - `node` 18+
 - `npm install -g korean-law-mcp` (로컬 CLI/로컬 MCP server 경로일 때)
 - MCP 클라이언트에 remote endpoint를 등록할 수 있는 환경
+- `법망` fallback (`https://api.beopmang.org`) 에 접근할 수 있는 네트워크

 무료 API key: `https://open.law.go.kr`

@ -57,7 +58,7 @@ korean-law list
 korean-law help search_law
 ```

-로컬 설치가 운영체제 정책이나 권한 때문에 막히면, 대체 구현을 만들지 말고 `korean-law-mcp` 의 remote MCP endpoint(`https://korean-law-mcp.fly.dev/mcp`)를 사용한다. 이 경우에도 **반드시 `korean-law-mcp`를 사용한 것**으로 취급한다.
+로컬 설치가 운영체제 정책이나 권한 때문에 막히면 먼저 `korean-law-mcp` 의 remote MCP endpoint(`https://korean-law-mcp.fly.dev/mcp`)를 사용한다. 그래도 기존 경로가 응답하지 않거나 서비스 장애로 조회가 막히면, 승인된 fallback 표면인 `법망` MCP/REST(`https://api.beopmang.org`)로 전환한다.

 ## MCP client setup

@ -88,6 +89,30 @@ Claude Desktop / Cursor / Windsurf 같은 MCP 클라이언트에는 아래처럼
 }
 ```

+## Fallback workflow (`법망`)
+
+기존 `korean-law-mcp` 경로가 동작하지 않을 때만 아래 fallback을 사용한다.
+
+### 1. MCP fallback
+
+```json
+{
+  "mcpServers": {
+    "beopmang": {
+      "url": "https://api.beopmang.org/mcp"
+    }
+  }
+}
+```
+
+### 2. REST fallback
+
+```bash
+curl "https://api.beopmang.org/api/v4/law?action=search&q=관세법"
+curl "https://api.beopmang.org/api/v4/tools?action=overview&law_id=001706"
+curl "https://api.beopmang.org/api/v4/law?action=get&law_id=001706&article=제750조"
+```
+
 ## CLI workflow

 ### 1. 법령명부터 찾기
@ -123,6 +148,7 @@ korean-law search_all --query "개인정보 처리방침 행정해석"
 ## Response policy

 - 한국 법령 관련 요청은 **항상 `korean-law-mcp`를 먼저 사용**한다.
+- 기존 `korean-law-mcp` 경로가 설치/네트워크/서비스 장애로 실패하면 `법망`(`https://api.beopmang.org`)을 fallback으로 사용한다.
 - 약칭(`화관법`)이면 `search_law` / `search_all` 로 정식 법령명을 먼저 확인한다.
 - 조문 요청이면 검색 결과의 식별자(`mst`)를 확인한 뒤 `get_law_text` 로 본문을 가져온다.
 - 판례는 `search_precedents`, 유권해석은 `search_interpretations`, 자치법규는 `search_ordinance` 를 우선 사용한다.
@ -138,9 +164,11 @@ korean-law search_all --query "개인정보 처리방침 행정해석"
 - 유권해석이면 `search_interpretations`, 자치법규면 `search_ordinance` 까지 명시적으로 연결했다.
 - 로컬 경로라면 `LAW_OC` 확보 방법을 정확한 변수 이름으로 안내했다.
 - remote endpoint라면 사용자 `LAW_OC` 없이 `url` 등록 상태를 확인했다.
+- 기존 경로 장애 시 `법망` fallback(MCP 또는 REST)으로 이어지는 안내가 포함되었다.

 ## Notes

 - upstream: `https://github.com/chrisryugj/korean-law-mcp`
+- fallback surface: `https://api.beopmang.org`
 - official data source: 법제처 Open API (`https://open.law.go.kr`)
 - 이 저장소 안에는 한국 법령 전용 npm package나 python package를 추가하지 않는다.
--- a/scripts/skill-docs.test.js
+++ b/scripts/skill-docs.test.js
@ -1072,7 +1072,8 @@ test("repository docs advertise the korean-law-search skill with mode-specific k
  assert.ok(fs.existsSync(featureDocPath), "expected docs/features/korean-law-search.md to exist");
  assert.match(readme, /\| 한국 법령 검색 \|/);
  assert.match(readme, /\[한국 법령 검색 가이드\]\(docs\/features\/korean-law-search\.md\)/);
-  assert.match(readme, /로컬 CLI\/MCP면 `LAW_OC` 필요, remote endpoint면 불필요/);
+  assert.match(readme, /로컬 CLI\/MCP면 `LAW_OC` 필요, remote endpoint\/법망 fallback은 불필요/);
+  assert.match(readme, /법망 fallback/i);
  assert.match(install, /--skill korean-law-search/);
  assert.match(install, /로컬 CLI\/MCP 경로는 `LAW_OC`/);
  assert.match(install, /remote endpoint는 `LAW_OC` 없이 `url`만/);
@ -1089,10 +1090,11 @@ test("repository docs advertise the korean-law-search skill with mode-specific k
  }

  assert.match(sources, /korean-law-mcp: https:\/\/github\.com\/chrisryugj\/korean-law-mcp/);
+  assert.match(sources, /beopmang: https:\/\/api\.beopmang\.org/);
  assert.match(roadmap, /한국 법령 검색 스킬 출시/);
 });

-test("korean-law-search skill keeps korean-law-mcp-only lookups while separating local LAW_OC setup from remote MCP fallback", () => {
+test("korean-law-search skill keeps korean-law-mcp-first guidance while documenting the approved Beopmang fallback", () => {
  const skillPath = path.join(repoRoot, "korean-law-search", "SKILL.md");
  const featureDoc = read(path.join("docs", "features", "korean-law-search.md"));
  const examplesSecrets = read(path.join("examples", "secrets.env.example"));
@ -1109,7 +1111,7 @@ test("korean-law-search skill keeps korean-law-mcp-only lookups while separating
  const doneSection = doneSectionMatch[1];

  for (const doc of [skill, featureDoc]) {
-    assert.match(doc, /반드시 .*korean-law-mcp|korean-law-mcp.*반드시/u);
+    assert.match(doc, /korean-law-mcp.*먼저|먼저.*korean-law-mcp|항상 `korean-law-mcp`를 먼저 사용/u);
    assert.match(doc, /npm install -g korean-law-mcp/);
    assert.match(doc, /로컬 CLI 또는 로컬 MCP server 경로는 `LAW_OC`/);
    assert.match(doc, /remote MCP endpoint는 사용자 `LAW_OC` 없이 `url`만으로 연결/);
@ -1120,6 +1122,9 @@ test("korean-law-search skill keeps korean-law-mcp-only lookups while separating
    assert.match(doc, /search_interpretations/);
    assert.match(doc, /search_ordinance/);
    assert.match(doc, /https:\/\/korean-law-mcp\.fly\.dev\/mcp/);
+    assert.match(doc, /법망|Beopmang/i);
+    assert.match(doc, /https:\/\/api\.beopmang\.org/);
+    assert.match(doc, /fallback/i);
    assert.match(doc, /MCP/i);
    assert.match(doc, /CLI/i);
    assert.doesNotMatch(doc, /packages\/korean-law-search/);
@ -1128,6 +1133,8 @@ test("korean-law-search skill keeps korean-law-mcp-only lookups while separating

  assert.match(doneSection, /search_interpretations/);
  assert.match(doneSection, /search_ordinance/);
+  assert.match(doneSection, /법망|Beopmang/i);
+  assert.match(doneSection, /fallback/i);

  assert.doesNotMatch(
    featureDoc,