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.43.0은 **도구 32종(title·annotations·구조화 출력 11종) + CLI 명령 10종, 공식 템플릿 22종, 설정 템플릿 21종, 5.x 전환 규칙(RTE 18모듈·클래스 331종 + 공통컴포넌트 1,089종 근거)과 적용·검증·재조립·사본 리허설, 의존성 기준(공식 parent 관리 좌표 139종+계열 6종+Spring Boot BOM 1,473종+RTE 전이 58종)·해석된 의존성 트리·CycloneDX·SPDX SBOM 생성·점검(최소 요소·비교·VEX), GitHub·GitLab·Jenkins CI 공급망 게이트, 규칙·기준 drift 감시, 폐쇄망 오프라인 번들, 네트워크 진단·AGENTS.md 생성, 공통컴포넌트 카탈로그 190항목(리프 176종+그룹 14종, v5.0.7)**을 제공합니다.

진행 현황 (2026-10-11)

• 소스 기준: v0.43.0(package.json), 도구 32종 + CLI 명령 10종·공식 템플릿 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.43.0 추가: CI·제출 형식 다변화 — generate_egovframe_ci(platform="gitlab"|"jenkins") 가 GitHub Actions 와 같은 빌드·공급망 게이트를 .gitlab-ci.yml(JUnit·CycloneDX 리포트)·Jenkinsfile(Declarative, Linux sh·Windows bat 공용)로 만들고, 게이트에 SBOM 최소 요소 점검(sbom-check --fail-on minimum)을 세 플랫폼 모두 추가했습니다. 사내 npm 레지스트리(npmRegistry)·오프라인 번들 경로(offlineBundle)는 환경 변수로 들어가고, 공급자 단서가 없으면 게이트가 실패할 것을 미리 알립니다. SBOM 은 SPDX 2.3 JSON 으로도 냅니다 — generate_egovframe_sbom(bomFormat="spdx-json") 이 패키지·DEPENDS_ON 관계(의존 없음은 NONE)·purl·공급자·creators·created·체크섬·선언 라이선스·OSV 권고·기준 판정(annotations)을 담고, check_egovframe_sbom 은 형식을 자동 판별해 SPDX 도 같은 최소 요소 7종·재판정·비교로 점검합니다(VEX 는 CycloneDX 만). 공식 web 템플릿을 실제 Maven 으로 만든 SBOM 은 SPDX 로 바꿔도 component 67·최소 요소 판정(요소별 충족 수까지)이 같고 SPDX ↔ CycloneDX 비교 차이 0 이며, 생성 .gitlab-ci.yml 은 GitLab 공식 CI 스키마를, SPDX 출력은 공식 spdx-spec v2.3 스키마를 통과합니다. 도구 수는 32종 그대로입니다.
• v0.42.0 추가: 폐쇄망(망분리) 운영 — 새 도구 prepare_egovframe_offline_bundle(32번째)이 인터넷 PC 에서 OSV Maven 취약점 전체 덤프(≈10MB, 7,190건)·고정 공통컴포넌트 아카이브(sha256 검증)·Initializr zip 템플릿(고정 지문)·재조립용 공식 공통컴포넌트 태그 22개 미러(≈37MB)를 한 디렉터리에 담고 bundle-manifest.json(파일별 sha256·크기·출처 URL·받은 시각)을 씁니다. 폐쇄망 PC 에서 EGOVFRAME_OFFLINE_BUNDLE 만 지정하면 다운로드는 번들 파일을 지문 검증 후 쓰고(변조 거부), offline=false 의 OSV 조회는 로컬 덤프로 판정하며(스냅숏 기준일 표시, 30일 넘으면 경고), 재조립은 번들 미러를 씁니다. 같은 날 받은 덤프의 로컬 판정이 온라인 OSV 와 질의 73/73·ID 134/134 일치했고, 네트워크를 막은 상태에서 프로젝트 생성·공통컴포넌트 조립·재조립 미리보기·SBOM 재점검이 번들만으로 끝나는 것(네트워크 시도 0건)을 CI 에서 확인합니다. CLI bundle, 네트워크 진단의 오프라인 번들 처방.
• v0.41.0 추가: 전환 리허설 — 새 도구 rehearse_egovframe_migration(31번째)이 프로젝트를 건드리지 않고 사본에서 공통컴포넌트 재조립 → 전환 자동 항목 적용 → 컴파일 → pom 을 공식 공통컴포넌트 v5.0.7 기준으로 맞춤 → 다시 컴파일까지 돌려 "자동 단계 뒤 사람이 고칠 것이 실제로 몇 건인가"를 잽니다(javac 의 오류 100개 상한 없이 전부 셈, 실행 전후 지문으로 원본 불변 확인). 공식 공통컴포넌트 v4.3.2 전체 트리(6,523 파일)는 자동 단계 뒤 컴파일 오류 6,003건(CI·JDK 17, JDK 21 은 6,335건) 중 4건을 뺀 전부가 누락 패키지와 그 연쇄(pom 의존성, 그 때문에 Lombok 이 돌지 못한 getter 등)였고, pom 을 맞추면 1건(GPKI 벤더 jar 의 javax 참조)만 남습니다 — CI 가 이 값을 기대값으로 고정합니다. 실측 중 찾은 두 결함도 고쳤습니다: 재조립은 전환 적용보다 먼저 해야 원본 태그가 식별되고(반대로 하면 4.3.2 가 v5.0.1 로 오인), 4.x 의 org.egovframe.rte 좌표가 5.x 로 분류되던 문제와 Maven 경고·fork 형식이 컴파일 오류로 잘못 읽히던 문제를 바로잡았습니다. 평가서 6절에 최근 리허설 실측이 함께 나옵니다.
• v0.40.0 추가: SBOM 운영 — 새 도구 check_egovframe_sbom(30번째)이 이미 만든 CycloneDX SBOM 을 제출물로서 점검합니다. (1) 최소 요소 7종(공급자·구성요소명·버전·고유식별자·의존관계·작성자·생성 시각, NTIA 최소 요소 = 국내 SW 공급망 보안 가이드라인 핵심 구성요소)을 component 마다 세어 "제출 가능/보완 필요"를, (2) 빌드 도구 없이 purl 만으로 기준 판정과 OSV 를 다시 해 생성 이후 바뀐 판정·새로 알려진 취약점을, (3) 이전 SBOM 과의 추가·제거·버전·판정·취약점 차이를, (4) vex=true 면 CycloneDX VEX 초안(새 취약점은 in_triage, 사람이 적은 판단은 보존)을 냅니다. generate_egovframe_sbom 은 supplier·author 옵션(기본 pom <organization>)과 공급자 표로 최소 요소를 생성 단계에서 채웁니다. 공식 web 템플릿 SBOM 은 공급자(주 component 포함 18종)·작성자가 비어 "보완 필요", 옵션으로 다시 만들면 "제출 가능"이고, SBOM·VEX 모두 CycloneDX 1.6 공식 스키마를 통과합니다. CLI sbom-check, 평가서 5절에 최소 요소·VEX 상태. 기획 세 버전(v0.38–v0.40)이 모두 완료됐습니다.
• v0.39.0 추가: CLI 모드와 CI 공급망 게이트 — npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate|diagnose|network> 가 AI 클라이언트 없이 같은 분석을 실행하고 종료합니다(인자 없는 실행은 기존 stdio 서버). --json 은 MCP structuredContent 와 같은 객체이고, --fail-on supplyChain:C·vulnerabilities·manual>20 같은 기준을 넘으면 종료 코드 2 로 파이프라인을 멈춥니다. generate_egovframe_ci(supplyChain=true) 는 SBOM 생성 → 평가서(등급을 PR 요약에) → 아티팩트로 이어지는 게이트 job 을 만듭니다(생성 결과는 CI 에서 actionlint 로 검사). MCP SDK 1.32.1(프로토콜 2025-11-25)로 올렸습니다.
• 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.41–v0.43 기획을 모두 마쳤습니다(기획 원문과 결과). 다음 세 버전 기획은 아직 없습니다.
• 배포 상태: npm 최신 배포 버전은 상단 npm 배지와 npm 패키지 페이지를 단일 출처로 확인합니다. 이 문서의 버전 표기는 저장소 소스(package.json) 기준이며, git 태그 vX.Y.Z가 해당 배포본의 커밋을 가리킵니다.

