io.github.EricSeokgon/egovframe-scaffold-mcp

egovframe-scaffold-mcp

English summary: README.en.md · 도구 설명을 영문으로 받으려면 EGOVFRAME_LANG=en

전자정부 표준프레임워크(eGovFrame) 프로젝트 스캐폴딩·조립·진단을 제공하는 MCP(Model Context Protocol) 서버 — 커뮤니티 PoC

eGovFramework/egovframe-common-components#1120 제안의 개념 증명(Proof of Concept) 구현입니다. #628(eGovFrame MCP Server 제안)을 "프로젝트 생성 → 컴포넌트 조립 → 진단·업그레이드" 수명주기로 구체화했습니다.

Claude, VS Code(Copilot), Cursor 등 MCP를 지원하는 AI 도구에서 대화 중 즉시 표준프레임워크 프로젝트를 만들고 공통컴포넌트·AI 계층을 조립할 수 있습니다. 기존 프로젝트 진단, 리포트, 안전한 upstream 재동기화도 지원합니다.

현재 v0.36.1은 **도구 28종(title·annotations·구조화 출력 6종), 공식 템플릿 22종, 설정 템플릿 21종, 5.x 전환 규칙(RTE 18모듈·클래스 331종 + 공통컴포넌트 1,089종 근거)과 적용·검증, 의존성 기준(공식 parent 관리 좌표 139종+계열 6종+Spring Boot BOM 1,473종+RTE 전이 58종)·해석된 의존성 트리·CycloneDX SBOM 과 규칙·기준 drift 감시, 네트워크 진단·AGENTS.md 생성, 공통컴포넌트 카탈로그 190항목(리프 176종+그룹 14종)**을 제공합니다.

진행 현황 (2026-10-06)

• 소스 기준: v0.38.0(package.json), 도구 29종·공식 템플릿 22종·설정 템플릿 21종·카탈로그 190항목(공통컴포넌트 v5.0.7).
• 안전성 기준선 완료: PR #7~#16을 반영해 provenance·strict assertion·safe remove와 프로젝트 생성/레시피/직접 조립/AI 조립/업그레이드 transaction을 갖췄습니다.
• v0.22.0 추가: EGOVFRAME_ALLOWED_ROOTS를 19개 도구 진입점에 적용해 ..·symlink/junction 이탈을 차단하고, 실패 시 rollback 결과를 구조화해 반환합니다. PR #16은 7파일(+340/−31), 로컬 16종 스위트 전체 통과 후 병합됐습니다.
• v0.23.0 추가: build_egovframe_project — 생성한 프로젝트를 실제로 빌드(maven/gradle·mvnw/gradlew 자동 감지)하고 컴파일·테스트 오류를 파일/라인 단위로 구조화해 생성→검증 루프를 완성합니다. 타임아웃·로그 상한·허용 root·dryRun 포함. PR #18은 4파일(+458/−3), 오프라인 40단언과 실제 spawn 경로를 검증했습니다.
• v0.24.0 추가: 공식 템플릿 커버리지 7 → 10종(msa-common-components·mobile-device-api·ai-rag, 모두 멀티 프로젝트). PR #19.
• v0.25.0 추가: test_egovframe_project — 테스트를 실행하고 빌드도구가 남기는 JUnit XML 리포트(surefire·gradle)를 읽어 스위트·케이스 단위로 결과를 구조화합니다. 실패 케이스의 메시지·예외 타입·테스트 파일/라인, testFilter(클래스/메서드 패턴), 이전 실행 리포트 제외, 종료 코드가 0이어도 리포트에 실패가 있으면 실패로 판정. 오프라인 54단언(npm run test:test).
• v0.25.2 추가: 보안·안정성 보강 — generate_egovframe_ci의 jdk 입력 검증(생성 YAML 주입 차단), 빌드·테스트 타임아웃 시 프로세스 트리 종료(래퍼가 띄운 JVM 때문에 타임아웃이 걸려도 호출이 끝나지 않던 문제 해결), MCP handshake 서버 버전을 package.json과 일치, 의존성 갱신으로 npm audit 0건.
• v0.25.3 추가: Linux·macOS에서 npx egovframe-scaffold-mcp(bin symlink 경유) 실행 시 서버가 기동하지 않고 종료되던 문제 수정, CI를 ubuntu·windows × Node 18·20·22 매트릭스로 확장.
• v0.26.0 추가: sync_egovframe_templates + catalog/templates.json — 그동안 Initializr(프로젝트 22종 zip 카탈로그)·MCP(TEMPLATES 10종 저장소 조달)·Development(wizards.xml 설정 마법사)에 흩어져 있던 "어떤 공식 프로젝트가 있는가"를 하나의 스키마로 합쳤습니다. 매핑은 catalog/template-mapping.json 에서 큐레이션하고(자동 추론 없음), upstream 과의 추가·삭제·변경과 MCP 커버리지 격차(현재 22종 중 9종 대응)를 도구로 조회합니다. 오프라인 148단언(npm run test:template-catalog).
• v0.27.0 추가: 공식 템플릿 커버리지 10 → 22종(Initializr 22종 기준 대응 9 → 21종). 단독 저장소가 없는 배치 6종·빈 골격(web·boot-web)·모바일 2종·MSA 포털 2종을 Initializr 의 zip(Git LFS)으로 조달하며, commit 과 sha256·크기를 고정해 내려받은 바이트를 검증합니다. sync_egovframe_templates 가 zip 지문의 upstream 변화도 함께 보고합니다(설계: docs/design-initializr-zip-templates.md).
• v0.28.0 추가: generate_egovframe_config — 공식 Initializr 설정 템플릿 21종(datasource·transaction·cache·logging·scheduling·idGeneration·property)을 패키지에 동봉해 오프라인으로 Spring 설정 파일을 생성합니다. xml·javaConfig·yaml·properties 형식, Initializr 폼과 같은 필드명·기본값, 기존 파일 보호. 리소스 egovframe://catalog/config-templates 로 필드·기본값·선택지를 조회할 수 있고, sync_egovframe_templates 가 동봉 템플릿의 upstream 변화를 보고합니다(설계: docs/design-config-generation.md).
• v0.29.0 추가: migrate_egovframe_project 1단계 — 3.x/4.x 프로젝트를 5.x(Jakarta EE 9+, Spring 6, Java 17) 기준으로 스캔해 RTE Maven 좌표·패키지·제거/이동 클래스·javax→jakarta·web.xml 스키마·제거된 egov-* XML 네임스페이스·교체 필요 라이브러리를 파일·라인 단위로 보고합니다(읽기 전용, auto/manual 구분). 규칙은 egovframe-runtime 태그(v3.10.0·v4.3.0-Final·v5.0.2-Final) 소스 트리 비교로 생성한 catalog/migration-rules.json 에 두고, 목적지 좌표 61건이 실제 Maven 저장소에 있음을 CI 에서 확인합니다. 공식 5.x 템플릿 2종에서 항목 0건(설계: docs/design-migration.md).
• v0.30.0 추가: migrate_egovframe_project 2단계(apply=true) — 진단의 auto 항목을 하나의 transaction 으로 실제 치환합니다(dryRun 기본, 원본 migration-backup/ 보관, migration-plan.json, 실패 시 복구). 3.10 좌표·javax 픽스처를 적용한 뒤 JDK 17 mvn compile 통과를 CI 에서 확인합니다. check_egovframe_dependencies — 공식 5.x parent 2종에서 추출한 기준(관리 좌표 139종 + BOM 계열 7종, catalog/dependency-baseline.json)과 의존성을 대조해 기준 충족/미만/parent 관리/전환 대상/교체 필요/기준 없음으로 분류하고, 보안 설정(sec.security·CSRF·XSS 필터·보안 헤더·HTTPS 저장소) 존재 여부를 근거와 함께 보고합니다. 기본 오프라인, offline=false 면 OSV 취약점 조회(설계: docs/design-dependency-check.md).
• v0.31.0 추가: 운영 편의 — diagnose_egovframe_network(도구가 쓰는 호스트 7종에 DNS·HEAD 프로브, 실패 종류 분류, HTTPS_PROXY+NODE_USE_ENV_PROXY·IPv4 우선·사내 CA 처방을 bash/cmd/PowerShell 명령으로), 모든 다운로드 실패 메시지에 같은 처방 한 줄 부착, generate_agents_md(진단 결과로 AI 코딩 도구용 AGENTS.md, ko/en), 영문 README(README.en.md)와 EGOVFRAME_LANG=en 영문 도구 설명, MCP Registry 메타데이터(server.json·mcpName). 기획 3개 버전(v0.29–v0.31)이 모두 완료됐습니다.
• v0.32.0 추가: MCP 프로토콜 현대화 — 도구 27종을 registerTool 로 전환해 title(ko/en)과 annotations(readOnlyHint 14종·destructiveHint 4종·idempotentHint·openWorldHint)를 tools/list 에 노출하고, format=json 을 제공하던 5종(diagnose_egovframe_project·validate_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network)은 outputSchema 와 structuredContent 를 함께 돌려줍니다(기존 text 유지). 테스트 이식성 가드(scripts/check-test-portability.mjs, 게이트 포함)와 플랫폼 주입 단언으로 Windows 전용 실패 재발을 막습니다.
• v0.38.0 추가: 공통컴포넌트 재조립 실행 — 새 도구 reassemble_egovframe_components(29번째)가 3.x/4.x 프로젝트에 복사된 공통컴포넌트 소스의 원본 태그를 공식 저장소 태그와 git blob id 로 대조해 찾고(파일 내용은 내려받지 않음), 원본·현재·목표로 파일마다 3-way 판정한 뒤 v5.0.7 로 다시 조립합니다. 사용자 수정은 원본 대비 unified diff 패치로 보존하고 작업 목록으로 돌려주며, 매니페스트를 남겨 이후 upgrade·validate·remove 가 그대로 적용됩니다. 공통컴포넌트 카탈로그·전환 규칙의 대응표를 upstream 새 태그 v5.0.7(2026-10-06)로 올렸습니다. 공식 v3.10.0 트리의 cmm·bbs 를 고친 픽스처에서 원본 v3.10.0 식별(99%), 780개 파일이 v5.0.7 tree 와 일치, validate 누락 0·upgrade 변경 0 을 CI 에서 확인합니다.
• v0.37.0 추가: 전환 준비도 평가서 + 회귀 코퍼스 — generate_egovframe_report(sections=["assessment"]) 가 진단·전환 진단·의존성·보안 설정·SBOM 확인을 한 번에 돌려 여섯 절(개요·전환 범위·의존성 조치 목록·보안·SBOM·등급과 근거)의 평가서를 만듭니다. 전환 난이도와 공급망 상태를 각각 A–D 로 매기되 요인·구간·점수 산식을 리포트에 그대로 인쇄해 사람이 재계산할 수 있고(테스트가 실제로 재계산), format=json(outputSchema)·outputPath(새 파일만, transaction) 를 지원합니다. 회귀 코퍼스 test:migrate-corpus 가 공식 공통컴포넌트 v3.10.0·v4.3.2 부분 트리(커밋 고정, sparse 클론 ≈3초)에 진단·dryRun 적용·의존성 점검·평가서를 돌려 catalog/migration-corpus.json 의 기대값과 ±1% 안인지 CI 에서 단언합니다 — 4.x→5.x 경로를 실제 자산으로 처음 확인했고 두 세대 모두 확인 필요 클래스 0·기준 없음 1(xerces)입니다. 릴리스 워크플로는 끊긴 배포를 이어 갑니다(npm 의 gitHead 커밋에 태그, 전파 대기 10분·경고만). 기획 세 버전(v0.35–v0.37)이 모두 완료됐습니다(설계: docs/design-assessment-report.md).
• v0.36.0 추가: 해석된 의존성 트리 + SBOM — check_egovframe_dependencies(resolve=true) 가 Maven(dependency:tree)·Gradle(dependencies)로 전이 의존성까지 해석해 기준·OSV 와 대조합니다(항목마다 origin·트리 경로 via, 선언과 다르게 해석된 버전은 differs). 공식 egovframe-web 템플릿은 선언 19건·조치 0 이지만 해석하면 65 artifact 중 기준 미만 11·OSV 권고 24건이 보입니다. 새 도구 generate_egovframe_sbom(28번째)이 빌드 파일 변경 없이 CycloneDX 1.6 JSON 을 만들고(Maven 은 cyclonedx-maven-plugin 으로 해시·라이선스 포함, Gradle 은 해석 트리로 구성) component 마다 기준 판정(egovframe:status·basis·baseline)을, offline=false 면 OSV 결과를 vulnerabilities[] 로 넣습니다 — 2027년부터 단계화되는 공공기관 SBOM 등록·제출에 쓸 수 있는 형식입니다.
• v0.35.0 추가: 릴리스 자동화 — main 에서 CI 가 성공하면 release.yml 이 네 조건(server.json 버전 일치·변경 이력 항목·태그 없음·npm 미배포)을 검사해 npm(OIDC trusted publishing, provenance 자동) → 그 커밋에 태그 → GitHub Release(변경 이력에서 추출) → MCP Registry(GitHub OIDC) 순으로 게시합니다. 사람은 PR 병합만 합니다. 게이트에 test:release(판정 함수·릴리스 노트·npm pack 내용·크기 상한)와 server.json 설명 100자 제한(레지스트리 검증 조건 — 실제 mcp-publisher validate 로 발견한 결함 수정)을 추가했습니다.
• v0.34.0 추가: 의존성 기준 완성 + 규칙·기준 drift 감시 — check_egovframe_dependencies 의 기준에 Spring Boot BOM 전체(spring-boot-dependencies 3.5.6 직접 항목 + BOM import 44종을 한 단계 풀어 1,473 좌표)와 RTE 모듈 18종의 전이 의존성(58 좌표, 어느 모듈이 끌어오는지)을 더해 항목마다 기준 출처(parent 직접·계열·Boot BOM·RTE 전이·전환 규칙)를 표시하고, 국내 벤더·기관 배포 좌표는 vendor 로, EOL·이전 좌표(옛 MySQL/Oracle 드라이버·Jackson 1·xmlbeans·Ehcache 2·HttpClient 4·ANTLR 3·Spring Social)는 교체 규칙으로 분류해 공식 공통컴포넌트 3.10 pom 의 '기준 없음'을 17 → 1 로 줄였습니다. sync_egovframe_templates 가 동봉 규칙·기준의 upstream drift(egovframe-runtime·공통컴포넌트 새 태그, 공식 parent 새 버전, 고정 pom sha256 변화)를 갱신 절차와 함께 보고합니다. 기준 parent 를 5.0.2 로 올렸습니다.
• v0.33.0 추가: migrate_egovframe_project 3단계 — verify=true 가 compile 을 실행해 컴파일 오류를 수동 항목과 연결하고 "처리하면 해결될 오류 수" 순 작업 목록을 냅니다(javac symbol:/location: 파싱). 규칙 카탈로그(schemaVersion 2)에 공통컴포넌트 3.x→5.x 대응표(egovframe-common-components v3.10.0↔v5.0.6, 제거 54·이동 4)를 추가해 egovframework.com.* 제거·이동 클래스를 진단하고, 3.x 공통컴포넌트 소스가 섞인 프로젝트에는 컴포넌트 단위 재조립 권고(skipComponents 로 치환 제외)를 냅니다.
• 다음 계획: v0.39 CLI 모드와 CI 공급망 게이트 → v0.40 SBOM 운영(최소 요소·비교·VEX). 다음 버전 기획 참조.
• 배포 상태: npm 최신 배포 버전은 상단 npm 배지와 npm 패키지 페이지를 단일 출처로 확인합니다. 이 문서의 버전 표기는 저장소 소스(package.json) 기준이며, git 태그 vX.Y.Z가 해당 배포본의 커밋을 가리킵니다.

