egovframe-scaffold-mcp

공식 egovframe-ai-rag 샘플 기반 AI RAG 챗봇(문서 업로드→임베딩→하이브리드 검색→LLM 응답)을 기존 Boot 프로젝트에 조립합니다. 소스·설정(application-ai.yml 프로필)·UI·인프라를 복사하고 pom에 누락 의존성만 마커 구간으로 삽입합니다(백업 생성, 제거 시 원복). 기존 파일과 충돌하면 아무것도 쓰지 않고 거부합니다. dryRun=true로 먼저 미리볼 수 있습니다.

공통컴포넌트를 골라 기존 프로젝트에 조립합니다. 의존 컴포넌트를 포함해 소스·매퍼·JSP를 복사하고, database 지정 시 DB DDL·DML 스크립트도 복사합니다. 기존 파일과 충돌하면 아무것도 쓰지 않고 거부합니다. dryRun=true로 먼저 미리볼 수 있습니다.

레시피 하나를 골라 프로젝트 생성 → 공통컴포넌트(필요 시 AI 계층) 조립까지 순차 실행합니다. dryRun=true로 전체 계획을 먼저 미리볼 수 있습니다.

생성한 eGovFrame 프로젝트를 실제로 빌드(컴파일·테스트·패키지)하고 결과를 구조화해 반환합니다. 빌드도구(maven/gradle)와 래퍼(mvnw/gradlew)를 자동 감지하고, 컴파일·테스트 오류를 파일·라인 단위로 파싱합니다. dryRun으로 실행 예정 명령만 미리볼 수 있습니다. (생성→검증 루프 완성)

프로젝트의 Maven/Gradle 의존성(resolve=true 면 빌드 도구로 해석한 전이 의존성까지, 트리 경로와 선언·해석 버전 차이 포함)을 공식 5.x parent(egovframe-web-config-parent·egovframe-boot-starter-parent)가 관리하는 기준 버전, Spring Boot BOM 전체(spring-boot-dependencies + import 한 단계), RTE 모듈 18종의 전이 의존성과 대조해 기준 충족/기준 미만/parent 관리/전환 대상(3.x·4.x RTE, javax 좌표)/교체 필요(DBCP 1.x·Log4j 1.x·Jackson 1·Ehcache 2 등)/벤더 배포(국내 DBMS·GPKI 등)/기준 없음 으로 분류하고 항목마다 기준 출처(parent 직접·계열·Boot BOM·RTE 전이)를 적으며, 5.x parent 사용 여부와 Java 버전, 보안 설정 존재 여부(sec.security 컴포넌트·CSRF·XSS 필터·보안 헤더·HTTPS 저장소)를 파일·라인 근거와 함께 보고합니다. 기본은 오프라인(동봉 기준 catalog/dependency-baseline.json)이며 offline=false 일 때만 OSV(api.osv.dev)로 알려진 취약점을 조회합니다. 디스크를 변경하지 않습니다. 멀티 모듈 작업공간이면 모듈별로 판정하고(모듈 parent·Gradle 버전 변수·공식 parent BOM) 모듈 요약을 함께 냅니다.

이미 만든 CycloneDX 또는 SPDX 2.x JSON SBOM 을 제출물로서 점검합니다(SBOM 파일은 바꾸지 않음, 형식은 자동 판별). (1) 최소 요소 7종 — 공급자·구성요소명·버전·고유식별자(purl/cpe)·의존관계·작성자·생성 시각(NTIA 최소 요소 = 국내 SW 공급망 보안 가이드라인 핵심 구성요소)을 component 마다 세어 '제출 가능/보완 필요'와 빠진 component 를 보고 (2) 빌드 도구 없이 purl 만으로 기준 판정을 다시 해 생성 당시와 달라진 판정을, offline=false 면 OSV 를 다시 조회해 생성 이후 새로 알려진 취약점을 보고(운영 중 주기 점검) (3) baselinePath(이전 SBOM)를 주면 추가·제거·버전 변경·판정 변화·새 취약점을 비교 (4) vex=true 면(CycloneDX 입력만) CycloneDX VEX 초안(기본 sbom/vex.cdx.json)을 씁니다 — 새 취약점은 analysis.state=in_triage, affects 는 BOM-Link 로 원본 SBOM 참조, 기존 VEX 에 사람이 적은 판단(not_affected·exploitable 등)은 보존하고 새 취약점만 추가합니다(dryRun=true 면 미리보기). 2027년 공공 SBOM 제출 제도화 대비.