제공 도구

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 적용)
• bomFormat — cyclonedx-json(기본, CycloneDX 1.6) | spdx-json(v0.43, SPDX 2.3 — CycloneDX 로 만든 뒤 변환)
• outputPath — 프로젝트 상대 경로(기본 sbom/bom.cdx.json, SPDX 는 sbom/bom.spdx.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)
• v0.40: supplier(공급자 — 주 component 와 metadata.supplier, 기본 pom <organization><name>)·author(metadata.authors, 기본 supplier)·componentName·componentVersion(주 component 덮어쓰기), fillSuppliers(기본 enrich 와 같음 — 공급자가 없는 component 를 catalog/sbom-rules.json 공급자 표로 보완하고 egovframe:supplierBasis=catalog 로 표시). 응답의 minimum 이 최소 요소 7종 판정을 요약합니다.

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
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, supplier="○○기관", author="○○정보기술")  # 최소 요소까지
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, bomFormat="spdx-json", supplier="○○기관")  # sbom/bom.spdx.json (SPDX 2.3)

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

check_egovframe_sbom 파라미터 (SBOM 점검)

• sbomPath — 점검할 SBOM(기본 sbom/bom.cdx.json; CycloneDX JSON 또는 SPDX 2.x JSON, 형식 자동 판별), baselinePath — 비교할 이전 SBOM(선택, 형식이 달라도 purl 좌표로 비교)
• offline — true(기본) | false OSV 재조회(생성 이후 새로 알려진 취약점·지금 조회되지 않는 취약점)
• vex — true 면 VEX 초안 작성·갱신(vexPath, 기본 sbom/vex.cdx.json, CycloneDX 입력만), dryRun — vex 미리보기
• SBOM 파일은 바꾸지 않습니다. VEX 는 새 파일로 만들고, 다음 실행은 기존 판단을 그대로 두고 새 항목만 덧붙입니다(깨진 VEX 는 덮어쓰지 않고 중단)