제공 도구

도구	설명
create_egovframe_project	공식 템플릿을 내려받아 projectName(artifactId)·groupId·DB 타입을 적용한 새 프로젝트 생성
list_egovframe_templates	사용 가능한 공식 템플릿 목록
sync_egovframe_catalog	공식 common-components 태그·commit·archive SHA-256/크기/파일 수 검증, sec.security와 미매핑 upstream 경로 탐지
list_egovframe_components	선택 설치 가능한 공통컴포넌트 카탈로그 (공식 v5.0.7 고정, 리프 176종 + 그룹 14종 — 리프는 서비스 단위, 그룹 id는 하위 일괄 설치)
add_egovframe_components	공통컴포넌트 완전 조립 — 소스·매퍼·JSP와 message·IDGN·scheduling·정적 자산·Spring/web fragment 복사, Maven 좌표 탐지, 컴포넌트별 선별 DDL·DML 생성(database), archive 검증·충돌 전체 거부·쓰기 실패 롤백·dryRun
search_egovframe_components	키워드로 컴포넌트 검색 (id·이름·설명, 점수순 상위 10건)
remove_egovframe_components	설치 매니페스트 기반 트랜잭션 제거 — 의존 컴포넌트·사용자 수정 hash 보호, dryRun 분류, force 시 remove-backup/ 백업 후 제거
validate_egovframe_project	조립 프로젝트 무결성 진단 — 파일 존재·DbType↔DB 스크립트 일치
get_egovframe_guide	컴포넌트의 공식 가이드 문서 조회 (egovframe-docs, 151종 매핑)
add_ai_components	공식 egovframe-ai-rag 샘플 기반 AI RAG 챗봇 조립 — Spring AI(Redis Stack)·LangChain4j(PGVector) 스택 선택(상호 배타), 소스·설정(application-ai.yml 프로필)·UI·인프라 복사, pom 누락 의존성만 마커 구간 삽입(백업 생성, 제거 시 원복), 충돌 시 전체 거부, dryRun 미리보기 (설계: docs/design-ai-components.md)
list_egovframe_recipes	큐레이션된 레시피(템플릿+컴포넌트 번들) 목록
apply_egovframe_recipe	레시피 하나로 생성→컴포넌트(→AI 계층)까지 조립하고 전체 성공 시에만 최종 경로로 atomic commit. 공식 템플릿이 제공하는 공통기반은 확인·보존하고 추가 컴포넌트만 설치 (dryRun 지원)
diagnose_egovframe_project	기존/레거시 프로젝트를 스캔해 빌드시스템·RTE 버전·DbType·설치 공통컴포넌트(pathPrefixes 지문)·설정 문제 진단 (읽기 전용)
search_egovframe_docs	공식 가이드 문서(egovframe-docs) 인덱스를 키워드로 검색 — 제목·경로·연계 컴포넌트, 문서 URL·조립용 id 반환 (오프라인)
generate_egovframe_report	프로젝트 리포트 — sections=["components"](기본) 설치 컴포넌트·참조 테이블·가이드 링크·이슈, sections=["assessment"] 5.x 전환 준비도 평가서(개요·전환 범위·의존성 조치·보안·SBOM·A–D 등급과 산식). Markdown/json, outputPath 로 새 파일 저장(선택)
reassemble_egovframe_components	3.x/4.x 프로젝트에 복사된 공통컴포넌트 소스를 v5.0.7 로 재조립 — 원본 태그 식별(git blob id 대조), 원본·현재·목표 3-way 판정, 사용자 수정은 패치·작업 목록으로 보존, 5.x 에서 없어진 파일은 백업 후 삭제, 매니페스트 생성, dryRun 기본·transaction·verify(compile)
upgrade_egovframe_project	설치 컴포넌트를 upstream과 3-way 비교해 갱신 — 사용자 수정 보존, dryRun 기본, 적용 직전 재검증, 파일·백업·매니페스트 단일 transaction (파괴적, 게이트)
explain_egovframe_component	컴포넌트 하나의 상세(설명·직접/전이 의존성·역의존·참조 테이블·가이드 링크·설치 명령)를 한 번에 반환 (읽기 전용)
generate_egovframe_ci	GitHub Actions CI 워크플로(빌드·테스트) 생성 — maven/gradle 자동 감지, dryRun, 기존 파일 보호
build_egovframe_project	생성한 프로젝트를 실제로 빌드(compile·test·package) — maven/gradle·mvnw/gradlew 자동 감지, 타임아웃·로그 상한, 컴파일 오류 파일/라인 구조화, dryRun
test_egovframe_project	테스트 실행 + JUnit XML 리포트(surefire·gradle) 구조화 — 스위트별 통과/실패/오류/건너뜀, 실패 케이스 메시지·예외 타입·테스트 파일/라인, testFilter, 이전 실행 리포트 제외, dryRun
generate_egovframe_crud	공식 Development CRUD wizard 입력 체계 기반 코드 생성 — VO·Mapper(XML)·Service·Controller·JSP(선택)·JUnit 5(선택), Classic/Boot 분기, 전체 충돌 사전 검사
sync_egovframe_templates	공식 프로젝트 템플릿 통합 카탈로그(Initializr·MCP·Development) upstream 대조 — 추가/삭제/변경 항목과 MCP 커버리지 격차, zip 조달 템플릿의 고정 지문(sha256·크기)과 동봉 설정 템플릿의 변화 보고, 동봉 5.x 전환 규칙·의존성 기준 카탈로그의 drift(새 RTE·공통컴포넌트 태그, 새 parent 버전, 고정 pom sha256 변화)와 갱신 절차 보고, 네트워크 필요
generate_egovframe_config	공식 Initializr 설정 템플릿 21종으로 Spring 설정 파일 생성(오프라인 동봉) — datasource(DBCP/C3P0/JDBC·JNDI)·transaction(datasource/JPA/JTA)·cache·logging(log4j2 5종)·scheduling(Quartz 5종)·idGeneration(3종)·property, xml/javaConfig/yaml/properties, Initializr 폼과 같은 필드·기본값, 기존 파일 거부, dryRun
migrate_egovframe_project	3.x/4.x 프로젝트의 5.x(Jakarta EE 9+·Spring 6·Java 17) 전환 — 진단(기본, 읽기 전용): RTE Maven 좌표(egovframework.rte:egovframework.rte.*·org.egovframe.rte:org.egovframe.rte.* → org.egovframe.rte:egovframe-rte-*)·RTE 버전·저장소 URL·5.x parent, 패키지 접두어·이름 변경·제거 클래스(대체 안내), javax→jakarta 패키지·의존성 좌표, web.xml 스키마, 제거된 egov-security/access/crypto 네임스페이스, 교체 필요 라이브러리를 파일·라인 단위 auto/manual 항목으로 보고. 적용(apply=true): auto 항목을 transaction 으로 치환, dryRun 기본, 원본 migration-backup/ 보관·migration-plan.json, 실패 시 복구, 적용 후 재진단. 검증(verify=true): compile 실행 후 컴파일 오류를 수동 항목과 연결한 작업 목록(해결될 오류 수 순). 공통컴포넌트 3.x→5.x 대응표(제거·이동 클래스)와 컴포넌트 단위 재조립 권고, skipComponents
check_egovframe_dependencies	의존성 점검(읽기 전용) — 선언된 의존성(resolve=true 면 Maven dependency:tree·Gradle dependencies 로 해석한 전이 의존성까지, 트리 경로·선언/해석 버전 차이 포함)을 공식 5.x parent 기준(관리 좌표 139종 + Spring/Security/Boot 등 BOM 계열) + Spring Boot BOM 전체(1,473종) + RTE 모듈 전이 의존성(58종)과 대조해 기준 충족/기준 미만/parent 관리/전환 대상(3.x·4.x RTE·javax)/교체 필요(DBCP 1.x·Log4j 1.x·Jackson 1·Ehcache 2 등)/벤더 배포(국내 DBMS·GPKI)/기준 없음 분류(항목마다 기준 출처 표시), 5.x parent·Java 버전 판정, 보안 설정 존재 점검(sec.security·CSRF·XSS 필터·보안 헤더·HTTPS 저장소, 파일·라인 근거). 기본 오프라인, offline=false 면 OSV 취약점 조회
diagnose_egovframe_network	도구가 내려받는 호스트 7종(codeload·raw·media.githubusercontent, maven.egovframe.go.kr, repo1.maven.org, registry.npmjs.org, api.osv.dev)에 DNS 조회·HEAD 요청을 보내 도달 여부·소요 시간·실패 종류(DNS·타임아웃·TLS·프록시 인증·거부)를 보고하고, 환경에 맞는 처방(HTTPS_PROXY+NODE_USE_ENV_PROXY=1, NODE_OPTIONS=--dns-result-order=ipv4first, NODE_EXTRA_CA_CERTS)을 bash/cmd/PowerShell 명령으로 안내. 프로젝트 디렉터리 불필요, 파일 무기록
generate_egovframe_sbom	SBOM 생성 — Maven/Gradle 프로젝트의 CycloneDX 1.6 JSON 을 빌드 파일 변경 없이 생성(Maven: cyclonedx-maven-plugin makeAggregateBom, 해시·라이선스 포함 / Gradle: 해석된 의존성 트리로 구성). enrich 로 component 마다 기준 판정(egovframe:status·basis·baseline) 속성, offline=false 로 OSV 취약점을 vulnerabilities[] 에 포함. 출력은 프로젝트 안 경로(기본 sbom/bom.cdx.json), 기존 파일은 overwrite 없이는 거부, dryRun(기본)은 계획만
generate_agents_md	프로젝트 진단 결과로 AI 코딩 도구용 AGENTS.md 생성 — 빌드·테스트 명령(래퍼 감지), RTE·5.x 전환 상태, DbType, 기본 패키지·설정 디렉터리, 설치 컴포넌트(매니페스트 여부), 규칙(좌표·백업 디렉터리·비밀 정보·의존성 기준), MCP 도구 목록. 기존 파일은 overwrite 없이는 거부, dryRun, ko/en, 파일명 변경(CLAUDE.md 등)

