docuking-mcp 2.9.3 → 2.11.0

package/README.md

@@ -2,22 +2,42 @@
 
 AI가 문서를 Push/Pull 할 수 있게 해주는 MCP 서버
 
-## 설치
+## 설치 (글로벌 설치 권장)
 
 ```bash
-npx docuking-mcp
+# 1. 글로벌 설치
+npm install -g docuking-mcp
+
+# 2. MCP 등록 (Claude Code)
+claude mcp add docuking -s user -- docuking-mcp
+```
+
+### 업데이트
+
+```bash
+npm update -g docuking-mcp
 ```
 
+> **참고**: MCP는 새 버전이 있으면 첫 도구 호출 시 자동으로 알려줍니다.
+
 ## MCP 설정
 
-### Claude Code
+### Claude Code (CLI로 등록)
+
+```bash
+claude mcp add docuking -s user -- docuking-mcp
+```
+
+### Claude Code (JSON으로 등록)
+
+`~/.claude.json`에 추가:
 
 ```json
 {
   "mcpServers": {
     "docuking": {
-      "command": "npx",
-      "args": ["-y", "docuking-mcp"]
+      "command": "docuking-mcp",
+      "args": []
     }
   }
 }
@@ -31,8 +51,23 @@ npx docuking-mcp
 {
   "mcpServers": {
     "docuking": {
-      "command": "npx",
-      "args": ["-y", "docuking-mcp"]
+      "command": "docuking-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+`~/.gemini/antigravity/mcp_config.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "docuking": {
+      "command": "docuking-mcp",
+      "args": []
     }
   }
 }
@@ -50,28 +85,35 @@ npx docuking-mcp
 | docuking_log | 커밋 히스토리 조회 |
 | docuking_diff | 버전 간 차이 비교 |
 | docuking_rollback | 특정 커밋으로 롤백 |
-| docuking_talk | AI 대화록 저장 (zz_ai_Talk/) |
-| docuking_plan | 작업 계획 관리 (zzz_ai_Plan/) |
+| docuking_talk | AI 대화록 저장 (zz_ai_1_Talk/) |
+| docuking_plan | 작업 계획 관리 (zz_ai_3_Plan/) |
 | docuking_done | 작업 완료 처리 |
-| docuking_todo | 킹투두 관리 (zz_ai_Todo/) |
+| docuking_todo | 킹투두 관리 (zz_ai_2_Todo/) |
+| docuking_urgent | 긴급 보고 (xx_Urgent/) |
+| docuking_delete | 서버 파일 삭제 |
+| docuking_validate | 정책 준수 검증 |
 
 ## 폴더 구조
 
 ```
 프로젝트/
-├── yy_All_Docu/              ← 동기화 대상 (Push/Pull)
-├── yy_Coworker_{이름}/       ← 협업자 작업 폴더 (동기화 대상)
-│   ├── zz_ai_1_Talk/         ← 협업자의 AI 대화록 (동기화 대상)
-│   ├── zz_ai_2_Todo/         ← 협업자의 AI 투두 (동기화 대상)
-│   └── zz_ai_3_Plan/         ← 협업자의 AI 플랜 (동기화 대상)
-├── zz_ai_1_Talk/             ← 오너의 AI 대화록 (동기화 대상)
-├── zz_ai_2_Todo/             ← 오너의 AI 투두 (동기화 대상)
-└── zz_ai_3_Plan/             ← 오너의 AI 플랜 (동기화 대상)
+├── xx_Infra_Config/         ← 시스템 설정 (동기화 대상)
+├── xx_Policy/               ← 정책 문서 (동기화 대상, 킹캐스트)
+├── xx_Urgent/               ← 긴급 보고 (동기화 대상)
+├── yy_All_Docu/             ← 문서 허브 (동기화 대상)
+├── yy_Coworker_{이름}/      ← 협업자 작업 폴더 (동기화 대상)
+│   ├── zz_ai_1_Talk/        ← 협업자의 AI 대화록
+│   ├── zz_ai_2_Todo/        ← 협업자의 AI 투두
+│   └── zz_ai_3_Plan/        ← 협업자의 AI 플랜
+├── zz_ai_1_Talk/            ← 오너의 AI 대화록 (동기화 대상)
+├── zz_ai_2_Todo/            ← 오너의 AI 투두 (동기화 대상)
+└── zz_ai_3_Plan/            ← 오너의 AI 플랜 (동기화 대상)
 ```
 
 **접두사 규칙:**