SBOM 제출 준비

2027년까지 공공 분야에 도입되는 IT 시스템·SW 제품의 SBOM 제출이 제도화됩니다(SW 공급망 보안 로드맵, 2026-06). 제출물에는 "만들었다"보다 빠진 요소가 없고, 이전 제출본과 무엇이 달라졌으며, 알려진 취약점을 어떻게 판단했는지가 함께 있어야 합니다.

generate_egovframe_sbom(projectDir, dryRun=false, offline=false, supplier="○○기관", author="○○정보기술")   # 1. 생성(최소 요소 포함)
check_egovframe_sbom(projectDir)                                     # 2. 최소 요소 7종 — 제출 가능/보완 필요
check_egovframe_sbom(projectDir, offline=false, vex=true)            # 3. 새 취약점 확인 + VEX 초안(in_triage)
#    → 담당자가 sbom/vex.cdx.json 의 analysis.state 를 not_affected(+justification)·exploitable·resolved 등으로 기록
check_egovframe_sbom(projectDir, baselinePath="sbom/bom-2026Q3.cdx.json", offline=false, vex=true)   # 4. 다음 제출 전: 비교 + 새 취약점만 VEX 에 추가

규칙은 catalog/sbom-rules.json 데이터입니다(출처: NTIA 최소 요소 2021, SW 공급망 보안 가이드라인 1.0) — 국내 지침이 요소를 더하면 데이터로 추가합니다. CI 에서는 npx -y egovframe-scaffold-mcp sbom-check --offline=false --fail-on "minimum,newVulns" 로 제출 전 점검을 게이트로 걸 수 있습니다.

제출처가 SPDX 를 요구하면(가이드라인 1.0 은 SPDX·CycloneDX 를 모두 언급) bomFormat="spdx-json" 으로 같은 내용을 SPDX 2.3 JSON 으로 냅니다. 체크섬·선언 라이선스(이름만 있는 라이선스는 LicenseRef- + hasExtractedLicensingInfos)·OSV 권고(SECURITY/advisory externalRefs)·기준 판정(egovframe:* annotations)도 옮기므로, SPDX 로 낸 뒤 check_egovframe_sbom(sbomPath="sbom/bom.spdx.json") 의 재판정·비교가 CycloneDX 와 같은 결과를 냅니다. SPDX 3.0, 취약점 판단 자동화(VEX 상태는 사람의 결정), 중앙 저장소 제출 API 는 범위 밖입니다.

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 적용이 오히려 위험).

rehearse_egovframe_migration 파라미터 (전환 리허설)

• projectDir — 대상 프로젝트(읽기만 함, 허용 root 적용)
• steps — 기본 ["reassemble","migrate","verify","align-pom"](순서 고정, 일부만 고를 수 있음)
• components·sourceTag — 재조립 단계에 그대로 전달
• keepWorkspace — true 면 사본(EGOVFRAME_CACHE_DIR/rehearsal/<이름>-*)을 남기고 경로를 돌려줌(기본: 끝나면 삭제), timeoutMs — 컴파일 1회(기본 900000), topN — 작업 목록 수