create_egovframe_project 파라미터

• projectName — 프로젝트명(artifactId). 소문자·숫자·하이픈 (예: my-egov-app)
• groupId — 자바 groupId (예: egovframework.example)
• database — hsql(기본) | mysql | oracle | altibase | tibero (템플릿 Globals.DbType 지원 값)
• template — simple-backend(기본, Spring Boot REST) | simple-react | simple-homepage | portal-site | enterprise-business | web-sample | msa-edu | msa-common-components | mobile-device-api | ai-rag | web | boot-web | batch-file-scheduler | batch-file-commandline | batch-file-web | batch-db-scheduler | batch-db-commandline | batch-db-web | mobile-web | mobile-common-components | msa-portal-backend | msa-portal-frontend (전체 22종, list_egovframe_templates로 확인)
  • 레거시 템플릿(simple-homepage·portal-site·enterprise-business·web-sample)은 egovProps/globals.properties의 Globals.DbType에 DB 타입을 적용합니다.
  • msa-edu·msa-common-components·mobile-device-api·ai-rag는 멀티 프로젝트라 좌표·DB 자동 적용 없이 원본 그대로 생성하고 README 안내를 반환합니다.
  • web부터 msa-portal-frontend까지 12종은 Initializr zip 조달 템플릿입니다. 고정 commit 의 zip 을 받아 sha256·크기를 검증한 뒤 pom.xml 의 ###GROUP_ID### 등 자리표시자를 채우고, globals.properties(배치는 egovframework/batch/properties/)에 DB 타입을 적용합니다. msa-portal-* 2종은 멀티 프로젝트라 자동 적용이 없습니다.
• outputDir — 생성 위치 상위 디렉터리
• ref — (선택) 내려받을 브랜치/태그. 미지정 시 템플릿 기본 브랜치. 예: main, v4.3.0 zip 조달 템플릿에 ref를 주면 고정 지문 검증을 건너뛰며 결과에 그 사실이 표시됩니다.
• dryRun — (선택, 기본 false) true면 디스크에 쓰지 않고 생성 예정 파일 수·적용 설정만 미리보기

동작: 공식 템플릿 zip 다운로드 → 압축 해제(zip-slip 방지) → pom.xml의 groupId/artifactId/name 적용(부모 POM 좌표는 유지) → application.properties의 Globals.DbType 설정, 프론트엔드 템플릿은 package.json의 name 설정. 기존 디렉터리가 있으면 거부합니다. 다운로드에는 30초 타임아웃이 적용되어 무응답 시 무한 대기하지 않습니다. dryRun으로 먼저 안전하게 미리볼 수 있습니다.

generate_egovframe_crud 핵심 파라미터

• projectDir — 대상 Maven/Gradle 프로젝트
• tableName, entityName — DB 테이블과 생성할 클래스명 (entityName 생략 시 테이블명에서 변환)
• basePackage — 기본 패키지. mapper·VO·service·impl·controller 패키지를 개별 재정의할 수도 있습니다.
• fields — columnName, javaType, jdbcType, primaryKey, generated, nullable, label 컬럼 스펙. 안전한 update/delete 생성을 위해 기본키가 최소 1개 필요합니다.
• profile — classic(Spring MVC+JSP) 또는 boot(REST Controller)
• checkDataAccess, checkService, checkWeb — 공식 wizard.xml의 생성 그룹과 대응
• includeJsp, withTest, dryRun — JSP·JUnit 5 테스트 선택 생성 및 무기록 미리보기

generate_egovframe_crud(
  projectDir="/work/my-egov-app",
  tableName="SAMPLE_BOARD",
  entityName="Board",
  basePackage="egovframework.example.board",
  profile="classic",
  fields=[
    { columnName: "BOARD_ID", javaType: "Long", jdbcType: "BIGINT", primaryKey: true, generated: true },
    { columnName: "TITLE", javaType: "String", jdbcType: "VARCHAR", nullable: false }
  ],
  withTest=true,
  dryRun=true
)

생성 전 모든 대상 경로를 검사하며 기존 파일이 하나라도 있으면 아무 파일도 쓰지 않습니다. 지원 타입과 출력 계약은 CRUD 생성 설계를 참고하세요.

generate_egovframe_config 핵심 파라미터

