Skip to main content
Glama

FRNC — 프랜차이즈 창업 전 10초 리스크 체크

Franchise, simplified. · KOREA FRANCHISE DISCLOSURE RISK CHECK

프랜차이즈 창업 전에 본부가 제시한 조건(정보공개서 수령 후 경과일, 가맹금 납부 방식, 예상매출 서면, 인테리어 지정, 영업지역, 폐점률, 법 위반 이력 등)을 가맹사업법·시행령 조문과 대조해 위험 신호·확인 체크리스트·질문·근거 조문을 돌려주는 웹·JSON API·MCP 서비스입니다. 계약서·특약 문구를 붙여넣으면 확인이 필요한 문구와 본부에 요청할 수정 문구를 짚어 주는 스캐너도 함께 제공합니다. 표준 라이브러리만 쓰고, 로그인·회원가입· 개인정보 입력이 없습니다.

확정 판정이 아닙니다. 조건 판정은 check_likely(확인 필요 신호 있음) / info_needed(정보 부족) / low_risk(뚜렷한 위험 신호 없음) 세 가지뿐이고, 모든 응답에 면책과 근거 조문이 붙습니다. 문구 스캔은 scan_flagged / scan_no_match / scan_text_needed 세 가지이며, 0건이어도 '안전·문제없음'을 쓰지 않습니다.


1. 무엇을 보나 (핵심 8축)

축

보는 것

근거

숙고기간

정보공개서·계약서를 받은 뒤 14일(자문 시 7일) 전 계약·입금

가맹사업법 제7조③, 제11조①

가맹금

예치기관 예치 또는 피해보상보험계약

제6조의5①, 시행령 제5조의8

매출 정보

예상매출액 산정서·산출근거 서면 교부

제9조③⑤

인테리어

본사 지정 100% 강제(구입강제)

제12조①3, 시행령 별표 2 3.가

영업지역

계약서 기재·계약 중 침해 금지

제12조의4, 제11조②5

폐점률

최근 3년 가맹점 변동(신규·계약종료·계약해지)

제9조①2

법 위반 이력

공정위 시정조치·과징금·형벌선고

제9조①2

해지·갱신

2개월 유예·서면 2회 통지, 갱신 10년 한도

제14조, 제13조

함정 코퍼스 17건(src/franchise_kr/traps.json)이 위 축과 그 밖의 조항(위약금, 필수품목· 판매목표, 필수품목 단가 미공개·차액가맹금 일방 인상, 판매가격 구속·재판매가격 유지, 광고·판촉비, 정보공개서 등록)을 덮습니다. 각 케이스의 law_refs 는 실조회한 조문 키와 1:1로 대조되며, 테스트가 그 대응을 강제합니다.

Related MCP server: 갈피 법령조회 MCP

2. 검증한 것 (추측 금지)

2-1. 법령 — 법제처 OPEN API 실조회

law-verification.json 은 src/tools/verify_law_articles.py 가 법제처 국가법령정보 공동활용 OPEN API(law.go.kr/DRF)로 받은 응답입니다. 조문 텍스트를 손으로 옮겨 적지 않았고, 조문내용·항·호·목 구조를 그대로 보존했습니다.

법령

MST

공포

시행

조문

가맹사업거래의 공정화에 관한 법률

288583

2026-08-04

2026-10-02

77

가맹사업법 시행령

288453

2026-08-04

2026-08-04

64

  • 조문 135개, 별표 17개(불공정거래행위 유형·기준 별표 2 포함) 저장.

  • get_law_article 툴(POST /v1/tools/get_law_article)로 원문을 그대로 조회합니다.

  • OC 인증값은 파일·응답·로그에 남기지 않습니다.

2-2. 공정거래위원회 가맹정보 오픈API — 실호출 결과

src/tools/verify_ftc_apis.py 가 후보 오퍼레이션을 실제로 호출해 응답 코드를 기록합니다. NO_OPENAPI_SERVICE_ERROR(12)는 오퍼레이션 이름이 틀렸다는 뜻이고, SERVICE_KEY_IS_NOT_REGISTERED_ERROR(30)은 이름은 맞지만 이 인증키가 해당 서비스에 등록되지 않았다는 뜻입니다. 2026-11-21 실측(api-verification-2026-11-21.json):

  • 호출 시도 18개 → 승인 4개 · 키 미등록(30) 13개 · 오퍼레이션 미확인(12) 1개

  • 문서 열람형(LINK) 3개(정보공개서 목록·목차·본문)는 REST 오퍼레이션이 공개되어 있지 않음

데이터셋

식별자

오퍼레이션

상태

브랜드 목록

15125467