사본은 빌드 산출물·VCS·백업 디렉터리를 빼고 만듭니다. 재조립을 전환 적용보다 먼저 하는 이유는 적용이 컴포넌트 소스를 바꾸면 원본 태그 지문이 깨지기 때문입니다(공식 4.3.2 트리를 거꾸로 돌리면 v5.0.1 로 오인되고 1,489개 파일이 "사용자 수정"이 됩니다). Maven 은 -Dmaven.compiler.fork=true 와 JDK_JAVAC_OPTIONS=-Xmaxerrs 100000 으로 javac 의 오류 100개 상한 없이 셉니다. pom 맞춤은 사본에만 적용하고 패치로 돌려주므로, 검토해서 실제 pom 에 반영하면 됩니다. 실측(공식 공통컴포넌트 v4.3.2 전체): 자동 단계 후 6,003건(JDK 17)·6,335건(JDK 21) → pom 맞춤 후 1건. javac 판본마다 같은 원인을 다른 모양으로 보고하므로(JDK 17 은 없는 패키지의 import 대신 쓰는 곳마다 "cannot find symbol") 분석은 파일의 import 문·타입 선언 파일·Lombok 사용 여부로 원인을 묶습니다. pom 에 소스 인코딩이 없으면 UTF-8 로 컴파일합니다(JDK 18+ 기본값).

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

generate_egovframe_report(projectDir, sections=["assessment"])        # 평가서: 재조립 권고·수동 항목·등급
rehearse_egovframe_migration(projectDir)                               # 사본에서 전 과정 실측: 남는 컴파일 오류·pom 변경안(원본 불변)
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 7912e13c…에 고정됩니다(v0.38 에서 v5.0.6 → v5.0.7, v0.39 에서 upstream 이 태그를 옮겨 3756ab2c… → 7912e13c… 로 재고정).
• 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."

CI 에서 쓰기 (CLI 모드)

AI 클라이언트가 없는 빌드 서버에서는 같은 패키지를 명령으로 실행합니다. 인자가 없으면 MCP 서버, 명령이 있으면 그 도구를 한 번 실행하고 종료합니다.

npx -y egovframe-scaffold-mcp assess --project . --offline=false --out assessment.md --fail-on supplyChain:C
npx -y egovframe-scaffold-mcp check --project . --resolve --json --fail-on "vulnerabilities,outdated>10"
npx -y egovframe-scaffold-mcp sbom --project . --write --offline=false
npx -y egovframe-scaffold-mcp sbom-check --project . --offline=false --fail-on "minimum,newVulns"
npx -y egovframe-scaffold-mcp migrate --project . --fail-on manual
npx -y egovframe-scaffold-mcp rehearse --project . --fail-on "errors>50"

옵션은 도구 파라미터와 같은 이름(kebab-case 가능)이고, 공통 옵션은 --project·--json(MCP structuredContent 와 같은 객체)·--out·--step-summary(Markdown 을 $GITHUB_STEP_SUMMARY 에)·--fail-on 입니다. 종료 코드는 0 통과 · 2 --fail-on 기준 초과 · 3 실행 실패 · 64 사용법 오류, 본문은 stdout·한 줄 요약은 stderr 입니다. 쓰기 도구(생성·조립·적용·재조립)는 CLI 에 노출하지 않습니다.

CI 설정 생성: GitHub Actions · GitLab CI · Jenkins

generate_egovframe_ci(projectDir, platform, supplyChain=true) 가 세 플랫폼에 같은 빌드와 같은 게이트를 만듭니다. 게이트는 SBOM 생성(sbom --write --offline=false) → 최소 요소 7종 점검(sbom-check --fail-on minimum, v0.43) → 전환 준비도 평가서(assess --fail-on <failOn>) 순서이고, CLI 의 종료 코드 2(기준 초과)·3(실행 실패)는 job 실패입니다. 보고서(egovframe-assessment.md·egovframe-sbom-check.md)와 sbom/bom.cdx.json 은 실패해도 보관하며, 패키지 버전은 생성 시점의 서버 버전으로 고정됩니다.

generate_egovframe_ci(projectDir="/work/my-egov-app", platform="gitlab", supplyChain=true, supplier="○○기관")
generate_egovframe_ci(projectDir="/work/my-egov-app", platform="jenkins", supplyChain=true, failOn="supplyChain:C",
                      npmRegistry="https://nexus.example.go.kr/repository/npm-group/", offlineBundle="/opt/egov-bundle")