-- `yy_*`: 사람용 폴더 (동기화 대상)
-- `zz_ai_*`: AI용 폴더 (동기화 대상)
+- `xx_*`: 시스템/인프라 폴더
+- `yy_*`: 사람용 폴더
+- `zz_ai_*`: AI용 폴더
 
 ## 웹사이트
 

package/handlers/sync.js

@@ -540,9 +540,10 @@ docuking_init을 먼저 실행하세요.`,
     console.error('[DocuKing] Sync 시작 알림 실패:', e.message);
   }
 
-  // 서버에서 파일 해시 조회 (Git 스타일 동기화용)
+  // 서버에서 파일 해시 및 메타 정보 조회 (Git 스타일 동기화용)
   let serverPathToHash = {};
   let serverHashToPath = {};
+  let serverPathToMeta = {}; // source, type, deletedAt 정보 포함
   let serverAllPaths = [];
   try {
     const hashResponse = await fetch(
@@ -557,6 +558,7 @@ docuking_init을 먼저 실행하세요.`,
       const hashData = await hashResponse.json();
       serverPathToHash = hashData.pathToHash || {};
       serverHashToPath = hashData.hashToPath || {};
+      serverPathToMeta = hashData.pathToMeta || {};
       serverAllPaths = hashData.allPaths || [];
     }
   } catch (e) {
@@ -734,24 +736,48 @@ docuking_init을 먼저 실행하세요.`,
     }
   }
 
+  // ========================================
   // 4. 서버에만 있고 로컬에 없는 파일 soft-delete (deleted_at 기반)
+  // ========================================
   // 단, 협업자 폴더(yy_Coworker_*)는 삭제하지 않음 (오너가 협업자 파일을 삭제하면 안됨)
-  // 기존 hard delete(delete-batch) → soft delete(soft-delete)로 변경
-  // 3일 후 크론잡에서 hard delete 수행
+  // source: 'web' 파일은 MCP에서 삭제 시도하지 않음 (클라이언트에서 필터링)
   // 중요: localPathsBeforePull 사용 (Pull 전에 수집한 목록)
   //       processedLocalPaths는 Pull로 내려받은 파일도 포함하므로 사용 금지
   let deleted = 0;
   const deletedFilePaths = [];
   let protectedFiles = []; // source: 'web' 파일 (보호됨)
+  const webProtectedPaths = []; // MCP에서 미리 필터링한 웹 파일
+
   if (serverAllPaths.length > 0 && !isCoworker) {
-    // 코워커가 아닌 경우에만 삭제 수행 (오너 전용)
+    // 오너만 삭제 수행
     // yy_Coworker_*로 시작하는 경로는 삭제 대상에서 제외
     // localPathsBeforePull: Pull 전에 수집한 로컬 파일 목록 (좀비 파일 방지)
-    const pathsToDelete = serverAllPaths.filter(p =>
-      !localPathsBeforePull.has(p) && !p.startsWith('yy_Coworker_')
-    );
+    //
+    // ★ 핵심: source: 'web' 파일은 삭제 대상에서 미리 제외!
+    // 이렇게 하면 웹에서 생성한 파일이 절대 삭제되지 않음
+    const pathsToDelete = serverAllPaths.filter(p => {
+      // 1. 로컬에 있으면 제외 (삭제 대상 아님)
+      if (localPathsBeforePull.has(p)) return false;
+
+      // 2. 협업자 폴더는 제외
+      if (p.startsWith('yy_Coworker_')) return false;
+
+      // 3. source: 'web' 파일은 제외 (웹에서 생성된 파일 보호)
+      const meta = serverPathToMeta[p];
+      if (meta && meta.source === 'web') {
+        webProtectedPaths.push(p);
+        return false;
+      }
 
-    console.error(`[DocuKing] soft-delete 대상: ${pathsToDelete.length}개 (서버에만 있고 Pull 전 로컬에 없던 파일)`);
+      return true;
+    });
+
+    // 웹 보호 파일 로그
+    if (webProtectedPaths.length > 0) {
+      console.error(`[DocuKing] source:web 파일 ${webProtectedPaths.length}개 삭제에서 제외:`, webProtectedPaths.slice(0, 5));
+    }
+
+    console.error(`[DocuKing] soft-delete 대상: ${pathsToDelete.length}개 (서버에만 있고 Pull 전 로컬에 없던 파일, source:local만)`);
 
     if (pathsToDelete.length > 0) {
       try {
@@ -774,15 +800,18 @@ docuking_init을 먼저 실행하세요.`,
           deletedFilePaths.push(...(deleteResult.deletedPaths || []));
           protectedFiles = deleteResult.protected || [];
 
-          // 보호된 파일이 있으면 로그 출력
+          // 보호된 파일이 있으면 로그 출력 (Backend에서 추가로 보호한 파일)
           if (protectedFiles.length > 0) {
-            console.error(`[DocuKing] 보호된 파일 ${protectedFiles.length}개 (source: web):`, protectedFiles.slice(0, 5));
+            console.error(`[DocuKing] Backend에서 추가 보호된 파일 ${protectedFiles.length}개:`, protectedFiles.slice(0, 5));
           }
         }
       } catch (e) {
         console.error('[DocuKing] 파일 soft-delete 실패:', e.message);
       }
     }