getBrandinfo

승인

가맹본부 일반 정보

15125450

getjnghdqrtrsGnlinfo2

승인

브랜드 가맹점 및 직영점

15125490

getbrandFrcsDmsstus2

승인

브랜드 가맹점 변경현황

15125491

getbrandFrcsFlctnstus

승인

브랜드별 가맹점 현황(평균매출)

15110241

getBrandFrcsStats

키 미등록

브랜드별 창업 금액

15110265

getBrandFntnStats

키 미등록

인테리어 비용

15125479

getbrandFrcsBzmnIntrrctinfo

키 미등록

가맹금 정보

15125476

getbrandFrcsJnntinfo

키 미등록

부담금 정보

15125475

getbrandFrcsbzmnAlotminfo

키 미등록

예치금 정보

15125480

getbrandFrcsBzmnDepoinfo

키 미등록

가맹본부 법 위반정보

15125463

getjnghdqrtrsLawVioltinfo

키 미등록

법 위반 시정조치

15125464

getjnghdqrtrsCorecActninfo

키 미등록

법 위반 형벌선고

15125466

getjnghdqrtrsPetyAdjuinfo

키 미등록

브랜드 지식재산권

15125471

getbrandIprsinfo

키 미등록

가맹기간

15125484

getbrandFrcsPdinfo

키 미등록

브랜드 비교 목록

15125517

getbrandCompListinfo

키 미등록

가맹본부 일반 변경 이력

15125452

getjnghdqrtrsGnlHist

키 미등록

단위면적당 평균매출

15125494

(오퍼레이션 미확인)

미확인

정보공개서 목록·목차·본문

15125569·15125570·15125571

LINK

문서 열람

아직 등록되지 않은 데이터셋의 활용신청 주소는 https://www.data.go.kr/data/{식별자}/openapi.do 이고, 서버는 신청 상태를 하드코딩하지 않고 응답의 apply_urls 와 /v1/meta 의 data_sources.apply_urls 로 알려 줍니다.

브랜드 색인 — getBrandinfo 에는 이름 검색 파라미터가 없습니다

brandNm 을 붙여도 무시되고 pageNo/numOfRows 로만 훑을 수 있습니다(2026-11-21 실측). 그래서 예전 코드는 1페이지 100건만 뒤져 BBQ·교촌 같은 브랜드를 못 찾았습니다. 지금은 전체 페이지를 받아 색인을 만들고, 조회는 그 색인을 먼저 봅니다.

항목

값

색인 파일

data/brands_index.json.gz (약 2.0MB 압축, 저장소·이미지에 포함)

수집 연도

2026·2025·2024·2023 (연도별 1만 건대, numOfRows=1000 × 11~12페이지)

브랜드 수

44,567건(연도 중복 포함) · 이름·관리번호로 즉시 검색

가맹점 수

승인된 가맹점 및 직영점(15125490) 도 연도별 전체 페이지(연간 18~20만 행)로 받아 40,195행에 합계 저장

갱신

src/tools/sync_brands_index.py + .github/workflows/sync-brands-index.yml (주 1회, 월 05:00 KST)

색인 신선도

45일 이내면 이름 미매칭을 확정으로 보고 실시간 순회를 생략(느린 전체 순회 방지)

PYTHONPATH=src python -m tools.sync_brands_index              # 브랜드 목록 + 가맹점 수(약 4분)
PYTHONPATH=src python -m tools.sync_brands_index --no-stores  # 브랜드 목록만(약 1분)
PYTHONPATH=src python -m tools.sync_brands_index --check       # 네트워크 없이 색인 상태만

조회 순서는 ① 로컬 색인 ② 실시간 API 전체 페이지(색인이 오래됐거나 관리번호로 조회할 때) ③ 내장 샘플 이고, 응답의 data_state(live/sample)와 data_source(index/api/sample)가 근거를 밝힙니다. 색인으로 찾은 브랜드에는 가맹점 수·직영점 수가 바로 붙고(예: BBQ 가맹점 2,316개 · 직영 71개, 2026-11-21 조회), 인증키가 있으면 승인된 가맹점 변경현황(15125491)으로 연간 폐점률(예: 2025년 연초 2,249 → 연말 2,316, 6.6%)까지 붙습니다. 못 찾았을 때는 "그 브랜드가 없다"고 단정하지 않고, 색인 규모·기준연도와 함께 표기 차이· 직영 브랜드 가능성을 안내합니다.

