PR MCP Builder

PR MCP Builder

MCP 연결·Kordoc 오류 빠른 해결

Missing or failed Kordoc evidence는 설치 여부가 아니라 해당 문서가 Kordoc으로 전처리됐는지를 뜻합니다.

1. MCP 화면은 Kordoc이 없으면 설치·검증을 한 번 자동 시도합니다.
2. 설치됐지만 증거가 없으면 기존 승인본을 보존한 새 draft를 만들어 자동 재전처리합니다.
3. status=parsed, parser=kordoc 확인 후에만 새 draft가 선택됩니다.
4. 새 결과를 사람 검토·승인·색인한 뒤 MCP 묶음을 생성합니다.

실패 시 기존 approved chunk·approval journal·vector는 바뀌지 않습니다. 저장된 원본이 없을 때만 원본을 다시 올리세요. 수동 설치가 필요하면 INSTALL_KORDOC_KO.ps1 또는 아래 명령을 사용합니다.

npm install -g kordoc
kordoc --version

자세한 PATH·portable·wheel 안내는 MCP 빠른 연결 안내를 참고하세요. 승인 JSON을 직접 수정하거나 Kordoc 게이트를 끄면 안 됩니다.

독립적으로 옮긴 MCP 번들에서 McpError: Connection closed가 나오면 오래된 전역 콘솔 스크립트가 선택된 것일 수 있습니다. 번들에 포함된 install_local_package.ps1을 먼저 실행하거나, 설치된 wheel 환경을 명시한 뒤 연결 BAT를 다시 실행합니다.

$env:REG_RAG_PYTHON = (Join-Path $env:USERPROFILE 'venvs\reg-rag\Scripts\python.exe')
& '.\run_mcp_stdio_server.ps1'

생성 launcher는 source/package Python을 import probe하고 PATH의 reg-rag-mcp-server도 --help 검증 후에만 사용합니다. 검증에 실패하면 설치 또는 REG_RAG_PYTHON 지정 안내를 출력합니다. PowerShell에 표시되는 사용자 홈 경로 같은 호스트 경로를 MCP 설정이나 공개 응답에 복사하지 말고 생성된 번들의 .bat/.ps1 파일을 사용하세요.

원본 문서가 현재 공개 소스 checkout에 없으면 해당 기관의 원본 파일이 있는 운영 환경에서 위 순서로 재처리·승인·색인을 완료한 뒤 번들을 다시 생성해야 합니다.

MCP 구축 후 사용 예시

GIF를 새 창에서 크게 보기

규정 문서를 전처리하고 승인한 뒤 MCP를 연결하면, AI 프로그램에서 승인된 규정만 검색하고 근거와 함께 답변받을 수 있습니다.

v1.2 업데이트 내역

이번 v1.2는 MCP 첫 연결 신뢰성과 파싱·전처리 변경 보호를 강화한 업데이트입니다.

• ChatGPT Desktop 로컬 direct MCP·선택형 플러그인과 ChatGPT 원격 HTTPS MCP 프로필을 실행 방식 기준으로 분리했습니다.
• 플러그인 등록, 현재 대화 첨부, MCP 초기화, 도구 검색, 종단간 검증 상태를 각각 구분합니다.
• initialize → tools/list → get_index_status가 모두 성공해야 연결 검증 완료로 표시합니다.
• Windows BAT의 한글·공백 경로, PowerShell 5.1 UTF-8, 반복 실행과 손상된 설정 복구를 보강했습니다.
• Windows PowerShell 5.1의 Set-Content -Encoding UTF8이 companion JSON에 BOM을 다시 붙이던 공급자 측 결함을 제거하고, 모든 기계 판독 JSON/TOML을 BOM 없는 UTF-8로 저장합니다.
• 동일 이름의 오래된 로컬 마켓플레이스를 현재 번들 경로로 교체하고, codex plugin list --json의 활성 플러그인 버전·공급 경로가 모두 일치해야 등록 성공으로 판정합니다.
• 동일 MCP의 로컬 마켓플레이스 설치를 직렬화하고, Codex가 방금 등록한 마켓플레이스를 일시적으로 찾지 못하면 플러그인 설치를 최대 3회 재시도합니다.
• ChatGPT/Codex 플러그인은 .codex-plugin/plugin.json의 mcpServers가 플러그인 루트의 ./.mcp.json을 가리키고, companion .mcp.json은 현재 Codex 플러그인 검증기·번들 플러그인·app-server가 함께 승인하는 mcpServers 컨테이너를 사용합니다. Codex 독립 로컬 설정의 config.toml은 snake_case [mcp_servers.*]를 사용하며 플러그인 JSON과 계약이 다릅니다. Claude API의 mcp_servers는 또 다른 API 요청 계약입니다.
• Claude Code BAT는 MCP를 --scope user로 등록하고 claude mcp get으로 다시 확인하므로 생성 폴더 밖의 다른 프로젝트에서도 같은 사용자에게 보입니다.
• 내용 기반 플러그인 cachebuster, strict JSON-RPC stdout 검사, ZIP 별도 경로 추출 smoke와 wheel-only 공급 검증을 추가했습니다.
• 파싱·전처리·MCP 연결 로직은 집중 회귀 테스트, 보호 PR 항목, Code Owner 검토를 거치도록 하네스를 추가했습니다.

