egovframe-scaffold-mcp 0.7.0 → 0.9.0

package/README.md

@@ -23,6 +23,7 @@ Claude, VS Code(Copilot), Cursor 등 MCP를 지원하는 AI 도구에서 **대
 | `remove_egovframe_components` | 설치 매니페스트 기반 컴포넌트 제거 — 의존 컴포넌트 보호, `dryRun` 미리보기 |
 | `validate_egovframe_project` | 조립 프로젝트 무결성 진단 — 파일 존재·DbType↔DB 스크립트 일치 |
 | `get_egovframe_guide` | 컴포넌트의 공식 가이드 문서 조회 (egovframe-docs, 45종 매핑) |
+| `add_ai_components` | 공식 [egovframe-ai-rag](https://github.com/eGovFramework/egovframe-ai-rag) 샘플 기반 AI RAG 챗봇 조립 — Spring AI(Redis Stack)·LangChain4j(PGVector) 스택 선택(상호 배타), 소스·설정(`application-ai.yml` 프로필)·UI·인프라 복사, **pom 누락 의존성만 마커 구간 삽입**(백업 생성, 제거 시 원복), 충돌 시 전체 거부, `dryRun` 미리보기 (설계: [docs/design-ai-components.md](docs/design-ai-components.md)) |
 
 ### create_egovframe_project 파라미터
 
@@ -106,11 +107,15 @@ Claude Desktop / Claude Code 설정 예 (`mcpServers`):
 
 1. 공통컴포넌트 선택 설치 — **M3 완료(v0.4.0)**: 저장소 스캔 기반 카탈로그 자동 생성(`npm run generate:catalog`, 68종) + 조립 파이프라인. 남은 항목: 컴포넌트별 테이블 선별 DDL, 이름·의존성 큐레이션 확대(`catalog/overrides.json` 기여 환영) (설계: [docs/design-components-parameter.md](docs/design-components-parameter.md))
 2. 실행환경 보일러플레이트(egovframe-msa 등) 템플릿 추가
-3. 검증 도구(`validate_egovframe_config`) 등 후속 도구
+3. AI 컴포넌트 조립(`add_ai_components`) — **M2 완료(v0.9.0)**: 실조립(복사+pom 마커 병합+설정 프로필화+remove/validate 연동). M3: langchain4j 실검증 확대, 진단 확장(ONNX 모델 경로·docker 서비스 감지), 패키지 재배치 옵션 검토 (설계: [docs/design-ai-components.md](docs/design-ai-components.md))
 4. 검증 후 eGovFramework 조직 공식 저장소 편입 제안
 
 ## 변경 이력
 
+- **0.9.0** — AI 컴포넌트 조립 M2(실조립): `add_ai_components`가 실제로 조립합니다 — 소스(`com.example.chat`)·설정(`application-ai.yml` 프로필, 기존 설정 불변)·UI·인프라(`docker-compose.ai.yml`·`Dockerfile.ai`·`k8s/ai/`) 복사(전체 사전 충돌 검사·원자적 거부), pom에 누락 좌표만 마커 주석 구간으로 삽입(exclusions 보존, `pom.xml.bak-ai` 백업), 매니페스트 기록으로 `remove_egovframe_components`가 파일·pom 삽입분을 함께 원복(바이트 단위 복원 검증), `validate_egovframe_project`에 pom 마커 진단 추가, 통합 테스트(`npm run test:ai-assembly`) 추가.
+
+- **0.8.0** — AI 컴포넌트 조립 M1: `add_ai_components` dryRun 미리보기(파일 복사 계획·pom 의존성 diff·부모 POM 호환성 게이트·스택 상호 배타 검사), AI 카탈로그(`catalog/ai-components.json`, egovframe-ai-rag 모듈 스캔 자동 생성 `npm run generate:ai-catalog`), `list_egovframe_components`에 AI 컴포넌트 노출, 오프라인 테스트(`npm run test:ai`) 추가.
+
 - **0.7.0** — `get_egovframe_guide`: 컴포넌트 id로 표준프레임워크 공식 가이드 문서(egovframe-docs)를 조회. 카탈로그에 문서 매핑 자동 생성(`--docs`, 지배적 패키지 참조 기준 45종) 추가. 한글명 큐레이션 12→27종.
 
 - **0.6.0** — 컴포넌트별 테이블 선별 DDL(M4): 카탈로그에 매퍼 기반 참조 테이블 자동 추출(48/68종), `database` 지정 시 통합 스크립트에서 해당 컴포넌트 구문만 추출해 `ddl|dml/<컴포넌트id>.sql` 생성(테이블 미상 컴포넌트는 통합본 폴백), 매니페스트에 컴포넌트별 스크립트 귀속(제거 시 함께 정리).

package/catalog/ai-components.json

@@ -0,0 +1,369 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repo": "eGovFramework/egovframe-ai-rag",
+    "branch": "main",
+    "surveyedAt": "2026-07-12"
+  },
+  "note": "add_ai_components용 카탈로그 — 조립 대상은 egovframe-boot-starter-parent 기반 Boot 프로젝트. 두 스택은 같은 패키지(com.example.chat)·UI 경로를 사용하므로 상호 배타(conflictsWith).",
+  "components": [
+    {
+      "id": "ai-rag-spring-ai",
+      "stack": "spring-ai",
+      "kind": "ai",
+      "name": "AI RAG 챗봇 (Spring AI + Redis Stack)",
+      "description": "Spring AI 기반 RAG 질의응답 — 문서 업로드(PDF·DOCX·HWP·HWPX·MD)→임베딩→Redis Stack 하이브리드 검색→Ollama LLM 응답, 채팅 UI 포함",
+      "modulePath": "spring-ai-rag-redis-stack",
+      "vectorStore": "Redis Stack",
+      "conflictsWith": [
+        "ai-rag-langchain4j"
+      ],
+      "requires": {
+        "java": "17",
+        "parent": "egovframe-boot-starter-parent:5.0.0"
+      },
+      "copyGroups": {
+        "source": {
+          "paths": [
+            "src/main/java/com/example/chat/"
+          ],
+          "files": 45
+        },
+        "config": {
+          "paths": [
+            "src/main/resources/application.yml -> src/main/resources/application-ai.yml",
+            "src/main/resources/log4j2-spring.xml -> src/main/resources/log4j2-ai.xml"
+          ],
+          "files": 2
+        },
+        "ui": {
+          "paths": [
+            "src/main/resources/templates/",
+            "src/main/resources/static/"
+          ],
+          "files": 3
+        },
+        "infra": {
+          "paths": [
+            "docker-compose.yml -> docker-compose.ai.yml",
+            "Dockerfile -> Dockerfile.ai",
+            "k8s/ -> k8s/ai/"
+          ],
+          "files": 6
+        },
+        "tests": {
+          "paths": [
+            "src/test/"
+          ],
+          "files": 15
+        }
+      },
+      "approxFiles": 56,
+      "mavenDependencies": [
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-actuator",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-client-chat"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-rag"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-starter-vector-store-redis"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-starter-model-ollama"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-advisors-vector-store"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-starter-model-transformers"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-pdf-document-reader"
+        },
+        {
+          "groupId": "org.springframework.ai",
+          "artifactId": "spring-ai-markdown-document-reader"
+        },
+        {
+          "groupId": "org.egovframe.rte",
+          "artifactId": "egovframe-rte-fdl-excel"
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-thymeleaf",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-web",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.egovframe.rte",
+          "artifactId": "egovframe-rte-ptl-mvc",
+          "exclusions": [
+            {
+              "groupId": "org.apache.commons",
+              "artifactId": "commons-lang3"
+            }
+          ]
+        },
+        {
+          "groupId": "kr.dogfoot",
+          "artifactId": "hwplib",
+          "version": "1.1.9"
+        },
+        {
+          "groupId": "org.projectlombok",
+          "artifactId": "lombok",
+          "optional": true
+        },
+        {
+          "groupId": "kr.dogfoot",
+          "artifactId": "hwpxlib",
+          "version": "1.0.8"
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-test",
+          "scope": "test"
+        }
+      ],
+      "mavenProperties": {},
+      "prerequisites": [
+        "ollama>=0.17.1",
+        "onnx-embedding-model",
+        "docker"
+      ]
+    },
+    {
+      "id": "ai-rag-langchain4j",
+      "stack": "langchain4j",
+      "kind": "ai",
+      "name": "AI RAG 챗봇 (LangChain4j + PGVector)",
+      "description": "LangChain4j 기반 RAG 질의응답 — 문서 업로드(PDF·DOCX·HWP·HWPX·MD)→임베딩→PostgreSQL(PGVector) 하이브리드 검색→Ollama LLM 응답, 채팅 UI 포함",
+      "modulePath": "langchain4j-ai-rag-postgre",
+      "vectorStore": "PostgreSQL (PGVector)",
+      "conflictsWith": [
+        "ai-rag-spring-ai"
+      ],
+      "requires": {
+        "java": "17",
+        "parent": "egovframe-boot-starter-parent:5.0.0"
+      },
+      "copyGroups": {
+        "source": {
+          "paths": [
+            "src/main/java/com/example/chat/"
+          ],
+          "files": 49
+        },
+        "config": {
+          "paths": [
+            "src/main/resources/application.yml -> src/main/resources/application-ai.yml",
+            "src/main/resources/log4j2-spring.xml -> src/main/resources/log4j2-ai.xml"
+          ],
+          "files": 2
+        },
+        "ui": {
+          "paths": [
+            "src/main/resources/templates/",
+            "src/main/resources/static/"
+          ],
+          "files": 3
+        },
+        "infra": {
+          "paths": [
+            "docker-compose.yml -> docker-compose.ai.yml",
+            "Dockerfile -> Dockerfile.ai",
+            "k8s/ -> k8s/ai/",
+            "init-scripts/ -> init-scripts/ai/"
+          ],
+          "files": 9
+        },
+        "tests": {
+          "paths": [
+            "src/test/"
+          ],
+          "files": 14
+        }
+      },
+      "approxFiles": 63,
+      "mavenDependencies": [
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-actuator",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "dev.langchain4j",
+          "artifactId": "langchain4j"
+        },
+        {
+          "groupId": "dev.langchain4j",
+          "artifactId": "langchain4j-ollama"
+        },
+        {
+          "groupId": "dev.langchain4j",
+          "artifactId": "langchain4j-pgvector"
+        },
+        {
+          "groupId": "dev.langchain4j",
+          "artifactId": "langchain4j-embeddings"
+        },
+        {
+          "groupId": "dev.langchain4j",
+          "artifactId": "langchain4j-document-parser-apache-pdfbox"
+        },
+        {
+          "groupId": "org.egovframe.rte",
+          "artifactId": "egovframe-rte-fdl-excel",
+          "exclusions": [
+            {
+              "groupId": "org.apache.commons",
+              "artifactId": "commons-lang3"
+            }
+          ]
+        },
+        {
+          "groupId": "dev.langchain4j",
+          "artifactId": "langchain4j-reactor"
+        },
+        {
+          "groupId": "com.h2database",
+          "artifactId": "h2",
+          "version": "2.2.224",
+          "scope": "test"
+        },
+        {
+          "groupId": "org.postgresql",
+          "artifactId": "postgresql",
+          "scope": "runtime"
+        },
+        {
+          "groupId": "org.testcontainers",
+          "artifactId": "postgresql",
+          "scope": "test"
+        },
+        {
+          "groupId": "org.testcontainers",
+          "artifactId": "junit-jupiter",
+          "scope": "test"
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-thymeleaf",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-web",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-webflux",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-data-jpa",
+          "exclusions": [
+            {
+              "groupId": "org.springframework.boot",
+              "artifactId": "spring-boot-starter-logging"
+            }
+          ]
+        },
+        {
+          "groupId": "org.egovframe.rte",
+          "artifactId": "egovframe-rte-ptl-mvc",
+          "exclusions": [
+            {
+              "groupId": "org.apache.commons",
+              "artifactId": "commons-lang3"
+            }
+          ]
+        },
+        {
+          "groupId": "commons-codec",
+          "artifactId": "commons-codec"
+        },
+        {
+          "groupId": "kr.dogfoot",
+          "artifactId": "hwplib",
+          "version": "1.1.9"
+        },
+        {
+          "groupId": "kr.dogfoot",
+          "artifactId": "hwpxlib",
+          "version": "1.0.5"
+        },
+        {
+          "groupId": "org.projectlombok",
+          "artifactId": "lombok",
+          "optional": true
+        },
+        {
+          "groupId": "org.springframework.boot",
+          "artifactId": "spring-boot-starter-test",
+          "scope": "test"
+        }
+      ],
+      "mavenProperties": {},
+      "prerequisites": [
+        "ollama>=0.17.1",
+        "onnx-embedding-model",
+        "docker"
+      ]
+    }
+  ]
+}