15125490 은 시·도 행과 '전체' 합계 행을 함께 줍니다. 둘을 모두 더하면 가맹점 수가 두 배가 되어(2026-11-21 이전 코드: BBQ 4,632개) 폐점률도 절반으로 깎였습니다. 지금은 '전체' 행이 있으면 그 값만 쓰고, 색인을 만들 때도 같은 규칙으로 합칩니다. 15125491 은 jngBizCrtraYr+brandMnno 를 반드시 요구해(전체 목록 호출은 코드 11) 색인에 넣지 않고 실시간 조회에서만 붙입니다. 그래서 인증키가 없으면 연초·변동·폐점률이 비고, field_status.null 이 그 이유를 적습니다. 가맹점 수는 기준연도 자료의 회계연도(예: 2026년 자료 → 2025년 말) 값이며, 응답의 base_year(기준연도)와 closure_rate_year(회계연도)를 구분해 적습니다.

3. 빠른 실행

cd projects/franchise-kr
PYTHONPATH=src python -m franchise_kr.server          # http://localhost:8787
PYTHONPATH=src python -m franchise_kr.cli check --brand 샘플치킨 --days 0 --payment hq_account
PYTHONPATH=src python -m franchise_kr.cli law "제7조"
PYTHONPATH=src python -m unittest discover -s src/tests -t src/tests   # 413 tests(색인 포함)
PYTHONPATH=src python -m tools.sync_brands_index                        # 브랜드 색인 갱신(키 필요)

의존성 설치 단계가 없습니다(표준 라이브러리만). Python 3.12 기준.

환경변수

.env.example 참고. DATA_GO_KR_SERVICE_KEY 는 선택입니다. 로컬에서는 프로젝트 루트의 .env(gitignore)를 서버·CLI 진입점이 읽고, 없으면 색인만으로 동작합니다(가맹점 수는 색인에, 연초·변동·폐점률은 생략). FRNC_BRANDS_INDEX 로 색인 파일 경로를 바꿀 수 있습니다. LAW_GO_KR_OC 는 law-verification.json 을 다시 만들 때만 씁니다(서버는 쓰지 않음).

운영용(모두 선택):

변수

기본

역할

FRNC_RATE_LIMIT_PER_MINUTE

240

일반 요청 분당 허용(0이면 끔)

FRNC_RATE_WRITE_PER_MINUTE

30

문의 등 쓰기 분당 허용

FRNC_RATE_WINDOW_SECONDS

60

제한 창

FRNC_INQUIRY_WEBHOOK_URL

(없음)

문의 접수 시 POST 알림(Slack·Discord·자체 엔드포인트)

FRNC_INQUIRY_WEBHOOK_CONTACT

꺼짐

1 이면 알림에 연락처도 포함(기본은 미포함)

FRNC_INQUIRY_MIRROR

(없음)

문의 JSONL 미러 파일 — 재시작 시 DB 로 복구

FRNC_ADMIN_TOKEN

(없음)

GET /v1/inquiries 토큰(없으면 그 경로는 404)

검증 자료 재생성

LAW_GO_KR_OC=<OC> PYTHONPATH=src python -m tools.verify_law_articles     # → law-verification.json
DATA_GO_KR_SERVICE_KEY=<키> PYTHONPATH=src python -m tools.verify_ftc_apis  # → api-verification-YYYY-MM-DD.json

3-1. 질문형 가이드 17종 (/guides/) — AI 인용·검색 유입

사람들이 AI·검색에 던지는 질문 하나에 답 하나를 두고, 인용되는 형식으로 만든 페이지입니다.

#

가이드

질문

근거 조문

1

가맹계약 14일 숙고기간

정보공개서를 받은 지 14일이 안 됐는데 계약해도 되나요?

제7조·제11조·시행령 제6조

2

예상매출액 산정서 서면 교부

예상매출액 산정서는 꼭 받아야 하나요?

제9조·시행령 제9조·제8조

3

정보공개서 허위·과장 금지

"최저 수익 보장"이라고 하면 믿어도 되나요?

제9조·시행령 제8조·제6조의2

4

직영점 1년 이상 운영 의무

직영점을 1년 이상 운영해야 하나요?

제6조의3·시행령 제5조의5·제5조

5

가맹금 예치제 의무

가맹금을 본사 계좌로 바로 보내도 되나요?

제6조의5·시행령 제5조의8~10·제15조의2

6

인테리어·집기 구입강제 금지

지정 업체만 써야 하나요?

제12조·시행령 별표 2·제11조·제12조의2

7

과중 위약금·손해배상

중도해지 위약금이 크면 과중한가요?

제12조·시행령 제12조의2·별표 2

8

광고·판촉비 사전 동의

광고비를 걷는데 점주 동의가 필요하나요?

제12조의6·시행령 제13조의5·제13조의6

9

