갈피 법령조회 MCP

갈피는 법령검토에 필요한 법령·자치법규·행정규칙·법령해석례·판례를 Codex, Claude, ChatGPT가 실시간 조회하게 만드는 읽기 전용 MCP 서버다. 챗봇이나 정적 웹사이트가 아니다.

설계 방향

갈피의 제품 방향은 "자유 질문에 답하는 챗봇"이 아니라 "목적형 법령검토 워크플로 엔진"이다. 사용자는 먼저 감사, 계약, 법제, 인허가, 예산, 정보공개 같은 검토 목적을 고르고, 갈피는 목적별 절차에 따라 원문 조회, 증거 기록, 검증 게이트, 실무 서식 출력을 순서대로 수행한다.

첫 MVP는 7개 관점을 얕게 펼치지 않고 감사 대비 점검 엔진을 깊게 구현한다. 입력 문서에서 인용 법령과 조문을 추출하고, 공식 원문 API로 실재성·내용 일치성·기준일 현행성을 검증한 뒤, 검증된 근거만 감사 지적 가능 항목, 근거 조문 확인표, 보완 조치, 추가 조회 필요 항목으로 분리한다.

공개 배포는 GitHub Pages를 기본 채널로 둔다. 저장소에는 OC, 토큰, 개인정보를 넣지 않고, Pages 번들은 설치 없는 체험판과 설계 원칙만 제공한다. 실제 법령 조회가 필요한 배포는 무상태 릴레이 또는 HTTPS MCP 엔드포인트에서 비밀값을 서버 측 환경변수로 읽어야 한다.

GitHub Pages 첫 화면 index.html은 실측 질문·답변 예시로 갈피를 소개하는 페이지이고, 감사 점검 엔진 체험판은 outputs/galpi-purpose-tool.html에 있다. 설치와 사용법의 기준 문서는 이 README다.

성능 벤치마크

갈피와 평가일 현재 공개된 한국 법령 MCP 2종을 동일한 조건에서 비교했다. Codex CLI의 gpt-5.5, reasoning high, 기준일 2026-07-20을 고정하고, 35문항을 제품별 3회씩 독립 실행했다. 전체 표본은 315개 답변이며 문항마다 새 세션을 사용했다.

최종답변 품질은 비교군 A가 1.99점 높았다. 갈피는 기본조회 A레인과 자치법규 정합성 G레인에서 1위였고, 호출 오류율은 1.1%로 가장 안정적이었다. 감사·계약심사처럼 신뢰성이 중요한 업무에서는 최종답변 점수뿐 아니라 반복 호출 안정성과 확인 불가 처리도 함께 봐야 한다.

비교 대상은 특정 프로젝트의 서열화가 아닌 갈피의 품질 검증을 위해 익명 처리했다. 비교군 A는 정확도 우세형, 비교군 B는 경량 조회형 공개 MCP다. 점수는 동일 모델·질문·환경에서 수행한 자체 실험 결과이며 모델, 네트워크 및 법제처 API 상태에 따라 달라질 수 있다.

• 전체 문항별 점수·표준편차·용도별 판정

• 기계 판독용 상세 점수

• 315개 실행 무결성 감사

• 레인별 공식 원문 표본검증

• 재현 방법과 고정 버전

평가는 제품명을 가린 뒤 문항별 9개 답변을 블라인드 채점했고, 평가자 외부 도구 호출·실행 타임아웃·프로토콜 위반·OC 노출은 모두 0건이었다. 원시 실행 로그와 실제 비교 대상 대응표는 개인정보·비밀값, 공정한 익명 비교 및 저장소 용량 관리를 위해 배포본에서 제외한다.

처음 시작

Node.js 20 이상만 설치되어 있으면 된다.

git clone https://github.com/uscaidev/galpi-korean-law-mcp.git
cd <복제된_폴더>
npm run setup

setup은 처음부터 다음 순서로 진행한다.

1. 필요한 파일과 Node.js 버전을 확인한다.

2. 패키지나 빌드 파일이 없으면 자동으로 만든다.

3. 법제처 OPEN API OC가 있는지 먼저 묻는다.

4. OC가 없으면 가입·8개 API 선택 절차를 안내하고 멈춘다.

5. OC가 있으면 Git에서 제외된 .galpi/config.json에 저장한다.

6. 법령·자치법규·행정규칙·법령해석례의 필수 목록·본문 8개와 선택 판례 2개를 구분해 실시간 검증한다.

7. Codex와 Claude용 갈피 스킬을 설치한다.

8. 설치된 Codex·Claude Code CLI를 찾아 MCP 자동 등록 여부를 묻는다.

9. ChatGPT는 원격 연결 절차를 안내한다.

OC, 비밀번호, 전화번호, 인증번호는 Git에 저장하지 않는다.

AI에게 GitHub 주소만 줄 때

다음처럼 요청하면 된다.

이 GitHub 저장소를 지속적으로 사용할 폴더에 clone하고 설치해줘.
먼저 법제처 OPEN API OC가 있는지 물어보고, 없으면 신청 가이드를 보여줘.
있으면 npm run setup으로 API와 MCP를 검증하고 현재 사용 중인 AI 도구에 연결해줘.

저장소의 AGENTS.md와 CLAUDE.md가 Codex·Claude에게 같은 초기 절차를 알려준다. 설치 뒤에는 galpi-law 스킬이 법령조회와 장애 진단 절차를 자동으로 제공한다.

OC가 없을 때

npm run guide

법제처 OPEN API 가입·신청 가이드를 따라 다음 JSON 8개를 선택한다.

• 법령 목록·본문

• 자치법규 목록·본문

• 행정규칙 목록·본문

• 법령해석례 목록·본문