• projectDir — 대상 프로젝트
• configId — 설정 템플릿 id. datasource datasource-jndi transaction-datasource transaction-jpa transaction-jta cache-ehcache-default cache-spring logging-console logging-file logging-rolling-file logging-time-rolling-file logging-jdbc scheduling-bean-job scheduling-method-job scheduling-simple-trigger scheduling-cron-trigger scheduling-scheduler idgen-sequence idgen-table idgen-uuid property
• format — xml(기본) | javaConfig | yaml | properties (yaml·properties 는 logging 계열만)
• fields — 템플릿 변수 덮어쓰기. 필드명과 기본값은 Initializr 웹뷰 폼과 같습니다(예: txtDatasourceName, rdoType(DBCP|C3P0|JDBC), txtDriver, txtUrl, txtUser, txtPasswd, txtConfigPackage). 템플릿에 없는 필드나 선택지 밖 값은 거부합니다. 전체 목록은 리소스 egovframe://catalog/config-templates 참조
• fileName — 파일명(확장자 제외) 또는 JavaConfig 클래스명. 미지정 시 Initializr 기본값(context-datasource, EgovDataSourceConfig 등)
• outputDir — 프로젝트 상대 경로. 미지정 시 xml → src/main/resources/egovframework/spring(logging 은 src/main/resources), javaConfig → src/main/java/<패키지>
• dryRun — 내용·경로·컨텍스트만 반환

generate_egovframe_config(
  projectDir="/work/my-egov-app",
  configId="datasource",
  format="javaConfig",
  fields={ txtConfigPackage: "kr.go.sample.config", rdoType: "C3P0", txtUrl: "jdbc:mysql://db:3306/app", txtUser: "app", txtPasswd: "…" }
)

기존 파일이 있으면 쓰지 않고 거부하며, 결과의 컨텍스트에서 비밀번호 필드는 가려집니다. 템플릿은 eGovFramework/egovframe-vscode-initializr(Apache-2.0)의 templates/config 를 commit·sha256 고정으로 동봉합니다. 설계와 upstream 에서 발견한 문제는 설정 파일 생성 설계를 참고하세요.

migrate_egovframe_project 파라미터

• projectDir — 진단할 프로젝트(허용 root 적용). pom.xml(다중 모듈 포함)·build.gradle(.kts)·*.java·*.xml·*.jsp·web.xml·*.properties/yml 을 읽으며 target/·build/·.git/·node_modules/ 는 건너뜁니다
• target — 5.x(기본이자 현재 유일)
• format — markdown(기본, 수동 항목 → 자동 항목 순 요약) | json(항목 배열 {file, line, kind, from, to, action, reason, edits?} 과 summary.byKind, sourceEra)
• apply — true 면 2단계(적용). dryRun(기본 true)이면 파일별 변경 미리보기만, false 면 실제 치환
• verify — true 면 3단계(검증): 진단 뒤 compile 을 실행해 컴파일 오류를 수동 항목과 연결한 작업 목록을 반환(빌드 도구 필요, 파일 무기록)
• skipComponents — true 면 3.x 공통컴포넌트 디렉터리(재조립 권고 대상)의 자동 항목을 치환하지 않고 수동으로 남김

migrate_egovframe_project(projectDir="/work/legacy-3.10-app")                       # 1단계 진단
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", apply=true)           # 적용 계획(미리보기)
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", apply=true, dryRun=false)  # 적용
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", verify=true)   # 컴파일 → 오류 ↔ 수동 항목 작업 목록

action 이 auto 인 항목(좌표·RTE 버전 속성·패키지 접두어·패키지 이름 변경·javax→jakarta 패키지와 의존성 좌표·저장소 URL·Java 버전·web.xml 스키마)은 적용 단계가 원문 오프셋 기준으로 치환하고, manual(제거된 클래스·네임스페이스·교체 필요 라이브러리·Spring 버전·5.x parent 권고)은 사유와 대체 API 를 함께 남깁니다. 적용은 하나의 transaction 이며 원본을 migration-backup/<시각>-<id>/ 에 보관하고 migration-plan.json 을 남깁니다. 중간에 실패하면 작업 전 상태로 되돌립니다. 규칙의 출처와 제거 클래스 38종의 대체 근거는 전환 진단 설계를, 규칙 자체는 리소스 egovframe://catalog/migration-rules 를 참고하세요. 이 도구는 파일을 쓰지 않습니다.

check_egovframe_dependencies 파라미터

• projectDir — 점검할 프로젝트(허용 root 적용). Maven(다중 모듈 pom, <properties> 해석) 또는 Gradle
• offline — true(기본) 오프라인 기준 대조만 | false OSV(api.osv.dev) 취약점 조회 추가
• resolve — true 면 빌드 도구로 의존성 트리를 해석해 전이 의존성까지 판정(Maven maven-dependency-plugin:3.8.1:tree, Gradle dependencies --configuration runtimeClasspath; 빌드 도구·저장소 접근 필요). resolveScope runtime(기본) | all(test·provided 포함), resolveTimeoutMs
• format — markdown | json

check_egovframe_dependencies(projectDir="/work/my-egov-app", offline=false)
check_egovframe_dependencies(projectDir="/work/my-egov-app", resolve=true, offline=false)   # 실제로 실리는 artifact 전부

resolve=true 결과는 항목마다 origin(declared·transitive)과 전이 경로 via(예 egovframe-rte-ptl-mvc → spring-webmvc), 선언과 다르게 해석된 버전(treeVersion·resolution.differs)을 담고, parent 가 관리하는 좌표가 기준 미만 버전으로 해석되면 비고에 알립니다. 해석에 실패하면 선언 기준 결과에 이유를 붙여 돌려줍니다.

기준은 공식 5.x parent(org.egovframe.web:egovframe-web-config-parent·org.egovframe.boot:egovframe-boot-starter-parent 5.0.2)의 properties·dependencyManagement, Boot parent 가 상속하는 Spring Boot BOM 전체(spring-boot-dependencies 3.5.6 + import 한 단계), RTE 모듈 18종의 전이 의존성에서 추출한 catalog/dependency-baseline.json(schemaVersion 2) 이며 리소스 egovframe://catalog/dependency-baseline 로 조회할 수 있습니다. 대조 순서는 parent 직접 → 계열 → (Boot parent 프로젝트) Boot BOM → RTE 전이, 그 밖은 RTE 전이 → Boot BOM 이고 항목마다 basis 로 출처를 적습니다. RTE 전이 버전보다 낮게 명시한 좌표는 "충돌 가능" 사유와 함께 기준 미만으로 봅니다. 국내 벤더·기관 배포 좌표(Altibase·Tibero·CUBRID·GPKI·mGov)는 vendor, 기준에 없는 좌표는 unknown(판단 보류)으로 두고 둘 다 조치 목록에 넣지 않습니다. 보안 점검은 설정의 존재 여부와 근거만 보고합니다(설계: 의존성 점검 설계).

generate_egovframe_sbom 파라미터

• projectDir — Maven 또는 Gradle 프로젝트(허용 root 적용)
• outputPath — 프로젝트 상대 경로(기본 sbom/bom.cdx.json; ..·절대 경로·symlink 이탈 거부), overwrite — 기존 파일 덮어쓰기(기본 거부)
• scope — runtime(기본: compile+runtime) | all(test·provided 포함)
• enrich — true(기본) component 마다 egovframe:status·egovframe:basis·egovframe:baseline 속성 부착
• offline — true(기본) | false OSV 결과를 CycloneDX vulnerabilities[](affects 로 component 참조)로 포함
• dryRun — true(기본) 실행 없이 명령·출력 경로만 | false 생성·기록, timeoutMs(기본 600000)

generate_egovframe_sbom(projectDir="/work/my-egov-app")                              # 계획만
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, offline=false)  # sbom/bom.cdx.json + OSV

Maven 은 org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom 을 좌표를 완전히 적어 호출하므로 pom 을 바꾸지 않으며(해시·라이선스 포함, 멀티 모듈 합산), Gradle 은 해석된 트리로 이 서버가 문서를 구성합니다(해시·라이선스 없음, 빌드 파일 변경 없음). 문서의 metadata.tools 에 이 서버가 기록됩니다. 기준 판정은 check_egovframe_dependencies 와 같은 규칙입니다(설계: 의존성 점검 설계).

generate_egovframe_report 파라미터 (전환 준비도 평가서)

• projectDir — 평가할 프로젝트(허용 root 적용)
• sections — ["components"](기본, v0.16 리포트 그대로) | ["assessment"](평가서) | 둘 다(이어 붙임)
• resolve·resolveScope·resolveTimeoutMs — 평가서의 의존성 절을 빌드 도구로 해석한 전이 의존성까지 판정(기본 선언만)
• offline — true(기본) | false OSV 로 알려진 취약점 조회 — 공급망 등급은 취약점을 조회해야 "확정"으로 표시
• sbomPath — 요약할 SBOM(기본 sbom/bom.cdx.json; 없으면 "없음"으로 표시하고 만들지 않음), topN — 예상 수동 작업 상위 N(기본 20)
• outputPath — 프로젝트 상대 .md 경로. 주면 새 파일로만 저장(기존 파일 거부, ..·절대·symlink 이탈 거부, transaction), dryRun — 쓰지 않고 내용만
• format — markdown(기본) | json(outputSchema·structuredContent, 평가 데이터 포함)

generate_egovframe_report(projectDir="/work/legacy-app", sections=["assessment"])
generate_egovframe_report(projectDir="/work/legacy-app", sections=["assessment"], offline=false, resolve=true, outputPath="docs/assessment.md")

평가서 6절의 등급은 두 축입니다. 전환 난이도 = 수동 전환 항목 수(0 / 1–20 / 21–100 / 101+ → 0–3점) + 재조립 권고 공통컴포넌트 수(0 / 1–5 / 6–20 / 21+) + 제거된 API 참조 수(0 / 1–10 / 11–100 / 101+) + 현재 좌표 세대(5.x 0 · 4.x 1 · 3.x 2), 공급망 상태 = 기준 미만 의존성 수(0 / 1–3 / 4–10 / 11+) + 전환 대상·교체 필요 수(같은 구간) + 알려진 취약점이 있는 의존성 수(0 / 1–2 / 3–9 / 10+, 미조회면 0점으로 계산하고 주의) + 보안 설정 누락 수(0 / 1–2 / 3+ → 0–2점) + 5.x parent·Java 기준(각 미달 +1). 합계로 A=0 · B≤3 · C≤7 · D>7. 산식 전문은 리포트 안에 인쇄되며, 공식 5.x 템플릿은 전환 A, 공식 공통컴포넌트 3.10.0·4.3.2 전체 트리는 두 축 모두 D 입니다(구간을 정한 근거와 예시: docs/design-assessment-report.md). 비용·공수는 산정하지 않습니다.