행정안전부·KISA 「소프트웨어 개발보안 가이드」(2021) 구현단계 보안약점 중 정적 패턴으로 오탐을 통제할 수 있는 항목을 소스에서 찾습니다 — SQL 삽입(MyBatis ${…}·iBATIS $…$·JDBC 문자열 연결), 크로스사이트 스크립트(요청 값·EL param/header/cookie 무이스케이프 출력, <c:out escapeXml="false">), 경로 조작, 신뢰되지 않는 URL 자동접속, 운영체제 명령어, XML 외부개체, 취약한 해시·암호, 보안 문맥의 부적절한 난수, 코드·설정의 하드코드된 중요정보, HttpOnly·Secure 없는 쿠키, printStackTrace, 빈 catch, 역직렬화, 남은 디버그 출력. 규칙은 catalog/secure-coding-rules.json 데이터이고 주석은 무시합니다. 항목마다 파일·라인·CWE·등급·조치와 출처(공통컴포넌트 원본·수정본·매니페스트 없음·프로젝트 코드·테스트)를 냅니다. 예외는 .egovframe-secure-ignore.json(사유·검토자 필수), baselinePath(이전 JSON 결과·SARIF)와 비교해 새 항목 표시, format=sarif 또는 sarifPath 로 SARIF 2.1.0(GitHub code scanning 등). 패턴 기반 진단 보조이며 공인 진단을 대체하지 않습니다.

전자정부 표준프레임워크 공식 템플릿으로 새 프로젝트 골격을 생성합니다. 공식 GitHub 템플릿을 내려받아 projectName/groupId/DB 타입을 적용합니다. dryRun=true로 먼저 미리보기할 수 있습니다. alignParent=true 면 생성 직후 5.x parent·RTE 버전을 최신 5.0.x 로 맞춥니다(공식 Initializr 템플릿은 parent 5.0.0·5.0.1).