ChatGPT Desktop, Codex, Claude Code는 생성 번들을 로컬 작업공간으로 연 뒤 대상별 연결 요청문을 실행하는 방식이 기본입니다. 에이전트에 로컬 파일·터미널 권한이 없을 때만 생성된 .bat를 보조 수단으로 사용합니다. Claude Desktop은 전용 BAT가 기본입니다. 1.2 MCP 연결 상세에서 대상별 절차와 검증 상태를 확인할 수 있습니다.

공급자 회귀 하네스는 Windows 설치를 두 번 반복한 뒤에도 .mcp.json이 EF BB BF로 시작하지 않는지 확인하고, initialize → tools/list → get_index_status가 실제로 성공해야 직접 연결 검증을 완료합니다. 공급 ZIP에서는 .venv, __pycache__, 빌드 캐시와 로컬 런타임 부산물을 제외합니다.

v1.1.0 업데이트 내역

• /documents/{id}/chunks와 검색 경로에서 보안등급·부서 ACL을 일관되게 적용해 상위 등급 청크가 viewer에게 노출되지 않도록 했습니다.
• 폐지·대체 규정과 소급 개정의 효력일 처리를 fail-closed로 보강하고, 시점 조회와 현행 근거 선택의 정확도를 높였습니다.
• HWPX 섹션 순서·실패 신호, DOCX 병합 셀, 표 헤더 중복, 시각표의 시:분, 원문자 항목 등 규정 문서 파싱 경계 사례를 보완했습니다.
• Unicode 정규화, BM25/FTS 관련성 계산, RAG 가시성 캐시를 개선해 검색 결과의 일관성과 자원 사용을 높였습니다.
• 업로드 provenance의 경로 노출과 JSON Content-Type 우회 등 공개·운영 경계의 보안 검사를 강화했습니다.

공공기관 규정 MCP 빌더

PDF, HWP, HWPX, DOCX 형식의 공공기관 규정을 기관 → 규정 → 개정 버전 → 장·절·조문 구조로 정리하고, 사람이 승인한 내용만 검색 색인과 MCP 응답에 포함하는 Windows용 빌더입니다.

단순히 모든 문장을 같은 크기로 잘라 유사도 검색만 하지 않습니다. 규정명과 목차를 먼저 좁힌 뒤 최신 유효 개정본의 조문을 찾고, 필요한 경우 이전 개정 이력까지 추적합니다. 같은 기관의 개정판을 다시 넣으면 본문 앞부분의 제정·개정 이력과 시행일을 읽어 기존 규정 계열에 새 버전으로 연결합니다.

MCP 빌더 화면 안내

GIF를 새 창에서 크게 보기

[!IMPORTANT]현재 개발 중인 공개 소스 기반 개발판입니다. Streamlit 화면은 로컬 운영자용이며, 실제 기관 적용 전 문서 형식, 개정 이력, 반출 범위와 보안 정책에 맞춘 검증이 필요합니다. 승인되지 않은 청크는 검색 색인과 MCP 응답에 포함하지 마세요.

1.2 업데이트: MCP 첫 연결 신뢰성

1.2에서는 ChatGPT Desktop, Codex, Claude Code에 대상별 에이전트 연결 요청문을 기본으로 제공하고 BAT는 보조 수단으로 유지합니다. Claude Desktop은 전용 BAT를 기본으로 사용합니다. 내부 프로필과 상태 판정도 다음처럼 강화했습니다.

• chatgpt-desktop-local: ChatGPT Desktop과 Codex가 공유하는 ~/.codex/config.toml에 로컬 stdio MCP를 direct 등록합니다. 등록 후 ChatGPT Desktop을 완전히 재시작하고 새 대화에서 먼저 /mcp로 MCP 이름을 확인합니다. @MCP이름은 연결 확인 명령이 아니며 반복 입력해도 설치되지 않습니다. 생성된 플러그인 marketplace는 Work/Codex 플러그인 배포가 필요할 때만 쓰는 선택 산출물입니다.
• chatgpt-remote: 인증된 HTTPS Streamable HTTP 엔드포인트를 별도 등록합니다. ChatGPT 대화는 localhost MCP에 직접 연결하지 않으므로 공개 HTTPS 또는 승인된 Secure MCP Tunnel이 필요합니다.
• claude-desktop: 앱 설정의 로컬 stdio 프로필을 유지하며, Windows PowerShell 5.1의 UTF-8·한글/공백 경로와 손상된 생성 JSON 복구를 처리합니다.
• claude-code: 공식 CLI의 사용자 범위(--scope user)로 로컬 stdio MCP를 등록한 뒤 claude mcp get으로 확인해, 생성 폴더 밖에서 실행한 Claude Code에도 적용합니다.
• 같은 로컬 플러그인 연결 BAT가 겹쳐 실행되면 먼저 시작한 설치가 끝날 때까지 대기합니다. 마켓플레이스 등록 직후의 일시적인 marketplace ... is not configured or installed 오류는 마켓플레이스를 재확인한 뒤 최대 3회 재시도합니다.
• plugin_registered는 manifest 검증, 설치 명령 성공, codex plugin list --json에서 새 cachebuster 버전·활성 상태·현재 번들의 마켓플레이스 경로가 모두 일치한 경우에만 참입니다. 현재 대화의 도구 첨부와 동일하게 취급하지 않습니다.
• 실제 MCP initialize → tools/list → get_index_status가 모두 성공하면 transport_end_to_end_verified=true가 됩니다. ChatGPT Desktop의 end_to_end_verified=true는 Desktop 도구 노출과 현재 대화의 실제 호출까지 확인하기 전에는 기록하지 않습니다.