창업 지원금 확인 순서

창업비용을 낸 뒤 지원금은 어떻게 찾나요?

(법령 판단 없음 · GRNT 연결)

10

영업지역 보호·중복 출점

영업지역 안에 본사가 직영점을 내면?

제12조의4·제11조·시행령 제13조의4

11

폐점률·개점률 보는 법

정보공개서의 폐점률은 어떻게 읽나요?

시행령 별표 1·제9조

12

2개월 유예·서면 2회 해지

갑자기 해지하겠다고 하면?

제14조·시행령 제15조

13

계약갱신·10년 한도

계약이 끝나갈 때 갱신을 요구할 수 있나요?

제13조·시행령 제14조

14

가맹점주 단체의 협의 요청

단체를 만들어 조건을 협의할 수 있나요?

제14조의2·제14조의3

15

분쟁조정 신청과 시효

다툼이 생기면 어디에 신청하나요?

제16조·제21조·제22조·제28조·제32조의3

16

필수품목·차액가맹금 확인

필수품목 가격과 차액가맹금은 어떻게 확인하나요?

제11조②12·시행령 별표 1 5.나·6.가·별표 2 2.나·3.가

17

판매가격 구속(재판매가격 유지)

본사가 권장소비자가격을 지키라고 하면 따라야 하나요?

제12조①2·시행령 별표 2 2.가·별표 1 6.라.3

  • 페이지의 모든 숫자(14일·7일·2개월·40%·50%·70%·180일·1.7배·3.3㎡ 등)는 그 가이드가 인용한 조문 안에 실제로 있는지 테스트가 확인합니다(src/tests/test_guides.py). 40% 는 조문의 100분의 40 표기와 대조합니다.

  • /sitemap.xml(19 URL) · /llms.txt(가이드 17종 요약) · 홈 푸터·홈 카드·/v1/meta 의 guides 메타가 모두 같은 목록에서 생성됩니다.

  • 단정 표현 금지: "위법입니다 / 문제없습니다 / 안전합니다 / 무조건" 같은 확정 어구 0건을 src/tests/test_no_definitive_claims.py 가 검사하고, "확정 판정 아님" 문구가 남아 있는지도 봅니다.

색 대비·스크립트 검증

  • src/tests/test_a11y_contrast.py — 라이트/다크 토큰 24쌍의 WCAG 대비를 계산해 4.5:1 이상인지 확인합니다(현재 최저 4.73:1). 토큰만 있고 조합이 어긋나는 경우를 잡습니다.

  • src/tests/test_js_sanity.py — esprima 없이 문자열·주석·정규식 리터럴을 걷어낸 코드로 괄호 균형, 템플릿 문자열 금지, function 형식, id 참조 존재를 검사합니다.

3-2. 특약·계약서 문구 스캔 (scan_contract_text)

계약서·특약·본사 안내 문구를 텍스트로 받아, 가맹사업법·시행령 별표 2의 불공정 유형과 대조해 확인이 필요한 문구만 짚습니다. 결정적 규칙 엔진(정규식 12개 유형)이라 같은 문구는 언제 넣어도 같은 결과가 나옵니다.

#

유형

무엇을 찾나

근거 조문

1

구입강제·지정업체 강제

인테리어·설비·원부자재를 지정업체로만, 타사 제품 금지

제12조·시행령 제13조·별표 2 3.가

2

과중 위약금·손해배상 예정

잔여기간 로열티 전액, 보증금 몰수, 2~3배 배상, 위약금 20% 이상

제12조①5·시행령 제12조의2·별표 2 4.가

3

일방적 즉시 해지

최고·통지·유예기간 없이 즉시 해지

제14조·시행령 제15조

4

영업지역 미보장·인근 출점

영업지역 보장 없음, 본사 판단으로 인근 출점

제12조의4·시행령 제13조의4·제11조

5

숙고기간 포기·동시 입금

14일 숙고기간 포기, 당일 계약, 계약과 동시 입금

제7조③·시행령 제6조·제11조

6

가맹금 본사 직접 수령

본사 계좌 입금, 예치·보험 미이용

제6조의5·제15조의2·시행령 제5조의8

7

광고·판촉비 일방 부담

점주 부담 광고비, 사전 동의 없는 판촉비

제12조의6·시행령 제13조의5·제13조의6

8

매출·수익 보장

월 순수익 보장, 적자 보전, 수익 확실 단정

제9조·시행령 제8조·제9조

9

영업시간 구속·심야 강제

본사가 영업시간 결정, 단축 불허, 24시간 영업

제12조의3·시행령 제13조의3

10

갱신 거절 제한·과도한 경업금지