이 서버의 도구들이 내려받는 외부 호스트(codeload.github.com·raw.githubusercontent.com·media.githubusercontent.com·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 명령으로 안내합니다. 프로젝트 생성·컴포넌트 조립이 타임아웃으로 실패할 때 먼저 실행하세요. 파일을 쓰지 않으며 프로젝트 디렉터리도 필요 없습니다.

기존(스캐폴딩 도구로 만들지 않은 것 포함) 전자정부 표준프레임워크 프로젝트를 스캔해 빌드시스템·RTE 버전·DbType·설치된 공통컴포넌트(카탈로그 pathPrefixes 지문)·설정 문제를 진단합니다. 디스크를 변경하지 않는 읽기 전용입니다.

공통컴포넌트 하나의 상세(설명·직접/전이 의존성·이 컴포넌트에 의존하는 컴포넌트·참조 테이블·가이드 문서 링크·설치 명령)를 한 번에 반환합니다. (읽기 전용)

프로젝트를 진단해 AI 코딩 도구(Claude Code·Copilot·Cursor 등)용 AGENTS.md 를 생성합니다 — 빌드·테스트 명령(래퍼 감지), RTE 버전과 5.x 전환 상태, DbType, 기본 패키지·설정 디렉터리, 설치 공통컴포넌트(매니페스트 관리 여부), 지켜야 할 규칙(좌표·백업 디렉터리·비밀 정보·의존성 기준), 사용할 수 있는 MCP 도구. 기존 파일은 overwrite=true 가 아니면 거부하고, dryRun=true 면 내용만 돌려줍니다. 한국어(기본)·영어.

프로젝트에 CI 설정을 생성합니다 — platform=github(.github/workflows/egovframe-ci.yml, 기본)·gitlab(.gitlab-ci.yml)·jenkins(Jenkinsfile, Declarative). 빌드도구(maven/gradle) 자동 감지, JDK 지정, 빌드·테스트(GitLab 은 JUnit 리포트). supplyChain=true 면 이 서버의 CLI(npx egovframe-scaffold-mcp)로 SBOM 생성 → 최소 요소 7종 점검(sbom-check --fail-on minimum) → 전환 준비도 평가서(failOn 기준, 기본 supplyChain:D)를 돌려 기준을 넘으면 실패하고 보고서·SBOM 을 아티팩트로 남기는 공급망 게이트를 추가합니다(GitHub 은 PR 요약에 등급, GitLab 은 CycloneDX 리포트). npmRegistry(사내 npm 레지스트리)·offlineBundle(러너에서 본 오프라인 번들 경로)은 환경 변수로 넣습니다. dryRun으로 내용만 미리볼 수 있고, 실제 생성 시 기존 파일이 있으면 덮어쓰지 않고 거부합니다.

공식 eGovFrame Initializr 설정 템플릿(21종, 오프라인 동봉)으로 Spring 설정 파일을 생성합니다 — datasource(DBCP/C3P0/JDBC·JNDI), transaction(datasource/JPA/JTA), cache(Ehcache), logging(log4j2 console/file/rolling/time-rolling/jdbc), scheduling(Quartz job/trigger/scheduler), idGeneration(sequence/table/uuid), property. 형식은 xml(Spring XML)·javaConfig(@Configuration 클래스)·yaml·properties(logging 만). 필드를 생략하면 Initializr 웹뷰 폼과 같은 기본값을 쓰고, 기존 파일이 있으면 덮어쓰지 않고 거부합니다. 템플릿별 필드·기본값·선택지는 리소스 egovframe://catalog/config-templates 에서 확인하거나 dryRun 결과의 context 로 볼 수 있습니다.

eGovFrame Development의 공식 CRUD wizard 입력 체계에 맞춰 VO·Mapper(XML)·Service·Controller·JSP(선택)·JUnit 5 테스트(선택) 골격을 생성합니다. Classic XML과 Boot REST 프로필을 지원하며, 전체 파일 충돌을 먼저 검사해 하나라도 존재하면 아무것도 쓰지 않습니다.

프로젝트 진단(빌드 도구·패키징·Boot 여부·웹·actuator·DbType·설정 파일)으로 컨테이너·배포 산출물을 만듭니다 — Dockerfile(멀티 스테이지: Maven/Gradle 빌드 → Classic war 는 Tomcat 10.1(Servlet 6.1 이상이면 11.0)에 ROOT 로 풀어서, Boot jar 는 eclipse-temurin JRE 로; 비루트·HEALTHCHECK·Asia/Seoul·UTF-8, buildInImage=false 면 미리 빌드한 산출물), .dockerignore, deploy/docker-compose.yml(앱 + DbType 별 DB 컨테이너 mysql·mariadb·postgres, 템플릿 DDL·DATA 초기화, 상용 DB 는 연결 정보만), Kubernetes 매니페스트(deploy/k8s/<app>.yaml — Deployment(startup·readiness·liveness 프로브, 비루트 securityContext, 리소스)·Service·ConfigMap·Secret·선택 Ingress). DB 설정은 Boot 는 Spring 환경 변수(Globals.mysql.Url → GLOBALS_MYSQL_URL), Classic 은 globals.properties 사본을 볼륨·Secret 으로 덮어씁니다. imageRegistry 로 기반 이미지를 사내 레지스트리(폐쇄망)에서 받습니다. 새 파일만 쓰고(기존 파일 거부) dryRun(기본)은 내용만 보여 줍니다. 멀티 모듈·라이브러리 jar·빌드 파일 없는 프로젝트는 이유를 돌려줍니다. 멀티 모듈 작업공간(Maven <modules>·Gradle include·루트 빌드 파일 없는 독립 프로젝트 묶음)이면 서비스 모듈마다 이미지(자체 Dockerfile 은 그대로)와 하나의 docker-compose·서비스별 Kubernetes 매니페스트를 만들고, 설정의 localhost 참조(설정 서버·디스커버리·DB·메시지 브로커·캐시)를 서비스 이름으로 바꿉니다(모듈 설정은 환경 변수, 설정 서버 저장소는 사본). modules 로 일부 서비스만 고릅니다.

프로젝트 리포트를 Markdown(또는 format=json)으로 만듭니다. sections=["components"](기본)는 설치 공통컴포넌트·참조 테이블·가이드 문서 링크·이슈, sections=["assessment"]는 5.x 전환 준비도 평가서 — (1) 개요(빌드 도구·RTE 세대·parent·Java·공통컴포넌트) (2) 전환 범위(migrate 진단 요약: 자동/수동·종류별·재조립 권고·예상 수동 작업 상위 N) (3) 의존성(기준 판정 집계·조치 목록, resolve=true 면 전이 포함, offline=false 면 OSV 취약점) (4) 보안 설정 점검 (5) SBOM 요약(sbomPath 에 있으면) (6) 등급과 근거 — 전환 난이도·공급망 상태를 각각 A–D 로 매기고 산식(요인·구간·점수)을 리포트에 그대로 적어 사람이 재계산할 수 있게 합니다. 비용·공수는 산정하지 않습니다. outputPath 를 주면 프로젝트 안에 새 파일로만 저장하고(기존 파일 거부, transaction), 그 외에는 디스크를 바꾸지 않습니다.

Maven/Gradle 프로젝트의 SBOM 을 CycloneDX 1.6 JSON(기본) 또는 SPDX 2.3 JSON(bomFormat=spdx-json — 패키지·DEPENDS_ON 관계·purl·공급자·작성자·생성 시각)으로 만듭니다(빌드 파일 변경 없음). Maven 은 cyclonedx-maven-plugin(makeAggregateBom, 해시·라이선스 포함), Gradle 은 해석된 의존성 트리로 문서를 구성합니다. enrich=true(기본)면 component 마다 기준 판정(egovframe:status·basis·baseline)을 properties 로 붙이고, offline=false 면 OSV 로 알려진 취약점을 vulnerabilities[] 로 넣습니다. 출력은 프로젝트 안 경로(기본 sbom/bom.cdx.json)만 허용하고 기존 파일은 overwrite=true 가 아니면 거부하며, dryRun(기본)은 실행 없이 계획만 돌려줍니다. 2027년부터 단계화되는 공공기관 SBOM 등록·제출에 쓸 수 있는 표준 형식입니다.

컴포넌트의 공식 가이드 문서(표준프레임워크 포털 egovframe-docs)를 가져옵니다. 문서가 여러 건이면 목록을 함께 반환하며 docIndex로 선택할 수 있습니다.

선택 설치를 지원하는 공통컴포넌트 카탈로그를 반환합니다 (저장소 스캔으로 자동 생성, scripts/generate-catalog.mjs).

큐레이션된 레시피(템플릿+컴포넌트 번들) 목록을 반환합니다. apply_egovframe_recipe로 한 번에 조립할 수 있습니다.

사용 가능한 전자정부 표준프레임워크 프로젝트 템플릿 목록을 반환합니다.

표준프레임워크 3.x/4.x 프로젝트를 5.x(Jakarta EE 9+, Spring 6, Java 17) 로 옮기기 위해 바꿔야 할 것을 파일·라인 단위로 진단하고(1단계), apply=true 이면 auto 항목을 실제로 치환합니다(2단계). 진단: RTE Maven 좌표(egovframework.rte → org.egovframe.rte:egovframe-rte-*)·패키지(egovframework.rte.* → org.egovframe.rte.*)·5.x 에서 이름이 바뀌거나 제거된 클래스·javax→jakarta 패키지와 의존성·web.xml 스키마·제거된 egov-* XML 네임스페이스·교체 필요 라이브러리, 항목마다 auto(기계 치환 가능)/manual(코드 수정 필요). 적용: apply=true 는 dryRun=true(기본)면 파일별 변경 미리보기만 돌려주고, dryRun=false 면 auto 항목을 하나의 transaction 으로 치환하며 원본을 migration-backup/<시각>/ 에 보관하고 migration-plan.json 을 남깁니다(중간 실패 시 작업 전 상태로 복구). manual 항목은 건드리지 않고 결과에 남깁니다. verify=true 는 3단계(검증): 적용 뒤 compile 을 실행해 컴파일 오류를 수동 항목과 연결하고 "이 항목을 처리하면 해결될 오류 수" 순으로 작업 목록을 만듭니다. 3.x 공통컴포넌트 소스가 섞여 있으면 컴포넌트 단위 재조립 권고를 내고 skipComponents 로 치환에서 뺄 수 있습니다. 규칙은 egovframe-runtime·egovframe-common-components 태그 비교로 만든 동봉 카탈로그(catalog/migration-rules.json)에서 읽습니다. target 에 5.0.2 같은 5.0.x 를 주면 이미 5.x 인 프로젝트의 갱신 모드가 됩니다: parent·RTE 버전 속성·RTE 의존성 리터럴 버전과 예전 parent 기본값을 그대로 덮어쓴 속성은 auto, 그 사이 바뀐 RTE API·동작(보안 설정 Bean 시그니처, 엑셀 수식 주입 방지, XML XXE 차단 등)을 프로젝트가 참조하는 곳과 공통컴포넌트 최신 유지(upgrade·reassemble 안내)는 manual 로 보고하며, apply·dryRun·verify 는 전환과 같게 동작합니다(백업에 update-plan.json, 규칙 catalog/update-rules.json).

망분리(폐쇄망) 개발 환경용 오프라인 번들을 인터넷 PC 에서 만듭니다. OSV Maven 취약점 전체 덤프·고정 공통컴포넌트 아카이브(sha256 검증)·Initializr zip 템플릿(고정 지문)·재조립용 공식 공통컴포넌트 태그 미러를 한 디렉터리에 담고 bundle-manifest.json(파일별 sha256·크기·출처 URL·받은 시각)을 씁니다. 새(또는 빈) 디렉터리에만 쓰며 dryRun(기본)은 받을 목록만 보여 줍니다. 폐쇄망 PC 에서 환경변수 EGOVFRAME_OFFLINE_BUNDLE 에 옮긴 경로를 지정하면 다운로드는 번들 파일을 지문 검증 후 쓰고, offline=false 의 OSV 조회는 로컬 덤프로 판정하며(스냅숏 기준일 표시·30일 넘으면 경고), 재조립은 번들 미러를 씁니다. Maven 의존성 jar 는 담지 않습니다(기관 저장소 미러 사용).

3.x/4.x(또는 이전 5.x) 프로젝트에 복사돼 있는 공통컴포넌트 소스를 카탈로그 고정 버전(현재 v5.0.7)으로 다시 조립합니다. (1) 프로젝트 파일의 git blob id 를 공식 egovframe-common-components 후보 태그(좌표 세대별)와 대조해 원본 태그를 식별하고(파일 내용을 내려받지 않음, sourceTag 로 지정 가능) (2) 원본·현재·목표로 파일마다 목표와 같음/원본 그대로(교체)/사용자 수정/5.x 신규/5.x 에서 제거/원본 미확인/사용자 추가를 판정한 뒤 (3) dryRun=false 면 하나의 transaction 으로 목표 파일을 쓰고(아카이브 sha256 검증), 5.x 에 없는 원본 파일은 백업 후 지우고, 사용자 수정 소스는 교체하되 원본 대비 변경을 unified diff 패치로 보존하며(설정·자산 파일은 사용자본을 유지하고 목표본을 참고로 저장) 매니페스트를 기록해 이후 upgrade·validate·remove 도구가 적용되게 합니다. 백업·패치·reassemble-plan.json 은 migration-backup/<시각>-reassemble-*/ 에 남고, 작업 목록(패치 다시 반영·5.x 제거 파일·설정 비교)을 돌려줍니다. verify=true 면 적용 뒤 compile 을 실행해 오류를 작업 목록 파일에 붙입니다. 원본 태그 비교에 git 이 필요하며 캐시는 EGOVFRAME_CACHE_DIR(기본 ~/.cache/egovframe-scaffold-mcp)에 둡니다. 패치를 자동으로 다시 적용하지는 않습니다.

프로젝트를 건드리지 않고 사본에서 5.x 전환을 미리 돌려 봅니다. 사본(EGOVFRAME_CACHE_DIR/rehearsal, 빌드 산출물·VCS·백업 제외)에서 (1) 공통컴포넌트 재조립(원본 태그 식별이 깨지지 않도록 전환 적용보다 먼저) (2) 전환 자동 항목 적용 (3) 컴파일 — Maven 은 javac 를 fork 해 -Xmaxerrs 로 오류 100개 상한 없이 모두 셈 (4) 사본 pom 을 공식 공통컴포넌트 고정 태그 pom 기준(parent·누락 좌표·버전·scope·parent 관리 속성)으로 맞춘 뒤 다시 컴파일합니다. 두 시점의 오류 수, 누락 패키지와 후보 좌표, 같은 파일의 연쇄 오류, 남는 수동 항목·파일, 사라지는 오류 순 작업 목록, 사본에 적용한 pom 패치를 돌려주고, 실행 전후 디렉터리 지문으로 원본 불변을 확인합니다. 최근 결과는 평가서 6절에 실측으로 표시됩니다. keepWorkspace=true 면 사본을 남깁니다.

add_egovframe_components로 조립한 컴포넌트를 제거합니다. 설치 매니페스트에 기록된 파일만 삭제하며, 다른 설치 컴포넌트가 의존하거나 설치 시점 hash와 달라진 파일은 기본 거부합니다. force=true는 remove-backup/에 사본을 만든 뒤 트랜잭션 제거하며, dryRun 미리보기를 지원합니다.

키워드로 공통컴포넌트를 검색합니다 (id·이름·설명·카테고리 부분 일치, 점수순 상위 10건).

공식 가이드 문서(egovframe-docs) 인덱스를 키워드로 검색합니다. 기본은 오프라인 인덱스 검색(제목·경로·연계 컴포넌트·카테고리 점수순)이며, fetchTop>0이면 상위 결과의 문서 본문을 내려받아 스니펫도 함께 제공합니다.

공식 egovframe-common-components 태그·commit·아카이브 무결성을 검증하고, 고정 카탈로그 대비 upstream 변경과 sec.security 보안 패키지를 점검합니다.

공식 프로젝트 템플릿 통합 카탈로그(Initializr·MCP·Development)를 upstream 과 대조해 추가·삭제·변경과 MCP 커버리지 격차를 보고하고, 동봉한 5.x 전환 규칙·의존성 기준 카탈로그의 drift(egovframe-runtime·공통컴포넌트의 새 태그, 공식 parent 의 새 버전, 고정 pom sha256 변화)도 함께 보고합니다. 파일은 고치지 않습니다.

eGovFrame 프로젝트의 테스트를 실제로 실행하고 JUnit XML 리포트(surefire/gradle)를 읽어 결과를 구조화합니다. 스위트별 통과·실패·오류·건너뜀 수와, 실패 케이스의 메시지·예외 타입·테스트 파일/라인을 반환합니다. testFilter로 특정 클래스/메서드만 실행할 수 있고, dryRun으로 실행 예정 명령을 미리볼 수 있습니다. (build_egovframe_project 의 테스트 후속)

매니페스트에 기록된 설치 공통컴포넌트를 upstream 최신본과 비교해 갱신합니다. 사용자가 수정한 파일은 force 없이는 보존하며, dryRun(기본)으로 변경 계획을 먼저 확인합니다. 덮어쓰기 전 upgrade-backup/에 백업하고, 하드 충돌 시 아무것도 쓰지 않고 거부합니다.

조립된 프로젝트의 무결성을 진단합니다: 설치 매니페스트 기준 파일 존재 확인, Globals.DbType과 복사된 DB 스크립트 일치 확인.