ChatGPT Desktop 새 대화의 첫 검증 문장은 다음과 같습니다.

aksmcp MCP의 연결 상태와 사용 가능한 규정 도구를 보여줘.

direct MCP가 보이지 않으면 설치·로더 검증이 완료됐는지 확인한 뒤 ChatGPT Desktop을 완전히 종료해 재시작하고 새 대화에서 /mcp를 다시 확인합니다. 그 뒤에도 로컬 MCP가 보이지 않는 제품 구성에서는 chatgpt-remote 또는 Secure MCP Tunnel을 사용합니다. 선택형 플러그인은 Work/Codex 배포가 명시적으로 필요할 때만 사용하며, @aksmcp 반복 입력만으로 설치나 연결이 이루어지지는 않습니다.

1.2 연결 상태와 검증 기준

생성 번들의 bundle_status.json은 다음 상태를 서로 독립적으로 기록합니다.

• launcher_ready: 실행 launcher가 생성됨
• process_started: 로컬 프로세스 또는 원격 MCP 세션이 실제로 시작됨
• mcp_initialized: MCP initialize 성공
• tools_discovered: MCP tools/list 성공 및 도구 발견
• plugin_install_command_succeeded: 플러그인 설치 명령 종료 코드 성공
• plugin_manifest_validated: plugin.json, .mcp.json, marketplace.json의 strict UTF-8/JSON 검증 성공
• plugin_discoverable: 설치된 selector가 codex plugin list에서 발견됨
• plugin_registered: 위 manifest·설치와 정확한 버전·공급 경로 discoverability 조건이 모두 성공
• direct_stdio_verified: 생성 launcher로 직접 initialize, tools/list, get_index_status 성공
• desktop_tool_scan_verified: ChatGPT Desktop 자체 도구 scan에서 MCP 도구 노출 확인
• conversation_attachment_verified: 현재 대화에서 플러그인 도구 첨부 확인
• conversation_attachment_unverified: 제품 UI의 도구 노출 및 현재 대화의 실제 도구 호출이 아직 확인되지 않음
• end_to_end_verified: 해당 smoke 보고서의 MCP 전송 계약(initialize, tools/list, 필수 도구 호출)이 모두 성공함. ChatGPT Desktop의 현재 대화 첨부 완료를 뜻하지 않음

로컬 stdio와 원격 Streamable HTTP는 실제 MCP 세션으로 따로 검증합니다. .mcp.json은 첫 3바이트가 EF BB BF이면 계약 실패이며, 기계 판독 JSON/TOML은 BOM 없는 UTF-8로 저장합니다. Windows BAT는 한글·공백 경로, 반복 실행, 등록 실패 시 거짓 성공 방지와 손상된 Claude Desktop 생성 JSON 복구를 회귀 테스트합니다. 원격 연결은 인증된 HTTPS 엔드포인트를 대상으로 생성된 validate_chatgpt_remote_mcp.ps1에서 다시 검증하며, 이 성공도 ChatGPT의 현재 대화에 도구가 첨부됐다는 뜻은 아닙니다.

공급 ZIP은 생성 번들, 승인 runtime data, 빌드된 wheel만 allowlist로 포함합니다. .venv, venv, __pycache__, 테스트/빌드 캐시와 로컬 부산물은 포함하지 않으며, 로컬 플러그인의 세 companion JSON은 압축 직전에 다시 strict 검증합니다.

파싱·전처리·MCP 연결 로직과 회귀 기준은 보호 대상입니다. 관련 변경은 집중 회귀 테스트, PR 본문의 영향·불변조건·검증 근거, Code Owner 검토와 preprocessing-reviewed 라벨을 요구합니다. 자세한 절차는 파싱·전처리·MCP 연결 변경 보호 하네스를 따릅니다.

가장 쉬운 실행

Windows 실행판

배포 ZIP을 사용하는 경우 다음 세 단계만 수행합니다.