갱신 거절, 종료 후 장기 경업금지, 10년 초과

제13조·시행령 제14조·제12조

11

필수품목 과다·단가 미공개·차액가맹금 인상

필수품목 단가·산정기준 미기재, 일반 공산품까지 지정, 차액가맹금 일방 인상

제11조②12·시행령 별표 1 5.나·6.가·별표 2 2.나·3.가

12

판매가격 구속·재판매가격 유지

본사가 정한 가격 유지, 할인·변경 금지, 권장가 준수 의무, 가격 위반 제재

제12조①2·시행령 별표 2 2.가·별표 1 6.라.3

  • 항목마다 원문 인용(사용자가 넣은 글자 그대로), 위험 등급, 실조회 조문 발췌, 왜 위험한지, 본부에 요청할 수정 문구 예시가 붙습니다.

  • 0건이어도 "안전/문제없음"을 쓰지 않습니다. 응답에는 항상 고정 문장이 붙습니다: "제시된 패턴에서 잡히지 않았을 뿐, 다른 특약이나 정보공개서 불일치가 있을 수 있어 원문 전체와 가맹거래사 확인이 필요합니다."(engine.SCAN_NOT_A_CLEARANCE_KO)

  • 부정 문장은 세지 않습니다("위약금을 부과하지 않는다" → 신호 아님). 붙여쓰기·줄바꿈 차이는 공백을 지운 사본에서 대조해 흡수하고, 인용은 원문 위치로 되돌려 잘라 냅니다.

  • 웹 홈에는 "특약·계약서 문구 1초 스캔" 카드와 샘플 3종(구입강제·과중 위약금·즉시 해지) 버튼이 있습니다. 붙여넣은 문구는 저장하지 않고, 통계에도 넣지 않습니다.

  • src/tests/test_scan.py 가 규칙·인용·오탐 0건·0건 단정 금지·법 조문 키·조문 앵커 일치를 검사합니다.

  • 판매가격 구속 규칙은 시행령 별표 2 2.가 단서를 그대로 반영해 권장과 사전협의 문구는 신호로 세지 않습니다("권장소비자가격을 알려 주고 참고하게 한다", "가격을 바꿀 때 사전에 협의한다"). 본부가 정한 가격 유지·할인 금지·권장가 준수 의무·가격 위반 제재만 짚습니다.

  • 필수품목 규칙은 단가·산정기준 미기재, 일반 공산품까지 지정, 차액가맹금 일방 인상만 짚습니다. 품목별 공급가격과 산정기준을 별지에 적고 변경 시 통지하는 정상 문구는 세지 않습니다 (NORMAL_CLAUSES 로 고정).

한계: 정규식 규칙은 표시된 패턴만 찾습니다. 문장의 맥락, 예외 조항, 별지 특약 전체의 해석은 하지 않으며, 위법 여부 판정·계약서 검토가 아닙니다.

4. API · MCP

툴 7종

툴

하는 일

check_franchise_risk

조건 → 위험 신호·판정·질문·체크리스트·법 조문·GRNT 연결

scan_contract_text

계약서·특약 문구 → 확인 필요 문구·원문 인용·근거 조문·수정 요청 문구

lookup_brand_disclosure

브랜드 1건 요약 — 승인된 데이터셋이 주는 값만(브랜드 목록·가맹점 및 직영점·변경현황, data_source 로 근거 표시), 비어 있는 필드는 field_status.null 이 이유·신청 주소를 밝힘

compare_franchise_terms

두 프랜차이즈 조건 비교(비용·절차·위험 신호)

list_risk_cases

함정 코퍼스 17건(위험도·분류·키워드 필터, 조문 대조 여부)

get_law_article

실조회한 가맹사업법·시행령 조문 원문

get_service_meta

판정 등급·8축·법령·API 승인 상태·개인정보 설계

REST

curl -s http://localhost:8787/v1/tools/check_franchise_risk -H 'Content-Type: application/json' -d '{
  "brand_name": "샘플치킨", "industry": "치킨",
  "franchise_fee_krw": "1,100만원", "interior_krw": "5,500만원",
  "disclosure_days_before": 0, "payment_route": "hq_account",
  "revenue_claim_ko": "월 5천 보장", "revenue_written": false
}'