평가서 발췌(공통컴포넌트 v4.3.2 전체 트리):

- **전환 난이도 D · 공급망 상태 D** (산식은 6절)
## 2. 전환 범위
- 항목 1352건 = 자동 치환 635 + 수동 717 · 대상 파일 689개
- 재조립 권고 공통컴포넌트 155종: cmm, cop.adb, bbs, …
- 제거된 API 참조 552건 (제거된 RTE 클래스 · 제거된 공통컴포넌트 클래스 · 제거된 RTE 모듈 · 제거된 XML 네임스페이스)
## 6. 등급과 근거
### 전환 난이도: **D** (10/11점, A=0 · B≤3 · C≤7 · D>7)
| 요인 | 값 | 구간 | 점수 | 비고 |
| 수동 전환 항목 수 | 717 | 101+ | 3 |  |
| 재조립 권고 공통컴포넌트 수 | 155 | 21+ | 3 |  |
| 제거된 API 참조 수 | 552 | 101+ | 3 |  |
| 현재 좌표 세대 | 1 | 1 | 1 | sourceEra=4.x |

reassemble_egovframe_components 파라미터 (공통컴포넌트 재조립)

• projectDir — 대상 프로젝트(허용 root 적용)
• components — 재조립할 컴포넌트 id(그룹 id 는 하위로 펼침). 미지정 시 diagnose_egovframe_project 가 감지한 컴포넌트 전부
• sourceTag — 원본 태그(기본 auto: 프로젝트 파일의 git blob id 를 좌표 세대에 맞는 공식 태그와 대조해 일치가 가장 많은 태그), 예: v3.10.0
• database — 지정 시 컴포넌트별 DDL·DML 을 scripts/egovframe-components/<db>/ 에 함께 생성
• dryRun — true(기본) 분류·계획만(파일 내용을 내려받지 않음) | false 적용, verify — 적용 뒤 compile 해 오류를 작업 목록 파일에 붙임
• format — markdown(기본) | json(outputSchema)

파일마다 판정은 목표와 같음(유지)·원본 그대로(교체)·사용자 수정(소스는 교체 + 원본 대비 패치 보존, 메시지·설정 조각·웹 자산은 사용자본 유지 + 목표본 참고 저장)·5.x 신규(추가)·5.x 에서 제거(백업 후 삭제, 사용자 수정이면 패치도)·원본 미확인(백업 후 교체)·사용자 추가(유지)입니다. 백업·패치·reassemble-plan.json 은 migration-backup/<시각>-reassemble-*/ 에, 매니페스트는 .egovframe-components.json 에 남습니다. 원본 태그 비교에는 git 이 필요하고, blob 없는 bare 미러를 EGOVFRAME_CACHE_DIR(기본 ~/.cache/egovframe-scaffold-mcp)에 태그당 수백 KB 로 캐시합니다. 사용자 패치를 자동으로 다시 적용하지는 않습니다(5.x 소스가 많이 바뀌어 fuzz 적용이 오히려 위험).

3.x 프로젝트 전환 흐름:

generate_egovframe_report(projectDir, sections=["assessment"])        # 평가서: 재조립 권고·수동 항목·등급
reassemble_egovframe_components(projectDir)                            # 미리보기: 원본 태그·파일별 판정
reassemble_egovframe_components(projectDir, dryRun=false)              # 공통컴포넌트 v5.0.7 재조립 + 패치·작업 목록
migrate_egovframe_project(projectDir, apply=true, dryRun=false)        # 나머지 좌표·패키지·Jakarta 자동 치환
migrate_egovframe_project(projectDir, verify=true)                     # compile 오류 ↔ 수동 항목 작업 목록

diagnose_egovframe_network / generate_agents_md

diagnose_egovframe_network()                       # 호스트 7종 전부, 호스트당 10초
diagnose_egovframe_network(hosts=["codeload.github.com"], timeoutMs=20000)
generate_agents_md(projectDir="/work/my-egov-app", dryRun=true)   # 내용만
generate_agents_md(projectDir="/work/my-egov-app", lang="en", fileName="CLAUDE.md", overwrite=true)

네트워크 진단은 프록시 URL 의 자격 증명을 가려서 보고하며, NODE_TLS_REJECT_UNAUTHORIZED=0 이 설정돼 있으면 경고합니다. 다운로드가 실패하는 다른 도구들도 오류 메시지 끝에 같은 분류와 한 줄 처방을 붙입니다([네트워크 timeout] … 자세한 진단: diagnose_egovframe_network). AGENTS.md 의 사실 항목은 diagnose_egovframe_project·migrate_egovframe_project·빌드 도구 감지에서 오고, 규칙 항목은 이 서버의 도구가 지키는 원칙입니다.

sync_egovframe_catalog / 컴포넌트 조립

• 카탈로그는 common-components 공식 v5.0.7 태그와 commit 3756ab2c…에 고정됩니다(v0.38 에서 v5.0.6 → v5.0.7).
• sync_egovframe_catalog()는 태그 이동, archive SHA-256·크기·파일 수 불일치, sec.security 누락, 미매핑 Java·Mapper·JSP를 검사합니다.
• add_egovframe_components는 기존 파일이 upstream과 동일하면 재사용하고 내용이 다르면 전체 조립을 거부합니다.
• 감지된 mavenDependencies는 결과에 반환합니다. 프로젝트별 dependency management·버전 정책을 보호하기 위해 기존 pom.xml과 web.xml은 자동 덮어쓰지 않습니다.

상세 스키마와 안전 게이트는 카탈로그 동기화·완전 조립 설계를 참고하세요.

설치·사용

npm에 배포되어 설치 없이 바로 실행할 수 있습니다:

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "npx",
      "args": ["-y", "egovframe-scaffold-mcp"]
    }
  }
}

영문 도구 설명이 필요하면(응답은 한국어 그대로) env 에 "EGOVFRAME_LANG": "en" 을 추가합니다. 사내 프록시 환경에서 프로젝트 생성이 타임아웃되면 "HTTPS_PROXY": "http://proxy:8080", "NODE_USE_ENV_PROXY": "1" 을 같은 env 에 넣고, 원인 확인은 diagnose_egovframe_network 로 합니다.

소스에서 직접 빌드하려면:

npm install
npm run build

Claude Desktop / Claude Code 설정 예 (mcpServers):

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "node",
      "args": ["/절대경로/egovframe-scaffold-mcp/dist/index.js"]
    }
  }
}

빌드 없이 실행하려면 (로컬 클론 후):

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "npx",
      "args": ["-y", "tsx", "/절대경로/egovframe-scaffold-mcp/src/index.ts"]
    }
  }
}

사용 예 (AI 도구에서):

"표준프레임워크로 my-egov-app 프로젝트를 ~/work에 만들어줘. groupId는 egovframework.example, DB는 mysql."

리소스·프롬프트 (MCP Resources/Prompts)

도구(tools)뿐 아니라 MCP의 리소스·프롬프트도 제공합니다 (MCP 3대 프리미티브 완비).

Resources (읽기 전용) — 지원 클라이언트에서 도구 호출 없이 카탈로그를 탐색·인용:

모든 도구는 MCP annotations(readOnlyHint·destructiveHint·idempotentHint·openWorldHint)와 ko/en title 을 노출합니다 — 읽기 전용 14종(목록·검색·진단·검증·리포트·점검·upstream 대조), 파괴 가능 4종(remove_egovframe_components·upgrade_egovframe_project·migrate_egovframe_project(apply)·generate_agents_md(overwrite)), 네트워크 사용 도구는 openWorldHint. diagnose_egovframe_project·validate_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network 는 outputSchema 를 선언하고 structuredContent 로 같은 결과를 구조화해 돌려줍니다(text 는 그대로).

• egovframe://catalog/components · egovframe://catalog/components/{id} · egovframe://catalog/templates · egovframe://catalog/recipes · egovframe://catalog/ai-components · egovframe://catalog/config-templates · egovframe://catalog/migration-rules · egovframe://catalog/dependency-baseline

Prompts — 가이드형 워크플로: scaffold_board_login, scaffold_ai_chatbot, scaffold_portal, maintain_existing

레시피 — 자주 쓰는 조합을 한 번에 조립합니다. 예: apply_egovframe_recipe(recipeId="board-login", projectName="my-egov-app", outputDir="~/work"). 목록은 catalog/recipes.json에서 관리하며 기여 환영합니다.

MCP Registry

MCP Registry 용 메타데이터는 저장소의 server.json(이름 io.github.EricSeokgon/egovframe-scaffold-mcp)과 package.json 의 mcpName 이며, npm run test:registry 가 두 파일의 이름·버전·npm 좌표 일치를 검사합니다. 등록은 npm 배포 뒤 저장소 루트에서:

mcp-publisher login github     # GitHub device flow — io.github.EricSeokgon/ 네임스페이스 권한
mcp-publisher publish          # server.json 을 레지스트리에 게시
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.EricSeokgon/egovframe-scaffold-mcp"

버전을 올릴 때 server.json 의 version·packages[0].version 도 함께 올립니다(릴리스 절차 참조).

보안 설정 — 허용 root (선택)

환경변수 EGOVFRAME_ALLOWED_ROOTS를 설정하면, 모든 도구의 디렉터리 인자(outputDir·projectDir)가 지정한 root 내부일 때만 실행됩니다. 미설정 시 기존과 동일하게 제한이 없습니다.

// MCP 클라이언트 설정 예 (여러 root는 OS 경로 구분자로 연결: POSIX ":", Windows ";")
{ "mcpServers": { "egovframe-scaffold": {
    "command": "npx", "args": ["-y", "egovframe-scaffold-mcp"],
    "env": { "EGOVFRAME_ALLOWED_ROOTS": "/home/user/workspaces" }
} } }

• 검사는 realpath 기준이라 symlink를 통한 우회도 차단합니다.
• 위반 시 도구는 아무 파일도 만들지 않고 AllowedRootsError(허용 root 목록 포함)로 거부합니다.
• transaction 실패 메시지에는 사람용 문구와 함께 기계가 읽을 수 있는 rollback-report: {...} JSON 한 줄(복원·제거·정리 건수, 실패 목록)이 포함됩니다.

검증