1. 최신 GitHub Release의 Assets에서 PR-MCP-Builder-Windows-x64-<버전>.zip을 내려받아 일반 폴더에 완전히 압축 해제합니다.
2. 폴더 안의 **PR MCP Builder.exe**를 더블클릭합니다.
3. 브라우저에서 자동으로 열린 로컬 화면을 사용합니다.

작업 데이터는 기본적으로 %LOCALAPPDATA%\PR MCP Builder\data에 저장됩니다. 8501 포트가 사용 중이면 실행기가 다음 빈 포트를 자동으로 선택합니다.

소스 코드 실행

Python 3.11 이상을 설치한 뒤 프로젝트 폴더에서 **START_HERE.bat**를 더블클릭합니다. 첫 실행에는 가상환경과 패키지 설치를 위해 인터넷 연결이 필요합니다. 이후 기본 주소는 http://127.0.0.1:8501입니다.

같은 실행을 터미널에서 직접 시작하려면 다음 명령을 사용합니다. 로컬 운영 화면은 외부에 노출하지 않도록 127.0.0.1에만 바인딩합니다.

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

소스 실행 시 작업 데이터는 프로젝트 폴더의 data\에 저장됩니다. Windows 실행판은 위에서 안내한 %LOCALAPPDATA%\PR MCP Builder\data를 사용합니다.

실행 조건만 확인하려면 다음 명령을 사용합니다.

.\START_HERE.bat --check

처리 구조

기관 선택
→ 규정 파일 업로드
→ 규정명·개정일·시행일·개정 이력 인식
→ 규정/버전/목차/조문 계층 색인
→ AI 제안 검토 + 사람 원문 대조
→ 승인된 최신 유효본만 검색·MCP에 반영
→ ChatGPT Desktop·Codex·Claude 로컬 연결 또는 ChatGPT·Claude HTTPS 연결

• 기관별 작업 공간, 대기 파일, 프로젝트 저장, 승인 데이터와 MCP 산출물을 분리합니다.
• 같은 기관 안에서도 규정 ID와 버전 ID를 분리해 과거 개정본을 보존합니다.
• 사람에게 승인되지 않은 청크는 검색 색인과 MCP 응답에 포함하지 않습니다.
• 전체 규정을 다시 탑재해도 같은 기관명·규정명·개정 이력에서 동일한 계층 구조를 재구성합니다.
• MCP 서버 이름은 고정값이 아닙니다. 생성 화면에서 사용자가 직접 입력해야 하며, 화면의 예시는 자동 적용되지 않습니다.
• 저장 위치도 고정하지 않습니다. 사용자가 선택한 폴더의 절대 경로를 클라이언트별 설정에 반영합니다.

화면 사용 순서

아래 화면을 따라 기관 선택부터 MCP 연결까지 순서대로 진행합니다.

1. 기관 선택

첫 화면에서는 기관명만 입력하거나 등록된 기관을 선택합니다. 이 단계에서는 저장 프로젝트 불러오기, API 키, 규정 파일 또는 MCP 설정을 표시하지 않습니다. 기관을 선택한 뒤 열리는 두 번째 대시보드부터 해당 기관의 프로젝트 저장·불러오기를 사용할 수 있습니다.

기관을 선택한 뒤부터 문서, 승인 기록, 검색 범위와 MCP 산출물은 선택 기관 범위로 제한됩니다. 다른 기관의 저장 프로젝트나 문서 ID를 불러와도 현재 기관과 일치하지 않으면 화면에서 차단합니다.

2. 규정 업로드와 전처리

① 문서 올려서 전처리에서 PDF, HWP, HWPX 또는 DOCX 파일을 선택합니다. 여러 파일을 한 번에 넣어도 규정 계열과 개정 버전 순서로 분류합니다.

자동 인식은 파일명만 보지 않습니다. 본문 앞부분의 제정, 개정, 전부개정, 시행일과 개정 이력을 우선해 규정명과 버전을 정합니다. 특수한 문서만 자동 인식값을 직접 수정에서 보완합니다.

전처리 중에는 실제 작업 단계와 처리 건수를 게이지로 표시합니다. 큰 통합 규정집도 규정 1/N, 구조 저장, 청크 저장, 검사 결과 저장, 내보내기와 경과 시간이 계속 갱신됩니다.

선택 기능: 외부 AI 검수

AI 검수는 필수 전처리가 아니라 선택 기능이며 기본값은 꺼짐입니다. 끈 상태에서는 외부로 내용을 보내지 않고 로컬 파서와 사람 검수만 사용합니다. 켠 경우에만 품질 경고가 있는 조문, 표, 별표, 부록과 깨진 문자 같은 의심 구간을 선택한 공급자에 보내 검수 초안을 받습니다.

지원하는 공급자는 다음과 같습니다.

OpenAI에서는 구조화된 지시 준수, 속도와 비용의 균형을 기준으로 gpt-4.1-mini를 이 제품의 기본 권장값으로 표시합니다. 이 모델은 Chat Completions와 structured outputs를 지원합니다. 자세한 사양은 OpenAI 공식 GPT-4.1 mini 문서를 확인합니다.