신청 뒤 npm run setup을 다시 실행한다.

판례 사건번호 검색도 사용할 경우 판례 목록·본문 JSON 2개를 추가 신청한다. 판례 권한이 없어도 기본 8개 기능은 설치된다.

상태 확인과 복구

npm run doctor
npm run doctor -- --live
npm run guide

doctor는 Node.js, 패키지, 빌드, OC, 스킬 원본, Codex·Claude 설치 여부를 확인한다. --live는 실제 법제처 목록·본문까지 호출한다.

파일이 없거나 자동 등록이 실패하면 examples/mcp의 실행 가능한 샘플을 사용한다.

클라이언트 연결

Codex와 Claude Code

npm run setup이 CLI를 발견하면 자동 등록을 제안한다. OC는 클라이언트 설정에 복사하지 않고 scripts/run-stdio.mjs가 로컬 설정에서 읽는다.

수동 등록:

codex mcp add galpi-law -- node "<REPO>\scripts\run-stdio.mjs"
claude mcp add galpi-law --scope user -- node "<REPO>\scripts\run-stdio.mjs"

Claude Desktop

claude-desktop.json의 절대 경로를 바꿔 MCP 설정에 추가한다.

ChatGPT

ChatGPT는 로컬 stdio MCP에 직접 연결하지 않는다.

1. 이 서버를 HTTPS의 /mcp 주소로 배포하거나 Secure MCP Tunnel을 사용한다.

2. Settings > Apps > Advanced Settings에서 Developer mode를 켠다.

3. Settings > Apps > Create 또는 워크스페이스 Apps > Create에서 원격 주소를 입력한다.

4. Scan Tools에서 갈피 도구 9개를 확인한다.

상세 체크리스트는 chatgpt-checklist.md에 있다. 제공 범위와 게시 권한은 ChatGPT 요금제와 워크스페이스 정책에 따라 다르다.

제공 도구

본문 식별자는 다음처럼 고정한다.

자치법규ID와 법령해석례의 안건번호는 본문 식별자로 쓰지 않는다.

검색 결과의 resolution이 ambiguous면 첫 결과를 자동 선택하지 않는다. 본문 결과의 truncated=true 또는 verificationStatus=incomplete는 반환 범위가 잘렸다는 뜻이므로, 해당 조문이 없다고 판단할 수 없다. 이때는 korean_law_get_provision을 사용한다.

증빙 메타데이터는 다음 네 축을 분리한다.

판례 공식 DB의 not_found는 판례 자체의 부존재가 아니라 공식 DB 미검색을 뜻한다. 하급심·미수록 가능성을 별도로 확인해야 한다.

HWPX는 ZIP+XML을 직접 읽어 인용을 추출한다. 인용 추출 결과의 contentMatch=not_assessed는 인용된 주장과 원문 의미를 아직 대조하지 않았다는 뜻이다.

PDF 처리 경계

갈피 코어는 PDF 파일·Base64·페이지 이미지를 직접 받지 않으며 PDF 파서, OCR, 비전 모델을 포함하지 않는다. PDF는 Codex, Claude, ChatGPT 등 사용 중인 클라이언트가 읽고 추출한 텍스트만 korean_law_extract_citations.text로 전달한다.

이 경계는 의도된 설계다. PDF 판독 품질은 문서 구조·스캔 상태·OCR·사용 모델에 따라 달라지므로 갈피가 그 결과를 공식 원문처럼 보증하지 않는다. 갈피의 책임은 전달받은 텍스트에서 인용 후보를 뽑고, 법령 API 원문과 실재성·현행성·주소를 검증하는 데서 시작한다. 텍스트가 불완전하거나 조문번호가 모호하면 추정하지 않고 원문 재확인을 요구한다.

검증 기반 학습

갈피는 사용할 때마다 검색 내용이나 법률 사안을 저장하지 않는다. 도구별 성공·실패 횟수와 마지막 사용 시각만 .galpi/runtime-learning.json에 기록한다.

재사용할 기술적 발견이 있을 때만 후보를 남긴다.

npm run learn -- --kind schema --target ordin --summary "관찰 내용" --evidence "개인정보 없는 재현 근거"
npm run evolve

evolve는 8개 실시간 API가 모두 통과해야 설치된 Codex·Claude 스킬의 로컬 검증 정보를 갱신한다. 후보 내용은 자동으로 기준 지식에 합치지 않는다.

HTTP 서버와 배포

npm run start:http

• MCP: http://127.0.0.1:8787/mcp

• 상태: http://127.0.0.1:8787/health

외부 바인딩에는 HOST, PORT, MCP_BEARER_TOKEN을 설정한다. Docker 배포 파일도 포함되어 있다. 다중 사용자 공개 배포에는 OAuth 또는 인증 프록시, TLS, 요청 제한, 비밀 저장소를 사용한다.

개발

npm run check
npm run benchmark

benchmark는 로컬 OC로 실시간 회귀 문항을 실행한다. 가지조문, 항 단위, 판례 정확검색, 약칭, 대형 법령 절단, 기준일 연혁을 표와 점수로 출력한다.

주요 구조:

scripts/galpi.mjs            설치·진단·가이드·학습 CLI
scripts/run-stdio.mjs        OC를 노출하지 않는 MCP 실행기
skills/galpi-law/            배포용 표준 스킬 원본
.agents/skills/galpi-law/    Codex 저장소 자동발견 사본
src/                         API 코어와 MCP 서버
examples/mcp/                파일이 없을 때 사용할 샘플
onboarding/                  법제처 가입·신청 가이드

모든 법령 결과는 검토 보조 자료다. 최종 판단 전에 국가법령정보센터 원문과 현행성을 다시 확인한다.

라이선스

MIT