• 함수 레벨: 실제 템플릿(약 296파일) 생성, pom 좌표·DbType 적용, 중복 생성 거부, dryRun 미리보기(무기록) 확인 (npm run smoke)
• Maven 좌표 레벨: 프로젝트 직접 groupId/artifactId/name만 변경하고 parent·dependency artifactId 보존 (npm run test:pom, 네트워크 불필요)
• 카탈로그 레벨: schema v2, 고정 source/archive 지문, 자산 메타데이터, 무결성·위상 정렬·미리보기 검증 (npm run test:catalog, npm run test:catalog-sync, 네트워크 불필요)
• zip 조달 레벨: 자리표시자 치환·globals 경로 판별·12종 정의 유효성(npm run test:pom, 네트워크 불필요), batch-file-commandline 실생성으로 지문 검증·좌표·DbType·zip 루트 보존, 지문 불일치 거부와 무기록, ref 지정 시 검증 생략 표시(npm run test:templates, 네트워크 필요, CI 실행)
• 설정 생성 레벨: 동봉 템플릿 지문·카탈로그 무결성, 49건 전 형식 기본값 렌더링, 분기·필드 덮어쓰기, 필드·선택지·파일명·패키지 거부, dryRun 무기록, 충돌 거부, 비밀번호 가림, ..·절대경로·symlink 이탈 거부, CRLF 체크아웃 시뮬레이션 (npm run test:config, 506단언, 네트워크 불필요)
• 템플릿 카탈로그 레벨: catalog/templates.json 스키마·커버리지 계산·큐레이션 매핑 정합·변환기·upstream 차이 계산(추가/삭제/필드 변경) 검증 (npm run test:template-catalog, 256단언, zip 지문·동봉 설정 템플릿 drift·LFS 포인터 해석 포함, 네트워크 불필요)
• 동기화 레벨: 공식 v5.0.7 태그→commit, SHA-256·크기·파일 수, sec.security, 미매핑 경로 0건 검증 (npm run test:catalog-sync-live, 네트워크 필요)
• 조립 레벨: 실제 공통컴포넌트 저장소로 bbs+login+sec.security(+cmm) 843파일 조립, message·IDGN·웹 자산·공용 fragment·Maven 좌표·선별 DB 스크립트·충돌 전체 거부·파일/SQL/매니페스트 fault-injection rollback·상위 symlink 경계 검증 (npm run test:components)
• 수명주기 레벨: 설치 매니페스트 기록, 중복 설치 거부, 의존 컴포넌트 제거 보호, 제거·검증 동작 (npm run test:components)
• 프로토콜 레벨: 빌드된 서버를 실제 프로세스로 띄워 MCP initialize / tools/list 핸드셰이크, serverInfo.version↔package.json 일치, 핵심 도구 노출, jdk 패턴 제약 노출 확인 (npm run test:handshake, 네트워크 불필요)
• 릴리스 레벨: 배포 판정(버전·server.json·변경 이력·태그·npm 네 조건)과 릴리스 노트 추출, npm pack --dry-run 의 tarball 내용(포함·제외·크기 상한), server.json 설명 100자 제한 (npm run test:release·npm run test:registry, 네트워크 불필요); CI 통합이 mcp-publisher validate 로 레지스트리 스키마를 실제 검증
• 플랫폼 레벨: CI가 릴리스 게이트를 ubuntu·windows × Node 18·20·22 매트릭스로 실행하고, 공식 저장소를 내려받는 통합 테스트는 ubuntu/Node 20에서 실행합니다. 타임아웃 시 프로세스 트리 종료는 POSIX·Windows 모두 실제 프로세스로 검증합니다 (npm run test:build).
• 레시피 레벨: catalog/recipes.json의 컴포넌트 id·의존성·템플릿 제공 컴포넌트 정합 검증 (npm run test:recipes, 네트워크 불필요). 공식 simple-backend의 기존 cmm을 보존하고 board-login의 bbs 88파일·login 41파일·SQL 4건(총 133파일)을 조립한 뒤 검증하며, 컴포넌트 이후 fault injection의 전체 staging rollback도 확인 (npm run test:recipe-transaction)
• 진단 레벨: 픽스처(pom·DbType·컴포넌트 패키지)로 diagnose_egovframe_project의 빌드·버전·DbType·컴포넌트 지문·의존성 검출 검증 (npm run test:diagnose, 네트워크 불필요)
• 전환 진단 레벨: 3.10 스타일 픽스처(pom·gradle·java·Spring XML·MyBatis XML·web.xml·JSP)에서 항목 종류·auto/manual·라인·대응 좌표를 단언하고, 5.x 스타일 픽스처에서 항목 0건과 진단 전후 디스크 불변을 확인 (npm run test:migrate, 87단언, 네트워크 불필요). 규칙 카탈로그는 스키마·좌표 규칙성·제거 클래스의 대체가 동봉된 5.x 소스 트리에 존재하는지·JDK 내장 javax.* 제외·큐레이션과 생성물 일치를 검증 (npm run test:migration-rules, 579단언, 네트워크 불필요). 목적지 좌표(RTE 5.x 24종·3.x 원본 18종·parent 2종·Jakarta 좌표)가 표준프레임워크 Maven 저장소와 Maven Central 에 실제로 존재하는지는 CI 통합 job 에서 확인 (npm run test:migration-rules-live, 61건, 네트워크 필요)
• 전환 검증 레벨: 공통컴포넌트 대응표 판정(제거·이동·사용자 클래스 무시), 재조립 권고와 skipComponents, linkBuildError 8케이스(심볼·패키지 부재·라인 근접·규칙 심볼·javax 부재·무관), javac symbol:/location: 파싱(maven·gradle), 가짜 runner 로 verify 결과·작업 목록·Markdown·빌드 파일 없음 (npm run test:migrate 에 포함, 총 162단언). 실제 mvn compile 오류 3건이 수동 항목 2건에 전부 연결되는지는 CI 통합 job (npm run test:migrate-integration)
• 전환 적용 레벨: 3.10 픽스처에 대해 auto 항목의 편집 원문 일치, dryRun 무기록, fault-injection 롤백(내용·mtime 불변), 적용 후 pom·java·XML·web.xml·gradle·JSP 내용, 백업·migration-plan.json, 재적용 무기록, manual 항목 불변을 단언 (npm run test:migrate, 132단언, 네트워크 불필요). 3.10 좌표·javax 픽스처를 적용한 뒤 JDK 17 로 mvn compile 통과는 CI 통합 job 에서 확인 (npm run test:migrate-integration, 네트워크·JDK·Maven 필요)
• 의존성 점검 레벨: 기준 카탈로그 스키마·출처 sha256·RTE 5.x 모듈·BOM 계열, 분류 함수 12케이스, 3.10·5.x parent·gradle·빈 디렉터리 픽스처, OSV 모의 질의·매핑·실패 처리, 디스크 불변 (npm run test:dependencies, 68단언, 네트워크 불필요). 실제 OSV 조회는 CI 통합 job (npm run test:dependencies-live)
• 네트워크 진단 레벨: 오류 분류 8종, 프로브·DNS 주입으로 7가지 시나리오(전부 도달, 405/404/407/503, 프록시+타임아웃, 프록시 없음+IPv6 혼재, TLS, DNS, 필터)의 처방·안내·자격 증명 가림·셸별 명령을 단언하고, fetchWithTimeout 실패 메시지에 처방이 붙는지 확인 (npm run test:network, 33단언, 네트워크 불필요). 실제 호스트 7종 프로브는 CI 통합 job (npm run test:network-live)
• AGENTS.md 레벨: 5.x(매니페스트·래퍼·컴포넌트 2종·백업 디렉터리)와 3.x gradle 픽스처, 빈 디렉터리에서 사실 수집·ko/en 렌더링·dryRun 무기록·기존 파일 거부·overwrite·파일명 검증·staging 정리 (npm run test:agents-md, 22단언, 네트워크 불필요)
• 레지스트리 메타데이터 레벨: server.json ↔ package.json 의 이름(mcpName)·버전·npm 좌표·스키마 URL·환경변수 문서화 정합 (npm run test:registry, 네트워크 불필요)
• 프로토콜 레벨(추가): EGOVFRAME_LANG=en 으로 띄운 서버의 도구 29종 설명이 모두 영문이고 표에 빠진 도구가 없는지, tools/list 에 title·annotations(readOnly 13종·destructive 5종)·outputSchema 8종이 노출되는지 확인 (npm run test:handshake)
• SBOM·해석 레벨: Maven·Gradle 트리 파서(실제 출력 픽스처), resolve=true 의 전이 항목·경로·선언/해석 차이·실패 경로, CycloneDX 문서 구성·보강·취약점 병합·출력 경로 거부·overwrite·dryRun (npm run test:dependencies, npm run test:sbom, 네트워크 불필요); CI 통합이 공식 egovframe-web 템플릿을 실제 Maven 으로 해석하고 SBOM 을 생성 (npm run test:sbom-live)
• 메타데이터·구조화 출력 레벨: TOOL_META ↔ 등록 도구 일치, 읽기 전용·파괴·네트워크 힌트 배정, 영문 title, 7종 도구의 실제 결과(진단·검증·전환 진단/적용·의존성·네트워크·리포트, 빈 프로젝트 포함)가 outputSchema 를 통과하고 최상위 키가 전부 선언돼 있으며 잘못된 값은 거부 (npm run test:output-schemas, 47단언, 네트워크 불필요). MCP 프로토콜 경유 호출 시 SDK 가 structuredContent 를 스키마로 검증합니다
• 테스트 이식성 레벨: scripts/check-test-portability.mjs 가 test/*.mjs 에서 Windows 에서 깨지는 가정(정규화 없는 path.relative 비교, ./mvnw 리터럴 기대값, POSIX 절대 경로)을 찾아 실패시킵니다(npm run check:portability, 게이트 포함, 의도된 줄은 // portability: ok <사유>). 플랫폼 분기 함수(resolveCommand·collectAgentsFacts)는 platform 주입으로 linux·win32 양쪽을 단언합니다
• 문서 검색 레벨: search_egovframe_docs의 키워드 매칭·점수 정렬·컴포넌트 매핑·빈질의/미존재어 처리 검증 (npm run test:docs, 네트워크 불필요)
• 리포트 레벨: 픽스처로 generate_egovframe_report의 컴포넌트·테이블·가이드 링크 렌더링 검증 (npm run test:report, 네트워크 불필요)
• 평가서 레벨: 등급 산식 경계(구간·등급)와 리포트 숫자로의 재계산, 3.x(공통컴포넌트 소스·교체 라이브러리·http 저장소·벤더)·4.x 소형·5.x parent 픽스처의 절별 내용과 등급(5.x 는 전환 범위 0·A), OSV 조회·실패 시 취약점 요인, SBOM 요약·깨진 파일, 절 조립·중복 제거, outputPath 저장·dryRun·기존 파일/프로젝트 밖/절대 경로/symlink/.md 아님 거부, structuredContent 스키마 (npm run test:assessment, 55단언, 네트워크 불필요). CI 통합이 공식 5.x 템플릿 2종에서 전환 A 를 확인 (npm run test:dependencies-live)
• 재조립 레벨: 메모리 원본 저장소로 원본 태그 식별(세대 후보·지정·없는 태그), 8가지 판정(CRLF 체크아웃 포함)·처리, dryRun 무기록, 적용 후 파일·백업·자산 참고본·패치(원문 바이트 보존)·매니페스트·계획 파일, validate 누락 0, 매니페스트 관리 컴포넌트 거부, fault-injection rollback, 목표 내용 blob 불일치 거부, verify 오류 연결 (npm run test:reassemble, 46단언, 네트워크 불필요). CI 통합이 공식 v3.10.0 트리의 cmm·bbs 를 고친 픽스처를 실제 git 원본·sha256 검증 아카이브로 재조립해 v5.0.7 tree 일치·패치·validate·upgrade 변경 0 을 확인 (npm run test:reassemble-live)
• 회귀 코퍼스 레벨: 공식 공통컴포넌트 v3.10.0·v4.3.2 부분 트리(커밋 고정, sparse 클론, 캐시)에 진단·dryRun 적용·의존성 점검·평가서를 돌려 catalog/migration-corpus.json 기대값과 ±1% 안인지, 세대 판정·확인 필요 클래스 0·기준 없음은 xerces 뿐·계획=자동 전부·재조립 권고·등급 D/D·60초 미만을 단언 (npm run test:migrate-corpus, 20단언, git·네트워크 필요, CI 통합). 기대값 갱신은 npm run generate:migration-corpus(--check 는 차이만)
• 업그레이드 레벨: 3-way 판정 6분류(unchanged/update/user-modified/conflict/added/removed)·v1 보수모드·정상 적용/백업 계획·파일/매니페스트 fault-injection rollback·상위 symlink 경계 검증 (npm run test:upgrade, 네트워크 불필요)
• 컴포넌트 설명 레벨: explain_egovframe_component의 의존성(직접·전이)·역의존·테이블·가이드 URL·미존재 예외 검증 (npm run test:explain, 네트워크 불필요)
• CI 생성 레벨: generate_egovframe_ci의 maven/gradle 감지·YAML·dryRun 무기록·기존 파일 거부·빌드파일 부재 예외·jdk 주입 입력 거부 검증 (npm run test:ci, 네트워크 불필요)
• CRUD 생성 레벨: 공식 wizard 그룹, Classic/Boot 분기, DB 생성키, JUnit 5, dryRun, PK·경로 검증, 충돌 시 전체 무기록 검증 (npm run test:crud, 네트워크 불필요)
• CRUD 컴파일 레벨: 공식 simple-backend/Boot CRUD 7파일과 web-sample/Classic CRUD 9파일 생성 → JDK 17에서 mvn -q -DskipTests compile (npm run test:crud-integration, 네트워크 필요, CI 실행)
• 안전성 레벨: 19개 도구 공통 허용 root의 미설정 호환·격리·.. 이탈·symlink 우회·다중 root·비대상 인자 무해 6케이스와 구조화 rollback 필드를 검증합니다 (npm run test:allowed-roots, npm run test:transaction, 네트워크 불필요).

현재 지원 범위와 알려진 제약

• 공통컴포넌트 실행 자산과 Maven 좌표 탐지는 지원합니다. 기존 pom.xml·web.xml의 구조적 노드 병합은 프로젝트별 dependency management·설정 경로를 보호하기 위해 자동 수행하지 않습니다.
• 카탈로그는 공식 v5.0.7 태그·commit·archive 지문에 고정됩니다. 최신 main 변경은 sync_egovframe_catalog(ref="main") 결과를 검토한 뒤 생성 스크립트로 승격합니다.
• build_egovframe_project·test_egovframe_project는 로컬에 설치된 JDK와 maven/gradle(또는 프로젝트 래퍼)을 사용합니다. DB 등 외부 의존성이 필요한 테스트는 그 환경이 준비되지 않으면 오류(error)로 집계됩니다.
• 자바 패키지 구조 변경(groupId에 맞춘 소스 디렉터리 이동)은 미지원입니다. 현재는 IDE rename refactoring을 권장합니다.
• migrate_egovframe_project 의 적용은 진단이 auto 로 표시한 항목만 치환합니다. 정적 텍스트 스캔이므로 리플렉션·문자열 조립으로 만든 클래스명, 프로젝트 밖 라이브러리 안의 javax 사용, Spring Security 6·Hibernate 6 등 라이브러리 자체의 API 변경으로 인한 코드 수정 범위는 보고하지 않습니다(라이브러리 단위로 manual 안내만 합니다).
• 템플릿·컴포넌트·가이드 원본을 받을 때 GitHub(codeload.github.com, raw.githubusercontent.com, zip 조달 템플릿은 media.githubusercontent.com) 네트워크 접근이 필요합니다.

로드맵

v0.31.0까지 프로젝트·CRUD 생성, 검증된 공통컴포넌트 실행 자산 조립, 안전성 기반(테스트 판정 강제·사용자 파일 보호·전 도구 트랜잭션·허용 root·구조화 rollback 보고), 생성→검증 루프(실제 빌드·오류 구조화·테스트 리포트 구조화), 공식 템플릿 카탈로그 단일화와 커버리지 확대(22종 중 21종), 설정 파일 생성, 5.x 전환(진단·적용), 의존성 점검, 운영 편의(네트워크 진단·AGENTS.md·영문 설명·레지스트리 메타데이터)를 완료했습니다.

v0.32–v0.34 로 MCP 프로토콜 현대화, 5.x 전환 3단계(검증)와 공통컴포넌트 대응표, 의존성 기준 완성과 규칙·기준 drift 감시를, v0.35–v0.37 로 릴리스 자동화, 해석된 의존성 트리와 SBOM, 전환 준비도 평가서와 회귀 코퍼스를 마쳤습니다(기획 원문과 결과: 이전 기획). 다음 세 버전(v0.38–v0.40)의 범위는 다음 버전 기획에 있습니다. Homebrew 탭은 후순위에서 내렸습니다(npx 로 충분).

버전	핵심 기능	목표
v0.20 완료	generate_egovframe_crud	공식 wizard.xml 그룹과 경로 입력, VO·Mapper(XML)·Service·Controller·JSP(선택), Classic/Boot, JUnit 5, dryRun·충돌 원자적 거부 구현. 오프라인 테스트와 공식 simple-backend/Boot·web-sample/Classic Maven compile 통과
v0.21 완료	sync_egovframe_catalog + 컴포넌트 완전 조립	common-components v5.0.6 태그/commit/archive 고정, 190항목, message·IDGN·scheduling·정적 자산·web fragment 조립, Maven 좌표 탐지, sec.security·미매핑 경로 검증, 매니페스트 v3
v0.22 완료	전 도구 안전성 기반	모든 쓰기 경로 transaction, 사용자 파일 보호, 전 도구 허용 root, symlink/junction 이탈 차단, 구조화 rollback 보고
v0.23 완료	build_egovframe_project	Maven/Gradle·래퍼(mvnw/gradlew) 자동 감지, 타임아웃·로그 상한, 파일/라인 단위 오류 구조화로 생성→검증 에이전트 루프 완성(PR #18). test_egovframe_project는 v0.25에서 완료
v0.24 완료	공식 템플릿 커버리지 확대 (7 → 10종)	Initializr 카탈로그(22항목) 대조로 미커버 공식 자산을 식별해 msa-common-components(KRDS)·mobile-device-api·ai-rag 추가. 모두 멀티 프로젝트로 표시해 좌표/DB 자동 재작성을 건너뛰고 하위 모듈 참조를 보호하며, 실제 아카이브 다운로드 통합 테스트로 검증
v0.25 완료	test_egovframe_project	테스트 실행 후 JUnit XML 리포트(surefire target/surefire-reports, gradle build/test-results/test)를 읽어 스위트·케이스 단위 집계, 실패 메시지·예외 타입·테스트 파일/라인, testFilter, 오래된 리포트 제외, exit 0이어도 리포트 실패면 실패 판정
v0.26 완료	IDE·Initializr·MCP 공통 카탈로그	Initializr templates-projects.json(22종), MCP TEMPLATES(10종), Development wizards.xml(8카테고리)을 schemaVersion: 1 단일 스키마 catalog/templates.json 으로 통합. 변환기(fromInitializr·fromMcpTemplates)와 큐레이션 매핑(catalog/template-mapping.json), upstream 대조 도구 sync_egovframe_templates 로 커버리지 격차를 수작업 비교 없이 확인
v0.27 완료	공식 템플릿 커버리지 확대 (10 → 22종)	통합 카탈로그가 계산한 미커버 13종 중 12종을 Initializr zip(Git LFS) 조달로 추가. commit·sha256·크기 고정과 다운로드 검증, pom 자리표시자 치환, 템플릿별 globals.properties 경로 대응, sync_egovframe_templates 의 zip 지문 drift 보고
v0.28 완료	generate_egovframe_config	Initializr 설정 템플릿 21종(Handlebars)을 commit·sha256 고정으로 동봉해 오프라인 생성. xml·javaConfig·yaml·properties, Initializr 폼과 같은 필드·기본값, 선택지·파일명·패키지 검증, 기존 파일 거부, sync_egovframe_templates 의 동봉 템플릿 drift 보고
v0.29 완료	migrate_egovframe_project (1단계: 진단)	3.x/4.x 프로젝트를 5.x(Jakarta) 기준으로 스캔해 RTE 좌표·패키지·제거/이동 클래스·javax→jakarta·web.xml·XML 네임스페이스·라이브러리 전환 항목을 읽기 전용으로 auto/manual 구분 보고. 규칙은 egovframe-runtime 태그 3개 비교로 생성(catalog/migration-rules.json), 목적지 좌표는 CI 에서 실제 저장소와 대조
v0.30 완료	migrate_egovframe_project (2단계: 적용) + check_egovframe_dependencies	진단의 auto 항목을 원문 오프셋 편집으로 transaction 적용(백업·dryRun 기본·계획 파일·실패 복구, 적용 후 JDK 17 mvn compile CI 검증), 공식 5.x parent 에서 추출한 기준(관리 좌표 139종 + BOM 계열 7종)과 의존성 대조·보안 설정 존재 점검·선택적 OSV 조회
v0.31 완료	운영 편의	diagnose_egovframe_network(호스트 7종 프로브·실패 분류·셸별 처방, 다운로드 오류 메시지에 처방 부착), generate_agents_md(ko/en), 영문 README 와 EGOVFRAME_LANG=en 도구 설명, MCP Registry server.json·mcpName·정합 테스트
v0.32 완료	MCP 프로토콜 현대화	registerTool 전환(deprecated tool() 0건), 도구 27종에 ko/en title·annotations(readOnly 14·destructive 4·openWorld), 5종 outputSchema+structuredContent, 테스트 이식성 검사 스크립트(게이트)와 플랫폼 주입 단언
v0.33 완료	migrate_egovframe_project 3단계: 검증	verify=true 로 compile 오류 ↔ 수동 항목 연결 작업 목록(javac symbol/location 파싱, 연결 4단계), 공통컴포넌트 3.x→5.x 대응표(제거 54·이동 4, schemaVersion 2)와 재조립 권고·skipComponents
v0.34 완료	의존성 기준 완성 + drift 감시	Spring Boot BOM 전체(1,473종)·RTE 모듈 전이 의존성(58종)을 기준에 포함하고 항목마다 기준 출처 표시, vendor 분류·EOL 좌표 교체 규칙으로 공통컴포넌트 3.10 pom 의 unknown 17 → 1, sync_egovframe_templates 가 규칙·기준 카탈로그의 upstream drift(새 태그·새 parent·pom sha256)와 갱신 절차 보고
v0.35 완료	릴리스 자동화 (배포 공급망)	release.yml: main 의 CI 성공 → 네 조건 검사 → npm(OIDC trusted publishing, provenance) → 그 커밋에 태그 → GitHub Release(변경 이력 추출) → MCP Registry(OIDC). test:release(판정·노트·tarball 내용·크기), server.json 설명 100자 제한, CI 통합의 mcp-publisher validate
v0.36 완료	해석된 의존성 트리 + SBOM	check_egovframe_dependencies(resolve=true): Maven dependency:tree·Gradle dependencies 로 전이 의존성까지 판정(origin·via·differs), 새 도구 generate_egovframe_sbom(28종): CycloneDX 1.6 JSON(Maven 플러그인 / Gradle 트리 구성) + 기준 판정 속성 + OSV vulnerabilities[], 공식 web 템플릿 해석 65 artifact·SBOM 67 component·OSV 24건
v0.37 완료	전환 준비도 평가서 + 회귀 코퍼스	generate_egovframe_report(sections=["assessment"]): 개요·전환 범위·의존성 조치·보안·SBOM·A–D 등급(산식 인쇄, 재계산 테스트), json·outputPath. test:migrate-corpus: 공식 공통컴포넌트 v3.10.0·v4.3.2 부분 트리 기대값 고정(±1%, CI), 4.x→5.x 실자산 첫 확인. 릴리스 워크플로 재개(npm gitHead 태그)
v0.38 완료	공통컴포넌트 재조립 실행	평가서의 "재조립 권고"를 실행하는 reassemble_egovframe_components: 3.x/4.x 소스의 원본 태그를 지문으로 찾아 3-way 비교(원본·현재·5.0.6) → 5.0.6 조립 + 사용자 수정은 패치·작업 목록으로 보존, 매니페스트 생성(이후 upgrade·validate 적용), dryRun·transaction·compile 검증
v0.39 계획	CLI 모드 + CI 공급망 게이트	npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate> — AI 클라이언트 없이 CI·배치에서 같은 분석을 실행(JSON/Markdown, --fail-on 등급·판정 임계값, 종료 코드), generate_egovframe_ci 의 공급망 게이트 단계(평가서·SBOM 아티팩트), SDK 1.32(프로토콜 2025-11-25)
v0.40 계획	SBOM 운영: 최소 요소·비교·VEX	check_egovframe_sbom: 기존 SBOM 의 최소 요소(공급자·구성요소명·버전·고유식별자·의존관계·작성자·생성시각) 충족 점검, 빌드 도구 없이 purl 로 OSV 재조회, 이전 SBOM 과 비교(추가·제거·버전 변경·새 취약점), CycloneDX VEX 초안 생성; generate_egovframe_sbom 에 공급자·작성자 메타데이터 — 2027년 공공 SBOM 제출 제도화 대비

다음 버전 기획 (v0.38–v0.40)

v0.37.0 까지 끝난 상태(2026-10-05, 도구 28종, 테스트 약 1,500건, npm 0.36.1 까지 자동 배포·0.37.0 배포 진행)에서 다음 세 릴리스를 아래 순서로 진행합니다. 공통 원칙은 이전과 같습니다 — 규칙은 데이터로, 근거는 공식 저장소에서, 쓰기 도구는 dryRun·transaction, 각 버전은 "완료 정의"를 만족해야 릴리스합니다. 이번 세 버전의 공통 주제는 평가에서 실행으로 입니다 — 평가서가 가장 큰 수작업으로 지목한 공통컴포넌트 재조립을 도구가 수행하고(v0.38), 같은 분석을 AI 클라이언트 없이 CI 와 배치에서 돌리며(v0.39), SBOM 을 만드는 데서 그치지 않고 제출물로서 검증·비교·추적합니다(v0.40). 선행 조사 근거는 맨 아래 "선행 조사 결과 (2026-10-05)"에 있습니다.

v0.38.0 — 공통컴포넌트 재조립 실행 (reassemble_egovframe_components)

목표: 코퍼스가 보여 준 대로 3.x/4.x 프로젝트의 수동 전환 항목 대부분은 복사해 넣은 공통컴포넌트 소스 안에 있습니다(4.3.2 트리: 수동 717건 중 제거된 공통컴포넌트 클래스 524·재조립 권고 155). 지금은 "add_egovframe_components 로 5.0.6 을 다시 조립하고 사용자 수정은 백업과 diff 로 옮기세요"라고 안내만 합니다. 이 과정을 도구가 수행하되, 사용자가 손댄 파일을 한 줄도 잃지 않게 합니다.

범위 (포함)

• 선행: 공통컴포넌트 v5.0.7 대응 — upstream 이 2026-10-06 v5.0.7 을 냈습니다(v5.0.6 대비 1,672파일, 주로 uss·sym·cop 매퍼·JSP·uss/ion·cop/smt). 재조립 대상 버전이 곧 이 태그이므로, 먼저 컴포넌트 카탈로그(generate:catalog)·전환 규칙의 공통컴포넌트 대응표(components.toTag)·sync_egovframe_catalog 고정을 v5.0.7 로 올리고 회귀 코퍼스 기대값을 갱신합니다(drift 감시가 CI 에서 이미 경고 중).
• 새 도구 reassemble_egovframe_components(projectDir, components?, sourceTag="auto", database?, dryRun=true, verify=false)(29번째): (1) diagnose_egovframe_project 가 감지한 컴포넌트 중 전환 항목이 있는 것(평가서의 재조립 권고와 같은 기준)을 대상으로 삼고 components 로 좁힐 수 있습니다. (2) 원본 태그 식별 — 프로젝트의 컴포넌트 파일 해시를 세대에 맞는 후보 태그(3.x: v3.9.0·v3.10.0 / 4.x: v4.0.0–v4.3.2, 공식 저장소 태그 21종 중)의 같은 경로와 대조해 일치 비율이 가장 높은 태그를 고릅니다. 후보 트리는 v0.37 코퍼스의 sparse 부분 클론을 컴포넌트 접두어 단위로 재사용해(태그당 수 MB) .egov-cache 에 캐시하고, sourceTag 로 고정할 수 있습니다. (3) 3-way 분류 — 원본(식별한 태그)·현재·5.0.6 의 파일 해시로 unchanged(교체)·user-modified(교체 + 사용자 변경을 unified diff 패치로 보존)·added(사용자 파일, 유지)·removed-in-5.x(5.0.6 에 없는 파일, 백업 후 제거 — sec/rnc 실명확인·utl/sec 등 코퍼스에서 확인된 미대응 디렉터리는 작업 목록에 올림)로 나눕니다. upgrade_egovframe_project 의 classifyUpgrade 와 같은 규칙이며 매니페스트 대신 원본 태그가 기준선입니다. (4) 조립 — add_egovframe_components 의 계획기로 5.0.6 파일(소스·매퍼·JSP·메시지·설정 조각·DB 스크립트)을 내려받아 넣고 매니페스트(.egovframe-components.json, 해시 포함)를 기록해 이후 upgrade·validate·remove 수명주기 도구가 적용되게 합니다. 모든 변경은 하나의 transaction, 원본은 migration-backup/<timestamp>/, 사용자 패치는 migration-backup/<timestamp>/patches/<component>/*.patch 와 reassemble-plan.json(파일별 분류·패치 경로·작업 목록). (5) 작업 목록 — 사용자 수정 파일마다 "5.0.6 의 같은 파일에 이 패치를 다시 적용" 항목을, 5.x 에 없는 파일마다 "대체 방법" 항목을 내고, verify=true 면 build_egovframe_project(compile) 을 돌려 v0.33 의 연결 규칙으로 오류를 항목에 붙입니다. 결과는 Markdown·format=json(outputSchema), 도구 메타는 파괴적(destructive, 기존 파일 교체)·openWorld.
• migrate_egovframe_project 진단의 component-reassemble 항목 to 에 새 도