• npmRegistry 는 NPM_CONFIG_REGISTRY(npx 가 이 서버를 받는 사내 레지스트리), offlineBundle 은 EGOVFRAME_OFFLINE_BUNDLE(러너·에이전트에서 본 번들 경로)로 들어갑니다. 값은 따옴표·$·줄바꿈 없는 URL·절대 경로만 허용합니다(설정 파일 주입 차단).
• 공급자 단서가 없으면(supplier 미지정, pom <organization><name> 없음) SBOM 의 주 component 공급자·작성자가 비어 sbom-check 단계가 실패하므로, 생성 응답이 이를 미리 알립니다.
• GitLab 이미지는 공개 Docker Hub 기준입니다. 폐쇄망에서는 사내 레지스트리의 같은 이미지(JDK + Node.js 18 이상)로 바꾸세요. Jenkins 는 Pipeline 기본 단계(sh·bat·archiveArtifacts)만 쓰며 에이전트에 JDK·Maven·Node.js 가 있어야 합니다.
• 생성 .gitlab-ci.yml 은 테스트에서 GitLab 공식 CI 스키마로 검증하고, Jenkinsfile 은 Declarative 구조를 단언합니다(실제 Jenkins 실행 검증은 보류). 설계: docs/design-cli.md.

폐쇄망에서 쓰기 (오프라인 번들)

공공 개발 환경은 대부분 망분리라 인터넷 PC 에서 받은 자료를 반입해 씁니다. 이 서버가 실행 중에 인터넷을 쓰는 곳(공통컴포넌트 아카이브·Initializr zip 템플릿 다운로드, OSV 취약점 조회, 재조립 원본 태그 조회)을 번들 하나로 대신합니다.

# 1) 인터넷 PC — 번들 만들기(≈110MB: OSV 10 · 아카이브 45 · web 템플릿 15 · 태그 미러 37, 템플릿 12종 전부면 ≈150MB)
npx -y egovframe-scaffold-mcp bundle --output-dir ./egov-bundle --write
npx -y egovframe-scaffold-mcp bundle --output-dir ./egov-bundle --templates web,boot-web --write   # 템플릿 골라 담기

# 2) 폐쇄망 PC — 옮긴 디렉터리를 지정(MCP 클라이언트 설정의 env 에도 같은 값)
export EGOVFRAME_OFFLINE_BUNDLE=/opt/egov-bundle        # cmd: setx EGOVFRAME_OFFLINE_BUNDLE D:\egov-bundle

번들 파일은 쓸 때마다 manifest 의 sha256·크기와 대조하고 다르면 거부합니다. 번들에 없는 URL 은 평소처럼 네트워크로 가므로, 저장소 템플릿(simple-backend 등)이 필요하면 --templates 로 지정해 함께 담으세요. Maven 의존성 jar 는 번들에 넣지 않습니다 — 기관 Nexus·Artifactory 미러를 settings.xml 에 지정하세요. upstream 대조 도구(sync_egovframe_*)와 가이드 문서 조회는 인터넷이 필요합니다. 설계: docs/design-offline-bundle.md.