응답에는 verdict, risk_score, risk_points(이유·되돌리기 어려운 점·할 일·물어볼 것·조문), unknown_points, questions_ko, checklist_ko, money, law_basis, next_steps, startup_support(GRNT 링크), disclaimer_ko 가 들어 있습니다.

  • GET /healthz · /v1/meta · /v1/stats · /v1/mcp · /llms.txt · /sitemap.xml

  • POST /v1/tools/{tool} · POST /v1/inquiry(문의) · GET /v1/inquiries(문의 조회, X-Admin-Token 필요)

  • 문의(/v1/inquiry)는 contact·topic·message 외에 선택 필드 cohort(별칭 source)를 받습니다 — 무료 베타·소개 글 유입 구분 태그(beta_pilot, citechart 등 영문 소문자·숫자와 ._:-, 40자). 없으면 종전과 동일하게 동작하고, 있으면 inquiries.cohortㆍ미러 JSONLㆍ웹훅ㆍ/v1/inquiries 요약(by_cohort)에 남습니다. 공개 /v1/stats·/healthz 에는 넣지 않습니다. 웹 문의 폼도 /?cohort=beta_pilot 처럼 태그가 붙은 링크로 들어오면 그 값을 함께 보냅니다 (형식이 틀리면 보내지 않음).

  • 요청 제한: 넘으면 429 + Retry-After(기본 분당 240회, 문의 분당 30회, /healthz 예외). IP 는 저장하지 않고 프로세스 난수로 해시한 메모리 키만 씁니다(재배포 시 초기화).

  • 웹 UI GET / — 첫 화면은 브랜드명(또는 업종) 입력 1칸 + [리스크 확인하기] 버튼 + 예시 3개뿐이고, 금액·계약 조건 30여 항목과 원클릭 프리셋 4개(당일 계약·본사 송금 / 구두 매출 보장 / 인테리어 100% 강제 / 정상 조건)는 상세 조건 입력(기본 접힘) 안에 있습니다. 결과는 위에서부터 종합 신호 카드 → 핵심 지표 4개(초기 투자비용·폐점률·법적 분쟁·체크할 질문) → 확인할 신호 → 물어볼 질문 순서이고, 모르는 항목은 결과 자리에서 한 번에 답하는 질문 3개로 돌려줍니다. 근거 조문·체크리스트·비용 구조는 자세히 보기 에 접었습니다. 특약·계약서 문구 1초 스캔 카드(샘플 3종), 결과 요약 복사, 비식별 공유 링크 복사(/?brand=...#check 프리필), 다크 모드, 모바일 반응형. 공유 링크에는 브랜드명만 담고 금액·조건·연락처는 담지 않습니다.

  • 없는 주소(비-/v1/)는 JSON 이 아니라 사람용 404 안내 페이지를 돌려줍니다(다음에 할 일 링크).

  • 질문형 가이드 GET /guides/ · GET /guides/{slug} — 17종. 각 페이지는 한 줄 답, 법이 정한 기준, 계약 전 체크포인트, 흔한 오해, FAQ, 근거 조문 원문을 담고 FAQPage·BreadcrumbList· WebPage JSON-LD 를 포함합니다. /guides 는 /guides/ 로 301.

MCP

  • Streamable HTTP: POST /mcp (JSON-RPC 2.0, application/json 한 덩어리, SSE 없음)

  • stdio: PYTHONPATH=src python -m franchise_kr.mcp_stdio

  • 서버 카드: GET /.well-known/mcp/server-card.json

  • 인증 없음. initialize → tools/list → tools/call.

5. 개인정보·익명성

  • 판정 폼은 이름·연락처·주민등록번호를 받지 않습니다. 브랜드명·금액·조건은 요청 처리 중에만 쓰고 저장하지 않습니다.

  • 익명 카운터는 날짜 · 경로 · 툴 · 판정 등급 · 샘플/0건/오류 횟수만 남깁니다. 금액·조건 입력은 통계에도 저장하지 않습니다.

  • 예외 하나: 결과가 0건으로 끝난 브랜드 조회어만 개인식별 요소(전화번호·주민등록번호· 이메일·URL·@핸들·2자리 이상 숫자)를 지운 뒤 최대 30자로 /v1/stats 의 zero_result_queries 에 익명 카운트합니다(usage.sanitize_query). 0건은 "그 브랜드가 없다"도 "안전하다"도 아니며, 응답에는 고정 안내(live_api.ZERO_RESULT_NOTICE_KO)가 붙습니다.

  • 유일한 예외는 하단 문의 카드에 이용자가 직접 적은 연락처로, 회신 목적으로만 별도 표에 두고 응답에 되비추지 않으며 180일 뒤 지웁니다.

  • 무료 플랜은 영구 디스크가 없어 재시작 때 DB 가 초기화됩니다. 그래서 문의는 접수 성공 직후 ① 웹훅(FRNC_INQUIRY_WEBHOOK_URL) ② JSONL 미러(FRNC_INQUIRY_MIRROR)를 남길 수 있고, 미러가 있으면 서버가 다시 뜰 때 notify.restore() 가 SQLite 로 되돌려 놓습니다. 기본 웹훅 본문에는 연락처를 넣지 않고(접수번호·유형·미리보기만) 채널에 개인정보가 남지 않게 하며, 관리자 조회(GET /v1/inquiries, 토큰)에서만 연락처를 돌려줍니다.

  • 요청 제한은 IP 를 저장하지 않습니다 — 프로세스가 시작할 때 만든 난수로 해시한 메모리 키만 쓰고 창이 지나면 지웁니다. 막힌 요청은 /v1/stats 의 flags.rate_limited 횟수로만 남습니다.

  • 저장소에는 실명·연락처·직업·계정 같은 개인정보를 두지 않습니다. src/tests/test_privacy.py 가 휴대전화·주민등록번호·이메일·카드번호·인증키 패턴을 검사하고, 로컬 전용 .private-terms(gitignore·dockerignore 대상)가 있으면 그 문자열까지 확인합니다.

6. 배포

  • Dockerfile: python:3.12-slim, 비루트 사용자, HEALTHCHECK /healthz, 표준 라이브러리만

  • render.yaml: Render Blueprint(도커, free, singapore, /healthz) — 서비스 이름 frnc, 공개 주소 https://frnc.onrender.com. DATA_GO_KR_SERVICE_KEY 는 sync: false(대시보드에서 입력). 문의를 오래 보관하려면 유료 영구 디스크를 붙이고 FRNC_INQUIRY_MIRROR(예: /var/data/inquiries.jsonl)와 FRNC_ADMIN_TOKEN 을 함께 설정하세요(free 플랜은 재시작 때 DB 가 바뀝니다).

  • server.json: MCP 레지스트리 매니페스트(io.github.CLNS-KR/frnc, v0.1.12, 설명 100자 이하)

  • 고지 페이지(v0.1.9): GET /privacy · GET /terms · GET /about — 문의 연락처 180일 보관·삭제 요청 경로, 확정 판정 아님·전문가 자문 대체 아님, 공정위 정보공개서 출처와 3종 생태계 안내. 홈·가이드 푸터와 sitemap.xml 에서 이어집니다

  • 공유 카드(v0.1.9): /static/og.png(1200×630) + 홈·가이드·고지 페이지의 canonical·og:image 메타(파일이 없어도 표준 라이브러리 생성 PNG 로 200 유지)

  • 사용 통계 구분(v0.1.9): /v1/stats 의 traffic.by_channel·traffic.by_client — UA 원문·IP·쿠키는 저장하지 않습니다

  • AI 검색 구조화 데이터(v0.1.10): 홈에 Organization·WebSite(SearchAction ?brand=)·WebApplication 을 @graph 로 묶어 @id 로 연결했습니다(종전에는 홈에 구조화 데이터가 없었습니다). robots.txt 에 OAI-SearchBot·Claude-SearchBot·Google-Extended·CCBot·Applebot-Extended·Bingbot 을 더하고, llms.txt 에 '구조화 데이터(JSON-LD)' 안내를 넣었습니다

  • 가이드 푸터 고지 링크(v0.1.11): 검색으로 /guides/* 에 바로 들어온 사람이 홈까지 돌아가지 않아도 /privacy·/terms·/about 으로 이어지도록 가이드 페이지 푸터에 세 링크를 넣었습니다(자매 서비스 CLNS·GRNT 링크는 그대로)

  • 첫 화면 단순화(v0.1.12): "가독성이 떨어지고 선택할 게 많고 어디를 봐야 할지 모르겠다"는 피드백에 따라 홈을 다시 짰습니다. (1) 첫 화면에서 데이터 상태 배너·전문용어·30여 개 입력칸을 걷어내고 입력 1칸·버튼 1개·예시 3개만 남겼습니다(브랜드 조회 카드는 검색창 하나로 통합 — /#brand-card 앵커는 유지). (2) 결과 맨 위에 종합 신호 카드(주의 신호 N건 / 아직 판단하기 이르다 / 뚜렷한 위험 신호 없음)를 두고, 그 아래 초기 투자비용·폐점률·법적 분쟁·체크할 질문 네 칸을 놓았습니다. (3) 모르는 항목은 결과 자리에서 예/아니오로 답하는 질문 3개로 되물어 바로 다시 판정합니다. (4) 근거 조문·체크리스트·비용 구조·다음 단계는 자세히 보기 로 접었습니다. API·MCP·자매 서비스·데이터 상태 안내는 모두 아래로 내렸습니다

  • .github/workflows/publish-mcp-registry.yml: v* 태그 push(또는 수동 실행) 때 mcp-publisher 로 공식 레지스트리에 게시합니다. GitHub Actions OIDC 로 인증해 조직 네임스페이스를 쓰고, 게시 전에 단위 테스트·server.json 버전 대조·원격 /mcp 생존 확인을 거칩니다(원격 서버가 내려가 있으면 게시도 실패 — 의도된 동작).

7. 한계 (정직하게)

  1. 확정 판정이 아니다. 입력한 조건과 공개 조문의 대조일 뿐, 위법 여부·계약 효력을 판단하지 않습니다. 계약서 검토·법률 자문·신고 대행을 하지 않습니다.

  2. 브랜드 조회는 승인된 데이터셋(18개 중 4개)으로 답합니다. 브랜드명·본부·업종·가맹사업 개시일은 색인(승인 15125467)에서, 가맹점 수·직영점 수는 승인된 15125490 에서(시·도 행과 '전체' 행 중 '전체' 값 — 더하지 않습니다), 연초·신규·계약종료·계약해지·연간 폐점률은 승인된 15125491 에서 실시간으로 옵니다. 평균매출(15110241)·창업비용·법 위반 이력은 아직 미승인이라 값이 null 이며, 응답의 field_status.null 이 항목별 사유·데이터셋 번호· 신청 주소를 밝힙니다(null 은 '0'도 '없음·문제없음'도 아닙니다). 정보공개서 등록번호·등록일은 가맹정보 데이터셋에 없어 항상 비어 있습니다. 서버에 인증키가 없으면 색인만으로 답하고(data_state=live, 가맹점 수는 색인 값), 비는 항목의 이유를 field_status 에 "인증키가 없어 실시간 재조회를 하지 않았습니다"로 적습니다. 응답 봉투가 문서와 다르면 unexpected_shape 로 남기고 0건으로 단정하지 않습니다.

  3. 정보공개서 목록·목차·본문(15125569·15125570·15125571)은 data.go.kr 제공형태가 LINK라 REST 로 부를 수 없습니다. 본문은 가맹사업정보제공시스템에서 열람해야 합니다.

  4. 단위면적당 평균매출(15125494)은 오퍼레이션 이름을 확인하지 못해 unverified 로 남겼습니다.

  5. 폐점률은 기준연도 1년 변동입니다(연초 = 자료가 없으면 연말 - 신규 + 종료 + 해지). '최근 3년' 통계가 아니며, 3년치를 모르는 값을 그렇게 부르지 않습니다 — 응답은 closure_rate_pct·closure_rate_year·closure_rate_basis_ko 로 근거를 함께 줍니다. 색인의 브랜드 수는 연도별 목록을 합친 값이라 실제 브랜드 수와 다릅니다(중복 포함).

  6. 문구 스캔은 정규식 규칙이 표시된 패턴만 찾습니다. 잡히지 않은 문구를 '적법'으로, 잡힌 문구를 '위법'으로 단정하지 않습니다. 문장 구조를 해석하는 모델이 아니라, 사람이 확인할 목록을 빠짐없이 같은 기준으로 만들어 주는 도구입니다.

8. 출처

  • 법령: 법제처 국가법령정보 공동활용 OPEN API (law.go.kr/DRF)

  • 가맹정보: 공정거래위원회 가맹정보 오픈API (apis.data.go.kr/1130000, data.go.kr)

  • 정보공개서 원문: 가맹사업정보제공시스템 (franchise.ftc.go.kr)

  • 창업 지원금: GRNT (https://grnt-kr.onrender.com/)

  • 같이 쓰는 도구: 수입·유통 규제 체크 CLNS (https://clns-kr.onrender.com/)

MIT License.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Integrates Korean startup laws (19 curated laws) and K-Startup support programs, enabling legal article search, citation verification, reference tracking, and program lookup with real-time status.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search and retrieve Korean laws, regulations, administrative rules, legal interpretations, and precedents via official APIs for legal review workflows.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants and terminals to retrieve and cross-reference Korean legal sources through 10 tools built on 42 Ministry of Government Legislation APIs, covering statutes, precedents, administrative rules, ordinances, treaties, and interpretations. Adds hallucination-resistant citation verification, article impact graphs, point-in-time diffing of in-force versions, case citator checks, and applicable-law-at-the-time analysis.
      10
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Korean tax, accounting, and finance professionals to pull statute text, delegated enforcement decrees and rules, NTS rulings, and annexes in a single lookup, and to check whether every statute or article citation in an AI draft actually exists (±verified, missing, or unverifiable), with statutory-formula calculations for items like executive severance limits and entertainment-expense caps.
      7
      MIT