README 촬영용 샘플에서는 외부 API 키를 넣지 않았으므로 실제 AI 문장 수정은 실행되지 않았고, 로컬 파서가 위험 구간을 표시한 검수 초안이 중심이었습니다. 따라서 AI 검수 결과가 없거나 수정 제안이 적어도 오류가 아닙니다. AI 검수는 자동 승인 기능이 아니며, 결과를 사용하더라도 사람이 원문과 대조한 뒤 반영 여부를 결정해야 합니다.

3. 결과 확인

구조 노드 수, 청크 수, 이슈, 품질 점수와 인식된 규정·버전 정보를 확인합니다. 140개 이상의 규정이 들어 있는 파일도 먼저 규정과 목차를 좁히고 조문으로 들어갈 수 있도록 계층 색인을 만듭니다.

여러 규정 파일을 함께 올리면 모두 기본 선택된 함께 처리할 규정 디렉터리가 먼저 표시됩니다. 규정 열기를 누르면 그 규정의 상세 데이터만 불러오므로 대량 문서 전체를 매번 화면에 펼치지 않습니다. 선택한 규정에서는 다음 내용을 확인할 수 있습니다.

• 현재 규정과 직전·이전·이후 개정판 관계
• 목차와 청크 위치, 원문 페이지, 신뢰도와 경고
• 선택 청크의 원문과 전처리 결과 좌우 비교, 직전·현재·다음 청크 문맥

체크된 규정은 결과 확인, 검수·승인, MCP 생성 단계까지 한 작업 묶음으로 유지됩니다. 일부 규정을 이번 MCP에서 제외하려는 경우에만 체크를 해제합니다.

4. AI·사람 검수

검수는 청크별로 진행할 수도 있고 전체 버튼으로 마칠 수도 있습니다.

• 전체 규정 자료 AI 검수 완료: 기존 상태와 관계없이 전체 AI 제안을 한 번에 확인 처리합니다.
• 전체 규정 자료 사람 확인 완료: 전체 청크의 사람 확인을 한 번에 완료합니다.
• 나머지 부분 AI 점검 전체 완료: 이미 개별 처리한 반영·반영 안 함 결정은 보존하고, 아직 결정하지 않은 AI 제안만 확인 완료 처리합니다.
• 나머지 부분 사람 점검 전체 완료: 이미 사람이 확인한 청크는 그대로 두고, 아직 미확인인 청크만 확인 완료 처리합니다.

따라서 일부 청크를 먼저 자세히 수정한 뒤 나머지만 일괄 점검해도 앞선 작업이 덮어써지지 않습니다. AI 일괄 점검은 최종 승인을 대신하지 않으며, 승인 전 사람이 원문과 수정 후 결과를 확인해야 합니다.

승인하고 색인을 누르면 검수 완료된 청크만 승인 색인에 들어갑니다. 승인된 최신 유효본과 MCP에 노출되는 기록 수가 일치하는지 화면에서 확인합니다. 이 순서는 승인된 규정만 MCP 데이터로 생성하기 위한 필수 게이트입니다.

5. MCP 범위와 연결 대상 선택

④ MCP 생성·AI 연결에서 데이터 범위를 선택합니다.

• 선택한 규정 N개: 앞 단계에서 체크한 규정을 빠짐없이 하나의 MCP에 포함합니다. 기본 선택입니다.
• 현재 연 규정만: 디렉터리에서 현재 열어 본 규정 하나만 포함합니다.
• 선택 기관의 승인 규정 전체: 현재 기관의 승인된 최신 유효 규정을 모두 포함합니다.

선택한 규정 N개에서는 각 규정의 승인 청크 수와 MCP 노출 기록 수를 표로 확인합니다. 하나라도 검수·승인·색인이 끝나지 않았으면 누락된 채 생성하지 않고 MCP 생성 버튼을 잠급니다.

그다음 ChatGPT Desktop 로컬 direct MCP, Codex CLI, Claude Desktop, Claude Code, ChatGPT 원격 MCP 또는 Claude HTTPS 중 실제로 사용할 대상을 선택합니다. ChatGPT Desktop, Codex, Claude Code는 압축을 푼 번들 폴더를 로컬 작업공간으로 연 뒤 생성 결과 아래의 대상별 에이전트 연결 요청문을 붙여넣는 방식을 우선 사용합니다. 에이전트가 doctor·설치·각 CLI의 mcp get 검증을 실행하며, 일반 채팅처럼 로컬 파일·터미널 권한이 없는 화면에서는 BAT를 보조 수단으로 사용합니다.

6. MCP 파일 묶음 생성

생성할 MCP 이름을 사용자가 직접 입력하고 저장 폴더를 확인한 뒤 MCP로 쓸 파일 묶음 만들기 버튼을 누릅니다. 폴더명에서 만든 값은 입력 예시로만 표시되며 자동으로 적용되지 않습니다. 이름을 입력하지 않으면 ZIP, BAT, 연결 설정을 생성할 수 없고, 입력한 이름만 각 AI 앱의 MCP 이름으로 등록됩니다.