리소스·프롬프트 (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 으로 띄운 서버의 도구 32종 설명이 모두 영문이고 표에 빠진 도구가 없는지, tools/list 에 title·annotations(readOnly 13종·destructive 5종)·outputSchema 11종이 노출되는지 확인 (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)
• 오프라인 번들 레벨: Maven 버전 비교(숫자·한정자 순서·같은 표기), OSV 범위(여러 구간·fixed·last_affected), 덤프 색인(Maven 만·철회 제외·GIT 범위 무시)과 querybatch 같은 모양의 결과, 번들 만들기(dryRun·manifest 지문·고정 지문 불일치 거부·실패 시 무흔적·덮어쓰기 거부·로컬 git 원본 미러), 번들 읽기(fetch 훅·POST 제외·변조 거부·깨진 manifest), 원본 미러(태그·커밋·트리·blob, 없는 태그 안내), OSV 출처 노트와 30일 경고, 의존성 점검 연동, 네트워크 진단 처방 (npm run test:offline-bundle, 30단언, 네트워크 불필요); CI 통합이 실제 번들을 만들고 로컬 OSV 와 온라인 OSV 를 대조(97% 이상 일치 요구, 실측 100%)한 뒤 fetch 를 막고 생성·조립·재조립 미리보기·SBOM 재점검을 번들만으로 확인 (npm run test:bundle-live)
• 전환 리허설 레벨: pom 맞춤(parent 추가·교체, 누락 좌표, 버전·scope, parent 관리 속성, 주석·dependencyManagement·plugin 제외, 멱등), 누락 패키지·연쇄·수동 항목 분류와 후보 좌표, Maven fork 형식·경고 제외 파서, 사본 제외 규칙·원본 지문 불변, 단계 순서(재조립 → 적용 → 컴파일 → pom 맞춤 → 컴파일)·javac 상한 해제 인자, 단계 실패 계속, 기록과 평가서 6절 (npm run test:rehearse, 38단언, 네트워크 불필요); CI 통합이 공식 공통컴포넌트 v4.3.2 전체 트리를 실제로 리허설해 재조립·적용 수와 오류 6,003(±10%, 누락 패키지·연쇄 95% 이상)→≤5 를 단언 (npm run test:rehearse-live)
• SPDX 레벨: 실제 플러그인 출력 고정물을 SPDX 2.3 으로 바꿔 공식 spdx-spec v2.3 스키마 통과, 패키지 68·DEPENDS_ON 간선 수 = CycloneDX 의존 간선·의존 없음 NONE·체크섬·라이선스(LicenseRef)·DESCRIBES, 되읽었을 때 최소 요소 요소별 충족 수·purl·의존 간선·기준 판정(annotations)·취약점(advisory) 보존, 다른 도구 모양 SPDX(DEPENDENCY_OF·NOASSERTION·여러 DESCRIBES·Person/Organization/Tool)의 필드 대응, bomFormat="spdx-json" 생성·SPDX 입력 점검(형식 판별·CycloneDX 와 같은 판정·SPDX↔CycloneDX 비교 차이 0·VEX 거부)·outputSchema (npm run test:spdx, 43단언, 네트워크 불필요). 실제 Maven SBOM 의 SPDX 판정 일치는 CI 통합 test:sbom-live 가 확인
• SBOM 운영 레벨: 실제 플러그인 출력 고정물(공식 web 템플릿 67 component)로 최소 요소 7종(빠진 항목별)·공급자 표 보완·purl 재판정·가짜 OSV(새/사라진 ID)·비교(추가·제거·버전·판정·취약점)·VEX 생성/판단 보존/같은 ID 의 새 영향 component·깨진 VEX 중단을 단언하고, 생성 SBOM·VEX 를 CycloneDX 1.6 공식 JSON 스키마(specification 1.6.1)로 검증 (npm run test:sbom-check, 54단언, 네트워크 불필요); CI 통합이 실제 SBOM 으로 보완 필요(주 component 공급자·작성자) → supplier·author 로 보완(환경에 따른 다른 공백은 info: 로그), 두 SBOM 비교 차이 0, 실제 OSV VEX 초안·판단 보존을 확인 (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)
• CLI 레벨: 인자 해석(--x·--x=v·--no-x)·스키마 형 변환·모르는 옵션, --fail-on 등급·임계값·오류, 종료 코드 0/2/3/64, 쓰기 옵션 차단, --json = 라이브러리 결과, --out·--step-summary, 실제 프로세스(인자 유무로 서버/CLI) (npm run test:cli, 32단언, 네트워크 불필요). CI 생성 레벨에 공급망 게이트 job·failOn 주입 거부 추가(npm run test:ci), CI 통합에서 생성 워크플로를 actionlint 로 검사하고 4.3.2 코퍼스 트리로 CLI 평가서를 실행해 job 요약에 등급을 남깁니다
• 재조립 레벨: 메모리 원본 저장소로 원본 태그 식별(세대 후보·지정·없는 태그), 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·failOn·supplier·환경 변수 주입 입력 거부, 세 플랫폼 공통 게이트 명령(sbom → sbom-check → assess), 생성 .gitlab-ci.yml 의 GitLab 공식 CI 스키마(v19.4.1-ee 고정물) 통과, Jenkinsfile 의 Declarative 구조(pipeline·agent·options·stages·post, 괄호 짝, 단계 순서)·Windows 경로 이스케이프, 공급자 단서 없을 때 게이트 실패 예고 (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 으로 공통컴포넌트 재조립 실행, CLI 모드와 CI 공급망 게이트, SBOM 운영(최소 요소·비교·VEX)을, v0.41–v0.43 으로 전환 리허설, 폐쇄망 오프라인 번들, GitLab·Jenkins CI 와 SPDX 를 마쳤습니다(기획 원문과 결과: v0.41–v0.43 · v0.38–v0.40 · v0.35–v0.37). Homebrew 탭은 후순위에서 내렸습니다(npx 로 충분).