PR MCP Builder

최신 Kordoc 4.24.1 연동과 설치 도구를 반영했습니다(2026년 10월 23일 확인). 홍보 영상은 기능 소개이며, 아래 영상은 실제 앱의 클릭 과정을 녹화한 시연입니다. 홍보 영상 속 규정과 질문은 가상 예시입니다. AI 검수 의견 장면만 합성 규정에 실제 gpt-4.1-mini 검수를 돌린 결과입니다.

프로그램에서 Vercel 배포까지

④ 화면에서 파일 준비 → Vercel 계정 연결 → 배포 → URL 복사까지 진행합니다. 배포에는 AI 모델이나 AI API 키가 필요하지 않습니다.

1. ① 문서 올려서 전처리 후 ③ 검수하고 승인에서 사용할 규정을 승인·색인합니다. 여러 규정은 화면 위의 선택한 규정 전체 승인·색인으로 진행합니다. 같은 자리에서 범위와 주의사항을 확인한 뒤 실행합니다. AI 추가 검수를 켠 문서는 ② 결과도 확인합니다.
2. 사용할 AI를 ChatGPT·Claude·Codex에 MCP로 연결로 선택하고 ④로 갑니다.
3. 규정 범위를 확인하고 ChatGPT · Vercel HTTPS MCP 또는 Claude · Vercel HTTPS MCP를 선택합니다. MCP 이름을 입력하고 MCP로 쓸 파일 묶음 만들기를 누릅니다.
4. Vercel 계정 연결을 누릅니다. 처음에는 브라우저에서 로그인·승인합니다. Node.js가 필요하며 배포 도구가 없으면 화면에서 설치할 수 있습니다.
5. 새 프로젝트 또는 기존 주소 업데이트를 선택하고 이 규정을 인터넷에 공개해도 됩니다에 동의한 뒤 Vercel에 배포하고 연결 검사를 누릅니다.
6. 배포·검색 검사 완료가 나오면 표시된 https://…/mcp 주소를 복사해 AI 앱에 등록합니다. 새 대화에서 search와 fetch를 호출해 원문과 출처를 확인합니다.

저장 폴더·전달용 ZIP·수동 명령은 고급 메뉴에 있습니다. 첫 배포 전에 URL을 입력하거나, 배포 후 URL을 넣기 위해 파일 묶음을 다시 만들 필요가 없습니다.

MCP 이름을 입력하거나 추천 이름 사용을 누른 뒤 바로 파일 묶음을 만들 수 있습니다. 준비가 덜 된 항목은 생성 버튼 바로 위에 표시됩니다. 이전 ZIP 설정 때문에 막히면 ZIP 없이 계속하기 · Vercel 배포용 폴더 사용을 누르세요. 검토·승인·색인과 표 파싱 품질 확인을 마친 규정만 생성됩니다. MCP를 선택한 경우 이동 버튼과 현재 위치에도 ④ MCP 생성·외부 AI 연결이 표시됩니다.

공개 MCP는 URL을 아는 누구나 로그인 없이 조회할 수 있습니다. 공개 목록은 만들지 않고 검색엔진에 색인 제외를 요청하지만, URL 자체가 비밀번호나 접근 제한은 아닙니다. 기관 내부·비공개 규정은 인증 배포 안내를 따르세요.

화면은 합성 계정·프로젝트를 사용한 브라우저 검증 캡처입니다. 외부 배포 성공의 증거는 별도 실제 서버의 프로토콜 검사로 확인합니다.

최근 업데이트 · 2026-10-24

MCP 파일 묶음을 만들 때 도구 설계 규칙을 코드로 검사하는 최종 빌드 QA 게이트를 추가했습니다.

• 최종 빌드 QA 게이트: ④ 화면에서 MCP로 쓸 파일 묶음 만들기를 누르면 연결 파일을 만든 뒤, ZIP 압축 전에 scripts/mcp_build_qa_gate.py가 실행됩니다. 차단 항목이 하나라도 있으면 묶음을 완료로 표시하지 않고 차단 코드를 화면에 표시합니다. 같은 검사는 python scripts\mcp_build_qa_gate.py --bundle-dir <묶음 폴더>로도 실행합니다.
• 도구 수와 설명 토큰 상한: full·chatgpt-data 프로필마다 도구 수와 도구 설명 토큰 추정치를 계산합니다. 지금 값보다 늘어나면 차단하고, 설계 목표(도구 12개, 4,000토큰)에 못 미치는 항목은 보고서에 기록합니다.
• 도구 체이닝 검사: ID를 입력받는 도구의 설명에 그 ID를 주는 도구 이름이 없으면 차단합니다. 실제 묶음 데이터로 규정 목록, 목차, 조문, 검색, 원문 조회를 차례로 호출하고 0건이 나오면 차단합니다.
• 조문 번호 입력 보완: 목차에 표시되는 제1조 목적, 인용형 제1조(목적), 숫자 1로 조문을 조회하면 0건이 나오던 문제를 고쳤습니다. 정확히 일치하는 조문이 없을 때만 제1조 형태로 바꿔 다시 찾습니다.
• 입력·응답 보안 검사: 문자열 입력의 길이 상한, 도구의 읽기 전용 표시, 다른 기관 profile 요청 거부, 응답 속 로컬 경로와 토큰 형태 값을 검사합니다. 길이 상한이 없던 as_of_date 입력 9곳에 32자 상한을 추가했습니다.
• 윤문 게이트: 묶음의 README.md, README.ko.md, MCP 사용 시작하기.txt와 도구 설명에서 줄표, 문장 속 화살표, 챗봇 말투, 과장 어휘 같은 표현을 찾으면 차단합니다. 생성 안내문은 검사 끄기 표시로 검사를 끌 수 없습니다. 다른 문서는 scripts/korean_polish_gate.py로 따로 검사합니다.
• 소형 모델 체이닝 검사(선택): --model을 주면 로컬 Ollama 모델이 MCP 서버 없이 도구를 이어서 호출하는지 평가합니다. 근거가 있는데 "없다"고 답한 비율, 잘못된 도구 호출 비율, 문맥 토큰을 기록합니다. 도구 호출 기능이 약한 모델은 --tool-call-mode json으로 검사합니다.

변경 전 소스에 같은 게이트를 실행하면 차단 25건이었고, 수정 후에는 0건입니다.

차단 항목	변경 전	변경 후
입력 길이 상한 없음(as_of_date)	9	0
ID를 주는 도구 이름이 설명에 없음	9	0
서버 안내문에 빠진 도구(list_documents)	1	0
목차·인용형·숫자 조문 번호 조회 0건	6	0

아직 설계 목표에 못 미치는 항목이 있습니다.

• full 프로필 도구는 16개(목표 12개)이고 도구 설명은 약 4,580토큰(목표 4,000)입니다. ID 출처 안내와 입력 길이 상한을 넣으면서 4,464토큰에서 116토큰 늘었습니다.
• full search 설명은 566자(목표 400자)이고, 입력 수는 search 7개, lookup 8개(목표 6개)입니다.
• 소형 모델 체이닝 검사는 가짜 모델 응답으로만 확인했습니다. 실제 모델로 실행한 결과는 아직 없습니다.

적용 방법: 수정된 소스로 앱을 다시 실행하고 MCP 파일 묶음을 다시 만들면 게이트가 적용됩니다. 승인·색인 데이터는 바뀌지 않습니다. 검사 기준은 MCP 최종 빌드 QA 게이트를 참고하세요.

검증(2026-10-24): MCP·패키징·문서 테스트 1,083개 중 1개(sdist 문서 목록)가 처음 실패해 수정한 뒤 다시 통과했고, Streamlit 화면 테스트 355개는 모두 통과했습니다. 전체 테스트는 실행하지 않았습니다. sdist/wheel 빌드와 공개 소스 위생 검사(--include-untracked --include-source-path-scan)는 통과했습니다.

이전 업데이트 · 2026-10-23

로컬 LLM 답변의 사실 확인 방식을 바꾸고, 실제 규정으로 답변 품질을 측정하는 도구를 추가했습니다.

• 주장 감사를 문장 단위로 변경: 이전 감사기는 답변 전체가 맞는지를 근거 검토보다 먼저 판정하는 구조였습니다. Ollama 구조화 출력은 필수 칸을 정해진 순서대로 채우기 때문에 감사 모델이 근거를 보기 전에 판정부터 썼고, 근거와 일치하는 실제 답변 초안 24개를 모두 거절했습니다. 이제 서버가 답변을 문장으로 나누고, 감사 모델은 문장마다 서버가 고정한 근거 구간 ID를 고른 뒤 지지 여부를 판정합니다.
• 모델 없이 확인하는 관문 추가: 감사 모델을 부르기 전에 답변의 숫자와 조문 번호가 인용한 근거에 있는지, 문장의 명사가 근거에 60% 이상 있는지 확인합니다. 하나라도 어긋나거나 감사 모델이 지지하지 않은 문장이 있으면 모델 답변 대신 승인 근거 발췌 답변을 보여 줍니다.
• 실제 규정 회귀 실행기: scripts/run_real_regulation_e2e.py가 실제 PDF 재전처리, 승인 색인 검색, stdio MCP 조회, 로컬 API·Ollama 답변을 비공개 보고서 하나로 모읍니다. 문서를 승인하거나 색인을 교체하지 않습니다. 원문·질문·결과는 공개 checkout 밖에 둡니다.
• KPI 가드레일: scripts/check_real_regulation_kpi_guardrails.py가 실행 보고서를 정책 파일 scripts/policies/real_regulation_kpi_guardrails.v1.json으로 판정합니다. 자동 승인 없음, MCP 계약, 인용 추적 등 필수 항목 9개는 한 건만 어겨도 실패입니다. 목표 하한은 Recall@5 0.95, MRR 0.85, 최종 모델 답변률 0.95, 사실 충족률 0.90입니다. 정책 파일은 변경 보호 대상이라 기준을 바꾸려면 Code Owner 검토가 필요합니다.
• 평가셋 봉인과 반복 측정: 개발/보류 평가셋을 나누고, 보류셋은 봉인 기록을 남긴 뒤 한 번만 실행하게 합니다. 실패한 문항마다 검색·MCP·답변·감사 중 어디서 실패했는지 분류하고, 대표 문항을 반복 실행해 첫 실행(cold)과 이후 실행(warm)의 지연을 따로 기록합니다.
• 검증된 원문만 근거로 전달: API·MCP 답변 근거에 검색용 문자열 대신 승인 레코드와 대조한 청크 본문을 넣고 source_text_status로 상태를 표시합니다. 대조할 수 없으면 본문을 비워 두며 검색용 문구로 대신하지 않습니다. 근거 인용도 원문 본문 범위 안에서만 만듭니다.
• 표 구조 검토가 필요한 근거는 기권: table_review_required이고 열 개수가 불안정하다고 표시된 표를 인용한 답변은 table_structure_review_required 사유로 기권합니다.
• 발췌 답변의 인용 추적: 발췌 답변의 인용에도 근거 context ID와 승인 해시를 연결하고, approval_ids는 승인 레코드에서만 만듭니다.
• 재순위 계산 분리: CPU 재순위 계산을 요청마다 별도 자식 프로세스에서 실행하고, 끝나면 재순위 모델 메모리를 반환합니다. 실패하면 기존 검색 결과를 쓰고 reranker_status=degraded로 표시합니다. 모델을 매번 불러오므로 속도 개선은 아닙니다.

비공개 실제 규정 문항에서 같은 답변 초안으로 감사 방식을 비교했습니다. 변형 답은 맞는 답에서 숫자를 바꾸거나, 근거에 없는 예외 문장을 덧붙여 만들었습니다.

문항	맞는 답 통과	숫자를 바꾼 답 통과	예외 문장을 덧붙인 답 통과
개발 문항 18개	17	0	2
개선에 쓰지 않은 문항 14개	12	0	0

이 수치는 검토 지적을 반영하기 전 판으로 측정했습니다. 최종 판은 9문항과 합성 6문항을 실제 모델로 다시 실행했고, 나머지는 저장한 감사 모델 응답으로 모델 없는 관문만 다시 확인했습니다.

아직 남은 한계가 있습니다.

• 근거의 조건을 빼서 범위를 넓힌 답변(예: "허가할 수 있다"를 "가능하다"로 바꾼 답)은 막지 못합니다.
• 감사 모델(qwen3:4b)의 판정이 실행마다 달라 맞는 답이 거절될 때가 있습니다. 이때는 발췌 답변으로 바뀝니다.
• 40문항 전체 실행과 KPI 가드레일 판정은 아직 하지 않았습니다.

적용 방법: 수정된 소스로 API와 앱을 다시 실행하면 다중 모델 답변(orchestration_mode=multi_model)의 주장 감사에 새 방식이 적용됩니다. 승인·색인 데이터는 바뀌지 않습니다. 회귀 실행과 가드레일 판정 방법은 실제 규정·MCP·로컬 LLM 회귀 실행을 참고하세요.

검증(2026-10-23): 전체 unittest 4,948개 실행, 실패·오류 0개, 생략 17개(Windows 11, 테스트 모듈 374개를 12묶음으로 나눠 실행). sdist/wheel 빌드와 공개 소스 위생 검사(--include-untracked --include-source-path-scan)도 통과했습니다.

이전 업데이트 · 2026-10-14

• 일괄 승인 흐름 회귀 검증 보강: 선택한 규정 전체 승인·색인으로 확인 화면을 여는 단계에서는 승인·색인이 실행되지 않는지 검사합니다. 마지막 실행 버튼으로 선택한 규정과 수정 내용을 함께 승인·색인하는 흐름도 검증합니다.
• 새 초안 복구 시 원본 보존 검증: 복구 사유와 원본 문서 연결을 기록하고, 기관·프로필·규정 버전·시행일·출처·파일 해시 및 원본 바이트를 보존하는지 검사합니다. 새 초안에 기존 승인·색인 기록이 복사되지 않는지도 확인합니다.

검증(2026-10-14): 전체 unittest 4,299개 실행, 실패·오류 0개, 생략 17개. sdist/wheel 빌드와 공개 소스 위생 검사(--include-untracked --include-source-path-scan)도 통과했습니다.

합본·개별 규정 처리, 저장된 원본 복구, Vercel 배포 기능의 적용 방법은 아래 10월 13일 업데이트를 참고하세요.

이전 업데이트 — 2026-10-13

• 프로그램 안에서 Vercel 배포: 계정 연결, 팀·프로젝트 조회, 승인 데이터 업로드, Production 주소 확인과 search → fetch 검사를 이어서 실행합니다.
• 다음 행동이 보이는 화면: 통과한 품질·색인 상세와 저장 설정을 접고, 원리 설명·저장 설정의 중복 확인란을 줄였습니다. 초보자 안내도 계정 연결·공개 동의·배포 버튼으로 이어집니다.
• 기존 주소 업데이트와 복구: 같은 기관의 새 묶음에는 이전 배포 대상을 불러옵니다. 새 데이터가 아직 배포되지 않았음을 표시하고 공개 동의를 다시 받습니다. 업로드가 끝난 뒤 주소 확인이나 검색 검사만 실패했으면 프로그램을 다시 열어도 재업로드 없이 이어서 확인할 수 있습니다. 첫 배포 후에는 방금 만든 프로젝트를 업데이트 대상으로 선택합니다.
• 대용량 승인 데이터 배포: 전송 파일을 압축하고 서버 시작 시 원래 바이트로 복원합니다. 승인 manifest의 SHA-256을 확인한 데이터만 검색에 사용합니다.
• 합본·개별 규정 처리 보완: 단순 번호 목차, 반복 머리말, 본문 제목·개정 이력·제1조를 함께 확인해 PDF 합본의 규정 경계를 복원합니다. 날짜가 붙은 개별 규정 파일도 지원합니다. 목차나 경계 근거가 부족한 경우에는 해당 파일을 표시하고 검수를 요청합니다.
• 표 아래 본문 보존: 표의 하위 문단으로 추출된 일반 본문도 청크에 포함합니다. 이미 조문·별표에 포함된 문단은 중복 추가하지 않습니다.
• 합본의 규정별 날짜 보존: 합본 파일의 날짜를 모든 규정에 넣지 않고, 각 규정의 본문 개정·시행 이력을 사용합니다. 근거가 없는 날짜는 새로 만들지 않습니다.
• 재업로드 없이 복구: 경계 차단 안내의 저장된 원본으로 새 초안 복구로 최신 파서를 적용합니다. 기존 원본·승인본은 보존하며, 복구된 새 초안을 검수·승인합니다. 합본을 규정별 파일로 나누도록 요구하지 않습니다.
• 전체 승인 버튼 한 곳으로 정리: 초보자 모드에서는 상단의 선택한 규정 전체 승인·색인에서 이어서 처리합니다. 현재 규정만 승인하는 보조 동작은 고급 메뉴에 있습니다. 확인하지 않은 행은 행별 검수 완료로 기록하지 않습니다.

화면·배포 기능은 수정된 소스로 프로그램을 다시 실행하면 적용됩니다. 파싱 보완은 새로 처리하거나 복구한 초안에 적용되며 기존 승인본을 자동으로 변경하지 않습니다. 승인 전 색인 금지와 불확실한 경계의 승인 차단은 유지합니다. 실행판은 최신 Releases의 반영 여부를 확인하세요.

검증: 전체 회귀 4,292개에서 발견한 오류 안내 계약 1건을 수정한 뒤, 최종 공개 소스의 관련 **355개 검사 통과(2개 생략)**를 확인했습니다. 전체 앱 승인·복구 검사 24개, 실제 브라우저의 한 곳에서 전체 승인·색인 흐름, sdist/wheel 빌드와 공개 소스 위생 검사도 통과했습니다. 합본과 개별 파일의 규정 목록·목차·본문·검색 결과를 비교하는 회귀를 포함합니다.

이전 업데이트 — 2026-10-12