승인 데이터 복사, 계층 DB 생성, 연결 설정 작성, 스크립트 생성과 ZIP 압축 진행률이 실제 완료 항목에 맞춰 표시됩니다. C:\ 루트처럼 쓰기 권한이 제한될 수 있는 위치를 직접 지정하지 말고 문서, 바탕 화면 또는 사용자가 선택한 폴더에 저장합니다.

생성 폴더에는 선택한 클라이언트에 맞는 더블클릭용 파일이 들어갑니다.

대량 규정 진행 표시

800페이지 또는 140개 이상 규정이 포함된 통합 문서는 페이지 이동과 저장도 오래 걸릴 수 있습니다. 다음 작업은 흰 화면에서 무응답으로 기다리게 하지 않고 진행 창을 유지합니다.

• 전처리: 현재 파일, 내부 규정 번호, 구조·청크·검사·내보내기 건수와 경과 시간
• 다음 단계 이동: 문서·청크·목차·색인 상태를 백그라운드에서 미리 읽는 실제 진행률과 heartbeat
• 전체/나머지 검수: 완료 청크 수와 전체 청크 수
• 승인·색인: 승인 묶음 수, 색인 단계, 경과 시간
• MCP 생성: 승인 데이터 복사, 계층 DB와 BM25 생성, 연결 파일 작성, ZIP 압축 바이트 수

내부 라이브러리가 세부 건수를 잠시 주지 않는 구간에도 작업 중..., 경과 시간과 마지막 완료 단계를 0.5초마다 갱신합니다. 추정 진행률은 실제 측정값보다 앞서 완료 처리하지 않으며, 실제 완료 이벤트를 받은 뒤에만 100%가 됩니다.

로컬 연결

비개발자는 PowerShell 스크립트나 JSON 설정을 직접 편집할 필요가 없습니다.

1. ChatGPT Desktop, Codex, Claude Code는 압축을 푼 MCP 생성 폴더를 해당 앱의 로컬 작업공간으로 엽니다.
2. 아래 표의 대상별 에이전트 연결 요청문을 붙여넣고 doctor·설치·로더 검증이 끝날 때까지 실행합니다. 로컬 실행 권한이 없을 때만 같은 대상의 BAT를 사용합니다.
3. 검증 완료 후 해당 앱을 완전히 종료하고 다시 실행합니다.
4. 재시작한 새 대화 또는 task에서 /mcp로 입력한이름을 확인하고 입력한이름 MCP의 get_index_status를 실행해줘.라고 호출합니다.
5. Claude Desktop은 전용 BAT를 더블클릭하고 검증 완료 후 앱을 완전히 종료·재실행합니다. Claude Desktop에는 위 /mcp 단계를 적용하지 않습니다.

각 앱은 같은 승인 데이터를 사용하지만 설정 파일과 등록 방식이 다르므로 연결 경로도 분리합니다. ChatGPT Desktop, Codex, Claude Code는 대상별 요청문 실행과 설치 검증이 완료된 뒤 해당 앱을 완전히 종료·재실행하고 새 대화 또는 task에서 /mcp를 확인합니다. ChatGPT Desktop은 공유 config.toml direct 등록이 기본이며 플러그인은 Work/Codex 배포가 필요할 때만 선택합니다. ChatGPT Desktop의 Settings > MCP servers > Add server는 공식 내장 수동 대안이지만, 이 번들은 패키지 설치와 긴 인자·경로 검증까지 처리하는 복사 프롬프트를 우선합니다. Claude Desktop은 전용 BAT와 앱 재시작을 사용하고 /mcp 공통 지시에서는 제외합니다.

같은 MCP 이름으로 다시 생성하고 대상별 에이전트 프롬프트를 다시 실행하면 기존 항목을 중복 추가하지 않고 새 경로와 설정으로 교체합니다. 로컬 에이전트를 사용할 수 없을 때만 같은 클라이언트 BAT를 실행합니다. 생성할 때 현재 승인된 전체 청크를 다시 묶으므로 추가 규정과 개정판 청크도 같은 MCP 이름으로 조회됩니다. 폴더를 옮겼다면 새 폴더를 작업공간으로 열고 연결 프롬프트 또는 보조 BAT를 다시 실행합니다.

생성 폴더의 설치 후 MCP 사용 방법 보기.bat는 클라이언트별 확인 명령과 실제 MCP 이름이 들어간 첫 호출 문장을 보여줍니다. Codex 플러그인 MCP 입력값.txt는 Codex CLI 수동 호환 설정용입니다.

생성 파일의 의미, 수동 점검 명령과 장애 해결 절차는 MCP 빠른 연결 안내에 정리되어 있습니다.

ChatGPT 웹 연결