package/dist/index.js

@@ -506,6 +506,8 @@ export async function removeComponents(opts) {
                     fs.unlinkSync(target);
                 pruneEmptyDirs(path.dirname(target), projectDir);
             }
+            if (entry.pom)
+                stripAiPomAdditions(projectDir, id);
             delete manifest.components[id];
         }
         removed.push({ id, files: entry.files.length, sqlScripts: entry.sqlScripts.length });
@@ -533,6 +535,12 @@ export async function validateProject(opts) {
             if (missing.length > 0)
                 warnings.push(`컴포넌트 '${id}'의 파일 ${missing.length}개가 없습니다 (수동 삭제 또는 이동 가능성)`);
             components.push({ id, files: entry.files.length, missing: missing.length, missingSamples: missing.slice(0, 5) });
+            if (entry.pom) {
+                const pomPath = path.join(projectDir, "pom.xml");
+                const pomText = fs.existsSync(pomPath) ? fs.readFileSync(pomPath, "utf-8") : "";
+                if (!pomText.includes(`egovframe-scaffold-mcp:ai:${id}:deps:start`) && entry.pom.addedDeps.length > 0)
+                    warnings.push(`컴포넌트 '${id}'의 pom 삽입 마커가 없습니다 (수동 편집 가능성) — 의존성 ${entry.pom.addedDeps.length}건 확인 필요`);
+            }
         }
     }
     else {
@@ -584,10 +592,351 @@ export async function getGuide(componentId, docIndex = 0) {
     return { componentId, docs, selected: sel, content, truncated };
 }
 /* ------------------------------------------------------------------ */
+/* AI 컴포넌트 조립 (M1 미리보기 + M2 실조립) — 설계: docs/design-ai-components.md */
+/* 소스: eGovFramework/egovframe-ai-rag (Spring AI·LangChain4j RAG 샘플)   */
+/* ------------------------------------------------------------------ */
+export const AI_STACKS = ["spring-ai", "langchain4j"];
+const AI_CATALOG_URL = new URL("../catalog/ai-components.json", import.meta.url);
+/** AI 카탈로그 로드 + 무결성 검증 (id 중복, conflictsWith 대상 존재, stack 유일) */
+export function loadAiCatalog() {
+    const catalog = JSON.parse(fs.readFileSync(AI_CATALOG_URL, "utf-8"));
+    const ids = new Set();
+    const stacks = new Set();
+    for (const c of catalog.components) {
+        if (ids.has(c.id))
+            throw new Error(`AI 카탈로그 오류: 중복 id '${c.id}'`);
+        ids.add(c.id);
+        if (stacks.has(c.stack))
+            throw new Error(`AI 카탈로그 오류: 중복 stack '${c.stack}'`);
+        stacks.add(c.stack);
+    }
+    for (const c of catalog.components)
+        for (const x of c.conflictsWith)
+            if (!ids.has(x))
+                throw new Error(`AI 카탈로그 오류: '${c.id}'의 conflictsWith '${x}'가 카탈로그에 없습니다`);
+    return catalog;
+}
+/** pom 마커 주석 — 제거 시 이 구간만 걷어내 원복한다 */
+const AI_POM_MARKER = (id, kind, pos) => `<!-- egovframe-scaffold-mcp:ai:${id}:${kind}:${pos} -->`;
+const depCoord = (d) => `${d.groupId}:${d.artifactId}${d.version ? ":" + d.version : ""}${d.scope ? " (" + d.scope + ")" : ""}`;
+/** 공통 게이트·의존성 diff·복사 그룹 계산 (dryRun/실조립 공용) */
+function computeAiPlan(opts) {
+    if (!AI_STACKS.includes(opts.stack))
+        throw new Error(`stack은 ${AI_STACKS.join("|")} 중 하나여야 합니다: ${String(opts.stack)}`);
+    const catalog = loadAiCatalog();
+    const comp = catalog.components.find((c) => c.stack === opts.stack);
+    const projectDir = path.resolve(opts.projectDir);
+    // 매니페스트 게이트: 동일/배타 스택 설치 여부
+    const manifest = readManifest(projectDir);
+    if (manifest) {
+        if (manifest.components[comp.id])
+            throw new Error(`'${comp.id}'가 이미 설치되어 있습니다 (매니페스트 기준)`);
+        for (const x of comp.conflictsWith)
+            if (manifest.components[x])
+                throw new Error(`상호 배타 컴포넌트 '${x}'가 이미 설치되어 있습니다 — 두 AI 스택은 같은 패키지(com.example.chat)·UI 경로를 사용합니다. 먼저 remove_egovframe_components로 제거하세요`);
+    }
+    // 호환성 게이트: 부모 POM 좌표 확인 + 의존성/프로퍼티 diff
+    const warnings = [];
+    const pomPath = path.join(projectDir, "pom.xml");
+    const pomFound = fs.existsSync(pomPath);
+    let parentFound = null;
+    let parentOk = null;
+    const toAddDeps = [];
+    const alreadyPresent = [];
+    const toAddProps = {};
+    if (pomFound) {
+        const pom = fs.readFileSync(pomPath, "utf-8");
+        const pm = pom.match(/<parent>[\s\S]*?<\/parent>/);
+        if (pm) {
+            const a = pm[0].match(/<artifactId>([^<]*)<\/artifactId>/)?.[1]?.trim();
+            const v = pm[0].match(/<version>([^<]*)<\/version>/)?.[1]?.trim();
+            parentFound = a ? `${a}:${v ?? "?"}` : null;
+        }
+        const [reqA, reqV] = comp.requires.parent.split(":");
+        parentOk = parentFound !== null && parentFound.startsWith(`${reqA}:`);
+        if (!parentOk)
+            warnings.push(`부모 POM이 '${comp.requires.parent}'가 아닙니다(발견: ${parentFound ?? "없음"}) — Boot 기반 템플릿(simple-backend)에서 지원합니다`);
+        else if (parentFound !== comp.requires.parent)
+            warnings.push(`부모 POM 버전이 다릅니다(요구 ${reqV}, 발견 ${parentFound}) — BOM 관리 버전 차이를 확인하세요`);
+        for (const d of comp.mavenDependencies) {
+            if (pom.includes(`<artifactId>${d.artifactId}</artifactId>`))
+                alreadyPresent.push(depCoord(d));
+            else
+                toAddDeps.push(d);
+        }
+        for (const [k, v] of Object.entries(comp.mavenProperties))
+            if (!pom.includes(`<${k}>`))
+                toAddProps[k] = v;
+    }
+    else {
+        warnings.push("pom.xml이 없습니다 — Boot 백엔드 프로젝트 루트 경로인지 확인하세요");
+    }
+    // 복사 그룹: source·config 필수, ui/infra/tests는 옵션
+    const groups = ["source", "config"];
+    if (opts.includeUi !== false)
+        groups.push("ui");
+    if (opts.includeInfra !== false)
+        groups.push("infra");
+    if (opts.includeTests === true)
+        groups.push("tests");
+    return {
+        comp,
+        projectDir,
+        compatibility: { pomFound, required: comp.requires.parent, parentFound, parentOk, warnings },
+        toAddDeps,
+        alreadyPresent,
+        toAddProps,
+        groups,
+    };
+}
+/** AI 컴포넌트 조립 계획 — dryRun 미리보기 (네트워크 불필요) */
+export async function planAiComponents(opts) {
+    const p = computeAiPlan(opts);
+    const copyPlan = p.groups.map((g) => ({
+        group: g,
+        files: p.comp.copyGroups[g].files,
+        paths: p.comp.copyGroups[g].paths,
+    }));
+    return {
+        projectDir: p.projectDir,
+        component: { id: p.comp.id, name: p.comp.name, vectorStore: p.comp.vectorStore },
+        compatibility: p.compatibility,
+        dependencyChanges: { toAdd: p.toAddDeps.map(depCoord), alreadyPresent: p.alreadyPresent },
+        copyPlan,
+        totalFiles: copyPlan.reduce((n, g) => n + g.files, 0),
+        prerequisites: p.comp.prerequisites,
+        nextSteps: ["미리보기 모드입니다. 실제 조립하려면 dryRun 없이 다시 호출하세요."],
+        dryRun: true,
+    };
+}
+/** 프로세스 수명 동안 AI 샘플 zip을 1회만 내려받기 위한 캐시 */
+let aiZipCache = null;
+async function downloadAiZip(repo, branch) {
+    const key = `${repo}@${branch}`;
+    if (aiZipCache && aiZipCache.key === key)
+        return aiZipCache.zip;
+    const zipUrl = `https://codeload.github.com/${repo}/zip/${branch}`;
+    const res = await fetchWithTimeout(zipUrl, COMPONENTS_DOWNLOAD_TIMEOUT_MS);
+    if (!res.ok)
+        throw new Error(`AI 샘플 저장소 다운로드 실패 (${res.status}): ${zipUrl}`);
+    const zip = new AdmZip(Buffer.from(await res.arrayBuffer()));
+    aiZipCache = { key, zip };
+    return zip;
+}
+/** copyGroups 경로("src" 또는 "src -> dest")를 zip 상대경로 → 대상 상대경로 매핑으로 해석 */
+function mapAiEntry(relInModule, groupPaths) {
+    for (const spec of groupPaths) {
+        const [src, dest] = spec.split("->").map((s) => s.trim());
+        const target = dest ?? src;
+        if (src.endsWith("/")) {
+            if (relInModule.startsWith(src))
+                return target + relInModule.slice(src.length);
+        }
+        else if (relInModule === src) {
+            return target;
+        }
+    }
+    return null;
+}
+/** XML 의존성 블록 직렬화 (exclusions·scope·optional 보존) */
+function depToXml(d, indent = "        ") {
+    const i2 = indent + "    ";
+    const lines = [`${indent}<dependency>`, `${i2}<groupId>${d.groupId}</groupId>`, `${i2}<artifactId>${d.artifactId}</artifactId>`];
+    if (d.version)
+        lines.push(`${i2}<version>${d.version}</version>`);
+    if (d.scope)
+        lines.push(`${i2}<scope>${d.scope}</scope>`);
+    if (d.optional)
+        lines.push(`${i2}<optional>true</optional>`);
+    if (d.exclusions?.length) {
+        lines.push(`${i2}<exclusions>`);
+        for (const e of d.exclusions)
+            lines.push(`${i2}    <exclusion>`, `${i2}        <groupId>${e.groupId}</groupId>`, `${i2}        <artifactId>${e.artifactId}</artifactId>`, `${i2}    </exclusion>`);
+        lines.push(`${i2}</exclusions>`);
+    }
+    lines.push(`${indent}</dependency>`);
+    return lines.join("\n");
+}
+/** dependencyManagement 밖의 프로젝트 직속 </dependencies> 위치를 찾는다 */
+export function findProjectDependenciesClose(pom) {
+    const dmStart = pom.indexOf("<dependencyManagement>");
+    const dmEnd = pom.indexOf("</dependencyManagement>");
+    let idx = -1;
+    const re = /<\/dependencies>/g;
+    let m;
+    while ((m = re.exec(pom)) !== null) {
+        if (dmStart >= 0 && m.index > dmStart && m.index < dmEnd + 24)
+            continue; // dependencyManagement 내부
+        idx = m.index;
+        break;
+    }
+    return idx;
+}
+export const AI_POM_BACKUP = "pom.xml.bak-ai";
+/**
+ * AI 컴포넌트 실조립 (M2).
+ * - 파일 복사: 전체 사전 충돌 검사 후 하나라도 충돌하면 아무것도 쓰지 않고 거부 (원자적)
+ * - pom 병합: 누락 좌표만 마커 주석 구간으로 삽입(기존 항목 불변), 병합 전 pom.xml.bak-ai 백업
+ * - 설정 프로필화: application.yml → application-ai.yml 복사 (기존 설정 파일은 수정하지 않음)
+ * - 매니페스트 기록: remove_egovframe_components가 파일과 pom 삽입분을 함께 정리
+ */
+export async function addAiComponents(opts) {
+    if (opts.dryRun === true) {
+        const plan = await planAiComponents(opts);
+        return { ...plan, copiedFiles: 0, pomChanged: false, pomBackup: null };
+    }
+    const p = computeAiPlan(opts);
+    const { comp, projectDir } = p;
+    if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory())
+        throw new Error(`대상 프로젝트 디렉터리가 없습니다: ${projectDir} — 먼저 create_egovframe_project로 생성하세요`);
+    if (!p.compatibility.pomFound)
+        throw new Error(`pom.xml이 없습니다: ${projectDir} — Boot 백엔드 프로젝트 루트에서 실행하세요`);
+    if (p.compatibility.parentOk === false)
+        throw new Error(`부모 POM 불일치: 요구 '${comp.requires.parent}', 발견 '${p.compatibility.parentFound ?? "없음"}' — egovframe-boot-starter-parent 기반 Boot 프로젝트만 지원합니다 (dryRun으로 진단 가능)`);
+    // ---- 다운로드 & 파일 계획 ----
+    const catalog = loadAiCatalog();
+    const zip = await downloadAiZip(catalog.source.repo, opts.ref ?? catalog.source.branch);
+    const entries = zip.getEntries().filter((e) => !e.isDirectory);
+    const rootPrefix = entries[0].entryName.split("/")[0] + "/";
+    const modPrefix = rootPrefix + comp.modulePath + "/";
+    const plan = [];
+    for (const e of entries) {
+        if (!e.entryName.startsWith(modPrefix))
+            continue;
+        const relInModule = e.entryName.slice(modPrefix.length);
+        for (const g of p.groups) {
+            const destRel = mapAiEntry(relInModule, comp.copyGroups[g].paths);
+            if (destRel !== null) {
+                plan.push({ entry: e, destRel, group: g });
+                break;
+            }
+        }
+    }
+    if (plan.length === 0)
+        throw new Error(`조립할 파일을 찾지 못했습니다 — 카탈로그(${catalog.source.surveyedAt})와 저장소 구조가 달라졌을 수 있습니다. npm run generate:ai-catalog로 재생성하세요`);
+    // ---- 전체 사전 충돌 검사 (원자적 거부) ----
+    const conflicts = plan.filter((f) => fs.existsSync(path.join(projectDir, f.destRel))).map((f) => f.destRel);
+    if (conflicts.length > 0)
+        throw new Error(`기존 파일과 충돌하여 조립을 거부합니다 (${conflicts.length}개): ${conflicts.slice(0, 10).join(", ")}${conflicts.length > 10 ? " 외" : ""} — 아무 파일도 쓰지 않았습니다`);
+    const pomPath = path.join(projectDir, "pom.xml");
+    const backupPath = path.join(projectDir, AI_POM_BACKUP);
+    if ((p.toAddDeps.length > 0 || Object.keys(p.toAddProps).length > 0) && fs.existsSync(backupPath))
+        throw new Error(`pom 백업(${AI_POM_BACKUP})이 이미 있습니다 — 이전 조립 잔여물을 정리한 뒤 다시 시도하세요`);
+    // ---- 파일 복사 ----
+    for (const f of plan) {
+        const target = path.join(projectDir, f.destRel);
+        if (!target.startsWith(projectDir + path.sep))
+            throw new Error(`경로 이탈 감지: ${f.destRel}`);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, f.entry.getData());
+    }
+    // ---- pom 병합 (마커 구간 삽입) ----
+    let pomChanged = false;
+    if (p.toAddDeps.length > 0 || Object.keys(p.toAddProps).length > 0) {
+        let pom = fs.readFileSync(pomPath, "utf-8");
+        fs.writeFileSync(backupPath, pom);
+        if (p.toAddDeps.length > 0) {
+            const close = findProjectDependenciesClose(pom);
+            if (close < 0)
+                throw new Error("pom.xml에서 <dependencies> 블록을 찾지 못했습니다");
+            const block = [
+                `        ${AI_POM_MARKER(comp.id, "deps", "start")}`,
+                ...p.toAddDeps.map((d) => depToXml(d)),
+                `        ${AI_POM_MARKER(comp.id, "deps", "end")}`,
+                "    ",
+            ].join("\n");
+            pom = pom.slice(0, close) + block + pom.slice(close);
+        }
+        if (Object.keys(p.toAddProps).length > 0) {
+            const pClose = pom.indexOf("</properties>");
+            if (pClose < 0)
+                throw new Error("pom.xml에서 <properties> 블록을 찾지 못했습니다");
+            const block = [
+                `        ${AI_POM_MARKER(comp.id, "props", "start")}`,
+                ...Object.entries(p.toAddProps).map(([k, v]) => `        <${k}>${v}</${k}>`),
+                `        ${AI_POM_MARKER(comp.id, "props", "end")}`,
+                "    ",
+            ].join("\n");
+            pom = pom.slice(0, pClose) + block + pom.slice(pClose);
+        }
+        fs.writeFileSync(pomPath, pom);
+        pomChanged = true;
+    }
+    // ---- 매니페스트 기록 ----
+    const manifest = readManifest(projectDir) ?? {
+        schemaVersion: 1,
+        source: { repo: catalog.source.repo, branch: catalog.source.branch },
+        components: {},
+    };
+    manifest.components[comp.id] = {
+        installedAt: new Date().toISOString(),
+        files: plan.map((f) => f.destRel),
+        sqlScripts: [],
+        pom: pomChanged
+            ? { backup: AI_POM_BACKUP, addedDeps: p.toAddDeps.map((d) => d.artifactId), addedProps: Object.keys(p.toAddProps) }
+            : undefined,
+    };
+    writeManifest(projectDir, manifest);
+    const copyPlan = p.groups.map((g) => ({
+        group: g,
+        files: plan.filter((f) => f.group === g).length,
+        paths: comp.copyGroups[g].paths,
+    }));
+    return {
+        projectDir,
+        component: { id: comp.id, name: comp.name, vectorStore: comp.vectorStore },
+        compatibility: p.compatibility,
+        dependencyChanges: { toAdd: p.toAddDeps.map(depCoord), alreadyPresent: p.alreadyPresent },
+        copyPlan,
+        totalFiles: plan.length,
+        copiedFiles: plan.length,
+        pomChanged,
+        pomBackup: pomChanged ? AI_POM_BACKUP : null,
+        prerequisites: comp.prerequisites,
+        nextSteps: [
+            "Ollama(>=0.17.1) 설치 및 LLM 모델 준비 (폐쇄망 절차는 egovframe-ai-rag README 참조)",
+            "ONNX 임베딩 모델 익스포트·배치",
+            `docker compose -f docker-compose.ai.yml up -d 로 벡터 저장소(${comp.vectorStore}) 기동`,
+            "spring.profiles.active=ai 로 애플리케이션 실행 (application-ai.yml 사용)",
+            "브라우저에서 채팅 UI 접속 (경로·포트는 application-ai.yml 참조)",
+        ],
+        dryRun: false,
+    };
+}
+/** AI 컴포넌트의 pom 삽입분(마커 구간)을 걷어낸다 — remove 시 호출 */
+export function stripAiPomAdditions(projectDir, componentId) {
+    const pomPath = path.join(projectDir, "pom.xml");
+    if (!fs.existsSync(pomPath))
+        return false;
+    let pom = fs.readFileSync(pomPath, "utf-8");
+    let changed = false;
+    for (const kind of ["deps", "props"]) {
+        const start = pom.indexOf(AI_POM_MARKER(componentId, kind, "start"));
+        const endMark = AI_POM_MARKER(componentId, kind, "end");
+        const end = pom.indexOf(endMark);
+        if (start >= 0 && end > start) {
+            // 마커 라인 앞 들여쓰기부터 end 마커 라인 끝(개행 포함)까지 제거
+            const lineStart = pom.lastIndexOf("\n", start) + 1;
+            let lineEnd = end + endMark.length;
+            while (lineEnd < pom.length && pom[lineEnd] !== "\n")
+                lineEnd++;
+            lineEnd++; // 개행 포함
+            pom = pom.slice(0, lineStart) + pom.slice(lineEnd);
+            changed = true;
+        }
+    }
+    if (changed)
+        fs.writeFileSync(pomPath, pom);
+    const backup = path.join(projectDir, AI_POM_BACKUP);
+    if (fs.existsSync(backup))
+        fs.unlinkSync(backup);
+    return changed;
+}
+/* ------------------------------------------------------------------ */
 /* MCP 서버                                                             */
 /* ------------------------------------------------------------------ */
 export function buildServer() {
-    const server = new McpServer({ name: "egovframe-scaffold-mcp", version: "0.7.0" });
+    const server = new McpServer({ name: "egovframe-scaffold-mcp", version: "0.9.0" });
     server.tool("list_egovframe_templates", "사용 가능한 전자정부 표준프레임워크 프로젝트 템플릿 목록을 반환합니다.", {}, async () => ({
         content: [
             {
@@ -625,6 +974,17 @@ export function buildServer() {
     });
     server.tool("list_egovframe_components", "선택 설치를 지원하는 공통컴포넌트 카탈로그를 반환합니다 (저장소 스캔으로 자동 생성, scripts/generate-catalog.mjs).", {}, async () => {
         const catalog = loadCatalog();
+        let ai;
+        try {
+            const aiCat = loadAiCatalog();
+            ai = {
+                source: aiCat.source,
+                components: aiCat.components.map((c) => ({
+                    id: c.id, stack: c.stack, name: c.name, description: c.description, approxFiles: c.approxFiles,
+                })),
+            };
+        }
+        catch { /* AI 카탈로그가 없어도 기본 목록은 동작 */ }
         return {
             content: [
                 {
@@ -632,6 +992,7 @@ export function buildServer() {
                     text: JSON.stringify({
                         source: catalog.source,
                         sqlNote: catalog.sqlNote,
+                        aiComponents: ai,
                         components: catalog.components.map((c) => ({
                             id: c.id, name: c.name, category: c.category,
                             description: c.description, dependsOn: c.dependsOn, approxFiles: c.approxFiles,
@@ -726,6 +1087,42 @@ export function buildServer() {
         ].filter((l, i) => l !== "" || i >= 4).join("\n");
         return { content: [{ type: "text", text: head + r.content }] };
     });
+    server.tool("add_ai_components", "공식 egovframe-ai-rag 샘플 기반 AI RAG 챗봇(문서 업로드→임베딩→하이브리드 검색→LLM 응답)을 기존 Boot 프로젝트에 조립합니다. " +
+        "소스·설정(application-ai.yml 프로필)·UI·인프라를 복사하고 pom에 누락 의존성만 마커 구간으로 삽입합니다(백업 생성, 제거 시 원복). " +
+        "기존 파일과 충돌하면 아무것도 쓰지 않고 거부합니다. dryRun=true로 먼저 미리볼 수 있습니다.", {
+        projectDir: z.string().describe("대상 프로젝트 디렉터리(절대경로 권장). egovframe-boot-starter-parent 기반 Boot 프로젝트"),
+        stack: z.enum(AI_STACKS).describe("AI 스택: spring-ai(Redis Stack) | langchain4j(PGVector). 상호 배타"),
+        includeInfra: z.boolean().default(true).describe("docker-compose.ai.yml·Dockerfile.ai·k8s/ai 복사"),
+        includeUi: z.boolean().default(true).describe("채팅 UI(chat.html·static) 복사"),
+        includeTests: z.boolean().default(false).describe("샘플 테스트 복사"),
+        ref: z.string().optional().describe("egovframe-ai-rag 브랜치/태그 (기본: 카탈로그 기준 브랜치)"),
+        dryRun: z.boolean().default(false).describe("true면 복사·병합 없이 계획만 미리보기(네트워크 불필요)"),
+    }, async (args) => {
+        const r = await addAiComponents(args);
+        const c = r.compatibility;
+        const head = r.dryRun
+            ? `🔍 AI 컴포넌트 조립 미리보기(dryRun): ${r.projectDir}`
+            : `✅ AI 컴포넌트 조립 완료: ${r.projectDir}`;
+        const text = [
+            head,
+            `- 컴포넌트: ${r.component.id} — ${r.component.name}`,
+            `- 호환성: 부모 POM ${c.parentOk === true ? "일치" : c.parentOk === false ? "불일치" : "미확인"}` +
+                ` (요구 ${c.required}${c.parentFound ? ", 발견 " + c.parentFound : ""})`,
+            ...(c.warnings.length ? c.warnings.map((w) => `  ! ${w}`) : []),
+            `- pom 의존성: ${r.dryRun ? "추가 예정" : "추가됨"} ${r.dependencyChanges.toAdd.length}건` +
+                (r.dependencyChanges.alreadyPresent.length ? `, 이미 존재 ${r.dependencyChanges.alreadyPresent.length}건` : "") +
+                (r.pomBackup ? ` (백업: ${r.pomBackup})` : ""),
+            ...r.dependencyChanges.toAdd.slice(0, 8).map((d) => `  + ${d}`),
+            ...(r.dependencyChanges.toAdd.length > 8 ? [`  + … 외 ${r.dependencyChanges.toAdd.length - 8}건`] : []),
+            `- ${r.dryRun ? "복사 계획" : "복사 완료"} (총 ${r.totalFiles}개 파일):`,
+            ...r.copyPlan.map((g) => `  · ${g.group}: ${g.files}개`),
+            `- 실행 전제: ${r.prerequisites.join(", ")}`,
+            ``,
+            `다음 단계:`,
+            ...r.nextSteps.map((s, i) => `  ${i + 1}. ${s}`),
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+    });
     return server;
 }
 const isMain = process.argv[1] && import.meta.url.endsWith(path.basename(process.argv[1]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "egovframe-scaffold-mcp",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "전자정부 표준프레임워크(eGovFrame) 프로젝트 스캐폴딩·공통컴포넌트 조립 MCP 서버 — create/search/add/validate/remove",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,7 +15,10 @@
     "test:catalog": "node test/catalog.mjs",
     "test:components": "node test/components.mjs",
     "generate:catalog": "node scripts/generate-catalog.mjs",
-    "prepublishOnly": "npm run build && npm run test:catalog"
+    "prepublishOnly": "npm run build && npm run test:catalog && npm run test:ai",
+    "test:ai": "node test/ai.mjs",
+    "generate:ai-catalog": "node scripts/generate-ai-catalog.mjs",
+    "test:ai-assembly": "node test/ai-assembly.mjs"
   },
   "engines": {
     "node": ">=18"