+
+    // MCP에서 미리 제외한 웹 파일도 보호 목록에 추가 (결과 표시용)
+    protectedFiles = [...protectedFiles, ...webProtectedPaths];
   }
 
   // 5. 빈 폴더 생성
@@ -1018,54 +1047,79 @@ export async function handlePullInternal(args) {
     fs.mkdirSync(mainFolderPath, { recursive: true });
   }
 
-  // 파일 목록 조회
-  let files = [];
-  let deletedFiles = []; // 삭제된 파일 목록 (deleted_at 기반)
+  // ========================================
+  // 서버 메타정보 조회 (pathToMeta: source, type, deletedAt 포함)
+  // ========================================
+  let serverPathToHash = {};
+  let serverHashToPath = {};
+  let serverPathToMeta = {};
+  let serverAllPaths = [];
+  let deletedFiles = [];
 
   try {
-    const response = await fetch(
-      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+    const hashResponse = await fetch(
+      `${API_ENDPOINT}/files/hashes-for-sync?projectId=${projectId}`,
       {
         headers: {
           'Authorization': `Bearer ${apiKey}`,
         },
       }
     );
-
-    if (!response.ok) {
-      throw new Error(await response.text());
+    if (hashResponse.ok) {
+      const hashData = await hashResponse.json();
+      serverPathToHash = hashData.pathToHash || {};
+      serverHashToPath = hashData.hashToPath || {};
+      serverPathToMeta = hashData.pathToMeta || {};
+      serverAllPaths = hashData.allPaths || [];
+      deletedFiles = hashData.deletedFiles || [];
     }
-
-    const data = await response.json();
-    files = flattenTree(data.tree || []);
   } catch (e) {
-    throw new Error(`파일 목록 조회 실패 - ${e.message}`);
+    console.error('[DocuKing] 서버 메타정보 조회 실패:', e.message);
   }
 
-  // 서버에서 삭제된 파일 목록 조회 (deleted_at 기반 동기화)
+  // 파일 트리 조회 (폴더 포함)
+  let files = [];
   try {
-    const hashResponse = await fetch(
-      `${API_ENDPOINT}/files/hashes-for-sync?projectId=${projectId}`,
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
       {
         headers: {
           'Authorization': `Bearer ${apiKey}`,
         },
       }
     );
-    if (hashResponse.ok) {
-      const hashData = await hashResponse.json();
-      deletedFiles = hashData.deletedFiles || [];
+
+    if (!response.ok) {
+      throw new Error(await response.text());
     }
+
+    const data = await response.json();
+    files = flattenTree(data.tree || [], '', true); // 폴더 포함
   } catch (e) {
-    console.error('[DocuKing] 삭제 파일 목록 조회 실패:', e.message);
+    throw new Error(`파일 목록 조회 실패 - ${e.message}`);
   }
 
   if (filePath) {
     files = files.filter(f => f.path === filePath || f.path.startsWith(filePath + '/'));
   }
 
-  if (files.length === 0) {
-    // 빈 파일은 에러가 아님 - 정상 결과 반환
+  // ========================================
+  // 완전판 Pull 로직
+  // 1. 폴더 먼저 정렬 (상위 폴더 → 하위 폴더)
+  // 2. 파일 다운로드 (source:web 파일도 Pull)
+  // 3. mark-as-pulled 호출 (source: web → local 변경)
+  // ========================================
+
+  // 폴더를 먼저 정렬 (상위 폴더부터 생성해야 함)
+  const sortedFiles = [...files].sort((a, b) => {
+    // 폴더 먼저
+    if (a.type === 'folder' && b.type !== 'folder') return -1;
+    if (a.type !== 'folder' && b.type === 'folder') return 1;
+    // 경로 깊이 순 (상위 먼저)
+    return a.path.split('/').length - b.path.split('/').length;
+  });
+
+  if (sortedFiles.length === 0 && deletedFiles.length === 0) {
     return {
       text: 'Pull할 파일이 없습니다.',
       total: 0,
@@ -1076,20 +1130,64 @@ export async function handlePullInternal(args) {
     };
   }
 
-  // 파일 다운로드
   const results = [];
-  const total = files.length;
+  const total = sortedFiles.length;
   let current = 0;
   let downloaded = 0;   // 새로 다운로드
   let updated = 0;      // 업데이트 (변경됨)
   let skipped = 0;      // 스킵 (변경 없음)
   let failed = 0;       // 실패
+  let foldersCreated = 0; // 생성된 폴더
 
-  for (const file of files) {
+  // Pull 후 mark-as-pulled할 파일 목록 (source: web 파일들)
+  const filesToMarkAsPulled = [];
+
+  for (const file of sortedFiles) {
     current++;
     const progress = `${current}/${total}`;
 
+    // 서버 메타 정보 조회
+    const serverMeta = serverPathToMeta[file.path];
+
+    // 서버 경로에 따라 로컬 저장 위치 결정
+    let fullPath;
+    if (file.path.startsWith('xx_') ||
+        file.path.startsWith('yy_All_Docu/') ||
+        file.path.startsWith('yy_All_Docu') ||
+        file.path.startsWith('yy_Coworker_') ||
+        file.path.startsWith('zz_ai_')) {
+      fullPath = path.join(localPath, file.path);
+    } else {
+      fullPath = path.join(mainFolderPath, file.path);
+    }
+
     try {
+      // ========================================
+      // 폴더 처리 (type === 'folder')
+      // ========================================
+      if (file.type === 'folder') {
+        if (fs.existsSync(fullPath)) {
+          // 이미 있음 → 스킵
+          results.push({ type: 'skip', path: file.path, itemType: 'folder' });
+          skipped++;
+        } else {
+          // 폴더 생성
+          fs.mkdirSync(fullPath, { recursive: true });
+          results.push({ type: 'download', path: file.path, itemType: 'folder' });
+          foldersCreated++;
+          downloaded++;
+
+          // source: 'web' 폴더면 mark-as-pulled 대상
+          if (serverMeta && serverMeta.source === 'web') {
+            filesToMarkAsPulled.push(file.path);
+          }
+        }
+        continue;
+      }
+
+      // ========================================
+      // 파일 처리 (type === 'file')
+      // ========================================
       const response = await fetch(
         `${API_ENDPOINT}/files?projectId=${projectId}&path=${encodeURIComponent(file.path)}`,
         {
@@ -1107,25 +1205,6 @@ export async function handlePullInternal(args) {
 
       const data = await response.json();
 
-      // 서버 경로에 따라 로컬 저장 위치 결정
-      // 프로젝트 루트 기준 절대경로 그대로 사용
-      // - xx_Infra_Config/xxx → xx_Infra_Config/xxx (시스템/인프라)
-      // - xx_Policy/xxx → xx_Policy/xxx (정책)
-      // - yy_All_Docu/xxx → yy_All_Docu/xxx (오너 문서)
-      // - yy_Coworker_xxx/yyy → yy_Coworker_xxx/yyy (협업자 폴더)
-      // - zz_ai_xxx/yyy → zz_ai_xxx/yyy (AI 폴더)
-      let fullPath;
-      if (file.path.startsWith('xx_') ||
-          file.path.startsWith('yy_All_Docu/') ||
-          file.path.startsWith('yy_Coworker_') ||
-          file.path.startsWith('zz_ai_')) {
-        // 서버 경로 그대로 로컬에 저장
-        fullPath = path.join(localPath, file.path);
-      } else {
-        // 기타 (구버전 호환): yy_All_Docu/ 안에 저장
-        fullPath = path.join(mainFolderPath, file.path);
-      }
-
       // 인코딩에 따라 저장
       const content = data.file?.content || data.content || '';
       const encoding = data.file?.encoding || data.encoding || 'utf-8';
@@ -1145,6 +1224,13 @@ export async function handlePullInternal(args) {
 
       if (localExists) {
         try {
+          const localStat = fs.statSync(fullPath);
+          if (localStat.isDirectory()) {
+            // 로컬에 같은 이름의 폴더가 있으면 건너뜀
+            results.push({ type: 'skip', path: file.path, error: '같은 이름의 폴더 존재' });
+            skipped++;
+            continue;
+          }
           const localBuffer = fs.readFileSync(fullPath);
           localHash = crypto.createHash('sha256').update(localBuffer).digest('hex');
         } catch (e) {
@@ -1171,20 +1257,49 @@ export async function handlePullInternal(args) {
       }
 
       if (localExists) {
-        // 기존 파일 업데이트
         results.push({ type: 'update', path: file.path });
         updated++;
       } else {
-        // 새로 다운로드
         results.push({ type: 'download', path: file.path });
         downloaded++;
       }
+
+      // source: 'web' 파일이면 mark-as-pulled 대상
+      if (serverMeta && serverMeta.source === 'web') {
+        filesToMarkAsPulled.push(file.path);
+      }
     } catch (e) {
       results.push({ type: 'fail', path: file.path, error: e.message });
       failed++;
     }
   }
 
+  // ========================================
+  // mark-as-pulled 호출 (source: 'web' → 'local' 변경)
+  // Pull된 웹 파일/폴더는 이제 로컬이 관리권한을 가짐
+  // ========================================
+  if (filesToMarkAsPulled.length > 0) {
+    try {
+      const markResponse = await fetch(`${API_ENDPOINT}/files/mark-as-pulled`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          projectId,
+          paths: filesToMarkAsPulled,
+        }),
+      });
+
+      if (markResponse.ok) {
+        console.error(`[DocuKing] mark-as-pulled 완료: ${filesToMarkAsPulled.length}개`);
+      }
+    } catch (e) {
+      console.error('[DocuKing] mark-as-pulled 실패:', e.message);
+    }
+  }
+
   // 상세 결과 구성 (Push 스타일)
   let resultText = `✓ Pull 완료!
 

package/index.js

@@ -62,11 +62,17 @@ import {
 
 import { handleValidate } from './handlers/validate.js';
 
-// MCP 서버 생성
+// 버전 체크 모듈
+import { checkForUpdates, getVersionWarningMessage, getCurrentVersion } from './lib/version-check.js';
+
+// 세션당 1회 알림 플래그
+let versionWarningShown = false;
+
+// MCP 서버 생성 (package.json에서 버전 읽기)
 const server = new Server(
   {
     name: 'docuking-mcp',
-    version: '1.0.0',
+    version: getCurrentVersion(),
   },
   {
     capabilities: {
@@ -628,29 +634,55 @@ DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하
 
 작동 방식: 로컬 yy_All_Docu/ → Push → 킹폴더 → 캔버스에서 시각화
 
-## MCP 설정과 프로젝트 연결의 차이 (매우 중요!)
-
-### MCP 설정 (전역, 한 번만)
-- **목적**: MCP 서버를 AI 도구(Cursor, Claude Code 등)에 등록
-- **설정 파일 위치**:
-  - Cursor: \`~/.cursor/mcp.json\` (Windows: \`%USERPROFILE%\\.cursor\\mcp.json\`)
-  - Claude Code: \`~/.claude.json\`
-  - 기타 VSCode 계열: 각각의 설정 파일
-- **설정 내용**: \`docuking\` 서버를 \`mcpServers\` 객체에 추가
-- **재시작 필요**: MCP 설정 파일을 처음 만들었을 때만 필요 (Cursor/Claude Code 재시작)
-- **중요**: 이미 다른 MCP 서버가 설정되어 있으면, 기존 설정을 덮어쓰지 말고 \`docuking\` 항목만 추가해야 함
-
-### 프로젝트 연결 (각 폴더마다)
-- **목적**: 특정 로컬 폴더를 DocuKing 서버의 프로젝트 ID와 연결
-- **실행 방법**: \`docuking_init(projectId, localPath)\` 도구 호출
-- **결과**: 해당 폴더에 \`yy_All_Docu/\` 폴더 생성 및 프로젝트 매핑 저장
-- **재시작 불필요**: MCP가 이미 작동 중이면 바로 실행 가능
-- **다중 프로젝트**: 한 컴퓨터에서 여러 폴더를 각각 다른 DocuKing 프로젝트와 연결 가능
-
-**핵심 원칙:**
-1. MCP 설정은 한 번만 (모든 폴더 공통)
-2. 프로젝트 연결은 각 폴더마다 (폴더별로 다른 프로젝트 ID)
-3. 이미 MCP가 작동 중이면 재시작 없이 바로 프로젝트 연결 가능
+## MCP 설치 및 설정 (매우 중요!)
+
+### 1단계: 글로벌 설치 (필수)
+\`\`\`bash
+npm install -g docuking-mcp
+\`\`\`
+
+### 2단계: MCP 등록 (AI 도구별)
+
+**Claude Code:**
+\`\`\`bash
+claude mcp add docuking -s user -- docuking-mcp
+\`\`\`
+
+**Cursor:** \`~/.cursor/mcp.json\`에 추가
+\`\`\`json
+{
+  "mcpServers": {
+    "docuking": {
+      "command": "docuking-mcp",
+      "args": []
+    }
+  }
+}
+\`\`\`
+
+**Gemini CLI:** \`~/.gemini/antigravity/mcp_config.json\`에 추가
+\`\`\`json
+{
+  "mcpServers": {
+    "docuking": {
+      "command": "docuking-mcp",
+      "args": []
+    }
+  }
+}
+\`\`\`
+
+### 업데이트
+새 버전이 있으면 첫 도구 호출 시 자동으로 알려줍니다.
+\`\`\`bash
+npm update -g docuking-mcp
+\`\`\`
+
+### MCP 설정 vs 프로젝트 연결
+- **MCP 설정**: 전역, 한 번만 (위의 설치/등록)
+- **프로젝트 연결**: 각 폴더마다 \`docuking_init\` 실행
+- **중요**: 이미 다른 MCP 서버가 있으면 덮어쓰지 말고 \`docuking\` 항목만 추가
+
 
 ## .gitignore 설정 (중요!)
 
@@ -713,13 +745,30 @@ zz_ai_3_Plan/
 - planId로 계획 찾기
 - 완료 요약 및 산출물 기록
 
-### 12. docuking_delete
+### 12. docuking_todo
+킹투두를 관리합니다 (\`zz_ai_2_Todo/z_King_Todo.md\`).
+- action: "add" (추가), "done" (완료), "list" (조회)
+- 프로젝트 공식 할일 목록 (Push하면 웹에서 확인 가능)
+
+### 13. docuking_urgent
+긴급 보고를 \`xx_Urgent/\` 폴더에 작성합니다 (킹어전트).
+- 정책에 없는 예외 상황 발견 시 오너에게 보고
+- 협업자도 xx_Urgent/에 쓰기 가능 (유일한 예외)
+- 오너가 Pull할 때 "긴급 보고 N건" 알림
+
+### 14. docuking_delete
 서버에서 파일/폴더를 직접 삭제합니다.
 - 로컬에서 삭제한 파일이 Push 후에도 서버에 남아있을 때
 - 서버에만 존재하는 불필요한 파일 정리
 - soft-delete 처리 (3일 후 영구 삭제)
 - 권한: 오너는 자기 영역, 협업자는 자기 폴더만
 
+### 15. docuking_validate
+코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
+- .claude/rules/local/ 정책 기준으로 검증
+- 폴더 구조, 명명 규칙, API 규칙 등 체크
+- 위반 목록과 수정 제안 반환
+
 ## Git과의 유사성
 
 | DocuKing | Git | 설명 |
@@ -818,40 +867,75 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
   try {
+    let result;
     switch (name) {
       case 'docuking_init':
-        return await handleInit(args);
+        result = await handleInit(args);
+        break;
       case 'docuking_push':
-        return await handlePush(args);
+        result = await handlePush(args);
+        break;
       case 'docuking_pull':
-        return await handlePull(args);
+        result = await handlePull(args);
+        break;
       case 'docuking_list':
-        return await handleList(args);
+        result = await handleList(args);
+        break;
       case 'docuking_status':
-        return await handleStatus(args);
+        result = await handleStatus(args);
+        break;
       case 'docuking_log':
-        return await handleLog(args);
+        result = await handleLog(args);
+        break;
       case 'docuking_diff':
-        return await handleDiff(args);
+        result = await handleDiff(args);
+        break;
       case 'docuking_rollback':
-        return await handleRollback(args);
+        result = await handleRollback(args);
+        break;
       case 'docuking_talk':
-        return await handleTalk(args);
+        result = await handleTalk(args);
+        break;
       case 'docuking_plan':
-        return await handlePlan(args);
+        result = await handlePlan(args);
+        break;
       case 'docuking_done':
-        return await handleDone(args);
+        result = await handleDone(args);
+        break;
       case 'docuking_todo':
-        return await handleTodo(args);
+        result = await handleTodo(args);
+        break;
       case 'docuking_urgent':
-        return await handleUrgent(args);
+        result = await handleUrgent(args);
+        break;
       case 'docuking_delete':
-        return await handleDelete(args);
+        result = await handleDelete(args);
+        break;
       case 'docuking_validate':
-        return await handleValidate(args);
+        result = await handleValidate(args);
+        break;
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
+
+    // 버전 체크 알림 (세션당 1회)
+    if (!versionWarningShown) {
+      try {
+        const updateInfo = await checkForUpdates();
+        const warning = getVersionWarningMessage(updateInfo);
+        if (warning) {
+          versionWarningShown = true;
+          result.content.push({
+            type: 'text',
+            text: warning
+          });
+        }
+      } catch (e) {
+        // 버전 체크 실패해도 무시 (서버 작동에 영향 없음)
+      }
+    }
+
+    return result;
   } catch (error) {
     return {
       content: [

package/lib/files.js

@@ -193,18 +193,33 @@ export function collectFiles(basePath, relativePath, results, excludedFiles = nu
 }
 
 /**
- * 트리 구조를 평탄화
+ * 트리 구조를 평탄화 (파일 + 폴더 모두 포함)
+ * @param {Array} tree - 트리 구조
+ * @param {string} prefix - 경로 접두어
+ * @param {boolean} includeEmpty - 빈 폴더도 포함 (기본: true)
+ * @returns {Array} - { path, name, type } 배열
  */
-export function flattenTree(tree, prefix = '') {
+export function flattenTree(tree, prefix = '', includeEmpty = true) {
   const results = [];
 
   for (const item of tree) {
     const itemPath = prefix ? `${prefix}/${item.name}` : item.name;
 
     if (item.type === 'file') {
-      results.push({ path: itemPath, name: item.name });
+      // 파일
+      results.push({ path: itemPath, name: item.name, type: 'file' });
+    } else if (item.type === 'folder') {
+      // 폴더도 결과에 추가 (빈 폴더 동기화를 위해)
+      if (includeEmpty) {
+        results.push({ path: itemPath, name: item.name, type: 'folder' });
+      }
+      // 자식 탐색
+      if (item.children && item.children.length > 0) {
+        results.push(...flattenTree(item.children, itemPath, includeEmpty));
+      }
     } else if (item.children) {
-      results.push(...flattenTree(item.children, itemPath));
+      // 구버전 호환: type 없이 children만 있는 경우
+      results.push(...flattenTree(item.children, itemPath, includeEmpty));
     }
   }
 

package/lib/version-check.js

@@ -0,0 +1,119 @@
+/**
+ * DocuKing MCP 버전 체크 모듈
+ *
+ * npm registry에서 최신 버전을 확인하고,
+ * 현재 버전과 비교하여 업데이트 필요 여부를 알려줍니다.
+ */
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// 캐시 (세션 동안 유지)
+let cachedUpdateInfo = null;
+let lastCheckTime = 0;
+const CHECK_INTERVAL = 60 * 60 * 1000; // 1시간
+
+/**
+ * npm registry에서 최신 버전 확인 후 업데이트 필요 여부 반환
+ * - 1시간 캐시
+ * - 네트워크 오류 시 graceful degradation
+ */
+export async function checkForUpdates() {
+  const now = Date.now();
+
+  // 1시간 내 체크했으면 캐시 반환
+  if (cachedUpdateInfo && (now - lastCheckTime) < CHECK_INTERVAL) {
+    return cachedUpdateInfo;
+  }
+
+  try {
+    const current = getCurrentVersion();
+    const latest = await getLatestVersion();
+
+    cachedUpdateInfo = {
+      current,
+      latest,
+      available: compareVersions(latest, current) > 0
+    };
+    lastCheckTime = now;
+
+    if (cachedUpdateInfo.available) {
+      console.error(`[DocuKing MCP] 새 버전 ${latest} 출시! (현재: ${current})`);
+    }
+
+    return cachedUpdateInfo;
+  } catch (error) {
+    // 네트워크 오류 등은 무시 (서버 작동에 영향 없음)
+    console.error('[DocuKing MCP] 버전 체크 실패:', error.message);
+    return { available: false };
+  }
+}
+
+/**
+ * package.json에서 현재 버전 읽기
+ */
+export function getCurrentVersion() {
+  const pkgPath = join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  return pkg.version;
+}
+
+/**
+ * npm registry에서 최신 버전 조회
+ */
+async function getLatestVersion() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000); // 5초 타임아웃
+
+  try {
+    const response = await fetch('https://registry.npmjs.org/docuking-mcp/latest', {
+      signal: controller.signal
+    });
+    const data = await response.json();
+    return data.version;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * 버전 비교 (semver 단순 비교)
+ * @returns 1 if a > b, -1 if a < b, 0 if equal
+ */
+function compareVersions(a, b) {
+  const partsA = a.split('.').map(Number);
+  const partsB = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const numA = partsA[i] || 0;
+    const numB = partsB[i] || 0;
+    if (numA > numB) return 1;
+    if (numA < numB) return -1;
+  }
+  return 0;
+}
+
+/**
+ * AI에게 보여줄 업데이트 경고 메시지 생성
+ */
+export function getVersionWarningMessage(updateInfo) {
+  if (!updateInfo || !updateInfo.available) return null;
+
+  return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ DocuKing MCP 업데이트 필요
+
+현재 버전: ${updateInfo.current}
+최신 버전: ${updateInfo.latest}
+
+업데이트 명령어:
+  npm update -g docuking-mcp
+
+새 버전에서 버그 수정 및 기능 개선이 있습니다.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docuking-mcp",
-  "version": "2.9.3",
+  "version": "2.11.0",
   "description": "DocuKing MCP Server - AI 시대의 문서 협업 플랫폼",
   "type": "module",
   "main": "index.js",