chatgpt-desktop-local과 chatgpt-remote는 서로 다른 실행 방식입니다. ChatGPT 사용자 지정 MCP 앱은 인터넷에서 접근 가능한 원격 MCP 엔드포인트가 필요합니다. localhost나 로컬 stdio에 직접 연결할 수 없으므로 HTTPS 배포 또는 승인된 보안 Tunnel을 사용합니다.

생성 화면의 연결 방식 표기에서 MCP HTTP - URL로 연결은 운영자가 준비한 HTTPS 주소를 사용하고, OpenAI Secure MCP Tunnel은 생성된 run_openai_secure_tunnel.ps1을 이용하는 보안 Tunnel 흐름을 뜻합니다.

1. 생성 화면에서 ChatGPT HTTPS 또는 ChatGPT 보안 Tunnel을 선택합니다.
2. HTTPS 방식이면 공개 기본 주소를 입력합니다. 화면이 최종 /mcp 주소를 표시합니다.
3. MCP 묶음을 승인된 서버에 배포하고 TLS와 인증을 구성합니다.
4. ChatGPT의 Settings > Security and login에서 Developer mode를 켭니다.
5. Settings > Plugins 또는 https://chatgpt.com/plugins에서 개발자 모드 앱을 만들고 생성한 HTTPS MCP URL을 입력합니다. 표시된 도구 목록에 search와 fetch가 있는지 확인합니다.
6. 새 ChatGPT 대화에서 + → More를 열어 만든 앱을 선택한 뒤 MCP이름 MCP의 search 도구로 인사규정을 찾고, 반환된 첫 번째 id를 fetch 도구로 조회해 조문 원문과 출처를 보여줘.라고 요청합니다.

플랜과 워크스페이스 관리자 정책에 따라 개발자 모드나 사용자 지정 앱 메뉴가 보이지 않을 수 있습니다. 최신 조건은 OpenAI 공식 문서의 ChatGPT와 Codex 플러그인, Developer mode와 MCP apps 및 Apps in ChatGPT를 확인합니다.

Claude 연결

같은 PC의 Claude Desktop과 Claude Code는 로컬 stdio 방식이 가장 간단합니다. Claude Desktop은 위 표의 전용 BAT를 실행하고, Claude Code는 번들을 작업공간으로 연 뒤 CLAUDE_CODE_AGENT_CONNECT_PROMPT.md를 실행합니다. Claude Code에서 로컬 실행 권한이 없을 때만 보조 BAT를 사용합니다. 두 자동 경로 모두 Anthropic 공식 scope 구분에 따라 사용자 범위로 등록하므로 같은 사용자의 모든 프로젝트에서 사용할 수 있습니다.

Claude 웹 또는 원격 환경에서 사용하려면 다음 순서로 연결합니다.

1. 생성 화면에서 Claude HTTPS를 선택하고 공개 HTTPS 기본 주소를 입력합니다.
2. 생성한 MCP 묶음을 승인된 서버에 배포합니다.
3. Claude의 Settings → Connectors에서 사용자 지정 커넥터를 추가합니다.
4. 최종 /mcp URL과 필요한 인증 정보를 등록합니다.

로컬 Claude Desktop 설정과 원격 커넥터 설정은 서로 다릅니다. 원격 MCP URL을 claude_desktop_config.json의 로컬 stdio 항목처럼 넣지 않습니다. 자세한 내용은 Anthropic 공식 문서의 로컬 Claude Desktop MCP와 원격 custom connectors를 확인합니다.

HTTPS 배포 경계

PR MCP Builder가 자동으로 만드는 범위는 승인 데이터, 계층 검색 DB, MCP 서버 실행 파일, 클라이언트 설정과 연결 스크립트입니다. 다음 항목은 기관 전산 담당자가 운영 환경에 맞게 준비해야 합니다.

• 공개 또는 기관 승인 도메인과 DNS
• TLS 인증서와 HTTPS reverse proxy
• OAuth, mTLS 또는 bearer token 인증
• 서버 방화벽, 감사 로그, 백업과 비밀정보 관리
• ChatGPT/Claude 워크스페이스의 커넥터 승인

원격 MCP를 사용하면 MCP가 반환한 승인 규정 내용이 외부 AI 서비스로 전송될 수 있습니다. 공개 자료 또는 별도 반출 승인을 받은 자료에만 사용하고, 비공개 규정은 로컬 stdio 또는 승인된 내부망 MCP를 우선합니다.

개정판 업데이트 방식

예를 들어 같은 기관의 인사규정1.hwp, 인사규정2.hwp, 인사규정3.hwp를 넣으면 다음 기준으로 정리합니다.

1. 본문에서 규정명과 제정·개정·전부개정 이력을 찾습니다.
2. 같은 기관과 정규화된 규정명을 하나의 규정 계열로 묶습니다.
3. 개정일, 시행일과 내용 해시로 버전을 구분합니다.
4. 최신 승인본을 현재 유효본으로 사용하고 이전 승인본은 개정 이력으로 보존합니다.
5. 질의 시 기관 → 규정 → 목차/조문 → 최신 유효 버전 순으로 좁혀 검색합니다.