HWP 통합 규정집의 반복 승인 차단 수정 (PR #121)

• 머리말과 새 규정 본문 구분: 이전 규정의 머리말이 남아 있거나 홀수·짝수 쪽 머리말이 서로 다르면, HWP 통합본 전체가 ‘규정 경계 불명확’으로 차단되던 문제를 수정했습니다. HWP 원본의 머리말·본문 구분과 줄 배치 정보를 보존하고, 본문 제목·개정 이력·제1조 시작·규정 번호를 함께 확인해 경계를 복원합니다.
• 불확실한 경계는 계속 검수: 표 안의 제목, 배치 정보 누락, 규정 번호 충돌처럼 근거가 부족한 경우에는 차단을 유지합니다. 복원된 경계에도 검수 경고를 남기며 자동으로 승인하거나 색인하지 않습니다.
• 이전 결과 캐시 갱신: 전처리 버전을 2026.10.12-hwp-native-boundaries-1로 변경했습니다. 기존에 저장된 결과가 자동으로 수정되는 것은 아닙니다.

적용 방법: 수정된 소스로 앱을 다시 실행한 뒤 ③ 검수하고 승인의 경계 차단 안내에서 저장된 원본으로 새 초안 복구를 누릅니다. 합본을 나누거나 파일을 다시 올릴 필요 없이 최신 파서로 분석합니다. 기존 원본·승인 기록·색인은 보존되며, 복구한 새 초안을 검수한 뒤 승인합니다. 이 안내는 소스 변경 기준입니다. 다운로드한 실행판의 반영 여부는 Releases에서 확인하세요.

검증: HWP 파서·규정 경계·전처리 캐시 집중 회귀 175개, 합성 규정 생성기 16개 통과. sdist/wheel 빌드와 공개 소스 위생 검사도 통과했습니다. 로컬 재현 HWP는 추출 본문을 그대로 보존하면서 6,567개 검수 항목의 경계 차단 0건을 확인했습니다. 승인·색인은 실행하지 않았습니다. 전체 테스트 실행 내역과 환경 의존성 보완 결과는 PR #121에 기록했습니다.

이전 업데이트 — 2026-10-11

합본 규정집 참조·근거 조문 후속 수정 (PR #121)

• 분류코드가 붙은 인용 연결: 3-1-1. 보수규정 제29조처럼 앞에 분류코드가 붙은 인용이 미해결 참조를 하나 더 만들지 않습니다. 번호를 공개하지 않는 규정은 제목이 정확히 같을 때만 연결하고, 번호가 다른 규정에는 연결하지 않습니다.
• 행동강령 인용 연결: 「임직원 행동강령」 제13조 같은 기관 행동강령 인용을 외부 법령이 아닌 내부 규정 조문 참조로 읽습니다. 대통령령인 「공무원 행동강령」은 그대로 외부 법령으로 둡니다.
• search와 fetch의 근거 조문 일치: 서식·별표 검색 결과의 근거 조문을 fetch와 같은 범위(볼 수 있는 문서 전체 조문)에서 고릅니다. 이전에는 검색 결과 페이지 안에서만 골라서, 근거 조문이 비거나 서식을 인용한 두 조문 중 하나만 잘못 표시될 수 있었습니다.

행동강령 수정은 전처리 결과가 바뀌므로 같은 원본을 재전처리해야 반영됩니다. 분류코드 인용은 다음 MCP로 쓸 파일 묶음 만들기 때, search 수정은 앱을 다시 실행하면 반영됩니다.

검증: 전체 테스트 4,208개 실행, 새 실패 0개(Windows 11·Python 3.12.7, 이 PC의 Streamlit 1.50.0 환경 오류 3개는 변경 전과 같음·생략 16개), 공개 소스 위생 검사 통과. 합본 E2E 24개 체크 기준으로 48개 규정 DOCX·HWPX·PDF는 22개 → 24개, 6개 규정은 24개 그대로 통과했습니다. 서식 결과가 있는 검색은 문서 전체 조문을 확인하므로 느려집니다. 48개 규정 합본 기준으로 검색 p95가 약 65ms에서 180~320ms로 늘었습니다(fetch는 이전부터 같은 비용).

이전 업데이트 — 2026-10-10

합본 규정집 목차·규정 목록·참조 수정 (PR #120)

• 목차 순서 바로잡음: get_regulation_toc가 조문을 원문 순서대로 돌려줍니다. 이전에는 제10장이 제1장 앞에, 제12조가 제5조 앞에 나왔습니다.
• 장·조 종류 오분류 수정: 제6장 특별 지급처럼 제목에 별지·별표·서식·부칙 글자가 들어간 장·절·조가 별지·별표·부칙으로 잘못 분류되지 않습니다.
• 합본 표지가 규정으로 잡히지 않음: 합본 표지(…총규정)가 규정 목록에 하나 더 올라가고, 기관명이 들어간 질문의 검색 결과를 가로채던 문제를 고쳤습니다.
• 자기 참조 제거: 각 규정 머리줄(2-1-1. 인사규정)이 자기 자신을 가리키는 미해결 참조로 잡히지 않습니다.
• 합본 E2E 회귀 검증: 정답이 있는 가상 총규정을 업로드부터 MCP 도구 조회까지 확인하는 scripts/run_combined_book_e2e_regression.py를 Windows에서도 실행할 수 있습니다.

참조 수정은 전처리 결과가 바뀌므로 기존 결과가 자동으로 고쳐지지 않습니다. 같은 원본을 재전처리하세요. 목차·표지 수정은 다음 MCP로 쓸 파일 묶음 만들기 때 반영됩니다.

검증: 전체 테스트 4,183개 실행, 새 실패 0개(Windows 11·Python 3.12.7, 이 PC의 Streamlit 1.50.0 환경 오류 3개는 변경 전과 같음·생략 16개), 공개 소스 위생 검사 통과. 합본 E2E 24개 체크 기준으로 6개 규정 DOCX·HWPX·PDF는 19개 → 24개, 48개 규정은 15개 → 22개 통과했습니다. 48개 규정에서 남은 2개는 2026-10-11 업데이트(PR #121)에서 고쳤습니다.

Qwen 색인 메모리와 통합 규정집 첫 본문 복구 (PR #119)

• Qwen 색인 메모리 개선: CUDA가 사용 가능한 환경에서는 GPU FP16을 선택합니다. 긴 조항·별표는 전체 내용을 2,048자 이하 구간으로 임베딩한 뒤 길이 가중 평균으로 합치고, 모델 적재 전에 전처리·검수 사본을 해제합니다. 메모리가 부족하면 처리 묶음을 줄여 재시도합니다.
• 통합 규정집 첫 본문 복구: 규정 번호가 점선 목차 행 끝에 있는 문서에서 첫 본문 제목·개정 이력이 목차로 제거되던 오류를 수정했습니다. 첫 규정의 조문 소속을 보존하고, 처리 버전을 변경해 이전 결과의 재사용을 차단합니다.
• 역할별 로컬 모델 재검증: Qwen3 1.7B는 질의 분석·검색어 보정, 4B는 구조·표·답변 주장 검수, 8B는 승인 근거 기반 답변을 담당합니다. 의미 벡터와 재순위는 각각 Qwen3 전용 0.6B 모델을 사용합니다. 흐름·보안·색인 조건은 Python이 검사하고 최종 승인은 사람이 합니다.

2026-10-09 코드 검증: 전체 테스트 4,126개 실행, 실패 0개·생략 17개, sdist/wheel 빌드와 공개 소스 위생 검사 통과. 실제 로컬 모델 호출, 합성 승인 자료의 15단계 acceptance 15/15, MCP stdio·Streamable HTTP 프로토콜 검증도 통과했습니다. 실제 통합본은 검수 초안으로 저장했으며, 미승인 자료의 색인 거부와 근거 반환 0건을 확인했습니다.

이번 항목은 PR #119의 소스 변경 기준입니다. 실행판 반영 여부는 Releases에서 확인하세요. 기존 자료는 같은 원본으로 재전처리한 뒤 검수·승인해야 합니다. 상세 업데이트 내역을 참고하세요.

이전 업데이트 — 2026-10-06

• 전체 승인·색인 오류 안내 개선: 합본에서 반복 제목을 다른 규정의 시작으로 오인하던 경우를 보정했습니다. 경계가 불명확한 대상은 수정 내용 저장·증빙 생성·승인·색인 전에 확인하고, 한국어 복구 안내를 표시합니다.
• 저장된 원본으로 재전처리: 경계 차단 안내에서 새 초안 복구를 실행합니다. 이전 처리 결과를 재사용하지 않고 AI 추가 검수 없이 최신 파서로 분석하며, 기존 원본과 승인 기록은 보존합니다.
• 직접 제정·집필 화면 제거: 시작 화면·사이드바·작성 화면 진입점을 제거했습니다. 파일 업로드 → 전처리 → 검수·승인 → 검색 흐름은 유지하며, 기존 작성 초안과 API는 보존하고 작성 기능의 기본값은 비활성화했습니다.

기존에 저장된 전처리 결과가 자동으로 수정되는 것은 아닙니다. 수정된 소스로 앱을 다시 실행한 뒤 같은 원본을 재전처리하세요. 통합 규정집과 규정별 개별 파일을 모두 지원합니다. 재분석 후에도 경계 근거가 부족하면 해당 문서를 표시하고 검수를 요청하며, 확인 생략 사유로 승인 차단을 우회하지 않습니다.

검증: 전체 테스트 4,106개 실행, 실패 0개·생략 17개, sdist/wheel 빌드와 공개 소스 위생 검사 통과. 화면 변경 집중 테스트 137개와 문서 검사 14개도 통과했습니다. 이 안내는 소스 변경 기준이며 실행판 반영 여부는 Releases에서 확인하세요.

이전 업데이트 — 2026-10-05

• MCP 검색 개선: 선택적 BM25 색인을 사용할 수 없어도 규정명·조항·별표·부칙 일치와 기존 로컬 hash 벡터를 활용해 검색 순위를 보정합니다. 호환되지 않는 색인의 반복 읽기와 목록·토큰의 중복 계산도 줄였습니다.
• 승인·기관 경계 강화: 검색·본문 조회와 색인 등록에서 현재 문서의 기관 범위, 승인 기록·스냅샷, 최신 버전을 확인합니다. 승인 후 내용이나 접근 범위가 바뀐 자료를 거부하고, 승인된 개정본의 색인 실패는 내용이 그대로인지 재확인한 뒤 복구합니다.
• 초보자 안내 정리: AI 검수 실행 기록과 사람의 의견 확인을 구분하고, MCP 연결 확인란은 운영자가 직접 확인한 결과임을 명시합니다.

고정된 개발 평가셋 28개 질문(답변 가능 24개·근거 없음 4개)과 동일 승인 자료로 측정했습니다. 지연은 검색·근거 본문 조회·발췌 답변 구성 시간을 포함하며, 대조군과 개선본을 교차 실행한 3회 p95의 중앙값입니다.

지표	작업 시작 시 관측값	같은 세션의 7월 소스 대조군	개선본
순차 요청 p95	138.530ms	68.694ms	63.392ms
8개 동시 요청 p95	830.496ms	536.527ms	517.790ms
정답 조항 Recall@1	20.8%	41.7%	50.0%
정답 조항 Recall@3	33.3%	58.3%	54.2%
정답 조항 Recall@5	41.7%	62.5%	62.5%
정답 문서 Recall@1	95.8%	100%	100%
근거 없는 질문의 빈 결과 반환율	100%	100%	100%

장비 부하에 따라 지연이 달라지므로 시작 시점 대비 감소분 전체를 코드 개선 효과로 해석하지 않습니다. 개선본의 실행별 p95는 순차 53.54286.939ms, 동시 요청 507.503661.376ms였습니다. Recall@3은 7월 대조군보다 한 문항 낮아 추가 개선이 필요하며, 이 평가셋의 결과가 일반적인 검색 정확도를 보장하지는 않습니다. 로컬 전체 검증은 4,081개 테스트 실행, 실패 0개·생략 17개였고, sdist/wheel 빌드와 공개 소스 위생 검사를 통과했습니다. 기존 선택적 BM25 색인의 공식 재생성에는 누락된 파싱 근거 보완이 필요합니다. 측정·보안 기준은 MCP 성능·품질 게이트, MCP 묶음의 도구 수·체이닝·윤문 기준은 최종 빌드 QA 게이트, 병합 전 검토 절차는 변경 보호 하네스를 참고하세요.

초보자 클릭 안내 시연

초보자 안내 시작을 누르면 지금 눌러야 할 항목을 안내합니다. 검수 중에는 원문과 최종본을 가리지 않는 본문 안내를 사용하고, 직접 확인을 마치면 다음 조항으로 이어집니다. 챗봇 실행과 새 창 이동까지 안내가 연결됩니다.

새 초보자 화면: 한 조항만 펼치고 내용이 맞아요 · 다음으로 이어갑니다. 모든 조항을 확인하면 승인하고 AI 질문 준비하기 버튼이 나타납니다. 원래 문서와 저장할 내용을 나란히 보고, AI 수정안은 바로 아래에서 전문과 변경 부분을 확인합니다. 잘 모르겠어요 · 확인 방법 보기를 펼치면 날짜·금액·표를 비교하는 방법을 알려 줍니다. 확인이나 승인은 직접 해야 하며, AI 제안을 최종본에 반영을 눌러야 편집 칸에 들어갑니다.

처음부터 끝까지 3분 시연 MP4 (자막 있음)

기관 만들기 → 파일 올리기 → 전처리 → 한 조항씩 확인 → 승인 → Qwen 질문까지, 초보자 안내만 따라 누른 실제 화면 녹화입니다. 가상 장비 대여규정을 썼고, AI 검수(gpt-4.1-mini)와 내 PC의 Qwen3 8B 답변은 실제 실행 결과입니다. 기다리는 구간과 같은 확인이 반복되는 구간은 빠르게 재생했고 화면에 배속을 표시했습니다. 어린이를 대상으로 한 사용성 시험은 아닙니다.

쉬운 안내 24초 시연 MP4 · 검토 내용과 실제 실행 결과

가상 규정을 사용한 실제 브라우저 녹화에서 도움말·조항 확인·최종 승인·AI 답변 장면을 원래 속도로 발췌했습니다. 기다리는 구간과 일부 조항은 생략했습니다.

이전 화면 36초 시연 MP4 · 조항별 검수·AI 제안 표시·파싱 검증 결과

실제 브라우저 녹화의 주요 구간을 원래 속도로 발췌했습니다. 가상 규정의 전처리·조항 확인· 승인·Qwen 질문 장면과 별도로 준비한 저장된 AI 제안 표시 검사를 이어 붙였습니다. AI 제안 장면은 합성 저장 데이터를 사용하며, AI 제공자의 실제 교정 생성 시연은 아닙니다.

수정 후 85초 실제 클릭 검증 MP4 · 수정 내용·세 질문의 답변·검증 화면

새 가상 장비 규정을 넣고 기관 생성 → 업로드 → 8개 조항·표 대조 → 승인·색인 → Qwen 실행 → 세 질문과 근거 확인을 실제 화면으로 완료했습니다. 위 영상은 이 실행에서 주요 화면을 발췌하고 대기 구간을 줄인 편집본입니다. 일부 구간은 1.25–2배속이며, 모든 조항 확인 장면과 Windows 파일 선택창은 포함하지 않습니다. 안내는 실제 승인을 대신하지 않습니다.

이전 65초 시작 안내 시연 · 시작 안내 시연 재현 방법 · 이전 실행의 실패·복구 기록

사람이 승인·색인한 공공기관 규정을 독립 로컬 Qwen 챗봇에서 고르고 바로 대화하거나, 같은 승인 데이터를 MCP로 연결하는 Windows용 규정 전처리·RAG 빌더입니다.

실행 방법 한눈에

이 프로그램은 내 PC에서만 돌아가는 로컬 앱입니다. 원본 규정 파일과 승인 데이터는 프로그램 폴더의 data\에만 저장되고 외부 서버로 올라가지 않습니다. 아래 셋 중 하나로 실행하세요.

방법	언제 쓰나	하는 일
① Windows 실행판	설치 없이 바로 쓰고 싶을 때	Releases에서 압축을 풀고 PR MCP Builder.exe를 더블클릭합니다.
② 소스 폴더에서 더블클릭	소스를 내려받았고 Python 3.11+가 있을 때	START_HERE.bat을 더블클릭합니다. 처음 한 번은 .venv를 만들고 패키지를 설치한 뒤 자동으로 앱을 띄웁니다(인터넷 필요). 두 번째부터는 점검만 하고 바로 실행됩니다.
③ 명령으로 직접 실행	개발·검증용	아래 PowerShell 명령을 프로젝트 루트에서 실행합니다.

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m streamlit run frontend\streamlit_app.py --server.address 127.0.0.1

• 처음 실행은 오래 걸립니다. 멈춘 것이 아닙니다. 아래 표가 대략의 시간입니다. 검은 창에 새 줄이 몇 분간 안 올라와도 큰 패키지를 내려받는 중이니 창을 닫지 마세요. 창에도 같은 안내가 단계마다 표시됩니다.

  단계	처음	두 번째부터
  환경 점검 (START_HERE.bat 시작 직후, 출력 없음)	10~60초	10~60초
  패키지 설치 ([2/3])	5~15분	건너뜀
  앱 시작 → 브라우저 열림	1~3분	20~60초
  전처리 (HWP 규정 1개, 조항 약 200개)	10초 안팎	10초 안팎
  승인 후 검색 등록 (CPU에서 조항 임베딩)	조항 200개 기준 약 20~25분	새로 승인한 조항 수에 비례

• 검색 등록 중에는 진행 막대에 검색용 벡터 만드는 중 · n/N과 경과 시간이 계속 바뀝니다. 숫자가 늘고 있으면 정상이니 창을 닫지 마세요. 그래픽카드 없는 사무용 PC 기준 시간입니다.

• CUDA를 지원하는 PyTorch와 NVIDIA GPU가 있으면 Qwen 검색 등록은 GPU를 자동 사용하고, 그 외에는 CPU로 실행됩니다. 긴 조항·별표는 전체 내용을 2,048자 이하 구간으로 계산한 뒤 길이 가중 평균 벡터로 합쳐 메모리 사용을 줄입니다. 저장된 원문과 승인 단위는 바뀌지 않으며, 새 Qwen 벡터에는 embedding_input_strategy가 기록됩니다. 메모리가 부족하면 처리 묶음을 줄여 재시도하고, 한 구간도 처리하지 못하면 성공으로 표시하지 않습니다.

• 실행되면 브라우저가 http://127.0.0.1:8501로 열립니다(8501이 사용 중이면 다른 포트를 창에 표시합니다). 몇 분이 지나도 열리지 않으면 검은 창에 적힌 주소를 브라우저 주소창에 붙여 넣으세요.

• 끝낼 때는 검은 창에서 Ctrl+C를 누르거나 창을 닫습니다. 승인 데이터는 data\에 남습니다.

• 승인한 규정에 질문하려면 앱 왼쪽의 독립 Qwen 챗봇 실행 또는 RUN_QWEN_CHAT.bat을 쓰고, 외부 AI 앱과 연결하려면 ④ MCP 화면을 씁니다. Vercel 같은 외부 호스팅은 이 앱의 대상이 아닙니다.

• START_HERE.bat --check는 실행하지 않고 Python·가상환경·포트만 점검합니다.

AI 검수를 켜는 법 (선택)

AI 검수는 전처리할 때 함께 돕니다. 켜지 않고 전처리한 규정에는 "AI 검수 사용 안 함"만 남고, 켠 뒤에도 그 규정은 다시 전처리해야 의견이 붙습니다.

1. 왼쪽 사이드바 AI 검수를 펼쳐 AI 검수 사용을 켭니다.
2. 공급자·모델·API 키·주소를 넣고 저장하고 AI 검수 켜기를 누릅니다. 제목이 AI 검수 · 켜짐으로 바뀌어야 실제로 켜진 것입니다. 설정 필요로 남아 있으면 적힌 이유(키 없음 등)를 먼저 해결하세요.
3. ① 문서 올려서 전처리에서 전처리를 시작합니다. 화면에 🤖 AI 검수 켜짐 — 이번 전처리에 함께 실행됩니다가 보여야 합니다.
4. 결과는 ③ 검수하고 승인의 AI가 확인하거나 제안한 내용 칸과 AI 검수 작업 내용 요약에서 확인합니다.

재시작 뒤에도 켜진 상태로 두려면 둘 중 하나를 고르세요.

• 스위치·공급자·모델·한도는 저장 시 data\ai_review_preferences.json에 자동으로 기억됩니다. 다음 실행에서 사이드바가 "지난 설정을 불러왔습니다"라고 알리며 API 키만 다시 묻습니다.
• 키까지 기억시키려면 저장 전에 API 키를 이 PC의 .env 파일에도 저장을 켜거나, 전산 담당자가 프로그램 폴더에 .env 파일을 만들어 두세요. 앱은 시작할 때 이 파일을 자동으로 읽습니다 (이미 설정된 환경변수가 우선). .env는 Git에 올라가지 않습니다.

ENABLE_AGENT_REVIEW=true
LLM_PROVIDER=openai
AGENT_REVIEW_MODEL=gpt-4.1-mini
OPENAI_API_KEY=sk-...
# 0이면 문서의 모든 조항을 검수합니다. 비용을 제한하려면 숫자를 넣으세요.
AGENT_REVIEW_MAX_CHUNKS_PER_DOCUMENT=0
AGENT_REVIEW_MAX_INPUT_TOKENS_PER_DOCUMENT=0

AI 검수가 안 보이면 data\exports\<문서ID>.agent_review_plan.json의 status와 skip_reason을 보세요. agent_review_not_requested는 전처리 당시 스위치가 꺼져 있던 것이고, api_configuration_needed는 키·모델 설정 문제입니다. 본문에 로컬 경로 모양 문자열이 든 조항은 그 조항만 전송하지 않고 나머지는 정상 검수되며, 요약에 "AI 검수 일부 완료"로 표시됩니다.

여러 규정을 한꺼번에 승인·색인하기

초보자·일반 모드 모두 ③ 검수하고 승인 위쪽의 전체 규정 한꺼번에 처리를 누릅니다. 선택한 파일 전체가 대상이며, 통합 규정집은 그 파일 안의 모든 규정을 포함합니다. 규정 목록에서 내부 규정 하나를 열어 두었어도 이 버튼의 범위는 파일 전체입니다.

• 아직 승인하지 않은 내용이 있으면: 대상과 검수 상태를 확인한 뒤 전체 규정 최종 확정을 누릅니다. 초보자 모드에서 미검수 조항을 포함하면 일괄 승인 확인란을 먼저 켭니다. 명시적 최종 승인 후 선택한 규정을 함께 색인합니다.
• 승인은 끝났고 색인만 남았으면: 선택한 승인 규정 N개 한꺼번에 색인을 누릅니다. 승인 기록을 다시 만들지 않으며, 이미 정상 색인된 규정은 건너뜁니다.
• 조항을 직접 비교하려면: 한 조항씩 검수하는 화면으로 돌아갈 수 있습니다.

확인하지 않은 조항을 승인하면 미검수 일괄 승인으로 감사 기록에 남습니다. 규정 경계가 불명확하거나 다른 기관의 문서가 섞인 경우에는 일괄 승인을 차단합니다. 규정별 문서·조문 구조와 승인 기록은 유지됩니다.

규정 경계 차단이 표시되면: 안내에 나온 파일명과 영향 조항 수를 확인하고 저장된 원본으로 새 초안 복구를 누릅니다. 영향 조항 수는 문서 전체의 처리 범위이며, 그 수만큼 각각 다른 오류가 있다는 뜻은 아닙니다. 복구는 기존 원본·승인본을 보존한 채 새 초안만 만들며, 완료 후 같은 화면에서 검수·일괄 승인·색인으로 이어집니다. 파일명은 개별 규정처럼 보이더라도 실제 내용이 합본이면 본문 구조를 기준으로 처리합니다.

v1.2.21에서는 독립 Qwen 챗봇이 기본적으로 빠른 승인 BM25/lexical 검색을 사용합니다. 질문을 보내면 검색·답변·인용 검증의 실제 진행률과 경과 시간이 계속 보이고, 승인·색인이 끝난 규정만 선택할 수 있습니다. MCP 생성·연결 경로와 기존 승인 데이터는 그대로 유지됩니다.

현재 운영 UI에서는 규정 새로 작성 등 직접 집필 화면을 제공하지 않습니다. PDF·HWP·HWPX·DOCX 파일을 올려 전처리 → 사람 검수·승인 → 색인 순서로 진행합니다. 기존 초안 데이터와 작성 API는 보존하며, 작성 API는 명시적으로 켜야 사용할 수 있습니다. ENABLE_REGULATION_AUTHORING과 STREAMLIT_ENABLE_REGULATION_AUTHORING의 기본값은 false입니다. 설정을 켜도 운영 UI에 작성 메뉴가 다시 나타나지는 않습니다.

로컬 Qwen 질문 시연

MP4로 데모 보기

과거 작성 구현·보존 기능 참고: 규정 작성 빠른 시작 · 초보자 사용성 검증 계획 · Claude 독립 감리 · 작성 구현·검증 보고서 · 작성 MVP 계약 · 작성 보안 모델 · 작성 롤아웃 계획

초보자·유지보수 오케스트레이션 계획 · 처음 사용자 1–6단계로 바로 이동 · 문제 해결표로 이동 · 업데이트 내역 보기

초보자·유지보수 개선 현황

초보자가 화면에서 다음 행동을 바로 찾을 수 있도록 전처리·결과 확인·승인·연결 단계를 공통 상태로 표시합니다. MCP와 로컬 Qwen 연결 진단은 등록 필요, 연결 대기, 조치 필요, 오래된 상태, 사용 가능을 구분하고, 각 상태에 맞는 복구 안내를 제공합니다.

연결 진단·준비 상태·워크플로 진행 계산은 독립 서비스로 분리되어 화면 코드와 분리된 테스트가 가능합니다. 비정상 응답, 빈 경로, 허용되지 않은 경로, 과도하게 큰 설정 파일, 비정상 종료는 성공으로 표시하지 않도록 fail-closed로 처리합니다. 자세한 범위와 다음 단계는 초보자·유지보수 오케스트레이션 계획을 참조하세요.

코드와 실제 MCP STDIO 경로를 먼저 검증하려면 초보자 첫 성공 검증을 실행하세요. 합성 샘플과 임시 tenant만 사용하며, list_regulations·search·fetch까지 통과해야 성공으로 판정합니다.

이번 변경은 다음 명령으로 검증했습니다.

python -m unittest discover -s tests -q
python -m build --sdist --wheel
python scripts\audit_release_hygiene.py --workflow-scope available --include-untracked --include-source-path-scan

흩어진 공공기관 규정을, AI가 목록·목차·조문·참조 관계까지 찾아 쓰는 승인형 규정 MCP로 바꿉니다.

PR MCP Builder는 PDF·HWP·HWPX·DOCX로 흩어진 규정을 정리하고, 운영자가 최종 승인한 내용만 ChatGPT·Codex·Claude에서 조회하게 만드는 Windows용 프로그램입니다. 단순한 문서 검색기가 아니라 다음 세 부분을 한 흐름으로 묶습니다.

1. 계층형 규정 카탈로그 — 규정 목록과 장·절·조·별표·서식·부칙 구조를 보존합니다.
2. 승인 기반 RAG 검색엔진 — 사람이 승인한 청크만 검색하고 원문 근거를 돌려줍니다.
3. 로컬 Qwen 챗봇과 MCP 서버 — Qwen으로 이 PC에서 바로 질문하거나, 같은 승인 RAG를 로컬 STDIO 또는 Vercel HTTPS MCP로 AI 프로그램에 연결합니다.

처음 사용자를 위한 5분 빠른 시작

이 안내를 읽는 데 약 5분이 걸립니다. 문서 자체의 전처리 시간은 파일 크기·형식에 따라 별도로 걸릴 수 있습니다. 처음에는 아래의 사용 방법 하나를 고른 뒤, 공통 ①~③을 마치고 선택에 맞는 ④만 완료하세요.

Windows 실행판의 압축을 풀어 프로그램을 실행하고, 작업할 기관을 만들거나 선택하면 시작할 수 있습니다.

[!NOTE] 이 작업 트리에 새로 추가된 초보자 안내 모드와 Windows 실행 보완은 다음 portable 릴리스에 포함될 예정입니다. 현재 releases/latest 실행판에 첫 선택 화면이 보이지 않으면 정상입니다. 현재 실행판은 일반 모드로 시작하므로 아래 ①부터 바로 진행하세요. 초보자 안내 모드가 필요하면 개발자용 실행과 검증의 START_HERE.bat 소스 실행을 사용하세요. 새 portable 릴리스와 fresh-Windows 검증이 끝난 뒤에는 실행판에서도 안내 모드를 다시 확인할 수 있습니다.

규정 파일 업로드와 기존 초안 보존

현재 로컬 운영자 화면은 ① 문서 올려서 전처리에서 시작합니다. 준비한 규정 파일을 올리고 전처리 결과를 검수한 뒤, 사람이 승인한 내용만 색인하여 Qwen·MCP에서 사용합니다. 원문 파일이 없다면 별도 문서 도구에서 파일을 준비하세요. 운영 UI의 직접 제정·집필 화면과 홈·사이드바 바로가기는 제거되었으며, 예전 작성 화면 주소는 시작 화면으로 돌아갑니다.

기존 작성 초안 데이터와 저장소·API는 삭제하지 않고 보존합니다. 작성 API는 ENABLE_REGULATION_AUTHORING=false가 기본이며, 필요한 운영 환경에서만 명시적으로 활성화합니다. 로컬 Compose의 STREAMLIT_ENABLE_REGULATION_AUTHORING도 기본 false입니다. 이 설정을 켜더라도 운영 UI의 집필 화면은 제공되지 않습니다. 과거 작성 구현·보존 기능 참고: 규정 작성 빠른 시작은 보존된 초안 기능을 설명하는 자료이며, 현재 운영 UI 사용 순서는 아닙니다.

[!IMPORTANT] 보존된 작성 초안과 출력물은 공식 승인 아님입니다. 기존 승인·벡터·MCP 저장소와 분리되며 자동으로 색인하지 않습니다. 사용할 규정 파일은 전처리·사람 검수·승인·색인 절차를 별도로 거쳐야 합니다.

먼저, 규정을 어디에서 질문할지 고르기

첫 시작 화면의 최종 사용 방법에서 아래 둘 중 하나를 고릅니다. 둘 다 이미 승인된 동일한 로컬 RAG 색인만 읽으므로 별도 RAG를 만들거나 다시 색인할 필요가 없습니다. 선택을 잘못해도 왼쪽 메뉴의 Qwen 또는 MCP 선택에서 언제든 바꿀 수 있고, MCP를 고르더라도 로컬 Qwen 챗봇이 사라지지 않습니다.

첫 선택	이런 경우에 고르세요	④에서 하게 되는 일	미리 필요한 것
이 PC의 로컬 Qwen 챗봇으로 바로 질문 — 처음에는 이 경로 권장	규정을 외부 AI API로 보내지 않고 이 PC에서 바로 묻고 싶음	별도 localhost 챗봇을 한 번에 열고, 승인 규정 선택 → qwen3:8b 연결 확인 → 질문·근거 확인	실행 중인 Ollama, 설치된 qwen3:8b, 승인·색인이 끝난 규정
ChatGPT·Claude·Codex에 MCP로 연결	다른 AI 앱에서 규정 도구를 호출하고 싶음	MCP 번들 생성 → 앱 등록 → list_regulations·search·fetch 확인	연결할 AI 앱과 로컬 STDIO 또는 원격 HTTPS 방식 결정

시작 전 준비 체크

아래 항목 중 하나라도 준비되지 않았다면 질문 버튼을 반복해서 누르지 말고 표시된 단계로 돌아갑니다.

• 작업할 기관을 만들거나 정확한 기존 기관을 선택했다.
• PDF·HWP·HWPX·DOCX로 공식 MCP 묶음을 만들 예정이면 업로드 전에 화면에 Kordoc 사용 가능이 표시되는지 확인했다. 설치했다면 앱을 완전히 종료하고 PR MCP Builder.exe 또는 START_HERE.bat을 다시 실행했다.
• 결과 확인 화면에서 규정명·조문·표·별표를 원문과 비교했다.
• 검수·승인 화면에서 사람이 최종본을 확정했다.
• 규정 상태에 승인 완료와 색인 완료가 함께 표시된다.
• 로컬 Qwen 경로라면 Ollama가 실행 중이고 ollama list에 qwen3:8b가 보인다.
• MCP 경로라면 외부 AI로 전달해도 되는 승인 데이터인지 확인했다.

qwen3:4b는 기본 대화에 필수가 아닙니다. 독립 챗봇의 Qwen3 4B 정밀 근거 감사를 직접 켤 때만 필요하며, 기본값은 꺼짐입니다.

첫 업로드 전에 화면의 공식 MCP 품질 준비 확인을 먼저 보세요. PDF·HWP·HWPX·DOCX 모두 일반 본문과 조문 구조를 빠르게 읽는 전처리는 Kordoc 설치 전에도 시작할 수 있습니다. 다만 이 네 지원 형식으로 공식 MCP 파일 묶음을 만들 때는 Kordoc 표 파싱 품질 증거가 반드시 필요합니다. 준비되면 Kordoc 사용 가능, 없으면 Kordoc 설치·검증 시작이 표시됩니다. 설치 버튼은 Node.js/npm을 이용한 사용자 전역 설치임을 설명하며, 동의해 버튼을 누른 경우에만 설치를 시작합니다. 설치가 끝나면 앱을 완전히 종료하세요. Windows 실행판은 PR MCP Builder.exe를 다시 더블클릭하고, 소스 실행은 START_HERE.bat을 다시 실행해 Kordoc 사용 가능 표시를 확인하세요. Kordoc 없이 처리한 PDF·HWP·HWPX·DOCX는 ④ 전에 Kordoc을 설치한 뒤 새 초안으로 다시 전처리하고, 검수 권고를 확인한 운영자가 다시 승인해야 합니다. 이 재전처리는 화면 진입만으로 시작되지 않으며, 예상 작업을 읽고 안전 재전처리 버튼을 직접 눌렀을 때만 시작됩니다.

순서	화면에서 할 일	다음으로 넘어가는 신호
①	① 문서 올려서 전처리에서 문서 업로드 → 자동 인식 정보 확인 → 전처리 시작 순서로 진행. AI 검수를 함께 돌리려면 그 전에 왼쪽 사이드바 AI 검수에서 켜고 API 키를 입력한다	전처리 완료
② (선택)	초보자 기본 흐름은 ①에서 바로 ③으로 갑니다. 구조·표·품질 이슈·다운로드가 필요하면 ③의 상세 안내에서 ② 결과 확인 화면 열기를 누르세요.	상세 확인 후 ③으로 이동
③	원래 문서·저장할 내용을 한 조항씩 비교하고 아래 AI가 확인하거나 제안한 내용 읽기 → 필요하면 직접 수정하거나 AI 제안을 최종본에 반영 → 내용이 맞아요 · 다음 → 모두 확인한 뒤 승인하고 AI 질문 준비하기. 이전 조항은 확인한 조항 다시 검토하기에서 다시 열 수 있습니다.	선택한 모든 규정의 승인·색인 완료
④	로컬 Qwen 선택: 독립 Qwen 챗봇 실행 → 별도 앱에서 승인·색인 규정 선택 → 연결 확인 → 질문 → 답변과 근거 조문 확인. MCP 선택: MCP 원리·변환 과정 확인 → 규정 범위 → AI 앱 → 저장 설정·생성할 MCP 이름 (필수 입력) → MCP로 쓸 파일 묶음 만들기 → 앱별 등록·연결 진단 → list_regulations → search → fetch	Qwen은 독립 앱의 답변과 근거 조문 확인, MCP는 여섯 개의 실제 연결 확인 완료

첫 화면에서 초보자 안내 시작을 선택한 뒤 기관을 만들거나 선택하면, 지금 눌러야 할 곳에 초록색 테두리·화살표·단계 번호가 표시됩니다. 배경을 어둡게 하고 실제 클릭할 항목을 밝게 보여 주는 안내창이 함께 열립니다. 번호는 사이드바의 세부 확인 절차 목록과 같은 3-2 형식이라, 지금이 몇 번째 절차인지 화면과 목록에서 똑같이 확인할 수 있습니다. 사이드바에서는 끝난 절차가 ✅, 지금 할 차례가 👉로 표시되며, 아직 준비가 안 된 화면에서는 번호 대신 ! 표시와 함께 먼저 끝내야 할 준비 작업을 알려 줍니다. 초록색 테두리는 현재 안내 대상이라는 뜻입니다. 버튼을 누르기 전 짧은 설명을 읽고, 실제 완료 상태를 확인한 뒤 다음 단계로 이동하세요. 안내가 필요 없으면 첫 선택 화면에서 일반 모드로 계속을 누르면 됩니다. 기관을 이미 선택한 상태라면 사이드바의 초보자 안내 모드를 켜도 됩니다.

• 안내를 잠시 끄려면 안내 건너뛰기를 누르거나 사이드바에서 모드를 끕니다.
• 안내창에서 한 단계씩 시작을 누른 뒤 밝게 표시된 실제 항목을 직접 누르세요. 작업 상태가 바뀌면 다음 미완료 항목의 안내가 이어집니다. 접힌 메뉴 안의 작업은 먼저 메뉴 제목을 눌러 펼치도록 안내합니다.
• 안내창의 안내 잠시 멈춤 또는 Esc로 잠시 멈추고, 오른쪽 아래의 안내 이어서 보기로 현재 미완료 항목부터 다시 진행할 수 있습니다. 안내 접고 직접 하기는 현재 설명만 닫으며 다음 작업의 안내는 이어집니다.
• 다시 보려면 처음부터 다시 보기를 누릅니다.
• 이전 단계와 다음 단계는 설명 위치만 바꿉니다. 승인과 색인은 자동으로 실행되지 않으며 운영자가 최종 버튼을 눌러야 합니다. 원문 확인은 권고되며, 생략하면 감사 기록에 남습니다.
• 마지막 연결 확인은 하나의 확인란이 아니라 **AI 앱 등록, 앱 재시작 또는 새 대화, 연결 진단, list_regulations, search, fetch**의 여섯 항목입니다. 앞 항목을 완료해야 다음 확인란이 열립니다. 문서 범위·저장 방식이 다른 묶음을 새로 만들면 새 묶음에서 다시 확인해야 완료로 표시됩니다.
• 실제 AI 대화에서는 먼저 list_regulations로 승인된 규정 목록이 보이는지 확인한 다음, 필요한 규정을 search로 찾고 fetch로 승인 원문과 출처를 확인하세요.
• 규정별 파일을 여러 개 올려도 되고, 여러 규정을 합친 규정집 한 개를 올려도 됩니다. 제목·조문 경계가 분명하면 MCP의 규정 목록·목차·조문 결과는 같게 만들어집니다. 합본에서 별표·붙임 뒤에 새 규정을 이어 넣을 때는 새 페이지의 편·장 제목처럼 분명한 경계를 두세요.

처음에 로컬 Qwen을 골랐다면 왼쪽의 독립 Qwen 챗봇 실행으로 별도 앱을 열면 됩니다. MCP 연결을 골랐다면 ④는 MCP 생성·외부 AI 연결로 보이고 MCP 탭부터 시작합니다. 어느 경우에도 기존 승인 색인과 MCP 기능은 남아 있습니다. MCP를 쓸 때 Codex·Claude의 같은-PC 연결은 STDIO를 쓰지만, ChatGPT는 같은 PC의 로컬 서버에도 직접 연결하지 않고 원격 HTTPS 또는 OpenAI Secure MCP Tunnel을 사용합니다. 상세 설정은 빠른 시작을 마친 뒤 방법 A~E 중 내 앱 하나 고르기에서 실제로 사용할 방법 하나만 펼쳐 보세요. 원격 서버가 꼭 필요한 경우에만 방법 D·E의 Vercel 안내로 넘어가면 됩니다.

무엇을 할 수 있나요?

필요한 일	PR MCP Builder가 제공하는 방법
승인된 규정 전체 목록 확인	list_regulations가 중복 없는 규정 목록, 페이지, total_count를 반환
규정 구조 탐색	get_regulation_toc로 장·절·조·별표·서식 계층 확인
“인사규정 제16조” 정확히 찾기	get_regulation_article로 규정과 조문 번호를 지정해 조회
다른 규정을 인용한 부분 찾기	get_regulation_references로 들어오고 나가는 참조 확인
서로 물고 도는 참조 점검	list_regulation_reference_cycles로 순환참조 묶음 확인
자연어로 관련 규정 찾기	search로 후보를 찾고 fetch로 승인 원문과 출처 확인
최신 개정본 반영	같은 규정의 새 버전을 등록하고 해당 규정만 다시 처리·색인
시행일에 맞는 현재본 조회	개정 이력과 효력 기간을 보존하고 조회 기준일에 맞는 버전 선택
내 PC 또는 원격 AI에서 사용	Codex·Claude의 같은-PC 연결은 STDIO, ChatGPT와 원격 AI는 HTTPS /mcp로 연결

규정 한 건이 AI 도구가 되기까지

규정 파일 추가
  → 규정명·버전·장·절·조·별표·부칙 구조화
  → 원문과 처리 결과 비교
  → 사람이 승인
  → 승인 데이터만 검색 색인
  → MCP 번들 생성
  → ChatGPT·Codex·Claude에서 목록·목차·조문·검색 도구 사용

개정본도 같은 원칙을 따릅니다. 새 파일을 기존 규정의 다음 버전으로 등록하고 시행일과 개정 관계를 확인한 뒤 승인합니다. 그러면 변경된 규정 단위만 갱신되며, 나머지 규정을 전부 다시 처리할 필요가 없습니다.

[!NOTE] 현재 개발 중인 공개 소스 프로젝트이며 Windows 10/11 64비트 우선 지원입니다. Streamlit 화면은 로컬 운영자용이며 완성형 공개 SaaS 화면이 아닙니다.

[!IMPORTANT] 문서를 올렸다고 바로 AI 검색에 공개되지 않습니다. 승인하지 않은 내용은 MCP의 search와 fetch 결과에 포함하지 않습니다. 사람 검수를 권고하며, 운영자가 명시적으로 승인한 규정만 MCP 데이터로 생성합니다. 사람에게 승인되지 않은 청크는 검색 색인과 MCP 번들에 포함하지 않습니다.

이 README는 처음 설치하는 운영자부터 Vercel 배포와 소스 검증이 필요한 개발자까지 순서대로 필요한 깊이만 읽도록 구성했습니다. 화면 예시는 이해를 돕기 위한 샘플이며 앱 버전에 따라 버튼 위치나 이름이 조금 달라질 수 있습니다. 경로, 서버 이름, ID는 예시를 타이핑하지 말고 내 PC에서 생성된 값을 복사하세요.

이 문서에서 할 일

처음 사용하는 운영자는 0→1을 공통으로 읽은 뒤, 로컬 Qwen이면 1-6에서 대화를 시작하고 MCP이면 2→3→4로 진행합니다. 이미 번들을 만든 사람은 사용할 AI 앱의 방법 A~E로 바로 이동하세요. 보안·개발·배포 세부 정보는 뒤쪽에 모아 두었으므로 처음부터 모두 이해할 필요는 없습니다.

단계	내가 하는 일	끝났다는 신호
0. 출발점 선택	독립 로컬 Qwen 또는 MCP 연결 중 선택	질문할 위치와 ④ 메뉴 결정
1. 규정 준비	파일 추가 → 결과·검수 권고 확인 → 운영자 승인	승인 데이터의 색인 완료
1-6. 로컬 Qwen 대화	질문 가능 규정 선택 → 8B 연결 → 질문·근거 확인	진행률 100%와 승인 근거 조문 표시
2. MCP 연결	방법 A~E 중 실제 사용할 앱 하나만 설정	서버 또는 커넥터가 활성 상태
3. 기능 검증	목록·목차·조문·search·fetch 호출	승인 원문과 출처 반환
4. 문제 해결	증상별 표에서 원인 확인	실패한 단계의 성공 신호 확인

바로 이동:

• 이 프로그램이 제공하는 기능
• 완전 처음이라면 여기부터
• 처음 설치하고 승인 데이터 만들기
• 독립 로컬 Qwen 여섯 단계
• 새 규정과 개정본 관리하기
• 방법 A~E 중 내 앱 하나 고르기
• 방법 A: Claude Code 로컬 STDIO
• 방법 B: Codex CLI / Codex IDE 로컬 STDIO
• 방법 C: Claude Desktop 로컬 STDIO
• 방법 D: ChatGPT · Vercel HTTPS MCP
• 방법 E: Claude · Vercel HTTPS MCP
• search와 fetch로 최종 확인하기

먼저 알아둘 네 단어

단어	쉬운 뜻
MCP	AI 프로그램이 이 규정 검색기에 질문할 수 있게 해 주는 연결 규칙
번들	설정 파일, 실행 파일, 승인 검색 데이터를 한 폴더에 모은 것
STDIO	같은 PC의 AI 프로그램이 서버를 직접 켜고 대화하는 로컬 연결. Windows 실행판은 포함된 EXE, 소스 실행은 Python을 사용
HTTPS	Vercel에 서버를 배포하고 https://.../mcp 주소로 접속하는 원격 연결

MCP에는 두 종류의 읽기 도구가 함께 들어 있습니다.

• 구조를 알고 찾을 때: list_regulations → get_regulation_toc → get_regulation_article 순서로 목록, 목차, 정확 조문을 조회합니다. 규정 간 관계는 get_regulation_references와 list_regulation_reference_cycles로 확인합니다.
• 질문으로 찾을 때: search가 승인된 규정 후보와 id를 돌려주고, fetch가 그 id의 원문 내용과 출처를 돌려줍니다.

따라서 서버 이름이 보이는 것만으로는 성공이 아닙니다. 도구 목록을 확인하고 실제 규정 목록 또는 검색 결과와 승인 원문까지 반환돼야 연결 완료입니다.

0. 완전 처음이라면 여기부터

처음이라면 승인 규정과 Qwen이 모두 이 PC에 머무는 독립 로컬 Qwen 챗봇부터 확인하는 것을 권장합니다. 다른 AI 앱에서 규정 도구를 써야 할 때만 MCP 경로로 바꾸면 됩니다. Codex나 Claude의 MCP는 로컬 STDIO부터 성공시킨 뒤, 꼭 인터넷 주소가 필요할 때만 Vercel HTTPS로 넘어갑니다. ChatGPT만 쓴다면 방법 D의 원격 HTTPS 경로를 선택합니다. 로컬 Qwen과 로컬 STDIO에는 Vercel 계정, 도메인과 공개 서버가 필요하지 않습니다. 빠른 일반 구조 전처리는 Kordoc 설치 전에도 가능하지만, PDF·HWP·HWPX·DOCX 네 지원 형식으로 공식 MCP 묶음을 만들려면 ④ 전에 Kordoc 표 파싱 품질 증거가 필요합니다. Kordoc 설치에는 Node.js/npm이 필요합니다.

0-1. 나에게 맞는 출발점

지금 상황	먼저 읽을 곳	필요한 것
이 PC에서 승인 규정에 바로 질문	로컬 Qwen 여섯 단계	Ollama, qwen3:8b, 승인·색인이 끝난 규정
같은 PC의 Claude Code에서 사용	방법 A	Claude Code CLI, 생성한 번들 폴더
같은 PC의 Codex CLI 또는 IDE에서 사용	방법 B	Codex CLI 또는 IDE, 생성한 TOML
Claude Desktop과 이 프로그램을 같은 PC에서 사용	방법 C	Claude Desktop, 생성한 번들 폴더
ChatGPT에서 사용	방법 D	ChatGPT 웹 Developer mode, 지원 플랜·관리자 권한, 원격 HTTPS MCP
Claude에서 Vercel 주소로 원격 사용	로컬 검색 성공 후 방법 E	Vercel 계정, Node.js, 공개 승인 데이터
아직 규정 파일을 처리하지 않음	1장	Windows PC, 규정 원문

처음 연결하는 사람의 권장 순서

Windows 실행판 설치
  → 규정 1개 업로드
  → 원문과 비교
  → 사람 승인
  → 색인 완료 확인
  → 독립 Qwen에서 승인 규정 선택·연결 확인·첫 질문
  → 필요하면 방법 A·B·C 중 사용할 로컬 MCP 앱 하나 연결
  → MCP의 search와 fetch 확인
  → 필요할 때만 Vercel HTTPS 배포

0-2. 이 문서의 명령과 경로 읽는 법

• 회색 명령 상자 오른쪽 위에 복사 버튼이 보이면 눌러서 복사합니다.
• Claude Desktop 로컬 연결에서는 서버 이름이나 Python 경로를 다시 타이핑하지 않습니다. Builder가 만든 JSON 복사 상자를 사용합니다.
• Vercel 주소는 프로그램의 배포 완료 화면에서 복사합니다. 수동 배포는 PowerShell의 Aliased: 줄에 나온 실제 주소를 복사합니다.
• C:\MCP-Bundles\...는 설명용 예시입니다. 생성 완료 화면이나 내 파일 탐색기의 실제 경로를 복사합니다.
• JSON 안의 C:\\MCP-Bundles\\...처럼 역슬래시가 두 개인 것은 정상입니다. JSON이 Windows 경로를 안전하게 저장한 모습입니다.
• PowerShell 명령이 여러 줄이면 줄 끝의 백틱 `까지 포함해 한 덩어리로 복사합니다. 불편하면 한 줄로 붙여 넣어도 됩니다.
• 명령을 실행하는 검은색 또는 파란색 창을 이 문서에서는 PowerShell이라고 부릅니다.

0-3. 원하는 폴더에서 PowerShell 여는 가장 쉬운 방법

1. 파일 탐색기로 명령을 실행할 폴더를 엽니다.
2. 위쪽 주소 표시줄의 폴더 경로를 한 번 클릭합니다.
3. 경로 대신 powershell이라고 입력하고 Enter를 누릅니다.
4. 열린 창의 줄 앞에 현재 폴더 이름이 보이면 준비 완료입니다.
5. 문서의 명령을 붙여 넣고 Enter를 누릅니다.

명령 실행 중 빨간 글씨가 보이면 창을 바로 닫지 마세요. 마지막 20줄을 복사하거나 캡처해 두면 문제 해결표에서 원인을 찾기 쉽습니다. API 키, 토큰, 기관명과 개인 경로가 포함됐다면 공유하기 전에 가립니다.

0-4. 시작 전 1분 점검

• 규정 파일 한 개 이상을 사람이 원문과 비교했다.
• 사용할 조문을 승인했다.
• 승인 데이터의 검색 색인이 완료됐다.
• 번들 폴더를 앞으로 이동하거나 이름을 바꾸지 않을 위치에 만들었다.
• 로컬 연결이면 방법 A·B·C에서 선택한 앱을 설치하고 로그인했다.
• Vercel 연결이면 외부 공개가 허용된 데이터인지 담당자에게 확인했다.

1. 처음 설치하고 승인 데이터 만들기

이 장의 각 단계는 다음 성공 신호를 확인하고 넘어갑니다.

단계	클릭하거나 할 일	왜 필요한가	성공 신호	막히면
1-1	Release ZIP 압축 해제 후 PR MCP Builder.exe 실행	운영 화면 시작	기관 선택 화면 표시	ZIP 안에서 바로 실행하지 않았는지 확인
1-2	기관 생성 또는 기존 기관 선택	데이터와 승인을 기관 범위로 분리	선택한 기관의 대시보드 표시	잘못 골랐다면 파일을 올리기 전에 다시 선택
1-3	① 문서 올려서 전처리에서 규정 파일 추가	문서를 규정·조문 구조로 변환	전처리 완료 표시	규정명·버전·날짜와 오류 단계 확인
1-4	② 결과 확인에서 원문과 결과 비교	잘못 나뉜 조문·표·별표를 승인 전에 발견	검토할 청크와 앞뒤 문맥 확인	원문과 다르면 수정 또는 재처리
1-5	검토한 청크 승인 후 색인	승인된 근거만 RAG와 MCP에 포함	승인 완료 + 색인 완료	문제 해결표에서 승인·색인 상태 확인

1-1. 프로그램 내려받기

1. 최신 Windows 실행판을 엽니다.
2. Windows용 ZIP 파일을 내려받습니다.
3. ZIP 파일에서 바로 실행하지 말고, 새 폴더에 압축을 모두 풉니다.
4. 압축을 푼 폴더에서 PR MCP Builder.exe를 실행합니다.
5. Windows가 실행 여부를 물으면 게시자와 내려받은 주소가 이 저장소의 Release인지 먼저 확인합니다.

개발자가 소스에서 실행하는 방법은 개발자용 실행과 검증에 있습니다.

성공 신호: 기관을 새로 만들거나 기존 기관을 고르는 첫 화면이 열립니다.

1-2. 기관 선택

기관을 만들거나 기존 기관을 선택합니다. 문서와 승인 데이터는 선택한 기관 범위로 분리됩니다.

아래 이미지는 초보자 안내 시작 또는 일반 모드로 계속을 고른 다음 나타나는 기관 선택 화면입니다. 현재 버전에서는 이 이미지보다 앞에 안내 모드 선택 화면이 한 번 더 나옵니다.

선택 후 대시보드에서 현재 작업 상태와 다음 단계를 확인합니다.

성공 신호: 대시보드 위쪽에 지금 작업할 기관이 표시됩니다. 기관을 잘못 선택했다면 규정 파일을 올리기 전에 돌아가서 바꿉니다.

1-3. 규정 파일 올리기

1. ① 문서 올려서 전처리로 이동합니다.
2. PDF·HWP·HWPX·DOCX 규정 파일을 선택합니다.
3. 여러 규정은 한 번에 올릴 수 있지만 처음이라면 한 파일로 연습하는 것이 쉽습니다.
4. 자동 인식된 규정명, 버전과 개정일을 원문과 비교합니다.
5. 값이 맞으면 전처리를 시작합니다.

처리가 끝나면 완료 표시가 나타납니다.

왜 하나요? 이 단계가 문서의 평면 텍스트를 규정명·버전·장·절·조·별표·부칙 단위로 나눕니다. 성공 신호는 진행률 숫자가 아니라 전처리 완료 상태와 결과 확인 단계에서 실제 청크를 열 수 있는 것입니다.

1-4. 처리 결과 확인

② 결과 확인에서 처리할 규정을 불러옵니다. 품질 결과가 표시되어도 자동 승인된 것은 아닙니다.

여러 규정을 올렸다면 각 규정의 품질과 상태를 확인합니다.

원문, 전처리 결과와 앞뒤 문맥을 비교합니다. 조문 번호, 제목, 본문, 별표와 표 내용이 원문과 다르면 승인하기 전에 수정하거나 다시 처리합니다.

성공 신호: 규정명과 조문 번호가 원문과 일치하고, 조문 본문·표·별표가 엉뚱한 조문에 섞이지 않았습니다. 다르면 다음 단계로 넘기지 말고 수정하거나 다시 처리합니다.

1-5. 검수 권고를 확인하고 승인

AI 제안은 참고용입니다. 사람의 원문 확인을 권고하지만, 최종 승인 여부는 운영자가 결정합니다. 최종 버튼으로 명시적으로 승인된 내용만 검색 색인과 MCP에 들어가며, 원문 확인을 생략한 승인은 approved_without_review 감사 이벤트로 구분됩니다.

승인 화면에서 사용할 조문을 선택하고 승인 동작을 실행합니다.

색인 완료 상태가 표시돼야 Qwen 챗봇·MCP 연결 단계로 갈 수 있습니다.

성공 신호: 승인 완료와 검색 색인 완료가 함께 표시됩니다. 승인만 끝나고 색인이 실패했다면 ③ 검수하고 승인에서 문서 색인 복구를 실행합니다. 이는 승인 청크를 검색에 넣는 문서 색인 작업입니다. ④ Qwen 규정 챗봇·AI 연결에서 만드는 계층 색인은 MCP 파일 묶음을 만들거나 갱신할 때 자동으로 생성되므로, 따로 복구하거나 다시 만들 필요가 없습니다.

1-6. 로컬 Qwen으로 처음 질문하기 — 여섯 단계

첫 화면에서 이 PC의 로컬 Qwen 챗봇으로 바로 질문을 골랐다면, 승인·색인이 끝난 뒤 빌더와 분리된 Qwen 앱에서 아래 여섯 단계만 차례대로 진행하세요. 이 과정은 MCP를 만들거나 지우지 않습니다. Qwen과 MCP는 같은 승인 로컬 RAG를 공유하므로 별도 RAG 구축도 필요 없습니다.

1. 독립 챗봇 열기 — 빌더 왼쪽의 독립 Qwen 챗봇 실행을 한 번 누릅니다. 새 창이 자동으로 열리지 않으면 화면에 표시된 127.0.0.1 주소의 열려 있는 Qwen 챗봇으로 이동을 누릅니다. 빌더와 챗봇은 서로 다른 로컬 프로세스이므로 빌더 화면 안에서 대화하지 않습니다.

2. 기관과 승인 규정 선택 — 독립 앱에서 기관을 고른 다음 목록의 대화할 규정을 하나 선택합니다. 질문 가능은 활성 청크의 검수 결정이 끝났고 승인 청크 수와 색인 레코드 수가 일치하며 stale 기록이 0개라는 뜻입니다. 승인·색인 필요는 선택할 수 없으므로 빌더의 ③으로 돌아가 승인 또는 문서 색인 복구를 완료합니다.

3. AI 연결 확인 — 버튼을 누르고 연결되었습니다가 표시될 때까지 기다립니다. 첫 확인은 모델을 메모리나 GPU에 올리므로 수십 초 걸릴 수 있습니다. 이때 버튼을 반복해서 누르지 않습니다. 실패하면 새 PowerShell에서 ollama list를 실행해 qwen3:8b를 확인하고, 없으면 ollama pull qwen3:8b를 실행한 뒤 Ollama를 다시 시작합니다.

4. 답변 방식 선택(선택 사항) — 답변 설정·대화 지우기 안에 있습니다. 처음에는 Qwen3 4B 정밀 근거 감사를 끈 기본값 그대로 둡니다. 기본 빠른 모드는 승인 BM25/lexical 검색 → Qwen3 8B 짧은 답변 → 결정론적 근거 ID 검증 순서로 실행됩니다. 의미 단위의 추가 검토가 꼭 필요할 때만 토글을 켭니다. 토글을 켜면 8B 답변 뒤 4B 감사가 추가되고 GPU 모델 교체 때문에 훨씬 오래 걸릴 수 있습니다.
5. 질문하고 진행 게이지 보기 — 선택한 규정에 대해 질문하세요에 예를 들어 제5조 내용은 뭐야를 입력합니다. 화면에는 질문·범위 확인 → 승인 근거 검색 → 문맥 구성 → Qwen3 8B 답변 → 인용 검증의 현재 단계, 백분율과 경과 시간이 계속 표시됩니다. 정확한 단일 조문 질문은 이전 대화와 분리해 빠르게 찾고, 그 내용은?처럼 앞 질문이 필요한 후속 질문만 최근 사용자 질문을 검색 문맥으로 사용합니다.

6. 답변과 근거 조문 함께 확인 — 답변만 읽고 끝내지 말고 아래 근거 조문에서 규정명·조문 번호·페이지·승인 인용을 원문과 비교합니다. 기본 모드에서도 답변의 모든 [E번호]가 선언된 승인 검색 결과와 정확히 일치해야 표시됩니다. 존재하지 않는 조문이나 근거가 부족한 질문은 비슷한 다른 조문으로 바꾸지 않고 고정된 근거 부족 답변을 표시합니다.

위 캡처와 데모는 합성 샘플만 사용했습니다. 실제 기관명, 기관 문서, 사용자 로컬 경로는 포함하지 않았습니다.

실제 로컬 승인 데이터에서 이전 제1조 대화 뒤 제5조 내용은 뭐야를 질문했을 때, 기본 빠른 모드의 검색은 0.49초, 이미 적재된 Qwen3 8B 답변과 인용 검증까지는 7.34초가 걸렸습니다. 별도의 정밀 수용시험에서는 1.7B → Reranker → 8B → 4B 전체 역할도 계속 검증합니다.

빌더가 열려 있지 않아도 프로젝트 폴더의 RUN_QWEN_CHAT.bat를 실행하거나 설치 환경에서 reg-rag-qwen-chat을 실행하면 같은 독립 앱이 열립니다. 이 앱은 MCP 설정 화면을 포함하지 않고, 매번 현재 로컬 테넌트·기관 프로필·문서 소유 관계·승인 저널·색인 상태를 다시 검사합니다.

MCP 경로는 그대로 유지됩니다

첫 화면에서 ChatGPT·Claude·Codex에 MCP로 연결을 골랐다면 ④가 MCP 생성·외부 AI 연결로 바뀝니다. 승인 규정 범위와 사용할 앱을 고르고 MCP 묶음을 만든 뒤 list_regulations → search → fetch를 확인하세요. 이 선택은 독립 Qwen 앱, 승인 색인, 기존 MCP 번들을 삭제하지 않으며 왼쪽 Qwen 또는 MCP 선택에서 언제든 바꿀 수 있습니다.

[!WARNING] 원문 업로드, 미승인 데이터, API 키, 비밀번호와 기관 내부 비밀 자료를 공개 저장소나 공개 Vercel 배포에 넣지 마세요.

새 규정과 개정본 관리하기

규정 데이터는 파일이 들어온 순서가 아니라 다음 논리 계층으로 관리됩니다.

기관
└─ 규정
   ├─ 개정 버전과 효력 기간
   └─ 장 → 절 → 조 → 항·호
      └─ 별표·서식·부칙

[!TIP] 규정별 파일 여러 개와 여러 규정을 합친 통합 규정집 한 개는 모두 ④ Qwen 규정 챗봇·AI 연결에서 규정 단위로 자동 정규화됩니다. 따라서 list_regulations → get_regulation_toc → get_regulation_article의 논리 결과는 같은 규정·목차·조문을 가리켜야 합니다. 계층 색인은 번들을 만들거나 갱신할 때 자동 생성되므로 별도로 다시 만들 필요가 없습니다. 다만 출처 추적을 위해 원본 document_id와 보관 파일 수는 다를 수 있습니다. 원문에 규정 제목이나 조문 번호가 없어 규정 단위를 구분할 수 없으면 결과 확인 단계에서 검수가 필요합니다. 특히 별표·붙임 뒤의 같은 페이지에서 새 규정이 시작한다면, 새 규정 제목과 제1조만 두지 말고 번호가 있는 목차나 새 페이지의 편·장 제목처럼 경계를 확인할 수 있는 표지를 남기세요. 경계가 불명확하면 일부 규정만 잘못 만드는 대신 생성이 안전하게 멈춥니다.

[!IMPORTANT] ④ MCP로 쓸 파일 묶음 만들기는 선택한 규정의 현재 청크가 모두 승인되었거나 명시적으로 거부된 상태여야 진행됩니다. 검토가 남은 청크가 하나라도 있으면 안전하게 멈춥니다. 이때는 ③ 검수하고 승인으로 돌아가 원문과 비교해 승인 또는 거부를 결정하고, 문서 색인까지 완료한 뒤 다시 ④를 실행하세요. 한 규정의 현재 청크를 모두 명시적으로 거부했다면 그 규정은 MCP에서 제외되며, 다른 승인 규정의 생성을 막지 않습니다. 단, MCP에 넣을 승인·색인 규정이 최소 한 건은 있어야 합니다. 반려는 사유·담당자·결정 시각과 결정 후 내용 해시가 검토 기록에 남아야 하며, 파일의 상태 글자만 임의로 rejected로 바꾼 경우에는 생성기가 안전하게 멈춥니다. 계층 색인을 사용자가 따로 만들 필요는 없습니다. 거부·분할·병합으로 빠진 청크의 본문은 전달 ZIP에 넣지 않습니다. 대신 모든 현재 청크가 왜 포함되거나 제외됐는지 확인할 수 있도록 결정 ID·시각·내용 해시·분류만 담은 봉인된 최소 감사 스냅샷을 함께 만듭니다. 검토 사유, 담당자, 원문 경로와 원본 검토 저널은 전달 ZIP과 MCP 답변에 포함하지 않습니다. 전달 ZIP의 approvals.jsonl 역시 원본 검토 저널이 아니라 승인 ID·기관·문서·승인 시각·청크 ID·승인 내용 해시만 남긴 최소 결정 원장입니다. 담당자 이름, 메모, 검토 이벤트와 작업 PC 경로는 포함하지 않습니다.

처음 보는 규정을 추가할 때

1. ① 문서 올려서 전처리에서 파일을 올립니다.
2. 자동 인식된 규정명, 규정 번호, 버전, 개정일과 시행일을 원문과 비교합니다.
3. ② 결과 확인에서 구조와 내용을 검수합니다.
4. 사용할 청크를 승인하고 색인 완료를 확인합니다.
5. MCP를 다시 만들거나 기존 운영 절차에 따라 갱신한 뒤 list_regulations의 total_count와 새 규정명을 확인합니다.

성공 신호: 새 규정은 목록에 한 번만 나타나고, 목차에서 조문·별표·부칙으로 내려갈 수 있습니다.

기존 규정의 최신 개정본을 넣을 때

기존 파일을 덮어쓰지 말고 같은 규정의 새 버전으로 추가합니다. 그래야 언제 어떤 본문이 유효했는지 이력을 잃지 않습니다.

1. 개정본 파일을 추가하고 기존 규정과 같은 규정 계열인지 확인합니다.
2. 새 버전, 개정일, 시행일과 이전 버전 관계를 확인합니다.
3. 바뀐 조문뿐 아니라 목차·별표·부칙과 인용 관계도 원문과 비교합니다.
4. 새 버전을 승인하고 색인합니다.
5. 변경된 규정 단위의 색인이 끝났는지 확인합니다. 변경 없는 다른 규정은 다시 색인하지 않습니다.
6. 현재 날짜 조회와 과거 기준일 조회를 각각 실행해 올바른 버전이 선택되는지 봅니다.

성공 신호: 기본 조회에는 기준일에 유효한 현재본이 나오고, 이력 포함 또는 과거 as_of_date 조회에는 승인된 이전 버전과 효력 기간이 구분되어 나옵니다.

[!IMPORTANT] 제목이 비슷하다는 이유만으로 새 파일을 기존 규정에 임의로 연결하지 마세요. 규정 번호·버전·시행일과 원문의 개정 관계가 불명확하면 별도 규정으로 검토하거나 담당자가 계보를 확인한 뒤 승인합니다.

구조·조문·참조·개정 상태를 확인하는 질문 예시

승인된 규정 전체 목록과 total_count를 보여줘.
인사규정의 목차에서 장·절·조·별표·부칙을 보여줘.
인사규정 제16조의 승인 원문과 출처를 보여줘.
인사규정이 다른 규정을 참조하는 부분과 인사규정을 참조하는 규정을 보여줘.
현재 적재된 규정 사이의 순환참조를 보여줘.
2026-08-01을 기준으로 인사규정 제16조에 적용되는 버전을 보여줘.

목록·목차·조문은 구조 도구로 확인하고, 주제나 표현을 모를 때는 search와 fetch를 사용합니다. 참조 대상 규정이 아직 적재되지 않았다면 참조는 미해결 상태로 표시될 수 있으므로, “미해결”을 “참조가 없음”으로 해석하지 않습니다.

2. 다섯 방법 중 하나 선택하기

④ Qwen 규정 챗봇·AI 연결에 보이는 다섯 동그라미와 아래 방법 A~E는 순서와 이름이 정확히 같습니다. 내가 실제로 사용할 앱 한 줄만 고른 뒤 그 방법만 따라갑니다.

방법	Builder에서 누를 정확한 글자	연결되는 곳	최종적으로 옮길 값
A	Claude Code	같은 PC의 Claude Code CLI	생성된 claude_code_add_stdio.ps1 실행
B	Codex CLI / Codex IDE	같은 PC의 Codex	생성된 TOML 블록
C	Claude Desktop	같은 PC의 Claude Desktop	Builder가 만든 전체 JSON 또는 서버 한 항목
D	ChatGPT · Vercel HTTPS MCP	ChatGPT의 원격 MCP	검증을 통과한 고정 https://...vercel.app/mcp 주소
E	Claude · Vercel HTTPS MCP	Claude의 원격 Connector	검증을 통과한 고정 https://...vercel.app/mcp 주소

[!IMPORTANT] 방법 A·B·C는 로컬 STDIO이고, 방법 D·E는 Vercel HTTPS입니다.

• A·B·C에는 이 PC의 command, args, env 또는 생성된 설정 파일을 사용합니다.
• D·E에는 Vercel의 HTTPS /mcp URL만 사용합니다.
• Claude Desktop의 개발자 > 구성 편집과 Claude의 Connectors는 서로 다른 화면입니다.
• ChatGPT는 로컬 STDIO에 직접 연결하지 않습니다. 방법 D의 ChatGPT 웹 Developer mode와 원격 HTTPS MCP를 사용하세요.
• Claude Code는 명령창에서 쓰는 Claude CLI인 방법 A이고, Claude Desktop은 설정 JSON을 편집하는 데스크톱 앱인 방법 C입니다.

아래 다섯 줄 중 내가 실제로 쓸 앱 한 줄만 고르면 됩니다.

1. Claude Code / Claude CLI에 붙일 것 → 방법 A
2. Codex CLI / Codex IDE에 붙일 것 → 방법 B
3. Claude Desktop 앱의 JSON 설정 파일에 붙일 것 → 방법 C
4. ChatGPT의 HTTPS MCP URL 칸에 붙일 것 → 방법 D
5. Claude Connectors의 HTTPS URL 칸에 붙일 것 → 방법 E

헷갈리면 이 한 줄만 기억하면 됩니다.

• A는 Claude Code(Claude CLI) 입니다.
• C는 Claude Desktop 입니다.
• D와 E는 로컬 명령이 아니라 HTTPS URL만 넣는 원격 연결입니다.

방법 A — Claude Code 로컬 STDIO

언제 선택하나요? Builder와 Claude Code를 같은 PC에서 사용할 때 선택합니다.

1. Builder에서 Claude Code 왼쪽 동그라미를 누릅니다.
2. 저장 폴더와 MCP 이름을 넣고 MCP로 쓸 파일 묶음 만들기를 누릅니다.
3. 생성된 번들 폴더를 열고 그 폴더에서 PowerShell을 엽니다.
4. .\claude_code_add_stdio.ps1을 실행합니다.
5. claude mcp list에서 방금 만든 이름을 확인합니다.
6. Claude Code를 다시 열고 search와 fetch를 차례로 호출합니다.

방법 A 화면과 명령을 그대로 따라가기

성공 신호: claude mcp list에 서버가 보이고 실제 승인 원문이 반환됩니다. 막히면: 상세 절차의 claude mcp get 결과와 번들 진단 스크립트를 확인합니다.

방법 B — Codex CLI / Codex IDE 로컬 STDIO

언제 선택하나요? Codex CLI 또는 Codex IDE를 Builder와 같은 PC에서 사용할 때 선택합니다. ChatGPT 사용자는 방법 D로 이동하세요.

1. Builder에서 Codex CLI / Codex IDE 왼쪽 동그라미를 누릅니다.
2. 저장 폴더와 MCP 이름을 넣고 번들을 만듭니다.
3. 생성된 codex_config_snippet.toml의 블록 전체를 사용자 ~/.codex/config.toml에 붙여 넣고 Codex를 다시 시작합니다.
4. 새 대화에서 search와 fetch를 차례로 호출합니다.

방법 B 화면과 각 입력 칸을 그대로 따라가기

성공 신호: Codex가 설정 블록을 읽고 도구 목록을 표시합니다. 막히면: TOML 블록을 기존 설정 아래에 별도 블록으로 붙였는지, 번들 폴더를 생성 뒤 옮기지 않았는지 확인합니다.

Builder가 만든 mcp_config.bundle.json의 quickstart.codex_claude_team에는 Codex를 구현·수정 담당, Claude Code를 독립 감리 담당으로 두는 기본 handoff 순서와 공유 검증 산출물이 함께 들어 있습니다. 두 클라이언트를 같은 승인 번들로 병행 운용할 때는 이 계약을 기준으로 validate_client_config_smoke.ps1 이후 search와 fetch를 양쪽에서 같이 확인하세요.

저장소에는 Claude Code의 읽기 전용 프로젝트 에이전트 regulation-security-auditor와 regulation-release-reviewer도 포함됩니다. Codex가 구현과 focused test를 마치면 보안 감리, 보완, 릴리스 회귀 감리 순으로 handoff하며, Claude 에이전트는 구현 파일을 직접 수정하지 않습니다. 에이전트 정의를 새로 추가하거나 바꾼 뒤에는 Claude Code 세션을 새로 열어 프로젝트 정의를 다시 읽게 하세요.

방법 C — Claude Desktop 로컬 STDIO

언제 선택하나요? Claude Desktop과 Builder를 같은 Windows PC에서 사용할 때 선택합니다.

1. Builder에서 Claude Desktop 왼쪽 동그라미를 누릅니다.
2. 저장 폴더와 MCP 이름을 넣고 번들을 만듭니다.
3. Builder 완료 화면에서 첫 번째 JSON 상자인 처음 연결할 때: 설정 파일 전체에 붙여 넣을 JSON 복사를 누릅니다.
4. Claude Desktop에서 프로필 > 설정 > 개발자 > 로컬 MCP 서버 > 구성 편집을 누릅니다.
5. 처음 설치한 빈 설정 파일이면 열린 claude_desktop_config.json 파일 전체를 선택해 3번에서 복사한 JSON으로 바꾸고 저장합니다.
6. 기존 서버가 있으면 지우지 말고 Builder의 두 번째 JSON 상자인 기존 서버가 있을 때: mcpServers 안에 넣을 새 서버 한 항목 복사를 사용합니다. 정확한 삽입 위치는 방법 C의 기존 설정 병합 예시에 완성된 JSON으로 보여 줍니다.
7. Claude Desktop을 완전히 종료했다가 다시 열고 running을 확인합니다.
8. 새 대화에서 search와 fetch를 차례로 호출합니다.

방법 C 화면과 JSON 위치를 그대로 따라가기

성공 신호: 서버 이름 옆 파란 배지가 running이고 승인 원문이 반환됩니다. 막히면: 기존 서버 설정을 지우지 말고 상세 절차의 JSON 병합 예시와 disconnected 진단을 확인합니다.

방법 D — ChatGPT · Vercel HTTPS MCP

Vercel 주소가 아직 없어도 D를 선택하고 배포 준비용 MCP 묶음을 만들 수 있습니다.

1. ④에서 ChatGPT · Vercel HTTPS MCP를 선택하고 MCP 이름을 입력한 뒤 묶음을 만듭니다.
2. 바로 아래 Vercel 계정 연결에서 계정을 연결하고 새 프로젝트 또는 기존 주소 업데이트를 선택합니다.
3. 공개 동의 후 Vercel에 배포하고 연결 검사를 누릅니다. 완료 화면의 주소를 복사합니다.
4. ChatGPT Plugins → + → Add custom MCP server에서 이름·주소를 입력하고 No authentication으로 만듭니다.
5. 개인 플러그인 목록에서 설치한 뒤 Work 새 대화에서 @로 선택하고 search → fetch를 확인합니다.

묶음을 다시 만들 필요가 없습니다. 메뉴는 계정·워크스페이스에 따라 다를 수 있습니다. OpenAI 공식 연결 안내와 주소 입력 상세를 참고하세요.

방법 E — Claude · Vercel HTTPS MCP

1. ④에서 Claude · Vercel HTTPS MCP를 선택하고 이름을 입력해 묶음을 만듭니다.
2. Vercel 계정 연결 → 공개 동의 → Vercel에 배포하고 연결 검사를 차례로 진행합니다.
3. 완료 화면의 주소를 Claude Customize > Connectors > Add custom connector에 등록합니다. 공개 MCP는 별도 인증이 없습니다.
4. 새 대화에서 커넥터를 켜고 search → fetch로 원문과 출처를 확인합니다.

조직 계정은 관리자가 커넥터를 추가해야 할 수 있습니다. Claude 공식 연결 안내와 입력 상세를 참고하세요.

생성 완료 화면 읽는 법

아래는 로컬 STDIO·고급 수동 배포의 기존 화면 설명입니다. 새 Vercel 버튼 배포는 이 문서 위의 “프로그램에서 Vercel 배포까지”를 따르세요.

MCP 파일 묶음 생성 완료가 나오면 아래의 직접 MCP 연결 및 최종 확인까지 내려갑니다. 이 영역은 두 방식을 항상 비교해 보여 주고, 이번에 선택한 방식에는 실제 다음 명령과 등록 위치를 표시합니다.

실제 생성 완료 화면에서 확인할 곳

현재 생성 완료 화면의 값은 선택한 앱에 따라 달라집니다. ChatGPT는 웹 원격 HTTPS만, Codex·Claude의 같은-PC 연결은 로컬 STDIO로 표시됩니다. 이전 화면의 ChatGPT 로컬 설정 파일은 현재 실행 설정이 아니라 지원 종료 경고 파일이므로 이 안내에서는 사용하지 않습니다.

위에서 아래로 다음 다섯 곳을 확인합니다.

1. MCP 파일 묶음 생성 완료: 로컬 번들과 연결 파일 생성이 끝났다는 뜻입니다.
2. 첫 번째 HTTP MCP 주소: Vercel에 등록할 /mcp 주소 자리입니다. 캡처에서는 지웠지만 내 화면에서는 실제 주소를 끝까지 복사합니다.
3. 생성된 파일: connect_mcp_client.ps1, 앱별 설정 파일, README.ko.md 등이 만들어졌는지 확인합니다.
4. 초록색 선택한 AI 앱: 이번에 먼저 따라야 할 연결 절차를 알려 줍니다.
5. 아래쪽 최근 생성한 MCP 파일 묶음: 방금 만든 ZIP과 폴더를 다시 찾을 위치입니다.

[!IMPORTANT] 이 화면의 초록색 완료 문구는 로컬 파일 생성 완료입니다. Vercel 배포 완료가 아닙니다. Vercel은 V-6의 vercel --prod를 실행한 뒤 Ready, Aliased와 원격 smoke 성공까지 확인해야 합니다.

생성 버튼을 누르기 전 — 연결 앱·저장 폴더·서버 이름

완료 화면보다 먼저 아래 입력 화면이 나옵니다. 여기서 선택한 앱에 따라 아래쪽에 표시되는 등록 안내와 생성 설정 파일이 달라집니다. 캡처의 규정명, 저장 경로, ZIP 경로와 서버 이름은 공개용으로 지웠습니다. 내 화면에서는 이 칸을 비우지 말고 실제 값을 입력해야 합니다.

Codex CLI·IDE에 로컬 STDIO로 연결할 때

위 화면에서는 다음 순서로만 움직입니다.

1. 맨 위 선택 규정 MCP 준비 상태의 오른쪽 상태가 준비 완료인지 확인합니다.
2. 연결할 AI 앱에서 Codex CLI / Codex IDE 왼쪽 동그라미를 누릅니다.
3. 바로 아래에 선택된 연결 방식: 로컬 stdio가 보이는지 확인합니다.
4. Windows 탐색기에서 저장 폴더 선택을 누르고, 나중에 옮기지 않을 폴더를 고릅니다.
5. 처음에는 **폴더 + 전달용 ZIP (권장)**을 그대로 선택합니다.
6. **생성할 MCP 이름 (필수 입력)**에 앱에서 알아보기 쉬운 이름을 넣습니다. 이 값은 폴더 경로나 실행 명령이 아니라 MCP 서버 목록에 표시될 이름입니다.
7. 빨간 MCP로 쓸 파일 묶음 만들기 버튼을 한 번 누르고 100%가 될 때까지 기다립니다.

[!IMPORTANT] 전달용 ZIP을 다른 Windows PC로 옮겨 로컬 STDIO MCP를 실행하려면 그 PC에 Python 3.11 이상이 필요합니다. ZIP을 푼 뒤 먼저 install_local_package.ps1을 실행해 포함된 wheel을 설치하고, 그 다음 앱 등록·진단을 진행하세요. wheel은 Python 자체가 아닙니다. Python 설치 불필요 안내는 원래 PC에서 생성 폴더를 그대로 사용하는 경우, 즉 PR MCP Builder.exe가 함께 있는 경우에만 해당합니다.

Claude Desktop, ChatGPT · Vercel HTTPS MCP 같은 다른 동그라미를 동시에 선택하는 것이 아닙니다. 한 번 생성할 때 하나의 연결 앱만 고릅니다.

Claude Desktop에 로컬 STDIO로 연결할 때

Claude Desktop은 위 화면에서 다음 차이만 주의합니다.

1. 연결할 AI 앱에서 Claude Desktop 왼쪽 동그라미를 누릅니다.
2. Claude · Vercel HTTPS MCP가 아니라 Claude Desktop이 선택됐는지 다시 봅니다.
3. 저장 폴더와 MCP 이름을 채우고 MCP로 쓸 파일 묶음 만들기를 누릅니다.
4. 생성이 끝나면 아래 방법 C에서 JSON 복사 → 구성 편집 → 파일 전체 붙여 넣기를 순서대로 진행합니다.

[!TIP] 저장 경로와 서버 이름이 회색 또는 흰색 빈칸처럼 보이는 것은 공개용 비식별 처리입니다. 실제 사용자는 Builder가 표시한 경로와 자신이 입력한 서버 이름을 그대로 사용합니다.

• 같은 Windows PC의 Claude Code·Codex·Claude Desktop에서 쓸 것이면 방법 A·B·C 중 해당 앱의 로컬 STDIO 절차만 따라갑니다.
• ChatGPT 또는 Claude에서 Vercel 주소로 원격 사용할 것이면 방법 D 또는 E로 갑니다.
• 화면에 command, args, env가 보이면 로컬 STDIO 안내입니다. 이때는 URL을 넣지 않습니다.
• 화면에 https://.../mcp가 보이면 Vercel HTTPS 안내입니다. 이때는 내 PC의 폴더 경로나 command, args, env를 넣지 않습니다.
• 어느 쪽이든 마지막은 서버 이름이 보이는 것에서 끝나지 않고 search와 fetch가 실제로 성공해야 완료입니다.
• 로컬 STDIO를 선택한 경우: 생성된 실제 command/args/env, 앱별 설정 파일과 완전 재시작 순서가 보입니다. Windows 실행판은 포함된 PR MCP Builder.exe --mcp-server를 사용하므로 Python 진단 스크립트를 실행하지 않습니다. 소스 실행에서만 doctor_mcp_connection.ps1과 validate_mcp_smoke.ps1가 표시됩니다.
• Vercel HTTPS를 선택한 경우: 입력한 Production /mcp URL, staging 명령, vercel --prod, Connectors 등록, 원격 smoke 순서가 보입니다.
• 번들 폴더에는 양쪽 연결 파일이 들어갈 수 있지만, 현재 선택한 방식의 절차부터 완료합니다.
• MCP 파일 묶음 생성 완료는 Vercel 배포 완료가 아닙니다. Vercel은 Ready와 Aliased URL을 확인하고 원격 smoke까지 통과해야 합니다.

화면의 문구를 다음처럼 읽으면 됩니다.

완료 화면에 보이는 항목	정확한 뜻	지금 할 일
MCP 실행 데이터와 연결 파일 묶음을 만들었습니다	내 PC에 번들 폴더를 만들었음	아래 최근 생성한 MCP 파일 묶음 경로 열기
HTTP MCP 주소	앞으로 등록할 원격 주소	Vercel이 Ready가 되기 전에는 아직 사용하지 않기
선택한 AI 앱	이번에 우선 보여 줄 등록 절차	표시된 앱의 안내부터 따라 하기
생성된 파일	로컬 번들 안의 설정·진단 파일 목록	파일명과 폴더 경로 확인
직접 MCP 연결 및 최종 확인	실제 설치·배포·검증 안내	이 영역 끝의 search·fetch까지 완료

[!IMPORTANT] 완료 화면에 HTTPS 주소가 이미 적혀 있어도 서버가 자동으로 인터넷에 올라간 것은 아닙니다. 번들 생성 → staging 생성 → Vercel Production 배포 → 원격 smoke는 서로 다른 네 단계입니다.

초보자 기준으로는 이 화면을 아래처럼 읽으면 됩니다.

1. 맨 위 이번에 선택한 방식 줄을 먼저 봅니다.
2. 로컬 STDIO라면 claude_desktop_config.json 또는 해당 앱 설정 파일만 따라갑니다.
3. Vercel Streamable HTTP(HTTPS)라면 로컬 명령은 무시하고 vercel --prod 뒤 Aliased: 줄에서 복사한 실제 /mcp 주소만 사용합니다.
4. doctor_mcp_connection.ps1, validate_mcp_smoke.ps1는 소스 실행 전용 로컬 진단입니다. Windows 실행판은 생성된 EXE 설정을 그대로 등록하고 앱을 완전히 재시작한 뒤 새 대화에서 search와 fetch를 확인합니다.
5. reg-rag-mcp-vercel-stage, vercel, reg-rag-mcp-client-config-smoke는 원격 배포 및 검증용입니다.
6. 마지막 줄의 search then fetch 예시까지 성공해야 끝입니다. 서버 이름만 보여도 아직 완료가 아닙니다.

방법 A 상세: Claude Code 로컬 STDIO 연결

1. Builder의 ④ Qwen 규정 챗봇·AI 연결에서 Claude Code 왼쪽 동그라미를 누릅니다.
2. 선택된 연결 방식: 로컬 stdio가 보이는지 확인합니다.
3. 저장 폴더와 MCP 이름을 넣고 MCP로 쓸 파일 묶음 만들기를 누릅니다.
4. 생성이 끝나면 Windows 파일 탐색기에서 방금 만든 번들 폴더를 엽니다.

위 그림은 위치를 설명하는 예시입니다. 그림 속 C:\MCP-Bundles\my-regulations를 입력하지 말고, 방금 Builder가 만든 내 번들 폴더를 여세요.

5. 탐색기 위쪽 주소 표시줄을 클릭하고 powershell을 입력한 뒤 Enter를 누릅니다.
6. 열린 PowerShell에서 아래 한 줄을 실행합니다.

.\claude_code_add_stdio.ps1

7. 같은 PowerShell에서 아래 명령으로 등록된 서버 이름을 확인합니다.

claude mcp list

8. 목록에 방금 만든 서버 이름이 보이면 그 이름을 그대로 넣어 다시 조회합니다. 예를 들어 내 서버 이름을 test2로 만들었다면 아래처럼 실행합니다.

claude mcp get test2

9. Claude Code를 완전히 종료했다가 다시 열고 새 대화에서 아래 두 줄을 보냅니다.

연결한 규정 MCP의 search 도구로 복무를 검색해 줘.
첫 번째 검색 결과의 id를 fetch 도구에 넣어 원문과 출처를 보여 줘.

search 결과와 fetch 본문·출처가 모두 나오면 방법 A가 끝난 것입니다. 생성된 스크립트는 공식 claude mcp add --transport stdio --scope user 형식으로 등록합니다.

아래 그림처럼 search, fetch와 본문 반환이 모두 성공해야 끝입니다. 서버 이름만 목록에 보이는 것은 아직 연결 완료가 아닙니다.

방법 B 상세: Codex CLI / Codex IDE 로컬 STDIO 연결

1. Builder의 ④ Qwen 규정 챗봇·AI 연결에서 Codex CLI / Codex IDE를 선택합니다.
2. 저장 폴더와 MCP 이름을 입력하고 MCP로 쓸 파일 묶음 만들기를 누릅니다.
3. 100%와 MCP 파일 묶음 생성 완료가 보이면 아래 B-2로 이동합니다.

[!WARNING] ChatGPT는 로컬 STDIO MCP에 직접 연결하지 않습니다. 과거 화면에 ChatGPT용 STDIO 입력란이 보이더라도 이 프로그램의 지원 경로로 사용하지 말고 방법 D의 ChatGPT 웹 원격 MCP를 사용하세요.

B-2. Codex CLI·IDE에 생성된 TOML 넣기

ChatGPT의 인자 입력 화면은 열지 않습니다. Codex CLI 또는 Codex IDE에서 아래 순서를 계속합니다.

1. Codex CLI와 Codex IDE를 완전히 종료합니다.
2. Windows 파일 탐색기에서 Builder가 만든 번들 폴더를 엽니다.
3. codex_config_snippet.toml을 메모장이나 VS Code로 엽니다.
4. 파일 안에서 Ctrl+A를 누른 다음 Ctrl+C를 눌러 파일 전체를 복사합니다.
5. Win+R을 누릅니다.
6. 아래 한 줄을 그대로 입력하고 Enter를 누릅니다.

notepad %USERPROFILE%\.codex\config.toml

7. 열린 config.toml이 비어 있으면 그대로 Ctrl+V를 누릅니다.
8. 기존 설정이 있으면 지우지 말고 파일 맨 아래를 클릭합니다.
9. Enter를 두 번 눌러 빈 줄을 만든 뒤 Ctrl+V를 누릅니다.
10. Ctrl+S로 저장하고 메모장을 닫습니다.
11. Codex CLI 또는 Codex IDE를 다시 실행합니다.
12. MCP 목록에서 방금 만든 서버가 보이는지 확인합니다.
13. 새 대화에서 아래 두 문장을 보내 search와 fetch를 실제로 호출합니다.

연결한 규정 MCP의 search 도구로 복무를 검색해 줘.
첫 번째 검색 결과의 id를 fetch 도구에 넣어 원문과 출처를 보여 줘.

기존 파일이 아래처럼 다른 MCP 서버 하나를 가지고 있었다고 가정합니다.

[mcp_servers.weather]
command = "weather-mcp"
args = []

Builder가 만든 codex_config_snippet.toml 전체를 그 아래에 붙이면 위치는 아래처럼 됩니다. 이 예시의 경로나 이름을 직접 입력하지 말고, 내 번들의 파일 전체를 복사하세요.

[mcp_servers.weather]
command = "weather-mcp"
args = []

[mcp_servers.기관_규정]
command = "powershell.exe"
startup_timeout_sec = 45
cwd = "C:/MCP 번들/기관 규정"
args = [
  "-NoProfile",
  "-ExecutionPolicy",
  "Bypass",
  "-File",
  "C:/MCP 번들/기관 규정/run_mcp_stdio_server.ps1",
  "--data-dir",
  "C:/MCP 번들/기관 규정/data",
  "--tenant-id",
  "default",
  "--transport",
  "stdio",
  "--profile-id",
  "institution-example",
  "--flat-storage",
  "--tool-profile",
  "chatgpt-data",
  "--no-warm-cache",
]

확인할 것은 세 가지뿐입니다.

1. 기존 weather 블록은 그대로 남아 있습니다.
2. 새 [mcp_servers.기관_규정] 블록은 파일 맨 아래의 별도 블록입니다.
3. 같은 [mcp_servers.기관_규정] 제목이 이미 있으면 두 개를 만들지 말고 기존 그 블록만 지운 뒤 새 블록으로 바꿉니다.

search 결과와 그 결과의 id를 사용한 fetch 본문·출처가 모두 나오면 Codex 연결 완료입니다.

방법 C 상세: Claude Desktop 로컬 STDIO 연결

[!IMPORTANT] 이 안내에서는 명령어나 경로를 직접 만들지 않습니다. Builder에서 복사하고, Claude Desktop 설정 파일에 붙여 넣은 다음 running만 확인합니다.

[!TIP] 처음 연결이면 C-1부터 C-7까지만 그대로 하면 끝입니다.

1. Builder에서 Claude Desktop과 로컬 STDIO를 선택하고 번들을 만듭니다.
2. 완료 화면에서 처음 연결할 때: 설정 파일 전체에 붙여 넣을 JSON 복사를 누릅니다.
3. Claude Desktop에서 프로필 → 설정 → 개발자 → 구성 편집으로 들어갑니다.
4. 열린 claude_desktop_config.json 파일 전체에 Ctrl+A → Ctrl+V → Ctrl+S를 합니다.
5. Claude Desktop을 **종료(Quit)**까지 해서 완전히 끕니다.
6. Claude Desktop을 다시 켭니다.
7. 프로필 → 설정 → 개발자 → 로컬 MCP 서버에서 파란색 running을 확인합니다.

C-8과 C-9는 기존 설정이 있거나 실패했을 때만 읽습니다.

[!NOTE] 실제 캡처에서는 계정 이름, 이메일, 최근 대화, 로컬 절대경로, 서버 이름과 ID처럼 공개하면 안 되는 글자만 주변과 같은 색으로 가렸습니다. 가려진 빈칸을 비워 두라는 뜻은 아닙니다. Windows 작업표시줄도 개인정보 노출을 막기 위해 제거했습니다.

C-1. Builder에서 Claude Desktop 번들 만들기

1. Builder의 ④ Qwen 규정 챗봇·AI 연결 화면까지 내려갑니다.
2. 연결할 AI 앱에서 Claude Desktop을 누릅니다.
3. 로컬 STDIO가 선택되었는지 확인합니다.
4. 저장할 폴더와 MCP 이름을 입력합니다.
5. 빨간 MCP로 쓸 파일 묶음 만들기 버튼을 누릅니다.
6. 파란 진행 막대가 100%가 되고 MCP 파일 묶음 생성 완료가 보일 때까지 기다립니다.

C-2. Builder에서 JSON 복사하기

1. 생성 완료 화면을 아래로 내립니다.
2. Claude Desktop에 등록하는 방법을 찾습니다.
3. 먼저 보이는 생성된 설정 파일 경로 복사와 Claude Desktop 설정 위치는 경로 확인용입니다. 이 두 상자의 복사 아이콘은 누르지 않습니다.
4. 제목이 정확히 처음 연결할 때: 설정 파일 전체에 붙여 넣을 JSON 복사를 찾습니다.
5. 그 제목 바로 아래 코드 상자 오른쪽 위 복사 아이콘을 한 번 누릅니다.
6. 복사한 내용은 수정하지 않습니다. 서버 이름, Python 경로, args, env가 모두 들어 있습니다.

아래 캡처는 이전 버전 Builder 화면이라 같은 상자의 제목이 병합할 mcpServers JSON 복사로 보일 수 있습니다. 처음 연결이라면 그 상자 전체를 복사하면 됩니다. 현재 Builder에서는 처음 연결할 때: 설정 파일 전체에 붙여 넣을 JSON 복사로 표시됩니다.

스크린샷에서 개인정보 보호를 위해 가린 서버 이름과 경로를 직접 입력하지 마세요. 내 Builder 화면의 복사 아이콘으로 가져온 값만 사용합니다.

C-3. Claude Desktop 설정 파일 열기

1. Claude Desktop에서 설정 열기

1. 설치된 Claude Desktop 앱을 엽니다.
2. 왼쪽 아래 프로필 영역을 누릅니다.
3. 열린 메뉴에서 톱니바퀴 모양 설정을 누릅니다.

2. 구성 편집 누르기

1. 설정 창 왼쪽 메뉴를 아래로 내립니다.
2. 데스크톱 앱 아래의 개발자를 누릅니다.
3. 오른쪽 로컬 MCP 서버 화면에서 구성 편집을 누릅니다.

클릭 경로는 설정 > 개발자 > 로컬 MCP 서버 > 구성 편집입니다.

3. 설정 파일 열기

1. Windows 파일 탐색기가 열리면 가운데에서 claude_desktop_config 파일을 찾습니다.
2. 파일을 두 번 클릭합니다.
3. 어떤 앱으로 열지 묻는다면 메모장 또는 Visual Studio Code를 선택합니다.

파일 확장명이 숨겨진 Windows에서는 .json이 보이지 않을 수 있습니다. 파일 종류가 JSON 원본 파일이면 맞습니다.

직접 폴더를 열어야 한다면 실제 위치는 아래입니다.

%APPDATA%\Claude\claude_desktop_config.json

C-4. JSON 붙여 넣고 저장하기

처음 설치해 설정 파일이 비어 있거나 {}만 보이는 경우입니다.

초보자는 아래 한 문장만 기억하면 됩니다.

• Builder의 첫 번째 JSON 상자 전체를 복사해서, 열린 claude_desktop_config.json 파일 전체를 덮어씁니다.

1. 열린 설정 파일 안을 한 번 클릭합니다.
2. 키보드에서 Ctrl+A를 눌러 기존 내용을 모두 선택합니다.
3. Ctrl+V를 눌러 C-2에서 복사한 JSON을 붙여 넣습니다.
4. Ctrl+S를 눌러 저장합니다.
5. 편집기를 닫습니다.

붙여 넣을 위치는 파일 전체입니다. {} 안쪽에 넣는 것이 아닙니다. {}가 보이면 Ctrl+A로 {}까지 선택한 뒤 복사한 전체 JSON으로 바꿉니다. 초보자는 mcpServers 안쪽 줄을 손으로 맞추지 않습니다. 파일 전체 선택 후 그대로 붙여 넣기만 하면 됩니다.

스크린샷의 서버 이름, 경로, profile ID는 공개용으로 가렸고 Windows 작업표시줄도 제거했습니다. 빈칸을 따라 입력하지 말고 C-2에서 복사한 JSON을 그대로 붙여 넣습니다.

파일 안에 다른 서버나 preferences가 이미 있었다면 덮어쓰지 마세요. 저장하지 말고 닫은 뒤 C-8로 내려갑니다.

C-5. Claude Desktop 완전히 종료하고 다시 열기

1. Claude Desktop 창 오른쪽 위 X를 누릅니다.
2. Windows 화면 오른쪽 아래의 ^ 숨겨진 아이콘 표시를 누릅니다.
3. Claude 아이콘을 마우스 오른쪽 버튼으로 누릅니다.
4. **종료(Quit)**를 누릅니다.
5. Claude Desktop을 다시 실행합니다.

창만 닫으면 이전 설정이 남을 수 있으므로 **종료(Quit)**까지 해야 합니다.

C-6. running 확인하기

1. Claude Desktop 왼쪽 아래 프로필을 누릅니다.
2. 설정을 누릅니다.
3. 왼쪽의 개발자를 누릅니다.
4. 로컬 MCP 서버에서 방금 만든 서버 이름을 누릅니다.
5. 서버 이름 옆 파란 배지가 **running**인지 확인합니다.

이 화면에서는 다음 세 곳만 보면 됩니다.

1. 서버 이름 옆에 running
2. 가운데에 명령어와 인수
3. 아래에 로그 보기

running이 보이면 서버 실행까지 성공한 것입니다.

여기서 끝내지 말고 바로 아래 C-7까지 진행해야 실제 검색도 되는지 확인됩니다.

C-7. search와 fetch 확인하기

1. Claude Desktop 설정 창을 닫습니다.
2. 새 대화를 엽니다.
3. 아래 두 줄을 통째로 복사해 대화창에 붙여 넣고 전송합니다.

연결한 규정 MCP의 search 도구로 복무를 검색해 줘.
첫 번째 검색 결과의 id를 fetch 도구에 넣어 원문과 출처를 보여 줘.

아래 세 가지가 모두 보이면 연결 완료입니다.

1. 설정 화면의 서버 상태가 running
2. 대화에서 search 도구가 호출됨
3. 첫 검색 결과를 fetch로 열어 본문과 출처가 표시됨

여기까지 되면 Claude Desktop 연결은 끝입니다.

C-8. 기존 설정이 있을 때 병합하기

claude_desktop_config.json에 다른 서버나 preferences가 이미 있으면 Ctrl+A로 지우면 안 됩니다. 가장 쉬운 방법은 자동 병합입니다.

1. Claude Desktop을 **종료(Quit)**합니다.
2. 파일 탐색기에서 Builder가 만든 번들 폴더를 엽니다.
3. 탐색기 위쪽 주소 표시줄을 클릭합니다.
4. powershell이라고 입력하고 Enter를 누릅니다.
5. 열린 PowerShell에 아래 한 줄 전체를 붙여 넣고 Enter를 누릅니다.

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\connect_mcp_client.ps1" -InstallPackage -Target claude-desktop -InstallClaudeDesktop

6. 명령이 끝나면 Claude Desktop을 다시 실행합니다.
7. C-6으로 돌아가 running을 확인합니다.

정상이라면 PowerShell에서 Installed-config stdio verification passed가 보입니다. 이어서 CLAUDE DESKTOP VERIFICATION REQUIRED가 보여도 정상입니다. Claude를 다시 열어 running을 확인하라는 뜻입니다.

직접 붙여 넣기를 원한다면 Builder의 두 번째 상자인 기존 서버가 있을 때: mcpServers 안에 넣을 새 서버 한 항목 복사를 사용합니다. 이 상자는 기존 파일의 "mcpServers": { ... } 중괄호 안에만 추가합니다. JSON 쉼표가 헷갈리면 직접 편집하지 말고 위 자동 병합을 사용하세요.

직접 병합할 때 정확히 어디에 붙여 넣는지

딱 두 줄로 요약하면 아래와 같습니다.

1. 첫 번째 JSON 상자는 새 파일이거나 빈 파일일 때 파일 전체에 붙여 넣습니다.
2. 두 번째 JSON 상자는 기존 파일에 다른 서버가 있을 때 "mcpServers" 중괄호 안에만 붙여 넣습니다.

아래 세 상자는 위치를 설명하기 위한 완성 예시입니다. 예시의 서버 이름이나 경로를 입력하지 말고, 내 Builder의 두 번째 복사 상자에 나온 내용을 사용합니다.

1. 기존 파일을 열면 아래처럼 다른 서버와 preferences가 있을 수 있습니다.

{
  "mcpServers": {
    "weather-mcp": {
      "command": "C:\\Tools\\weather-mcp.exe",
      "args": []
    }
  },
  "preferences": {
    "theme": "dark"
  }
}

2. Builder에서 기존 서버가 있을 때: mcpServers 안에 넣을 새 서버 한 항목 복사의 복사 아이콘을 누릅니다. 복사되는 모양은 아래처럼 서버 이름 한 항목입니다.

"기관-규정": {
  "command": "C:\\Public Regulation MCP\\.venv\\Scripts\\python.exe",
  "args": [
    "-m",
    "scripts.run_regulation_mcp",
    "--data-dir",
    "C:\\MCP 번들\\기관 규정\\data",
    "--tenant-id",
    "default",
    "--transport",
    "stdio",
    "--profile-id",
    "institution-example",
    "--flat-storage",
    "--tool-profile",
    "full",
    "--no-warm-cache"
  ],
  "env": {
    "PYTHONPATH": "C:\\Public Regulation MCP",
    "PYTHONSAFEPATH": "1"
  }
}

3. 기존 weather-mcp의 마지막 } 뒤에 쉼표 ,를 하나 붙이고, 바로 다음 줄에 Builder에서 복사한 서버 한 항목을 붙여 넣습니다. 최종 파일은 아래처럼 됩니다.

{
  "mcpServers": {
    "weather-mcp": {
      "command": "C:\\Tools\\weather-mcp.exe",
      "args": []
    },
    "기관-규정": {
      "command": "C:\\Public Regulation MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "scripts.run_regulation_mcp",
        "--data-dir",
        "C:\\MCP 번들\\기관 규정\\data",
        "--tenant-id",
        "default",
        "--transport",
        "stdio",
        "--profile-id",
        "institution-example",
        "--flat-storage",
        "--tool-profile",
        "full",
        "--no-warm-cache"
      ],
      "env": {
        "PYTHONPATH": "C:\\Public Regulation MCP",
        "PYTHONSAFEPATH": "1"
      }
    }
  },
  "preferences": {
    "theme": "dark"
  }
}

확인할 것은 세 가지뿐입니다.

1. 새 서버는 "mcpServers": {와 그 닫는 } 사이에 있습니다.
2. 기존 weather-mcp와 새 서버 사이에만 쉼표가 하나 있습니다.
3. 기존 preferences는 mcpServers 밖에 그대로 남아 있습니다.

새 서버를 파일 맨 아래에 붙이거나, args 대괄호 안에 넣거나, 두 번째 "mcpServers"를 새로 만들면 안 됩니다. 저장하기 전에 PowerShell에서 아래 명령을 실행하면 Python 없이도 JSON 쉼표나 중괄호 오류를 먼저 찾을 수 있습니다.

Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" -Raw | ConvertFrom-Json | Out-Null

C-9. disconnected일 때 진단하기

[!IMPORTANT] 아래 두 스크립트는 소스 실행 사용자 전용입니다. Windows 실행판 사용자는 이 스크립트를 실행하거나 Python을 설치하지 말고, Builder가 생성한 PR MCP Builder.exe --mcp-server 설정을 그대로 등록한 뒤 Claude Desktop을 완전히 재시작하고 새 대화에서 search와 fetch를 확인하세요.

1. Builder가 만든 번들 폴더를 엽니다.
2. 탐색기 위쪽 주소 표시줄에 powershell을 입력하고 Enter를 누릅니다.
3. 아래 첫 줄을 실행하고, 끝나면 둘째 줄을 실행합니다.

.\doctor_mcp_connection.ps1
.\validate_mcp_smoke.ps1

첫 명령은 Python·프로젝트·import 오류를 정확히 표시합니다. 둘째 명령은 initialize → tools/list → search → fetch까지 실제 STDIO 연결을 확인합니다.

방법 D·E 공통 준비: Vercel HTTPS 배포와 검증

Vercel HTTPS는 승인된 MCP runtime을 인터넷에서 접속 가능한 서버로 배포하는 방법입니다. 공개 규정은 프로그램의 Vercel 계정 연결 → 배포 버튼을 사용하면 됩니다. 아래 V-1~V-7은 비공개 인증이나 직접 운영이 필요한 담당자를 위한 고급 수동 절차입니다.

처음이라면 Builder에서 원문 검수·승인·색인과 규정 조회를 먼저 확인하세요. Codex나 Claude를 함께 쓴다면 방법 A, B 또는 C의 로컬 search와 fetch까지 성공한 뒤 진행하는 것이 가장 안전합니다. 로컬에서도 검색되지 않는 데이터는 Vercel에 올린다고 검색되기 시작하지 않습니다.

[!WARNING] Vercel로 전송한 MCP 응답은 외부 AI 서비스로 전달될 수 있습니다. 공개 자료 또는 반출 승인을 받은 자료에만 사용하세요. 기관 내부 자료에는 공개 무인증 모드를 사용하지 말고 bearer 인증이나 OAuth를 먼저 설계하세요.

V-1. 준비물 확인

• Vercel 계정: https://vercel.com에서 Sign Up 후 이메일 또는 GitHub 계정으로 가입
• Node.js LTS와 npm: https://nodejs.org에서 LTS 설치판 사용
• Python 3.11 이상
• 사람 승인과 검색 색인이 끝난 배포 준비용 MCP 전달 ZIP
• 소스 실행자는 이 저장소를 그대로 사용할 수 있음

Vercel 주소가 전혀 없는 첫 배포라면 아래 순서로 준비합니다.

1. Builder에서 방법 D 또는 E를 선택하고 URL을 비운 채 배포 준비용 MCP 묶음을 만듭니다.
2. 생성된 전달 ZIP을 새 폴더에 완전히 풉니다.
3. 그 PC에 Python 3.11 이상이 없다면 먼저 설치합니다.
4. 압축을 푼 폴더에서 install_local_package.ps1을 한 번 실행해 포함된 wheel과 reg-rag-mcp-vercel-stage 명령을 설치합니다.
5. 같은 폴더의 data를 사용해 V-2부터 V-7까지 배포와 검증을 끝냅니다.
6. Builder로 돌아가 같은 D 또는 E를 선택하고 검증된 /mcp 주소를 입력해 묶음을 다시 만듭니다.

④ Qwen 규정 챗봇·AI 연결의 생성 버튼은 첫 배포 전에도 사용할 수 있습니다. 이때 만들어지는 것은 배포 준비용 파일이며 실제 AI 연결 완료가 아닙니다. 화면의 URL 예시를 복사하지 말고 V-6에서 얻고 V-7에서 검증한 주소를 넣어 묶음을 다시 만들어야 합니다.

Node.js를 설치한 뒤 새 PowerShell을 열고 다음 두 명령을 실행합니다.

node --version
npm --version

두 명령 모두 숫자 버전을 보여야 합니다. 'node' 또는 'npm'을 찾을 수 없습니다가 나오면 모든 PowerShell 창을 닫고 새로 연 뒤 다시 확인합니다.

V-2. 배포 전용 폴더 만들기

전달 ZIP을 푼 폴더에서 PowerShell을 열고 먼저 다음 명령을 실행합니다. Windows에서 스크립트 실행을 묻거나 차단하면 파일을 이 저장소의 Release에서 받았는지 확인한 뒤 전체 명령을 그대로 사용합니다.

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install_local_package.ps1

설치가 끝나면 같은 창에서 아래 명령을 실행합니다. 첫 번째 경로는 압축을 푼 폴더의 data이고, 두 번째는 새 Vercel 배포 전용 폴더입니다.

$RuntimeDataDir = (Resolve-Path ".\data").Path
$StageDir = Read-Host "새 Vercel 배포 전용 폴더 전체 경로"
reg-rag-mcp-vercel-stage `
  --runtime-data-dir "$RuntimeDataDir" `
  --out-dir "$StageDir"

소스 실행자는 프로젝트 폴더, 즉 README.md, app, scripts가 함께 보이는 폴더에서 다음 명령을 대신 사용할 수 있습니다.

$RuntimeDataDir = Read-Host "생성 번들의 data 폴더 전체 경로"
$StageDir = Read-Host "새 Vercel 배포 전용 폴더 전체 경로"
python scripts\prepare_vercel_mcp_deployment.py `
  --runtime-data-dir "$RuntimeDataDir" `
  --out-dir "$StageDir"

패키지를 이미 설치해 CLI 명령을 사용할 수 있다면 같은 작업을 다음처럼 실행할 수 있습니다.

reg-rag-mcp-vercel-stage `
  --runtime-data-dir "$RuntimeDataDir" `
  --out-dir "$StageDir"

이 명령은 전체 프로젝트나 원본 업로드 폴더를 배포하지 않고 다음 항목만 포함한 vercel-mcp-stage를 만듭니다.

• MCP 실행에 필요한 공개 소스
• api/index.py Vercel 진입점
• vercel.json
• 승인된 MCP runtime

기존 출력 폴더는 자동 덮어쓰지 않습니다. 기존 폴더를 재사용하려면 내용과 비밀값을 확인하고 새 빈 폴더를 선택하는 것이 안전합니다.

명령이 끝나면 방금 입력한 배포 전용 폴더를 파일 탐색기로 열어 최소한 다음 항목이 보이는지 확인합니다.

• api 폴더
• app 폴더
• mcp_runtime 폴더
• vercel.json
• pyproject.toml

하나라도 없으면 아직 배포하지 말고 staging 명령의 빨간 오류부터 해결합니다.

[!CAUTION] .env.local, .vercel, 토큰, 원본 업로드와 보고서 전체를 ZIP이나 Git으로 함께 올리지 마세요. .gitignore만 믿고 폴더 전체를 수동 업로드하지 말고, 위 staging 명령으로 만든 범위를 배포 입력으로 사용하세요.

V-3. Vercel CLI 설치하고 로그인

처음 한 번만 설치합니다.

npm install -g vercel
vercel --version
vercel login

vercel --version이 버전을 보여야 설치된 것입니다. vercel login이 브라우저를 열면 방금 만든 Vercel 계정으로 로그인하고 승인합니다. 브라우저에 성공 표시가 나오면 PowerShell로 돌아와 로그인 완료 문구를 확인합니다. 토큰이나 로그인 링크를 다른 사람에게 보내지 마세요.

[!NOTE] Vercel 홈페이지에서 빈 프로젝트를 먼저 만들 수도 있지만 필수는 아닙니다. 아래 CLI가 프로젝트 생성과 로컬 staging 폴더 연결을 수행합니다. 홈페이지는 이후 상태와 로그를 확인할 때 사용합니다.

즉, 홈페이지에도 들어가지만 실제 배포 명령은 PowerShell에서 실행합니다.

V-4. Vercel 프로젝트 만들고 staging 폴더 연결

아래 명령은 프로젝트 이름을 명령 안에서 찾아 바꾸지 않아도 됩니다. 한 줄씩 그대로 실행하고, 이름을 물을 때만 영문 소문자·숫자·하이픈으로 원하는 이름을 입력합니다.

$StageDir = Read-Host "V-2에서 만든 배포 전용 폴더 전체 경로"
$VercelProject = Read-Host "새 Vercel 프로젝트 이름"
vercel project add $VercelProject
vercel link --yes --project $VercelProject --cwd "$StageDir"

PowerShell이 새 Vercel 프로젝트 이름:이라고 물으면 그때 한 번만 이름을 입력하고 Enter를 누릅니다. 완료 후 Vercel 홈페이지 Dashboard에 같은 이름의 프로젝트가 보입니다.

Dashboard에 프로젝트가 보인다고 배포가 끝난 것은 아닙니다. 반드시 뒤의 vercel --prod까지 실행하고, 출력의 마지막에 Ready와 Aliased 주소가 보여야 합니다.

명령이 팀을 선택하라고 물으면 개인 연습은 본인 계정을 선택합니다. 기존 프로젝트에 연결할지 묻고 처음 만드는 경우에는 새 프로젝트를 선택합니다. 프로젝트 이름에는 공백과 한글 대신 영문 소문자, 숫자, 하이픈을 사용합니다.

V-5. 공개 또는 비공개 방식 선택

공개해도 되는 승인 규정의 read-only endpoint

공개가 허용된 규정만 포함했고 누구나 읽기 전용 목록·계층·조문·검색 도구를 호출해도 되는 경우에만 다음 값을 Production 환경에 넣습니다.

$StageDir = Read-Host "V-2에서 만든 배포 전용 폴더 전체 경로"
vercel env add MCP_ALLOW_UNAUTHENTICATED_HTTP production `
  --value "true" --yes `
  --cwd "$StageDir"

vercel env add MCP_TOOL_PROFILE production `
  --value "chatgpt-data" --yes `
  --cwd "$StageDir"

이 모드는 쓰기 도구 없이 원격 공개 범위를 list_regulations, get_regulation_toc, get_regulation_article, get_regulation_references, list_regulation_reference_cycles, search, fetch로 제한하는 용도입니다.

명령 실행 뒤 Vercel 홈페이지에서도 확인할 수 있습니다.

1. Dashboard에서 만든 프로젝트를 엽니다.
2. Settings > Environment Variables로 이동합니다.
3. MCP_ALLOW_UNAUTHENTICATED_HTTP와 MCP_TOOL_PROFILE이 Production에 있는지 확인합니다.
4. 값이 없거나 오타가 있으면 배포하지 말고 먼저 수정합니다.

기관 내부 자료나 비공개 endpoint

MCP_ALLOW_UNAUTHENTICATED_HTTP=true를 사용하지 않습니다. MCP_AUTH_TOKEN을 Vercel Secret으로 관리하고 bearer 인증을 지원하는 클라이언트에 환경변수 이름만 연결하거나 OAuth를 구성합니다. 토큰 값을 README, JSON, TOML, Git 커밋에 기록하지 마세요.

ChatGPT 웹 hosted connector와 Claude remote connector의 인증 지원 범위가 다를 수 있으므로 기관 운영 배포는 Vercel HTTPS MCP 배포 안내의 인증 조건을 먼저 확인합니다.

V-6. Production 배포

미리보기 배포로 오류를 먼저 확인한 뒤 Production으로 배포합니다.

$StageDir = Read-Host "V-2에서 만든 배포 전용 폴더 전체 경로"
vercel --cwd "$StageDir"
vercel --prod --cwd "$StageDir"

마지막 출력에서 Ready 줄과 Aliased: 줄을 찾습니다. Aliased: 오른쪽에 실제로 표시된 https:// 주소가 고정 Production 주소입니다.

1. Aliased: 오른쪽 주소만 마우스로 선택해 복사합니다.
2. 메모장에 한 번 붙여 넣습니다.
3. 주소 맨 끝에 /mcp를 붙입니다.
4. 완성한 전체 주소를 다시 복사합니다.

예를 들어 복사한 주소가 https://my-regulation-mcp.vercel.app이었다면 최종 주소는 https://my-regulation-mcp.vercel.app/mcp입니다. 예시 주소를 입력하지 말고 내 PowerShell에 나온 주소를 복사하세요.

배포마다 생기는 긴 Preview URL 대신 고정 Aliased 주소를 사용하세요. 같은 Vercel 배포와 /mcp endpoint를 ChatGPT·Codex·Claude가 함께 사용하므로 앱마다 새 서버를 배포할 필요가 없습니다.

PowerShell 출력을 놓쳤다면 Vercel 홈페이지에서 다시 찾을 수 있습니다.

1. Dashboard에서 프로젝트를 엽니다.
2. Deployments에서 가장 최근 Production 배포를 엽니다.
3. 상태가 Ready인지 확인합니다.
4. Domains 또는 배포의 Aliased 주소에서 .vercel.app 주소를 복사합니다.
5. 복사한 주소 끝에 /mcp를 붙입니다.

브라우저 주소창에 /mcp를 열었을 때 일반 웹페이지 대신 오류나 메서드 안내가 보일 수 있습니다. MCP는 브라우저로 읽는 홈페이지가 아니므로 이것만으로 실패라고 판단하지 말고 반드시 다음 smoke 명령으로 프로토콜을 검사합니다.

V-7. 주소를 등록하기 전에 프로토콜 검증

프로젝트 루트에서 실행합니다. 첫 줄을 실행하면 PowerShell이 URL을 물어봅니다. V-6에서 만든 실제 /mcp 주소 전체를 붙여 넣고 Enter를 누르세요.

$McpUrl = Read-Host "V-6에서 복사한 전체 /mcp 주소"
python scripts\run_mcp_client_config_smoke.py `
  --remote-url $McpUrl `
  --allow-unauthenticated-remote `
  --timeout-seconds 120 `
  --fail-on-issue

공개 무인증 endpoint일 때만 --allow-unauthenticated-remote를 사용합니다. 비공개 endpoint에는 설정한 인증을 사용합니다.

결과에서 다음이 모두 확인돼야 합니다.

• mcp_initialized: true
• tools_discovered: true
• end_to_end_verified: true
• tool_names: list_regulations, get_regulation_toc, get_regulation_article, get_regulation_references, list_regulation_reference_cycles, search, fetch 포함

이 네 값 중 하나라도 false이면 Claude나 ChatGPT에 등록하지 않습니다. Vercel Dashboard의 Logs에서 가장 최근 Function 오류를 확인하고 문제 해결표의 Vercel 항목을 먼저 처리합니다.

방법 D 상세: ChatGPT · Vercel HTTPS MCP 연결

④의 배포·검색 검사 완료 화면에서 주소를 복사합니다. 서버 파일 준비와 실제 배포는 별도 상태이며, URL이 생긴 것만으로 검사가 통과한 것은 아닙니다.

D-1. ChatGPT 웹에 원격 MCP 앱 등록

1. ChatGPT Plugins에서 + → Add custom MCP server를 선택합니다.
2. 이름과 MCP 주소를 입력하고 공개 MCP는 No authentication으로 선택합니다.
3. 표시되는 연결 권한을 확인하고 Create as a plugin을 누릅니다.
4. 개인 플러그인 목록에서 해당 플러그인을 설치합니다.

ChatGPT 웹 앱 설정	넣을 값
이름 (Name)	알아보기 쉬운 이름
URL (MCP URL / Server URL)	프로그램 완료 화면의 https://…/mcp 전체 주소
인증	이번 공개 배포는 No authentication. 비공개 서버는 별도 인증 구성이 필요함
로컬 Command / Arguments / Working directory	넣지 않음

이전 UI에서는 Settings > Apps > Advanced settings > Developer mode로 표시될 수 있습니다. 메뉴가 없으면 워크스페이스 관리자 권한을 확인하세요. 특정 플랜에서 모든 메뉴가 보인다고 가정하지 않습니다.

OpenAI 공식 연결 안내 (2026-10-13 확인). 사설망 서버는 OpenAI Secure MCP Tunnel을 참고하세요.

D-2. 저장하고 실제 도구 확인

ChatGPT 홈에서 Work를 선택하고 새 대화에서 @로 설치한 플러그인을 고릅니다. 아래 최종 확인 질문으로 search와 fetch를 호출합니다. 프로그램의 서버 검사 결과와 실제 AI 대화의 도구 실행 결과를 각각 확인해야 합니다.

방법 E 상세: Claude · Vercel HTTPS MCP 연결

1. ④에서 Claude · Vercel HTTPS MCP를 선택해 묶음을 만들고 프로그램 안에서 Vercel에 배포합니다.
2. 배포·검색 검사 완료 화면의 전체 /mcp 주소를 복사합니다.
3. Claude의 Customize > Connectors > Add custom connector를 엽니다. 조직 계정은 관리자의 커넥터 설정이 필요할 수 있습니다.
4. 이름과 URL을 입력합니다. 이 공개 배포는 별도 인증 없이 조회하므로 No sign in을 선택합니다.
5. 새 대화에서 커넥터를 켜고 최종 확인 질문으로 search와 fetch를 호출합니다.

Claude 공식 연결 안내 (2026-10-13 확인).

이 화면은 로컬 STDIO 화면과 다릅니다. 아래 항목은 넣지 않습니다.

• C:\\...\\python.exe
• -m scripts.run_regulation_mcp
• PYTHONPATH
• run_mcp_stdio_server.ps1

Vercel 연결 화면에는 로컬 command, args, cwd, PYTHONPATH를 입력하지 않습니다. 필요한 것은 최종 HTTPS /mcp URL과, 비공개 서버일 때 승인된 인증뿐입니다.

전체 흐름을 한 장으로 보면 다음과 같습니다.

3. search와 fetch로 최종 확인하기

로컬 STDIO와 Vercel HTTPS 모두 같은 방식으로 최종 확인합니다. 연결 직후에는 search만 시험하지 말고 목록 → 구조 → 정확 조문 → 참조 → 검색 원문 순서로 확인해야 규정 MCP가 제대로 만들어졌는지 알 수 있습니다.

1. AI 프로그램을 완전히 종료하고 다시 실행합니다.
2. 새 대화를 만듭니다.
3. 방금 등록한 MCP 서버 또는 커넥터를 활성화합니다.
4. 아래 요청을 차례로 보내되 규정명과 검색어는 내 데이터에 있는 값으로 바꿉니다.

3-1. 전체 목록과 수 확인

연결한 규정 MCP의 list_regulations 도구로 승인된 규정 목록을 보여줘.
페이지를 끝까지 확인하고 total_count와 중복 없는 규정 수를 알려줘.

성공 신호: 조항·별표·부칙 청크가 각각 규정처럼 중복되지 않고, 하나의 규정이 목록에 한 번만 나타납니다. 규정이 많으면 페이지를 넘겨도 total_count가 유지됩니다.

3-2. 계층과 정확 조문 확인

목록에서 인사규정을 찾아 get_regulation_toc으로 목차를 보여줘.
그다음 get_regulation_article로 인사규정 제16조의 승인 원문과 출처를 보여줘.

성공 신호: 목차가 장·절·조·별표·부칙의 부모-자식 관계로 나오고, 제16조 요청에는 다른 조문의 유사 문장이 아니라 제16조의 본문이 반환됩니다.

3-3. 다른 규정 참조와 순환참조 확인

get_regulation_references로 인사규정이 참조하는 규정과 인사규정을 참조하는 규정을 보여줘.
list_regulation_reference_cycles로 현재 승인 규정 사이의 순환참조를 보여줘.

성공 신호: 들어오는 참조와 나가는 참조가 구분됩니다. 아직 적재되지 않은 대상은 미해결로 표시될 수 있고, 순환참조가 없으면 빈 목록이 정상입니다.

3-4. 자연어 검색과 원문 확인

다음 요청의 검색어만 내 규정에 있는 말로 바꿉니다.

연결한 규정 MCP의 search 도구로 인사규정을 찾아줘.
첫 번째 검색 결과의 id를 fetch 도구에 넣어 원문과 출처를 보여줘.

정상이라면 다음 순서가 보입니다.

1. MCP search 도구가 실행됩니다.
2. 한 개 이상의 검색 결과와 각 결과의 id가 나옵니다.
3. 그중 하나의 id로 MCP fetch 도구가 실행됩니다.
4. 승인된 규정 본문과 출처가 표시됩니다.

왜 둘 다 호출하나요? search 성공은 후보를 찾았다는 뜻이고, fetch 성공은 그 후보의 승인 원문과 출처를 실제로 읽을 수 있다는 뜻입니다.

반대로 아래 중 하나라도 보이면 아직 완료가 아닙니다. 해당 현상을 그대로 문제 해결표에서 찾습니다.

• 서버 이름만 보이고 도구 목록이 비어 있다.
• Claude Desktop에서 running이 아니라 disconnected다.
• list_regulations의 수가 예상과 다르거나 같은 규정이 청크별로 반복된다.
• 목차에서 장·절·조 관계가 끊기거나 정확 조문 요청에 다른 조문이 나온다.
• search는 되지만 결과마다 id가 없다.
• fetch에 제목이나 본문을 넣고 있고, search가 준 id를 넣지 않았다.

다음 항목을 모두 체크하면 연결 완료입니다.

• 서버 또는 커넥터가 목록에 보인다.
• Claude Desktop은 running이고, 다른 로컬 앱은 서버가 등록·활성화되어 있다.
• 도구 목록에 list_regulations, get_regulation_toc, get_regulation_article, get_regulation_references, list_regulation_reference_cycles, search, fetch가 보인다.
• list_regulations의 total_count와 페이지별 고유 규정 수가 맞고, 첫 규정의 목차·조문 조회가 된다.
• search가 한 개 이상의 결과를 반환한다.
• 검색 결과의 id로 fetch가 본문과 출처를 반환한다.

4. 문제 해결표

보이는 현상	주된 원인	해결
독립 Qwen 챗봇 실행을 눌렀지만 새 창이 안 열림	브라우저 팝업 차단 또는 이미 챗봇 프로세스가 실행 중	빌더에 표시된 127.0.0.1 주소의 열려 있는 Qwen 챗봇으로 이동을 누르고, 없으면 RUN_QWEN_CHAT.bat을 한 번만 실행
규정은 목록에 있지만 선택할 수 없음	사람 승인 미완료, 승인 청크와 색인 수 불일치, stale 색인 존재	규정 카드의 준비 사유를 읽고 빌더 ③에서 검수·승인을 마친 뒤 필요하면 문서 색인 복구 실행
AI 연결 확인 실패	Ollama가 꺼졌거나 모델 미설치, endpoint가 localhost가 아님	ollama list로 확인하고 없으면 ollama pull qwen3:8b; Ollama 재시작 후 127.0.0.1:11434로 다시 확인
첫 연결 확인이 오래 걸림	qwen3:8b를 RAM/GPU에 처음 적재하는 중	경과 시간을 보고 기다리며 버튼을 반복해서 누르지 않기; 완료 뒤 같은 세션의 질문은 보통 더 빠름
질문 뒤 승인 근거 검색 2/5에서 오래 멈춤	구버전 독립 챗봇 프로세스, 너무 넓은 질문 또는 손상된 BM25 색인	독립 챗봇 프로세스만 종료·재실행하고 먼저 제5조 내용은 뭐야처럼 선택 규정의 정확 조문 질문으로 확인; 계속되면 색인 상태 점검
Qwen3 4B 정밀 근거 감사를 켠 뒤 매우 느림	8B 답변 뒤 4B 모델을 추가 적재·실행함	일반 대화에서는 토글을 끈 기본 빠른 모드 사용; 의미 감사가 꼭 필요한 질문에만 켜기
답변 대신 승인된 규정 근거에서 확인할 수 없습니다 표시	선택 규정에 해당 조문·내용이 없거나 승인 근거가 부족함	다른 규정으로 범위를 바꾸기 전에 근거 조문 목록과 원문을 확인하고, 필요한 문서가 실제 승인·색인됐는지 점검
답변 아래 근거 조문이 예상과 다름	다른 규정을 선택했거나 질문이 너무 넓음	화면 상단의 기관·선택 규정을 다시 확인하고 규정명·조문 번호를 포함해 질문; 원문과 다르면 답변을 사용하지 말고 운영자에게 검수 요청
Claude Desktop 서버가 목록에 없음	JSON 문법 오류, 잘못된 설정 파일, 재시작 안 함	설정 > 개발자 > 구성 편집에서 생성 항목을 확인하고 완전히 재시작
ChatGPT 웹에서 새 앱/MCP 메뉴가 안 보임	지원 플랜, Developer mode 또는 워크스페이스 관리자 권한 부족	공식 ChatGPT MCP 안내에서 플랜을 확인하고 관리자에게 앱·Developer mode 권한 요청
Claude Code 또는 Codex 서버가 목록에 없음	등록 스크립트 미실행 또는 TOML 미반영	claude mcp list 또는 ~/.codex/config.toml을 확인하고 앱을 다시 시작
Vercel 원격 서버가 목록에 없음	원격 smoke 실패, ChatGPT 앱/Claude Connector 미저장	방법 D는 ChatGPT 웹 Apps, 방법 E는 Claude Connectors에서 URL과 저장 상태 확인
Claude Desktop이 disconnected	command, args, env 일부 누락	생성 JSON의 한 서버 항목을 수정 없이 다시 병합

지원 범위와 안전 원칙

항목	현재 지원
운영체제	Windows 10/11 64비트 우선
입력 파일	PDF, HWP, HWPX, DOCX
규정 구조	규정 → 버전 → 장·절·조·항·호, 별표·서식·부칙
목록·조문	승인된 고유 규정 페이지 목록, 목차, 정확 조문
관계	규정·조문 간 들어오는/나가는 참조와 순환참조
개정 관리	규정 단위 갱신, 효력 기간에 따른 현재본과 승인 이력
검색 데이터	사람이 승인한 규정 중 조회 기준일에 유효한 버전
로컬 연결	Codex CLI / Codex IDE, Claude Desktop, Claude Code
원격 연결	ChatGPT 웹 또는 Claude가 사용하는 HTTPS /mcp

꼭 지켜야 할 운영 원칙

• 전처리 결과는 검토용 초안이며 자동 승인이 아닙니다.
• 원문, API 키, 토큰, 기관 내부 식별자와 사용자 로컬 경로를 공개 저장소에 올리지 마세요.
• 원격 MCP의 응답은 외부 AI 서비스로 전송될 수 있습니다.
• 공개 Vercel 배포에는 공개가 허용된 승인 데이터만 포함하세요.
• Vercel Function 로그는 기관용 영속 감사 저널을 대신하지 않습니다.
• 공개 또는 기관 운영 전에는 SECURITY.md를 확인하세요.

• 파일 업로드와 전처리 완료만으로는 검색 대상이 되지 않습니다.
• 운영자가 최종 버튼으로 명시적으로 승인한 청크만 공식 색인과 MCP 번들에 들어갑니다. 초보자 모드는 모든 조항의 확인을 마친 뒤 최종 승인합니다. 일반 모드의 미검수 승인은 사유와 감사 이벤트로 구분됩니다.
• 목록·목차·조문·참조·검색 도구도 호출자의 기관·프로필·접근 범위 안에서만 승인 데이터를 반환합니다.
• 과거 개정본은 승인 증거와 효력 기간이 확인되고 과거 기준일 또는 이력 조회를 명시했을 때 구분해 사용합니다.
• 공개 Vercel endpoint는 read-only 도구만 노출하고, 공개가 허용된 데이터인지 기관 담당자가 별도로 판단해야 합니다.

더 자세한 안내

처음 설치 중이라면 이 README만 따라가고, 특정 연결이나 운영 계약을 확인할 때 아래 문서를 여세요.

• MCP 빠른 연결 안내
• 이미지 기준 전처리·로컬 QA 파이프라인 구현
• AI 에이전트 오케스트레이션 역할
• 로컬 AI 설치·운영 런북
• Qwen3 8B 로컬 LLM 플랫폼 구현 계획
• MCP 클라이언트 설정 예시
• MCP 도구 계약과 프로필
• 실제 규정·MCP·로컬 LLM 회귀 실행
• Vercel HTTPS MCP 배포 안내
• MCP 로컬 서버 공식 문서
• OpenAI ChatGPT Developer mode·MCP 공식 안내
• OpenAI Secure MCP Tunnel 공식 안내
• Claude Code MCP 공식 문서
• Claude 원격 custom connector 공식 안내

개발자용 실행과 검증

Python 3.11 이상에서 프로젝트 루트 기준으로 실행합니다.

Windows에서 처음 소스를 실행할 때는 START_HERE.bat를 사용할 수 있습니다. 수동으로 실행할 때는 가상환경을 만들고 같은 Python으로 Streamlit을 시작합니다. 로컬 runtime은 프로젝트 폴더의 data\에 저장되므로 공개 Git 커밋에 포함하지 않습니다. 프로젝트 루트의 .env 파일은 app.core.config가 시작 시 자동으로 읽습니다(이미 설정된 환경변수가 우선, REG_RAG_DOTENV_PATH로 위치 변경 가능). 테스트는 PYTHONUTF8=1로 실행하세요.

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m streamlit run frontend\streamlit_app.py --server.address 127.0.0.1
python -m unittest discover -s tests -v
python -m build --sdist --wheel
.\scripts\build_windows_portable.ps1
python scripts\audit_release_hygiene.py `
  --workflow-scope available `
  --include-untracked `
  --include-source-path-scan

Windows 포터블 빌드는 일반 CPython 3.11 이상을 권장합니다. 현재 터미널의 python이 Anaconda/Miniconda이거나 이전 빌드 가상환경이 남아 있다면, 설치된 CPython 실행 파일을 명시하고 빌드 환경을 새로 만드세요.

python scripts\run_release_harness.py --mode public --keep-going `
  --portable-python "C:\Users\<사용자>\AppData\Local\Programs\Python\Python311\python.exe"

하네스는 이 값을 Windows 포터블 빌드의 -BasePython으로 전달하고 기존 빌드 가상환경을 재생성합니다. 경로는 각 PC에 실제 설치된 python.exe 위치로 바꿔야 합니다.

기여 규칙은 CONTRIBUTING.md, 공개 저장소 이력 원칙은 docs/public_repository_history_policy_ko.md를 확인하세요.

업데이트 내역

최근 소스 변경은 아래 업데이트 내역에 날짜별로 정리했습니다. 배포 버전별 변경 내용과 다운로드 파일은 GitHub Releases에서 확인할 수 있습니다.

Kordoc 사용 고지

PDF·HWP·HWPX·DOCX로 공식 MCP를 만들 때 필요한 표 파싱 품질 증거와 HWP/HWPX 문서 구조·표 추출 교차 검증에는 Kordoc을 사용했습니다. 배포 번들에는 Kordoc 소스나 실행 파일이 포함되지 않음에 유의하세요. 라이선스는 Kordoc LICENSE와 THIRD_PARTY_NOTICES.md에서 확인할 수 있습니다.

---

최근 업데이트: 2026년 10월 24일

MCP 최종 빌드 QA 게이트와 윤문 게이트

• MCP 파일 묶음을 만들 때 도구 수, 도구 설명 토큰, 도구 체이닝, 입력·응답 보안, 안내문 윤문을 코드로 검사하고, 차단 항목이 있으면 묶음을 완료로 표시하지 않습니다.
• 목차 label·인용형·숫자로 조문을 조회하면 0건이 나오던 문제를 고쳤습니다.
• 상세 변경과 검증 결과는 10월 24일 업데이트에 정리했습니다.

이전 업데이트: 2026년 10월 23일

문장 단위 주장 감사와 실제 규정 KPI 가드레일

• 로컬 LLM 답변을 문장마다 근거와 대조하고, 숫자·조문 번호·명사가 근거에 없으면 승인 근거 발췌 답변으로 바꿉니다.
• 실제 규정 회귀 실행기, KPI 가드레일 검사기, 평가셋 봉인·반복 측정·실패 원인 분류를 추가했습니다.
• 상세 변경과 검증 결과는 10월 23일 업데이트에 정리했습니다.

이전 업데이트: 2026년 10월 14일

일괄 승인·새 초안 복구 후속 검증

• 일괄 승인 확인 화면 진입과 최종 실행을 구분하고, 선택한 여러 규정의 수정 내용까지 승인·색인되는 흐름을 회귀 테스트에 반영했습니다.
• 새 초안 생성 시 복구 사유·원본 연결·규정 메타데이터·파일 내용을 보존하고, 기존 원본과 승인·색인 기록을 변경하지 않는지 검증합니다.
• 상세 변경과 검증 결과는 10월 14일 업데이트에 정리했습니다.

이전 업데이트: 2026년 10월 13일

합본·개별 규정 처리와 승인·배포 흐름 개선

• PDF 합본의 목차·반복 머리말·본문을 함께 분석해 규정 경계를 복원하고, 표 아래 일반 본문과 규정별 개정·시행일을 보존합니다.
• 저장된 원본으로 새 초안을 복구할 수 있으며, 초보자 모드의 전체 승인·색인 진입점을 한 곳으로 정리했습니다.
• 프로그램 안에서 Vercel 계정 연결·프로젝트 선택·배포·검색 검사를 진행하고, 기존 주소 업데이트와 중단된 연결 검사를 이어서 처리합니다.
• 자세한 적용 방법은 10월 13일 업데이트와 Vercel 배포 안내를 참고하세요.

이전 업데이트: 2026년 10월 12일

• HWP 통합 규정집의 원본 문단·머리말·줄 배치를 근거로 규정 경계를 복원하고, 불확실한 경계는 계속 검수를 요청합니다. 변경 내용과 적용 방법을 참고하세요.

이전 업데이트: 2026년 10월 11일

합본 규정집 참조·근거 조문 후속 수정

• 분류코드 인용: 참조 그래프가 3-1-1.보수규정 같은 문자열 언급을 번호와 제목으로 나눠 읽습니다. 범위 안에 그 번호를 공개한 규정이 없으면 제목이 정확히 같은 규정에 연결하되, 번호가 없거나 같은 번호인 규정만 허용합니다. 같은 규정을 가리키는 조문 인용이 있으면 중복 언급은 버리고, 자기 머리줄을 가리키는 옛 처리 결과의 언급도 자기 순환으로 만들지 않습니다. 제목에서 글자를 떼거나 추측하지 않습니다.
• 행동강령 인용: 내부 규정 접미사에 강령을 넣고, 조문 앞 규정명 정규식을 같은 목록에서 만들어 두 목록이 다시 어긋나지 않게 했습니다. 「공무원 행동강령」만 외부 법령으로 남깁니다. 전처리 버전은 2026.10.11-code-of-conduct-references-1입니다.
• 근거 조문: 계층 검색이 서식·별표 결과마다 fetch와 같은 함수로 근거 조문 후보를 받습니다. 가시성·승인·최신 판 필터가 fetch와 같아서 숨겨진 조문 번호가 검색으로 새지 않습니다. 같은 문서의 결과는 한 번 받은 후보를 재사용합니다.
• 회귀 테스트: tests/test_regulation_reference_graph.py, tests/test_metadata_extractor.py, tests/test_pipeline.py, tests/test_regulation_mcp_tools.py에 집중 테스트 11개를 추가했습니다. 10개는 수정 전 코드에서 실패하고 수정 후 통과합니다. 나머지 1개는 「공무원 행동강령」을 외부 법령으로 유지하는지 지키는 반대 사례입니다.

합본 E2E (통과 체크 / 24)	변경 전	변경 후
6개 규정 DOCX · HWPX · PDF	24	24
48개 규정 DOCX · HWPX · PDF	22	24

이전 업데이트: 2026년 10월 10일

합본 규정집 E2E 회귀 검증과 목차·규정 목록·참조 수정

• E2E 하네스: scripts/generate_synthetic_combined_regulation_book.py가 만든 가상 총규정을 업로드 → 전처리 → 승인 → 색인 → MCP 묶음 → MCP 도구 조회까지 실제 코드 경로로 돌리고 생성기 정답과 비교합니다. Windows에는 resource 모듈이 없어 시작하자마자 멈추던 문제를 고쳤습니다.
• 목차 순서: 청커가 기록한 원문 순서(order_index)가 벡터 레코드로 넘어가지 않아, 계층 색인이 계층 경로를 문자열로 정렬하고 있었습니다. 이제 목차·문서 조회가 원문 순서를 따릅니다.
• 목차 노드 종류: 맨 앞의 제N장·제N절·제N조를 먼저 판정합니다. 제6장 특별 지급(공백을 빼면 별지 포함), 제15조(서식), 제2절 특별표창이 별지·별표로 바뀌던 문제를 고쳤습니다. 제N장 부칙, 부칙 <…>, [별표 1], [별지 제1호서식]은 그대로 분류합니다.
• 합본 표지: 번호 규정이 둘 이상인 문서에서 첫 규정보다 앞에 있고 조문 번호·규정 경계가 없는 표지 문단은 목차와 같은 안내 단위로 둡니다. 규정 목록·검색·참조 그래프·규정 수에서 빠지며, 승인·색인된 청크는 그대로 남습니다. 첫 규정 앞의 번호 없는 조문(예: 정관)은 계속 규정으로 표시합니다.
• 분류코드 자기 참조: 현재 규정과 번호나 제목이 같은 N-N-N. 제목 줄은 참조로 뽑지 않습니다. 다른 규정을 가리키는 1-1-1. 인사규정 제1조 같은 인용은 그대로 추출합니다. PR #119와 합친 전처리 버전은 2026.10.11-contents-opening-and-self-reference-1이며, 두 PR 중 하나만 반영된 처리 결과(2026.10.09-…, 2026.10.10-…)도 재사용하지 않습니다.
• 회귀 테스트: tests/test_hierarchical_index.py, tests/test_vector_ingestion_adapter.py, tests/test_metadata_extractor.py, tests/test_chunker.py, tests/test_pipeline.py, tests/test_run_combined_book_e2e_regression.py에 집중 테스트 11개를 추가했습니다. 제품 수정마다 붙인 테스트는 수정을 되돌리면 실패하는 것을 확인했고, 정관처럼 번호 없는 조문을 숨기지 않는 반대 사례도 함께 고정했습니다.

합본 E2E (통과 체크 / 24)	변경 전	변경 후
6개 규정 DOCX · HWPX · PDF	19	24
48개 규정 DOCX · HWPX · PDF	15	22

48개 규정에서 남은 2개는 변경 전후 결과가 같아 후속 과제로 남깁니다. 「임직원 행동강령」 제13조를 가리키는 참조 2건이 해석되지 않고, 검색 결과 1건(Q18)의 조문 번호가 fetch 결과와 다릅니다. 3-1-1. 보수규정 제29조처럼 분류코드가 붙은 정상 인용도 아직 미해결 참조를 하나 더 만듭니다. 이 세 가지는 2026년 10월 11일 업데이트에서 고쳤습니다.

기존 전처리 결과는 같은 원본을 다시 올려 재전처리해야 참조 수정이 반영됩니다. 목차·표지 수정은 MCP 묶음을 다시 만들 때 반영됩니다.

Qwen 색인 메모리 개선과 통합 규정집 첫 경계 복구

• 색인 실행: CUDA/CPU를 자동 선택하고, 긴 입력의 모든 문자를 2,048자 이하 구간에 포함해 길이 가중 평균 벡터를 만듭니다. 원문·승인 단위·색인 레코드 수는 유지하며 새 Qwen 벡터에 embedding_input_strategy를 기록합니다.
• 메모리 부족 처리: 모델을 적재하기 전에 전처리·검수용 사본을 해제합니다. CUDA 메모리 부족은 같은 입력의 처리 묶음을 줄여 재시도하며, 한 구간도 처리하지 못하거나 결과가 부족·비정상이면 실패를 전달합니다.
• 목차와 본문 구분: 행 끝 규정 번호를 가진 목차 뒤에서는 이어지는 제목 또는 장·절·조문과 실제 본문 조문을 함께 확인해 첫 규정 경계를 보존합니다. 본문 도입 근거가 없는 목차 항목은 본문으로 승격하지 않습니다.
• 처리 결과 재사용: 파이프라인 버전을 2026.10.09-combined-book-contents-opening-1로 변경했습니다. 수정 전 결과는 재사용하지 않고 같은 원본의 새 검수 초안을 만듭니다. 기존 문서와 승인 기록은 보존합니다.

역할별 모델과 실행 조건

역할	모델·담당
흐름 제어·보안·품질·색인 조건·인용 검증	결정적 Python
질의 분석·검색어 보정	Qwen3 1.7B
불확실 구조·표·답변 주장 검수	Qwen3 4B
승인 근거 기반 답변 초안	Qwen3 8B
의미 벡터 생성	Qwen3 Embedding 0.6B
검색 후보 재순위	Qwen3 Reranker 0.6B
한국어 OCR	Korean PP-OCRv5
최종 승인	사람 검수와 승인 journal

모델 호출은 단계 조건에 따라 실행합니다. 구조·표 검수는 선택한 불확실 후보에만 적용하며 finding을 남깁니다. 독립 챗봇의 기본 빠른 검색과 특정 조문을 바로 찾는 경로에서는 일부 모델 호출을 생략합니다. 전체 다중 모델 질의응답 경로는 질의 분석 → 검색·재순위 → 근거 답변 → 주장·인용 검증 순서입니다. 자세한 역할·권한·실패 정책은 AI 에이전트 역할 체계를 참고하세요.

통합본 및 연결 검증 결과

• 1,787쪽·140개 규정의 통제된 native 파서 비교에서 규정 번호 없는 조문 청크 19개 → 0개, 품질 점수 85.8 → 87.8을 확인했습니다.
• 표 파서를 포함한 경로에서는 검수 초안 청크 6,773개, 품질 점수 88, 오류 0개를 확인했습니다. 표 검수 플래그 811건과 원문 위치의 불확실성은 유지합니다. 품질 통과는 사람 승인을 대신하지 않습니다.
• 실제 통합본의 승인 전 색인 요청이 HTTP 400으로 거부되고, 해당 자료 질의의 citation이 0건인 것을 확인했습니다.
• 로컬 Qwen3 1.7B·4B·8B 역할 호출과 합성 승인 자료 15단계 acceptance를 통과했습니다. 이 승인 자료의 연결 테스트는 실제 통합본 전체의 승인·색인 완료를 뜻하지 않습니다.
• MCP stdio와 Streamable HTTP에서 initialize, tools/list, 상태 조회, search, fetch를 검증했습니다. 운영자 앱에 플러그인이 등록되었다는 판정과는 구분합니다.
• 2026-10-09 전체 unittest는 4,126개 실행, 실패 0개·생략 17개였습니다. sdist/wheel 빌드와 공개 소스 위생 검사를 통과했으며, 코드 커밋의 GitHub preprocessing-regression CI도 통과했습니다.

원본 규정과 실행 산출물은 로컬에만 보존했습니다. 실제 자료의 검수 플래그를 확인하고 승인 journal을 남긴 뒤 색인하세요. 변경 검토 절차는 전처리 변경 보호 하네스, 실행판 배포는 Releases에서 확인하세요.

이전 업데이트: 2026년 10월 6일

합본 경계 판정·승인 복구 개선과 직접 작성 화면 제거

• 명시적 번호 제목 바로 뒤의 같은 페이지 반복 제목은 새 경계로 오인하지 않도록 했습니다. 번호 뒤 구분자 누락은 같은 페이지 제목·제1조와 뒤쪽의 동일 번호·제목이 모두 확인될 때만 복원합니다.
• 선택 규정, 파일 전체, 초보자, 여러 문서, 고급 수동 승인에서 같은 경계 검사를 사용합니다. 여러 문서 중 하나라도 차단되면 앞 문서부터 저장하거나 부분 승인하지 않습니다.
• 승인 화면에서 같은 원본의 재업로드를 안내하고, 차단된 처리 캐시와 재전처리 초안의 경계를 다시 확인합니다. 불명확한 경계의 승인 금지와 승인된 내용만 색인하는 조건은 유지합니다.
• 직접 제정·집필 메뉴를 제거하고 예전 작성 주소·세션은 시작 화면으로 돌려보냅니다. 파일 업로드와 기존 초안 데이터는 보존합니다.
• 전체 테스트 4,106개에서 실패·오류 0개, 환경·선택 의존성 조건에 따른 생략 17개를 확인했습니다. sdist/wheel 빌드, 공개 소스 위생 검사와 변경 파일 검사도 통과했습니다.

기존 결과는 같은 원본을 다시 올려 재전처리해야 합니다. 재분석 후에도 불명확한 경계가 남으면 규정별 분리 업로드가 필요합니다.

이전 업데이트: 2026년 10월 3일

실행 방법 정리와 AI 검수가 조용히 꺼지지 않도록 보완

• 실행 방법 한눈에: README 상단에 실행판·START_HERE.bat·명령 실행 세 가지와 접속 주소, 종료 방법, AI 검수 켜는 순서, 한 번에 승인하는 방법을 정리했습니다.
• .env가 실제로 읽힙니다: 문서는 오래전부터 영구 설정을 .env에 두라고 안내했지만 읽는 코드가 없었습니다. 이제 앱 시작 시 프로젝트 루트의 .env를 읽고, 이미 설정된 환경변수는 그대로 우선합니다.
• AI 검수 설정 복원: 사이드바에서 저장한 스위치·공급자·모델·한도는 data\ai_review_preferences.json에 남아 재시작 후 복원됩니다. 키는 저장하지 않으며, 켜져 있는데 키가 없으면 "설정 필요"로 드러나고 전처리 화면에도 경고가 뜹니다. 원하면 API 키를 이 PC의 .env 파일에도 저장을 켤 수 있습니다.
• 경로 유출 검사의 범위: 본문에 로컬 경로 모양 문자열이 든 조항이 있으면 예전에는 문서 전체 호출을 막았습니다. 이제 그 조항만 빼고 나머지는 검수하며, 뺀 조항은 "AI 검수 일부 완료"와 함께 사람이 확인하도록 표시됩니다. 전송 자체를 막는 검사는 그대로입니다.
• 초보자 모드의 한 번에 승인: 조항을 다 확인하지 않아도 **⏩ 남은 조항 N개를 AI 검수 결과대로 한 번에 승인하기 (선택)**를 펼쳐 끝낼 수 있습니다. 사람이 마지막은 직접 검수하기를 추천하는 안내와 확인란을 거치며, 미검수 사실은 감사 기록에 남습니다.
• 검색 등록 진행 표시: 승인 뒤 검색 등록(임베딩)이 조항 200개 기준 CPU에서 20분 넘게 걸리는데 진행 막대가 멈춰 보였습니다. 이제 검색용 벡터 만드는 중 · n/N으로 실제 진행을 보여 줍니다.
• 실행 창 안내: START_HERE.bat·INSTALL_AND_RUN.bat·RUN_APP.bat이 출력 없이 기다리는 단계마다 예상 시간과 "멈춘 것이 아닙니다" 안내를 표시합니다.
• 회귀 테스트: tests/test_ai_review_persistence.py에 .env 로딩·설정 복원·조항 단위 차단을, tests/test_ai_review_restart_ui.py에 설정 복원과 초보자 일괄 승인 화면을, tests/test_embedding_progress.py에 임베딩 진행 보고를 고정했습니다.

이전 업데이트: 2026년 9월 29일

처음 보는 사람을 위한 쉬운 안내 보완

• 쉬운 버튼: ‘고칠 곳이 있어요’, ‘이 문제는 없어요’, ‘내용이 맞아요 · 다음’, ‘승인하고 AI 질문 준비하기’로 행동을 설명합니다.
• 모를 때 도움말: 날짜·금액·표를 비교하는 순서를 알려 줍니다. 도움말이나 AI 제안 반영만으로 승인되지 않습니다.
• 넓어진 비교 화면: 두 칸으로 원래 문서와 저장할 내용을 보고, AI 제안은 아래에서 확인합니다. 작은 화면에서도 각 내용 앞에 제목이 붙습니다.
• 질문 화면 정리: ‘AI 연결 확인’이 끝나야 질문창이 나타납니다. 준비 상태 표와 세부 답변 설정은 접어 둡니다.
• 현재 단계에 맞는 안내: 검토 중에 다시 검토 화면으로 이동하라는 문구와 승인 뒤 남아 보이던 미확인 경고를 바로잡았습니다.
• 검증과 시연: 가상 규정으로 처음부터 끝까지 진행한 결과와 위 24초 영상을 참고하세요.

한 조항씩 진행하는 초보자 화면과 AI 수정안 표시 복구

• 클릭 순서 단순화: 설정·규정 목록을 접고 한 조항만 펼칩니다. 확인한 조항은 다시 열 수 있으며, 준비되지 않은 진행 버튼은 숨기고 가능한 다음 동작을 안내합니다.
• AI 수정안 표시: 저장된 수정안 전문, 추가·삭제 표시, 검수 의견을 검증 칸에 함께 표시합니다. 반영은 명시적 클릭으로만 하며, 수정 후에는 다시 확인해야 합니다. 자동 승인하지 않습니다.
• 파싱 보완: DOCX 중첩 표 텍스트, 병합 셀 중복, 콘텐츠 컨트롤 안의 조문, 공백 없이 붙은 조문 경계를 보완했습니다. 복잡한 표는 원문 대조 플래그를 유지합니다.
• 직접 검증: 가상 규정 8개 조항·표 → 조항 재검토 → 승인 기록 1건 → 실제 검색 벡터 8개 → Qwen 답변과 제2조 근거를 확인했습니다. 검증 범위와 실행 결과를 참고하세요.

최신 소스는 처음 사용하는 사람이 화면을 보면서 지금 해야 할 한 가지를 바로 이해하고, 단계가 바뀌어도 안내를 잃지 않도록 초보자 흐름도 함께 보완했습니다. 아래 개발 내역은 현재 Windows 실행판에 모두 포함되었다는 뜻은 아니며, 배포 여부는 Releases에서 확인하세요.

2026년 9월 29일 — 실제 조항 안내 검증과 Kordoc·Qwen 복구 보완

• 검색 준비와 오류 복구: 승인 화면에서 검색 패키지 누락을 미리 알리고, 검색 기능 설치·준비 / 검색 모델 준비·점검 버튼으로 실제 모델 실행을 확인합니다. 색인에 실패해도 저장된 승인 숫자와 재등록 안내를 즉시 갱신합니다. 승인된 조항을 아직 검색 등록되지 않았는데 완료라고 설명하던 문구도 고쳤습니다. 새 합성 규정 8개 조항에 색인 오류를 한 번 주입한 뒤 화면 버튼으로 준비·재등록을 확인했습니다. 복구 과정과 검증 범위를 참고하세요.

• 초보 안내에서 발견한 문제 수정: 검수 안내가 원문을 가리지 않도록 본문에 배치하고, 긴 원문은 줄바꿈합니다. 챗봇 실행·이동 안내를 연결하고 준비 직후 3 / 3 완료를 갱신합니다. AI 사용 여부와 무관한 검수 확인 문구, 중복 인용 정리, 근거 부족 답변의 인용 제거를 반영했습니다. 새 가상 규정 8개 청크의 승인·실제 색인과 Qwen 세 질문을 다시 완료했습니다. 수정 후 실제 화면·검증 결과를 참고하세요.

• 합성 DOCX의 8개 항목을 초보 안내에 따라 검수·승인·색인하고 실제 Qwen3 8B에 연속 질문했습니다. 신청 기한·보관 기간과 근거 조문, 규정에 없는 내용의 답변 제한을 확인했습니다. 안내 막대가 추가 질문의 전송 버튼을 덮는 문제를 수정했으며, 설치·원문 대조 등 남은 불편도 실제 클릭 검증 결과에 공개했습니다.

• README 맨 위의 20초 홍보 영상에 Kordoc 4.16.0, 초보자 클릭 안내, 사람 승인과 로컬 Qwen·MCP를 담았습니다. GIF·MP4·정지 화면과 바로 아래 65초 실제 사용 시연을 제공합니다.

• 영문 Windows 환경에서도 독립 Qwen 실행 안내와 오류 메시지를 한글로 출력하도록 UTF-8을 적용했습니다. 출력 때문에 앱 실행이나 보호 모드 안내가 중단되지 않습니다.

• 실제 Streamlit 브라우저에서 공개 합성 문서를 올리고 첫 검수 항목 → 제1조 → 제2조로 안내 대상이 이동하는 것을 조항 ID로 확인했습니다. 안내를 멈춘 상태의 화면 재실행과 이어 보기도 검사했으며, 안내 조작만으로 승인 저널이나 색인이 생성되지 않았습니다.

• Kordoc 준비 확인은 설정된 전체 명령을 검사합니다. node만 정상이고 뒤의 CLI 스크립트가 없는 경우를 준비 완료로 표시하지 않습니다. 설치 도구는 npm 설치 위치의 실행 파일과 4.16.0 버전까지 확인하고, 불일치하면 원인별 복구 안내를 표시합니다.

• Qwen에서 기관·문서 준비가 안 됐을 때 돌아갈 빌더 화면과 다음 행동을 안내합니다. 인용이 없거나 잘못된 형식이면 근거 부족 경고를 표시하며, 답변 생성 완료를 사람이 근거까지 확인한 것으로 표시하지 않습니다.

• 빌더의 Qwen 단계는 승인·색인 준비와 앱 실행까지만 완료로 계산합니다. 기관·규정 선택, 질문과 답변 근거 확인은 독립 Qwen 창에서 이어집니다.

• Orca 역할 분담과 토론 결정, 검증 범위와 실행 방법을 기록했습니다.

2026년 9월 28일 — 초보자 안내, AI 검수 신뢰성, 설치·연결 복구 개선

• 클릭 안내 추가 보완: 지금 누를 항목을 강조하는 안내창이 실제 작업 상태에 따라 다음 항목으로 이어집니다. 접힌 메뉴 열기, 일시정지·이어 보기, 화면 재실행 시 안내 복원과 키보드 조작을 보강했습니다. 앱의 승인 확인창과 진행창이 열리면 안내는 잠시 물러나며, 설명을 넘기는 것으로 승인·색인 또는 완료 상태를 바꾸지 않습니다.
• 실제 앱의 초보자 클릭 시연 GIF·MP4를 README에 추가했습니다. 검수 화면에서도 항목별 판단 → 검수 확인 → 원문 대조 → 다음 조항으로 안내가 이어집니다.
• 독립 Qwen 챗봇에도 한 단계씩 클릭 안내를 추가했습니다. 기관과 규정을 직접 선택한 뒤 연결 확인 → 질문 입력 → 답변의 근거 인용 확인 순서로 안내합니다.
• Kordoc 설치 기준과 설치·복구 문구를 4.15.7로 함께 갱신했습니다. 실제 4.15.7 실행 파일로 공개 합성 DOCX의 표 추출을 확인했습니다. 기존 승인 문서는 자동으로 재처리하지 않으며, 새 파싱 결과를 반영할 때는 재처리·사람 승인·색인 절차를 거칩니다.
• 초보자 안내 카드와 단계별 진행 표시를 보강했습니다. 화면을 방문한 횟수가 아니라 실제 완료 상태로 진행률을 계산하고, 여러 규정을 선택했다면 다음 미완료 규정으로 이어서 안내합니다. 안내용 JavaScript·CSS도 설치 패키지에 포함했습니다.
• AI 검수에서 검토한 조문 수와 발견한 문제 수를 구분합니다. 문제가 없다는 정상 응답도 검토 완료로 집계하고, 실패하거나 빠진 항목은 재시도할 수 있도록 안내합니다. 진행 상황을 저장해 검수가 어디까지 진행됐는지 확인할 수 있게 했습니다.
• 잘린 AI 응답, 잘못된 응답 형식, 요청하지 않은 조문과 중복 조문을 정상 검수 결과로 받아들이지 않습니다. 검수 결과 재사용은 기관과 모델·연결 주소·검수 설정을 구분하며, 재검수할 때 기존 승인 결과를 보존하도록 보강했습니다.
• 로컬 Qwen의 준비 상태를 CLI와 두 화면에서 같은 기준으로 진단합니다. 주소만 확인한 상태와 실제 모델 응답 성공을 구분하고, 설정을 바꾸면 이전 연결 확인을 다시 요구합니다. 실패 원인과 다음 행동은 한국어로 보여 주며, 확인 결과는 다른 화면 항목을 조작해도 유지됩니다.
• Kordoc 설치 실패·시간 초과·Node.js/npm 누락에 맞는 복구 안내를 추가했습니다. 설치 도구가 없어도 준비 상태 재확인과 빠른 구조 전처리는 계속할 수 있으며, 설치는 사용자가 버튼을 눌렀을 때만 실행됩니다.
• Qwen 앱 실행과 설치·진단 처리를 화면 밖의 서비스로 분리했습니다. 규정 작성 화면의 템플릿 조회와 초안 생성도 같은 서비스를 사용하며, GitHub 자동 검증에서 새 서비스와 복구 화면 테스트를 기존 전처리 회귀 검사보다 먼저 실행합니다.
• 해당 개발 완료 시 기록된 전체 검증은 3,753개 실행, 실패·오류 0개, 16개 건너뜀이며, sdist·wheel 빌드와 공개 소스 위생 감사를 통과했습니다. 합성 문서의 실제 MCP STDIO 조회와 숨김 Qwen 앱의 시작·상태 응답도 확인했습니다. 이는 실제 Qwen 모델의 답변 품질이나 초보자 5명 사용성 파일럿 완료를 의미하지 않습니다.
• 상세 근거와 남은 과제는 초보자 화면 안내 검증과 초보자·유지보수 Sprint 2 기록을 참고하세요.

2026년 9월 19일 — AI 검수 결과 표시와 첫 MCP 성공 검증 보강

• AI 검수 응답 처리와 결과 표시를 보완하고, 처리 서비스 회귀 테스트를 추가했습니다.
• 공개 합성 문서와 임시 기관만으로 전처리·승인·색인 후 실제 MCP 프로세스의 list_regulations·search·fetch까지 확인하는 첫 성공 검증 도구를 추가했습니다.
• README에 현재 실행판과 소스 실행의 차이, Kordoc 준비 확인, 검증 진입점을 안내했습니다. 실행 순서는 초보자 첫 성공 검증에서 확인할 수 있습니다.

2026년 9월 14일 — 초보자 흐름과 유지보수 경계 개선

• 전처리·결과 확인·승인·연결 단계를 공통 상태로 계산하고, 사이드바에 현재 단계와 다음 행동을 한국어로 표시합니다. 상태 계산에 문제가 생겨도 안전한 전처리 단계로 돌아갑니다.
• MCP와 로컬 Qwen 연결 진단에서 등록 필요, 연결 대기, 조치 필요, 오래된 상태, 사용 가능을 구분하고 상태별 복구 안내를 제공합니다.
• 연결 진단, 준비 상태 변환, 워크플로 계산을 독립 서비스로 분리해 화면 코드와 별도로 테스트하고 유지보수할 수 있도록 했습니다.
• 빈 경로, 허용되지 않은 경로, 과도하게 큰 설정 파일, 비정상 응답과 비정상 종료를 성공으로 표시하지 않는 fail-closed 처리를 추가했습니다.
• Local LLM 진단과 Qwen 연결 상태가 같은 준비 상태 계약을 사용하도록 정리했습니다.
• 이번 변경에 대한 집중 테스트 114개, 전체 테스트 3,694개 통과(16개 건너뜀)와 빌드·릴리스 위생 검사를 완료했습니다.
• 자세한 범위와 보류 항목은 초보자·유지보수 오케스트레이션 계획에서 확인할 수 있습니다.

2026년 8월 31일 — 파일 단위 일괄 최종 확정과 사람 검토 권고

• 한 파일에 승인 대기 조문이 남아 있으면 초보자 모드에서도 "이 파일의 전체 규정 N개 최종 확정" 버튼을 바로 누를 수 있게 했습니다. 이전에는 모든 조문을 하나씩 검수해야만 버튼이 활성화돼, 큰 합본을 한 번에 승인할 수 없었습니다.
• 검수하지 않은 조문은 기본 사유와 함께 approved_without_review(검토 없이 승인)로 감사 추적에 자동 기록되고, 버튼을 누를 때 사람 검토 권고 경고가 항상 표시됩니다(승인을 막지 않는 안내용).
• 규정을 한 건씩 확정하는 "이 규정 최종 확정" 버튼은 기존의 조문별 검수 게이트를 그대로 유지합니다. 검수를 마친 조문은 approved_without_review로 잘못 기록되지 않습니다.

2026년 8월 30일 — 초보자용 규정 작성 MVP와 안전한 검토 경계

• 원문 없이 시작할 수 있는 신규 제정·일부 개정·전부 개정 템플릿과 단계별 쉬운말 안내를 추가했습니다.
• 필수 메타데이터, 빈 조문, 조문 번호 중복, 끊어진 내부 참조와 체크리스트 누락을 검토 요청 전에 결정론적으로 검사합니다.
• 작성 상태를 계획 → 작성 → 검토 요청 → 수정 요청 → 내용 동결 → 내보내기의 명시적 상태 머신으로 관리하고, 잘못 만든 작업은 별도로 폐기할 수 있습니다.
• 작성 데이터는 기관·프로필별 저장소에 격리하고, revision 충돌·감사 이벤트·무결성 해시, export/purge 경합과 비정상 종료 복구를 강화했습니다.
• 로컬 1인 연습은 명시적 동의가 있어야 training_only로 동결할 수 있고, 보호 환경에서는 서로 다른 작성자·확인자만 동결할 수 있습니다. 작성 초안은 공식 승인·RAG·MCP로 자동 전달되지 않습니다.
• 전체 테스트 3,614개 통과(16개 건너뜀), 작성 기능 집중 테스트 108개 통과 (2개 건너뜀), 브랜치 포함 작성 경로 커버리지 **85%**를 확인했습니다.
• Claude 최종 읽기 전용 감리에서는 새 High/Medium/Low 코드 결함이 발견되지 않았습니다. 다만 일반 출시 전에는 초보자 5명 이상 실제 파일럿, 운영 계정 분리 증거, symlink 실행이 가능한 CI 검증이 필요합니다.

구현 범위와 남은 출시 조건은 작성 구현·검증 보고서, Claude 독립 감리, 초보자 사용성 검증 계획에서 확인할 수 있습니다.

2026년 8월 29일 — 초보자 검수, 파싱 안전성, 승인 RAG 정확성 강화

이번 업데이트는 단순 처리 속도보다 잘못 읽거나 근거 없이 답하는 경우를 줄이고, 처음 사용하는 사람도 승인까지 안전하게 끝내는 것에 초점을 맞췄습니다.

처음 사용하는 사람을 위한 검수 흐름

• AI 검수 의견은 오른쪽의 읽기 전용 참고 자료로 분리했습니다. AI가 사람의 최종본을 자동으로 바꾸거나 승인하지 않으며, 가운데 최종본은 사용자가 직접 확인·수정합니다.
• AI 의견을 수정 필요로 판단했다면 실제 내용을 고치거나 처리 근거 메모를 남겨야 완료할 수 있습니다. 승인 뒤 본문이 바뀌면 이전 확인은 자동으로 무효가 됩니다.
• 여러 규정을 처리할 때 현재 규정부터 한 건씩 검수하도록 페이지를 나누고, 초보자에게 필요하지 않은 내부 청크 정보는 숨겼습니다.
• 실제 기관 문서 없이도 전체 흐름을 연습할 수 있는 합성 DOCX 예제를 추가했습니다.
• 문서·기관 삭제는 삭제 대상을 먼저 보여 준 뒤 다시 확인하는 2단계 방식으로 바꾸고, Vector/BM25 정리 중 일시 오류가 나면 안전하게 재시도합니다.

HWP·HWPX·XML 파싱 안전성

• UTF-8뿐 아니라 UTF-16/UTF-32의 little-endian·big-endian XML도 올바르게 판별합니다.
• 외부 엔티티·DTD가 포함되거나 XML이 손상된 HWPML/HWPX는 일부 내용만 조용히 통과시키지 않고 안전하게 실패 처리합니다.
• 깨진 대체 문자, 원본 페이지 위치 누락, 불확실한 구조 제목은 자동 승인하지 않고 사람이 확인할 항목으로 표시합니다.
• 새 규정·부칙·별표 경계를 더 보수적으로 판단해 합본 문서의 조문이 다른 규정에 섞이는 위험을 줄였습니다.

승인 RAG와 MCP의 근거 정확성

• 검색된 후보 전체가 아니라 실제로 답변을 뒷받침하는 승인 근거만 citation으로 반환합니다. 질문을 뒷받침할 근거가 없으면 다른 조문을 억지로 인용하지 않고 답변을 보류합니다.
• verifier 오류, 비승인 청크, 손상된 근거 데이터는 fail-closed로 차단합니다.
• 정확한 조문 번호가 낮은 순위에 있더라도 다시 살리는 exact-anchor 경로와 한글·한자·전각 문자를 일관되게 찾는 NFKC tokenizer/BM25 v3를 적용했습니다.
• citation URL은 공개 HTTP(S) 주소만 허용하고 로컬 경로, 인증정보, localhost·사설 주소, 비밀값이 담긴 query/fragment는 외부 응답에서 제거합니다.
• HTTP MCP bearer token은 상수시간 byte 비교를 사용하며 비ASCII 입력도 500 오류 없이 정상적으로 거절하거나 설정값과 비교합니다.

검증 결과와 성능 수치

• 독립 CPython 3.11.9와 공개 릴리스 하네스에서 전체 테스트 3,435개 통과 (14개 건너뜀).
• 파싱·인증·citation·RAG/MCP·삭제·초보자 UI 핵심 테스트 448개를 5회 반복해 추가 2,240개 실행 모두 통과했습니다.
• 공개 릴리스 하네스의 build, sdist, Windows portable, 설치형 console, MCP 실제 전송, 공개 위생 검사를 포함한 필수 단계 13/13 통과, 공개 release gate finding 0을 확인했습니다.
• 실제 프로세스로 Streamlit과 FastAPI를 기동하고, bearer 인증을 건 streamable-http MCP의 full·ChatGPT-data 프로필을 끝까지 호출했습니다.
• 100페이지 합성 문서 처리 기준 3.934초, 초당 25.419페이지, 품질 98점, 오류 0건을 확인했습니다. 이전 버전과 동일 fixture로 측정한 전후 기준은 없으므로 순수 속도가 몇 % 빨라졌다는 의미는 아니며, 이번 업데이트의 주효과는 정확성·안전성·운영 편의성입니다.
• Claude 최종 전체 diff 검토와 파싱·RAG·UX 독립 감사 결과에서 남은 P0/P1 문제는 발견되지 않았습니다.

2026년 8월 23일 — 독립 Qwen 챗봇을 MCP 수준의 빠른 검색·응답 경로로 변경

이전 질문이 제1조였던 상태에서 제5조 내용은 뭐야를 물으면 두 조문을 하나의 검색문으로 합쳐 CPU 재랭커를 실행하던 문제를 수정했습니다. 독립 Qwen 챗봇의 기본 모드는 이제 MCP와 같이 승인 BM25 인덱스를 빠르게 조회하고, Qwen3 8B는 짧은 답변과 사용한 근거 ID만 만듭니다.

• 현재 질문만으로 조문이 명확하면 이전 대화를 검색어에 섞지 않습니다. 그 내용은?처럼 앞 질문이 필요한 경우에만 최근 사용자 질문을 검색 문맥으로 사용합니다.
• 독립 챗봇 기본 검색에서는 Qwen3 1.7B 질문 분석, Qwen3 Embedding 질의 계산, CPU Qwen3 Reranker를 실행하지 않습니다. 승인·tenant·기관·문서·ACL·최신본 필터는 유지됩니다.
• 기본 빠른 모드는 Qwen3 8B 한 모델을 GPU에 유지하며, 답변에 표시된 근거 ID가 실제 승인 검색 결과에 존재하는지 결정론적으로 검증합니다.
• 화면의 Qwen3 4B 정밀 근거 감사를 켜면 기존 다중 주장 의미 감사를 추가합니다. 로컬 GPU 메모리에 따라 8B와 4B를 교체하므로 응답이 크게 느려질 수 있어 기본값은 꺼짐입니다.
• 실제 로컬 데이터와 이전 대화가 있는 제5조 내용은 뭐야 재현에서 검색은 0.49초, 연결 확인으로 8B를 적재한 뒤 답변·인용 완료는 7.34초였습니다.
• 최초 AI 연결 확인은 모델을 GPU에 올리는 과정 때문에 측정 PC에서 약 23초가 걸렸습니다. 이 적재를 질문 전에 명시적으로 끝내므로 대화 화면이 멈춘 것처럼 보이지 않고, 빠른 모드에서는 답변 후 4B로 모델을 바꾸지 않습니다.

2026년 8월 23일 — 정확한 조문 질문의 검색 지연 개선

독립 Qwen 챗봇에서 규정을 고른 뒤 제1조에 대해서 알려줘처럼 조문 하나를 정확히 지정한 질문이 승인 근거 검색 2/5에서 오래 멈추던 문제를 수정했습니다. 원인은 답변을 만드는 Qwen3 8B가 아니라, 이미 조문 번호를 알고 있는데도 질문 분석·의미 임베딩과 CPU 재랭커를 매번 실행하던 검색 경로였습니다.

• 선택한 규정 안의 단일 조문 질문은 기존 tenant·기관·문서·승인·ACL·최신본 필터를 모두 통과한 뒤 article_no가 정확히 일치하는 조항만 바로 찾습니다.
• 제1조는 제11조와 섞이지 않으며, 존재하지 않는 제999조를 물으면 의미가 비슷한 다른 조항으로 바꾸지 않고 근거 없음으로 안전하게 답합니다.
• 정확 조문 경로에서는 Qwen3 1.7B 질문 분석, 질의 임베딩, Qwen3 Reranker를 불러오지 않습니다. 현재 로컬 승인 데이터로 전체 검색 함수를 다시 측정했을 때 검색 단계가 약 0.51초에 끝났습니다.
• 독립 챗봇의 일반 자연어 질문도 승인 BM25/lexical 빠른 검색을 사용합니다. Qwen3 1.7B, Embedding과 재랭커를 쓰는 전체 하이브리드 경로는 API 기본 모드와 정밀 수용시험에 유지되며, 이 경로의 CPU 재랭킹 후보는 최대 20개로 제한하고 적재한 재랭커를 재사용합니다.
• 검색 뒤 Qwen3 8B 답변 생성에는 PC 성능에 따른 시간이 추가로 필요합니다. 선택형 4B 정밀 감사를 켠 경우에만 감사 시간이 더해지며, 진행 상태로 검색·답변·감사를 구분합니다.

2026년 8월 23일 — Qwen을 점검 도구가 아닌 실제 로컬 챗봇으로 연결

별도 RAG 프로젝트를 다시 만들 필요는 없습니다. 이 저장소의 기존 전처리 → 운영자 승인 → 로컬 색인 결과를 Qwen 챗봇과 MCP가 함께 사용합니다. 다만 실제 Qwen 대화는 빌더 안의 탭이 아니라 빌더와 분리된 로컬 챗봇 앱에서 진행합니다. 빌더는 문서 구축·승인·색인을 담당하고, 독립 챗봇은 승인된 규정을 골라 질문하는 역할만 합니다.

• 빌더의 독립 Qwen 챗봇 실행을 한 번 누르면 127.0.0.1의 별도 프로세스와 새 브라우저 창이 열립니다.
• 독립 챗봇은 현재 기관에서 전처리한 규정을 목록으로 보여 주되, 운영자 승인·색인이 모두 끝난 규정만 질문 가능으로 표시하고 질문 입력을 허용합니다. 사람 검수는 승인 전에 권고하지만 완료 여부가 승인 버튼을 막지는 않으며, 미검수 승인은 감사 저널에 별도 기록됩니다.
• 소스 사용자는 RUN_QWEN_CHAT.bat 또는 reg-rag-qwen-chat 명령으로 빌더 없이 챗봇만 실행할 수도 있습니다.
• 기본 빠른 모드는 Qwen3 8B 답변의 근거 ID를 결정적으로 검증합니다. 선택형 4B 정밀 감사를 켜면 Qwen3 4B 주장 감사까지 통과해야 그대로 표시됩니다.
• 의미 검색 Python 런타임이 없으면 기존 승인 색인을 다시 만들지 않고 BM25로 안전하게 내려갑니다.
• Qwen 초안이 감사를 통과하지 못하면 오류 화면으로 끝내지 않고, 승인 근거에서 검증 가능한 발췌 답변과 인용을 반환합니다.
• 질문을 보낸 뒤 화면이 멈춘 것처럼 보이지 않도록 질문 분석 → 승인 근거 검색 → 문맥 구성 → Qwen3 8B 답변 → 결정론적 인용 검증의 실제 단계, 진행 게이지와 경과 시간을 계속 표시합니다. 정밀 감사 토글을 켠 경우에는 Qwen3 8B 답변 뒤 Qwen3 4B 감사 단계도 표시됩니다.
• 질문 기록은 기관 프로필 + 선택한 규정 단위로 분리됩니다. 규정을 바꾸면 이전 규정의 대화가 섞이지 않으며, 실제 검색 요청도 선택한 document_id와 profile_id로 제한됩니다.
• MCP는 같은 승인 RAG를 외부 AI 앱에 연결하는 선택 기능이며, 로컬 Qwen 챗봇 사용에 필수는 아닙니다.
• 첫 시작 화면에서 로컬 Qwen 또는 MCP 연결을 고릅니다. 이 선택은 ④ 메뉴 제목과 초보자 안내의 마지막 절차만 바꾸며, 나중에 왼쪽 메뉴에서 언제든 바꿀 수 있습니다. MCP 기능이나 기존 승인 데이터는 삭제되지 않습니다.

이번 Qwen 독립 실행 변경 검증

• 저장소 전체 회귀 테스트 3,342개 통과(14개 건너뜀)
• 설치·패키징 엔트리포인트와 RUN_QWEN_CHAT.bat --check 통과
• 로컬 Ollama의 Qwen3 1.7B·4B·8B로 질문 분석부터 답변·주장 감사·인용 검증까지 실제 실행 확인
• python -m build --sdist --wheel과 공개 릴리스 위생 검사 통과

2026년 8월 23일 — 전체 과정 설명과 역할·모델 분배

초보자 모드에서는 첫 화면의 초보자 안내 시작을 누른 뒤, 필요할 때 사이드바의 전체 과정과 담당 모델을 한눈에 보기를 펼쳐 보세요. 이 긴 설명은 기본으로 접혀 있어 ①~④ 작업 메뉴를 가리지 않습니다. 전처리 8단계와 질의·답변 7단계를 각 단계의 받는 것 → 만드는 것, 담당 역할, 사용 모델, 문제가 생겼을 때의 다음 행동까지 한 번에 설명합니다. 문서를 실제로 처리한 뒤에는 같은 위치에서 역할별 대기·실행 중·완료·사람 확인 필요·차단 상태와 다음 행동을 확인할 수 있습니다.

• 질문 분석·검색어 보정: Qwen3 1.7B
• 구조·표 검수와 주장 감사: Qwen3 4B
• 근거 기반 답변 초안: Qwen3 8B
• 의미 검색·재순위: Qwen3 Embedding/Reranker 0.6B
• 한국어 OCR: PaddleOCR Korean PP-OCRv5
• 보안 검사·승인·인용 검증·색인 반영: 결정론적 규칙과 사람 확인
• 저장소 .venv 실제 acceptance: 15/15 단계 통과, 외부 API 호출 0건

AI는 승인되지 않은 원문을 색인에 넣거나 사람 승인을 대신하지 않습니다. 모델이나 전문 런타임을 사용할 수 없으면 해당 역할은 제한된 실행 또는 사람 확인 필요로 표시하고 자동으로 다음 단계로 건너뛰지 않습니다. 역할 계약과 실제 실행 규칙은 docs/agent_orchestration_roles_ko.md에서 확인할 수 있습니다.

2026년 8월 22일 — 초보자 모드 실제 사용성 보완

• 각 화면 상단에 지금은 이것만 하세요 안내판을 추가했습니다. 현재 단계의 목적, 지금 해야 할 행동, 끝난 뒤 이동할 위치를 한 문장씩 보여 줍니다.
• 안내판이 고정 문구를 반복하지 않고 기관·문서·승인 상태를 읽어 다음 행동을 계산합니다. 아직 전처리한 문서가 없으면 ②~④ 화면에서도 먼저 ① 문서 올려서 전처리로 이동하도록 안내합니다.
• 초보자 모드 시작 직후 사이드바 토글이 꺼져 보이거나 메뉴 이동 중 모드가 풀리던 상태 동기화 문제를 수정했습니다. 시작, 메뉴 이동, 안내 모드 켜기·끄기 상태가 동일하게 유지됩니다.
• Kordoc 준비 상태를 화면 표시 여부가 아니라 실제 사용 가능 여부로 판단하도록 바꿨습니다. 사이드바와 본문이 서로 다른 다음 행동을 가리키지 않습니다.
• 이전에 저장된 대기 규정은 초보자 모드에서 선택 사항 접힌 영역으로 묶었습니다. 새 파일을 올리는 사용자는 불필요한 목록을 열지 않아도 되고, 기존 파일을 고르면 자동으로 다음 문서 정보 확인 절차를 안내받습니다.
• 초보자 모드에서는 삭제·전문가 설정처럼 실수 가능성이 큰 기능의 노출을 줄이고, 필요한 경우 일반 모드에서 처리하도록 설명을 덧붙였습니다.
• 실제 로컬 브라우저에서 초보자 시작 → 기관 선택 → 단계 이동 → 대기 규정 선택까지 시뮬레이션했습니다. 기존 문서를 실제로 전처리하거나 삭제하는 동작은 데이터 변경을 피하기 위해 실행하지 않았습니다.

이번 변경 검증

• 초보자 모드·운영자 UI 관련 테스트 106개 통과
• python -m py_compile frontend\\streamlit_app.py 통과
• git diff --check 통과
• 공개 릴리스 위생 검사 통과

---

이번에는 화면에 보이는 것과 실제 상태가 다르던 문제를 집중적으로 고쳤습니다. 연결이 되는데 안 된다고 하거나, 지웠는데 지워지지 않거나, AI가 본 내용을 안 봤다고 하던 경우들입니다.

ChatGPT 원격 연결이 "Request timeout"으로 끊기던 문제

• ChatGPT에 Vercel 주소(https://.../mcp)를 등록할 때 커넥터 생성 중 오류 · Request timeout이 뜨며 연결되지 않던 문제를 수정했습니다.
• 원인은 서버가 절대 오지 않을 응답을 기다리게 만든 것이었습니다. Vercel 서버는 먼저 말을 거는 기능이 없는데도, 그 통로를 열어 둔 채 아무것도 보내지 않아 ChatGPT가 첫 응답을 무한정 기다렸습니다. 이제 그 통로를 즉시 닫아 알려 주므로 ChatGPT가 바로 정상 경로로 연결합니다.
• 실제 배포 주소에서 연결부터 list_regulations · search · fetch까지 정상 동작을 확인했습니다.

전처리 진행 막대가 뒤로 되돌아가던 문제

• 파일이 크거나 처리가 오래 걸릴 때 진행률이 100%까지 갔다가 74%로 되돌아가는 등 뒤로 밀리던 문제를 수정했습니다. 작업이 취소된 것처럼 보여 불안을 주던 증상입니다.
• 이제 한 번 올라간 진행률은 내려가지 않습니다. 아래 막대는 '지금 단계의 낱개 진행'이라 단계가 바뀌면 다시 0부터 세는 것이 정상이므로, 단계 이름을 함께 표시해 되돌아간 것으로 오해하지 않도록 했습니다.

깨진 HWP 글자 복구

• HWP 원본 안의 그림·좌표 같은 글자가 아닌 데이터가 한글 사이에 한자나 이상한 기호로 섞여 들어오던 것을 찾아내 정리합니다.
• 품질 검사와 본문 정리가 각자 다르게 판단하던 것을 한 곳으로 모아, 같은 글자를 두고 화면과 검사 결과가 엇갈리지 않습니다.

AI 검수 의견이 화면에 보이지 않던 문제

• 같은 규정을 다시 올리면 이전 검수 결과를 재사용하느라 AI를 다시 부르지 않는데, 그때 이전 검수 의견이 새 문서로 옮겨오지 않아 검수 화면이 조항마다 "AI 검수 의견 없음" 으로 보이던 문제를 수정했습니다.
• 이미 저장된 규정에는 scripts/backfill_agent_review_findings.py로 전처리를 다시 하지 않고 의견만 채워 넣을 수 있습니다. 이미 승인·색인이 끝난 조항은 건드리지 않습니다. 승인 당시 내용이 그대로 보존되어야 색인된 근거와 화면이 어긋나지 않기 때문입니다.

기관을 지우면 정말 지워지도록

• 기관 프로필만 지우면 그 기관의 규정과 승인 기록이 남아 있었고, 기관 ID가 기관명 해시라 같은 이름으로 다시 등록하는 순간 지운 규정이 전부 되살아나던 문제를 수정했습니다.
• 되돌릴 수 없는 삭제이므로 두 단계로 나눴습니다. 먼저 무엇이 몇 개 지워지는지 화면에 보여 주고, 확인한 뒤에 지웁니다.
• 이어서 삭제가 전처리 대기 파일과 저장해 둔 작업 폴더는 찾지 못하던 문제도 수정했습니다. 폴더를 만드는 쪽과 지우는 쪽이 폴더 이름을 서로 다르게 계산하고 있어, 화면은 "지울 데이터 없음"이라고 말한 뒤 실제로 아무것도 지우지 않았습니다. 같은 이유로 지금 쓰고 있는 기관이 '주인 없는 데이터'로 표시되어, 그 화면에서 지우면 살아 있는 기관의 대기 파일이 사라지던 위험도 함께 없앴습니다.
• 다만 이 수정 이전에 만들어진 폴더는 어느 기관 것인지 기록이 없어 자동으로 이어 붙이지 못합니다. 예전 잔여 폴더가 걱정되면 data/pending_uploads와 data/operator_projects를 직접 확인하세요.

표가 있는 규정에 없는 손실을 경고하던 문제

• 별표·서식처럼 표가 들어간 규정마다 "원문에 있는데 색인에 없다"는 경고가 뜨고 품질 점수가 깎이던 문제를 수정했습니다.
• 원인은 같은 내용을 서로 다른 모양으로 비교한 것이었습니다. 원문에서 표 한 줄은 수상종류 표창대상 포상금액처럼 글자만 있고, 정리된 본문은 | 수상종류 | 표창대상 | 형태라 구분선 때문에 서로 다른 글로 취급됐습니다. 이제 양쪽에서 표 구분선을 똑같이 걷어내고 비교합니다.
• 표 바깥의 문장이 진짜로 빠진 경우는 그대로 잡아냅니다. 이 검사가 만들어진 이유인 별표의 ※ … 평균 90점 이상이 된 후보자를 … 같은 단서 누락은 계속 경고합니다.
• 이 경고에 걸린 문서는 AI 검수 대상으로도 끌려갔기 때문에, 표가 있는 규정을 처리할 때 불필요하게 늘던 시간과 API 비용도 함께 줄어듭니다.

검수 화면과 저장 내용의 크고 작은 수정

• 전체 규정 확인 열기를 켜는 순간 원본 · 전처리본 · AI 검수 의견 비교 화면이 통째로 사라지던 문제를 수정했습니다. 아래 전체 목록이 실제로 그 조항을 보여 줄 때만 위 비교 화면을 접습니다.
• 표가 있는 규정에서 표의 각 줄이 본문에 두 번 저장되던 문제를 수정했습니다. 색인 본문이 불필요하게 커지고 MCP가 인용하는 표 내용이 겹쳐 보이던 원인입니다.
• AI 검수 한도가 0(제한 없음)일 때 화면이 "문서당 최대 0개까지 보냅니다"라고 사실과 반대로 안내하던 문구를 바로잡았습니다.
• 보낼 조항이 하나도 없어 AI를 한 번도 부르지 않은 경우를 AI 오류로 기록하던 문제를 수정했습니다. 없던 장애를 알리고 다음 실행의 재사용 판단까지 어긋나게 하던 원인입니다.

검증

• 저장소 전체 테스트 3,146개 통과(14개 건너뜀). 이번에 고친 문제마다 실패를 재현하는 테스트를 함께 넣어, 같은 증상이 되돌아오면 테스트가 먼저 깨지도록 했습니다.
• 수정본을 코드 리뷰에 두 차례 태워, 나온 지적을 반영한 뒤 다시 검증했습니다.
• 전처리 진행 막대는 실제 처리 순서를 그대로 재생해 확인했습니다. 고치기 전에는 되돌아감이 33회(최악 100% → 74%), 고친 뒤에는 129번 갱신 중 0회입니다.

---

이전 업데이트: 2026년 8월 3일

이 시기에는 처음 사용하는 사람도 규정 파일을 올려 MCP를 만들 수 있도록 화면 안내를 보완하고, 규정을 각각 올렸을 때와 합본 규정집으로 올렸을 때의 결과가 같도록 처리 기준을 강화했습니다.

8월 3일 추가 보완 — 단일 규정 오판 수정과 절차별 초보자 안내

• 4-4-3. 여비규정.hwp처럼 한 규정 안의 별표 제목이 있는 문서를 합본 규정집으로 잘못 판단해 승인을 막던 문제를 수정했습니다. 별표 뒤의 짧은 제목만으로는 새 규정으로 보지 않고, 실제 제1조 재시작과 규정 경계 근거가 함께 있을 때만 합본 경계를 의심합니다.
• 초보자 안내를 4개의 큰 설명에서 30개의 세부 확인 절차로 나눴습니다. 왼쪽에는 전체 절차와 완료 상태가 계속 보이고, 화면의 빨간 안내는 현재 해야 할 한 항목만 가리킨 뒤 완료 즉시 다음 미완료 항목으로 이동합니다.
• 전처리 전에는 자동 인식한 규정 정보와 AI 추가 검수 사용 여부를 각각 확인해야 하며, 결과 화면에서는 요약의 전처리된 글자와 품질 경고·이슈·표·별표 확인을 따로 마쳐야 합니다.
• 검수 화면에서는 AI 제안별 판단 → AI 검증 결과 확인 → 왼쪽 원본 규정과 오른쪽 전처리·수정 결과 비교 → 사람 검증 결과 확인 → 다음 미검수 청크 → 승인·색인 순서로 안내합니다. 규정 하나가 끝나면 다음 미완료 규정 결과 확인 버튼을 가리키며, 선택한 모든 규정에서 같은 절차를 반복하기 전에는 MCP 단계로 넘어갈 수 없습니다. 승인만 끝나고 색인이 남은 경우에는 이미 승인된 내용 AI에 등록만 실행 버튼을 별도로 가리킵니다.
• MCP 화면에서는 먼저 승인 조문이 계층 색인과 MCP 도구로 변환되는 원리, 각 도구의 역할, 로컬 STDIO와 원격 HTTPS의 차이를 설명하고 확인받습니다. 그다음 규정 범위 → 사용할 AI 앱 → 저장 위치·방식·MCP 이름 → 파일 묶음 생성을 각각 확인합니다. 이후 선택한 방식에 맞춰 Claude Code, Codex CLI·IDE, Claude Desktop 로컬 연결 또는 ChatGPT·Claude Vercel HTTPS 연결 절차만 보여 줍니다.
• 실제 연결 완료도 한 번에 체크하지 않습니다. AI 앱 등록 → 앱 재시작/새 대화 → 연결 진단 → list_regulations → search → fetch를 순서대로 하나씩 확인해야 완료됩니다.

초보자 안내 모드 추가

• 첫 화면에서 초보자 안내 시작과 일반 모드 중 하나를 선택할 수 있습니다.
• 초보자 모드에서는 지금 눌러야 할 위치를 빨간 테두리·화살표와 3-2 형식의 세부 절차 번호로 보여 주고, 이전·다음·건너뛰기·다시 시작을 지원합니다. 화면의 번호와 사이드바 세부 확인 절차 목록의 번호가 서로 일치합니다.
• 파일 등록 → 결과·검수 권고 확인 → 운영자 승인 → Qwen 챗봇·MCP 연결 순서로 안내하되, 승인이나 색인을 사용자 확인 없이 자동 실행하지 않습니다.
• 같은 문서를 안내 단계마다 다시 전처리하지 않고 기존 결과를 이어서 사용하도록 해 불필요한 대기 시간을 줄였습니다.

개별 규정 파일과 합본 규정집의 결과 통일

• 규정을 파일별로 각각 올리거나 여러 규정을 합친 규정집 한 개로 올려도 MCP에서 보이는 규정 목록·목차·조문·검색 결과의 논리적 구조가 같도록 정규화했습니다.
• MCP를 만들거나 갱신할 때 계층 색인을 자동 생성하므로 사용자가 별도로 다시 만들 필요가 없습니다.
• 합본 안의 규정 경계를 확실히 구분할 수 없으면 일부 조문을 잘못 등록하지 않고 검수와 MCP 노출을 안전하게 차단합니다.
• chatgpt-data 연결에는 list_regulations를 포함해 목록 → 목차 → 정확 조문 → 참조 관계 → 검색 → 원문 확인에 필요한 읽기 도구 7개를 노출합니다.

안전성과 성능 검증 보강

• 같은 폴더의 HWP 규정 45개를 공통 구조 감지·승인 차단 조건으로 다시 검사해 45개 모두 파싱 완료, 총 3,128개 청크, 불명확 합본 경계 0건, 동일한 400 승인 차단 0건을 확인했습니다.
• 사람이 승인한 내용만 검색 색인과 MCP에 포함하며, 전달 파일에는 담당자 이름·검토 메모· 작업 PC 경로 같은 운영 정보를 넣지 않도록 승인 자료를 최소화했습니다.
• 500페이지 합성 텍스트 PDF를 같은 바이트로 다시 측정한 결과 16.981초, 초당 29.445페이지, 품질 98점을 확인했습니다. 이 수치는 스캔 이미지 OCR이나 모든 HWP/HWPX 문서의 속도를 보장하는 값은 아닙니다.
• 저장소 전체 3,014개 테스트, 핵심 업로드·계층 MCP·성능 회귀 315개 테스트, 격리된 소스 배포본 296개 테스트와 Windows 실행판 자체 점검을 통과했습니다.

---

이전 업데이트: 2026년 7월 29일~8월 1일

아래 내용은 이 기간에 적용된 주요 변경을 비전공자도 이해하기 쉽도록 기능 중심으로 정리한 것입니다.

7월 29일 — 많은 규정을 더 빠르고 정확하게 관리

• 규정을 단순한 파일 목록이 아니라 규정 → 개정본 → 장·절·조·별표·부칙 순서로 살펴볼 수 있도록 구조를 정리했습니다.
• 새 규정이나 개정본을 추가할 때 전체 자료를 처음부터 다시 만들지 않고, 바뀐 규정만 다시 처리하고 검색 목록에 반영하도록 개선했습니다.
• 현재 시행 중인 규정과 과거 개정본을 구분해, 질문한 날짜에 맞는 내용을 찾을 수 있도록 날짜 기준 조회를 보강했습니다.
• ChatGPT·Codex·Claude가 규정을 조회하게 하는 MCP 연결 기능에서 규정 목록, 목차, 조문, 인용 관계, 순환 인용, 자연어 검색과 원문 확인을 일관되게 사용할 수 있도록 7개 도구의 동작을 점검했습니다.
• 처음 사용하는 사람도 파일 등록부터 검수·승인, AI 연결까지 따라 할 수 있도록 README 안내를 쉬운 표현과 단계별 흐름으로 개편했습니다.

7월 31일 — 검색 속도와 Windows 배포 안정성 개선

• 규정 수가 많아져도 목록·목차·조문 검색이 느려지지 않도록 반복 작업을 줄이고 검색 처리 속도를 개선했습니다.
• 검색 속도와 결과 품질을 같은 기준으로 측정할 수 있도록 검증 자료와 자동 점검 절차를 보강했습니다.
• Windows에서 테스트와 배포를 실행할 때 운영체제별 경로 차이 때문에 실패하던 문제를 수정했습니다.

8월 1일 — 반복 조회와 첫 연결의 대기 시간 단축

• 한 번 안전성을 확인한 검색 데이터를 다시 사용할 수 있도록 저장해, 같은 자료를 반복해서 확인하는 시간을 줄였습니다.
• 규정의 장·절·조 연결 구조를 매번 새로 계산하지 않고 재사용하도록 개선해, 목록·목차· 조문을 연속해서 조회할 때의 준비 시간을 단축했습니다.
• 잘못된 형식의 MCP 요청은 실제 검색을 시작하기 전에 명확하게 거절하도록 입력 검사를 강화했습니다.
• 서버가 시작할 때 미리 수행하던 불필요한 작업을 줄여 첫 연결과 첫 요청의 대기 시간을 개선했습니다.
• 성능 개선으로 기존 검색 결과가 달라지지 않는지 자동 테스트를 추가했습니다.
• 자동 배포가 다른 변경과 겹쳐도 버전이 잘못 게시되지 않도록 배포 절차를 안정화했습니다.

버전별 세부 변경 내용과 다운로드 파일은 GitHub Releases에서 확인할 수 있습니다.

---