본문 이력이 누락되거나 날짜가 충돌하는 문서는 자동 확정하지 않고 검토 대상으로 표시합니다. 파일명은 보조 단서일 뿐 최종 개정 판단의 유일한 기준이 아닙니다.

지원 범위와 제한

선택적 Kordoc 보강

HWP 표 추출을 보강할 때는 Kordoc 프로젝트를 별도로 설치할 수 있습니다. PR MCP Builder는 Kordoc이 추출한 셀·열 구조를 기본 파서 결과와 대조하고, 일치도가 충분한 표를 검수 후보로 연결합니다. Kordoc 결과도 자동 승인하지 않으며 원본 표와 사람이 대조해야 합니다.

• 이 프로젝트에서의 역할: HWP를 중심으로 표 셀, 열 위치와 병합 구조 보강
• 연동 방식: 사용자가 별도로 설치한 Kordoc CLI를 subprocess로 호출
• 배포 범위: PR MCP Builder 소스와 Windows ZIP에 Kordoc 소스·실행 파일을 포함하지 않음
• 검수 원칙: Kordoc 표 매칭·승격·미매칭 결과에 검수 표시를 남기고 승인 전 원문 대조
• 과거 증거 복구: MCP 화면에서 기존 승인본을 덮어쓰지 않고 같은 원본의 새 draft를 만든 뒤 Kordoc evidence를 검증하고, 사람 승인·색인은 다시 요구

Kordoc 소스나 실행 파일이 포함되지 않음이 기본 배포 원칙입니다.

Kordoc은 Chris가 공개한 별도 MIT 프로젝트입니다. 사용 전 Kordoc 라이선스와 이 저장소의 THIRD_PARTY_NOTICES.md를 함께 확인하세요.

보안 원칙

• 전처리 자체를 보안 통제로 간주하지 않습니다.
• 검사, 분류, 사람 승인, 감사 로그와 미승인 청크 색인 차단이 실제 통제입니다.
• 원본 규정, 런타임 산출물, API 키, 토큰과 사용자 로컬 경로를 공개 저장소에 커밋하지 않습니다.
• 공유 배포에서는 인증, 기관별 테넌트 격리, 접근 제어와 기관 보안 정책을 별도로 적용합니다.
• 공개 배포 전 SECURITY.md와 공개 저장소 이력 정책을 확인합니다.

개발자 검증과 빌드

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

Windows portable ZIP은 다음 명령으로 만듭니다.

powershell -ExecutionPolicy Bypass -File scripts\build_windows_portable.ps1

버전은 app\__init__.py에서 자동으로 읽으며, 결과 파일은 dist\PR-MCP-Builder-Windows-x64-<버전>.zip입니다. data/, reports/, .tmp/, build/, dist/, 가상환경과 실제 기관 문서는 Git에 커밋하지 않습니다.

릴리스 자동화와 버전

최신 공개 릴리스의 태그와 Assets를 기준으로 배포 상태를 확인합니다. 버전의 단일 원천은 app\__init__.py의 __version__이며, Python 패키지 메타데이터, FastAPI OpenAPI 버전, Windows portable ZIP 이름, GitHub 태그와 Release가 모두 이 값을 사용합니다.

main 푸시 자동 릴리스

main에 병합하거나 직접 푸시한 변경은 .github/workflows/auto-release.yml로 자동 릴리스됩니다. 워크플로는 Python 3.11 환경에서 전체 unittest를 통과한 경우에만 다음을 수행합니다.

1. 아직 태그가 없는 새 버전은 app\__init__.py의 버전으로 GitHub Release를 발행합니다.
2. 이후 main 변경은 patch 버전을 하나 올리고 같은 값을 패키지, API와 모든 배포 파일에 적용합니다.
3. source distribution(.tar.gz), wheel(.whl), Windows portable ZIP을 모두 빌드하고 새 태그의 GitHub Release에 첨부합니다.

릴리스 커밋에는 [skip auto-release] 표식을 넣어 자체 푸시가 다시 버전을 올리는 무한 반복을 막습니다. 동일 커밋의 워크플로 재실행은 기존 태그와 Release를 재사용하고 세 Assets를 다시 검증·업로드해 불완전한 릴리스를 복구합니다. 테스트나 빌드가 실패하거나 세 산출물 중 하나라도 없으면 버전·태그·Release 발행을 완료하지 않습니다. 리포지토리의 Settings → Actions → General → Workflow permissions는 Read and write permissions를 허용해야 하며, main 브랜치 보호 규칙이 GitHub Actions의 릴리스 커밋 푸시를 막지 않도록 설정해야 합니다.

자세한 설계와 운영 문서는 docs를 참고합니다. 소스 코드는 MIT License를 따르며 외부 구성요소의 조건은 THIRD_PARTY_NOTICES.md에 정리되어 있습니다.