docuking-mcp 2.11.1 → 2.13.0

package/handlers/sync.js

@@ -37,6 +37,17 @@ import {
 
 import { executeKingcast } from './kingcast.js';
 
+import {
+  loadIndex,
+  saveIndex,
+  detectChanges,
+  updateIndexEntry,
+  removeIndexEntry,
+  updateIndexAfterSync,
+  computeFileHash,
+  getIndexStats,
+} from '../lib/index-cache.js';
+
 // 레포지토리 매핑 (메모리에 캐시)
 const repoMapping = {};
 
@@ -522,6 +533,16 @@ docuking_init을 먼저 실행하세요.`,
   let current = 0;
   let skipped = 0;
 
+  // ========================================
+  // 로컬 인덱스 로드 (mtime 기반 변경 감지용)
+  // ========================================
+  const localIndex = loadIndex(localPath);
+  const indexStats = getIndexStats(localIndex);
+  console.error(`[DocuKing] 로컬 인덱스: ${indexStats.fileCount}개 파일 (${indexStats.totalSizeMB}MB)`);
+
+  // 동기화 후 인덱스 업데이트용 배열
+  const syncedFiles = [];
+
   // 시작 안내 메시지 출력 (AI가 사용자에게 전달할 수 있도록)
   console.error(`[DocuKing] Push 시작: ${total}개 파일 (총 ${totalSizeMB.toFixed(1)}MB)`);
   console.error(`[DocuKing] 💡 실시간 진행상황은 DocuKing 웹(https://docuking.ai)에서 확인하세요`);
@@ -582,32 +603,75 @@ docuking_init을 먼저 실행하세요.`,
     }
 
     try {
-      // 파일 해시 계산 (변경 감지)
+      // ========================================
+      // 로컬 인덱스 기반 mtime 체크 (해시 계산 최소화)
+      // ========================================
+      const cached = localIndex.files[file.serverPath];
       let fileHash;
       let content;
       let encoding = 'utf-8';
+      let usedCache = false;
 
-      if (file.fileType === 'binary') {
-        // 바이너리 파일은 Base64로 인코딩
-        const buffer = fs.readFileSync(file.fullPath);
-        fileHash = crypto.createHash('sha256').update(buffer).digest('hex');
-        content = buffer.toString('base64');
-        encoding = 'base64';
-      } else {
-        // 텍스트 파일은 UTF-8
-        content = fs.readFileSync(file.fullPath, 'utf-8');
-        fileHash = crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+      // mtime 비교: 변경되지 않았으면 캐시된 해시 사용
+      if (cached) {
+        try {
+          const stat = fs.statSync(file.fullPath);
+          const currentMtime = stat.mtimeMs;
+
+          // mtime 동일 (1초 오차 허용) + 서버 해시와도 동일 → 완전 스킵
+          if (Math.abs(currentMtime - cached.mtime) < 1000) {
+            if (serverPathToHash[file.serverPath] === cached.hash) {
+              const resultText = `${progress} ⊘ ${file.serverPath} (변경 없음)`;
+              results.push(resultText);
+              skipped++;
+              continue;
+            }
+            // mtime 동일하지만 서버 해시 다름 → 캐시 해시 사용, 업로드 필요
+            fileHash = cached.hash;
+            usedCache = true;
+          }
+        } catch (e) {
+          // stat 실패 시 해시 계산으로 폴백
+        }
+      }
+
+      // 캐시 사용 못하면 파일 읽어서 해시 계산
+      if (!usedCache) {
+        if (file.fileType === 'binary') {
+          // 바이너리 파일은 Base64로 인코딩
+          const buffer = fs.readFileSync(file.fullPath);
+          fileHash = crypto.createHash('sha256').update(buffer).digest('hex');
+          content = buffer.toString('base64');
+          encoding = 'base64';
+        } else {
+          // 텍스트 파일은 UTF-8
+          content = fs.readFileSync(file.fullPath, 'utf-8');
+          fileHash = crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+        }
       }
 
       // Git 스타일 동기화:
       // 1. 같은 경로 + 같은 해시 → 스킵 (변경 없음)
       if (serverPathToHash[file.serverPath] === fileHash) {
+        // 인덱스 업데이트 (다음 Push 때 스킵 가능하도록)
+        syncedFiles.push({ serverPath: file.serverPath, fullPath: file.fullPath, hash: fileHash });
         const resultText = `${progress} ⊘ ${file.serverPath} (변경 없음)`;
         results.push(resultText);
         skipped++;
         continue;
       }
 
+      // 업로드 필요 → content가 없으면 파일 읽기
+      if (!content) {
+        if (file.fileType === 'binary') {
+          const buffer = fs.readFileSync(file.fullPath);
+          content = buffer.toString('base64');
+          encoding = 'base64';
+        } else {
+          content = fs.readFileSync(file.fullPath, 'utf-8');
+        }
+      }
+
       // 2. 같은 해시가 다른 경로에 있음 → Move (경로 변경)
       const existingPath = serverHashToPath[fileHash];
       if (existingPath && existingPath !== file.serverPath) {
@@ -632,6 +696,9 @@ docuking_init을 먼저 실행하세요.`,
             // 이동된 파일의 해시 맵 업데이트
             delete serverHashToPath[fileHash];
             serverHashToPath[fileHash] = file.serverPath;
+            // 인덱스에 이동된 파일 기록 (기존 경로 삭제, 새 경로 추가)
+            removeIndexEntry(localIndex, existingPath);
+            syncedFiles.push({ serverPath: file.serverPath, fullPath: file.fullPath, hash: fileHash });
             continue;
           }
         } catch (e) {
@@ -684,6 +751,8 @@ docuking_init을 먼저 실행하세요.`,
               : `${progress} ✓ ${file.path}`;
             results.push(resultText);
             success = true;
+            // 인덱스에 업로드된 파일 기록
+            syncedFiles.push({ serverPath: file.serverPath, fullPath: file.fullPath, hash: fileHash });
             break; // 성공하면 재시도 중단
           } else {
             const error = await response.text();
@@ -843,6 +912,16 @@ docuking_init을 먼저 실행하세요.`,
     }
   }
 
+  // ========================================
+  // 로컬 인덱스 업데이트 및 저장
+  // ========================================
+  if (syncedFiles.length > 0) {
+    updateIndexAfterSync(localIndex, syncedFiles, deletedFilePaths);
+    if (saveIndex(localPath, localIndex)) {
+      console.error(`[DocuKing] 로컬 인덱스 업데이트: ${syncedFiles.length}개 파일`);
+    }
+  }
+
   // Sync 완료 알림
   try {
     await fetch(`${API_ENDPOINT}/projects/${projectId}/sync/complete`, {
@@ -1142,14 +1221,54 @@ export async function handlePullInternal(args) {
   // Pull 후 mark-as-pulled할 파일 목록 (source: web 파일들)
   const filesToMarkAsPulled = [];
 
-  for (const file of sortedFiles) {
+  // ========================================
+  // 로컬 인덱스 로드 (Pull 후 업데이트용)
+  // ========================================
+  const localIndex = loadIndex(localPath);
+  const syncedFiles = []; // 다운로드/업데이트된 파일 목록
+
+  // ========================================
+  // 폴더 먼저 처리
+  // ========================================
+  const folders = sortedFiles.filter(f => f.type === 'folder');
+  const files_only = sortedFiles.filter(f => f.type !== 'folder');
+
+  for (const folder of folders) {
     current++;
-    const progress = `${current}/${total}`;
+    const serverMeta = serverPathToMeta[folder.path];
+    let fullPath;
+    if (folder.path.startsWith('xx_') ||
+        folder.path.startsWith('yy_All_Docu/') ||
+        folder.path.startsWith('yy_All_Docu') ||
+        folder.path.startsWith('yy_Coworker_') ||
+        folder.path.startsWith('zz_ai_')) {
+      fullPath = path.join(localPath, folder.path);
+    } else {
+      fullPath = path.join(mainFolderPath, folder.path);
+    }
 
-    // 서버 메타 정보 조회
-    const serverMeta = serverPathToMeta[file.path];
+    if (fs.existsSync(fullPath)) {
+      results.push({ type: 'skip', path: folder.path, itemType: 'folder' });
+      skipped++;
+    } else {
+      fs.mkdirSync(fullPath, { recursive: true });
+      results.push({ type: 'download', path: folder.path, itemType: 'folder' });
+      foldersCreated++;
+      downloaded++;
+      if (serverMeta && serverMeta.source === 'web') {
+        filesToMarkAsPulled.push(folder.path);
+      }
+    }
+  }
 
-    // 서버 경로에 따라 로컬 저장 위치 결정
+  // ========================================
+  // 파일 처리 - Batch API 사용 (200개씩)
+  // ========================================
+  const BATCH_SIZE = 200;
+
+  // 먼저 로컬 해시 기반으로 스킵할 파일 필터링
+  const filesToDownload = [];
+  for (const file of files_only) {
     let fullPath;
     if (file.path.startsWith('xx_') ||
         file.path.startsWith('yy_All_Docu/') ||
@@ -1161,116 +1280,159 @@ export async function handlePullInternal(args) {
       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++;
+    const serverHash = serverPathToHash[file.path];
 
-          // source: 'web' 폴더면 mark-as-pulled 대상
-          if (serverMeta && serverMeta.source === 'web') {
-            filesToMarkAsPulled.push(file.path);
-          }
+    // 로컬 파일 해시 비교
+    if (fs.existsSync(fullPath)) {
+      try {
+        const localStat = fs.statSync(fullPath);
+        if (localStat.isDirectory()) {
+          results.push({ type: 'skip', path: file.path, error: '같은 이름의 폴더 존재' });
+          skipped++;
+          current++;
+          continue;
         }
-        continue;
+        const localBuffer = fs.readFileSync(fullPath);
+        const localHash = crypto.createHash('sha256').update(localBuffer).digest('hex');
+        if (localHash === serverHash) {
+          results.push({ type: 'skip', path: file.path });
+          skipped++;
+          current++;
+          continue;
+        }
+      } catch (e) {
+        // 해시 계산 실패 시 다운로드 대상
       }
+    }
 
-      // ========================================
-      // 파일 처리 (type === 'file')
-      // ========================================
-      const response = await fetch(
-        `${API_ENDPOINT}/files?projectId=${projectId}&path=${encodeURIComponent(file.path)}`,
-        {
-          headers: {
-            'Authorization': `Bearer ${apiKey}`,
-          },
-        }
-      );
+    filesToDownload.push({ ...file, fullPath });
+  }
 
-      if (!response.ok) {
-        results.push({ type: 'fail', path: file.path, error: await response.text() });
-        failed++;
-        continue;
-      }
+  console.error(`[DocuKing] Batch Pull: ${filesToDownload.length}개 파일 다운로드 필요 (${Math.ceil(filesToDownload.length / BATCH_SIZE)}개 배치)`);
 
-      const data = await response.json();
+  // Batch API로 파일 다운로드
+  for (let i = 0; i < filesToDownload.length; i += BATCH_SIZE) {
+    const batch = filesToDownload.slice(i, i + BATCH_SIZE);
+    const batchPaths = batch.map(f => f.path);
+    const batchNum = Math.floor(i / BATCH_SIZE) + 1;
+    const totalBatches = Math.ceil(filesToDownload.length / BATCH_SIZE);
+
+    console.error(`[DocuKing] Batch ${batchNum}/${totalBatches}: ${batch.length}개 파일 다운로드 중...`);
 
-      // 인코딩에 따라 저장
-      const content = data.file?.content || data.content || '';
-      const encoding = data.file?.encoding || data.encoding || 'utf-8';
+    try {
+      const batchResponse = await fetch(`${API_ENDPOINT}/files/batch-pull`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          projectId,
+          paths: batchPaths,
+        }),
+      });
 
-      // 서버 파일 해시 계산
-      let serverBuffer;
-      if (encoding === 'base64') {
-        serverBuffer = Buffer.from(content, 'base64');
-      } else {
-        serverBuffer = Buffer.from(content, 'utf-8');
+      if (!batchResponse.ok) {
+        const errorText = await batchResponse.text();
+        console.error(`[DocuKing] Batch Pull 실패: ${errorText}`);
+        // 배치 실패 시 모든 파일 실패 처리
+        for (const file of batch) {
+          results.push({ type: 'fail', path: file.path, error: 'Batch request failed' });
+          failed++;
+          current++;
+        }
+        continue;
       }
-      const serverHash = crypto.createHash('sha256').update(serverBuffer).digest('hex');
 
-      // 로컬 파일 존재 여부 및 해시 비교
-      let localExists = fs.existsSync(fullPath);
-      let localHash = null;
+      const batchData = await batchResponse.json();
+      const filesData = batchData.files || [];
+
+      // 파일별 처리
+      for (const file of batch) {
+        current++;
+        const fileData = filesData.find(f => f.path === file.path);
+        const serverMeta = serverPathToMeta[file.path];
+
+        if (!fileData || fileData.error) {
+          results.push({ type: 'fail', path: file.path, error: fileData?.error || 'Not found' });
+          failed++;
+          continue;
+        }
 
-      if (localExists) {
         try {
-          const localStat = fs.statSync(fullPath);
-          if (localStat.isDirectory()) {
-            // 로컬에 같은 이름의 폴더가 있으면 건너뜀
-            results.push({ type: 'skip', path: file.path, error: '같은 이름의 폴더 존재' });
-            skipped++;
-            continue;
+          const content = fileData.content || '';
+          const encoding = fileData.encoding || 'utf-8';
+
+          // 서버 파일 버퍼
+          let serverBuffer;
+          if (encoding === 'base64') {
+            serverBuffer = Buffer.from(content, 'base64');
+          } else {
+            serverBuffer = Buffer.from(content, 'utf-8');
           }
-          const localBuffer = fs.readFileSync(fullPath);
-          localHash = crypto.createHash('sha256').update(localBuffer).digest('hex');
-        } catch (e) {
-          localExists = false;
-        }
-      }
+          const serverHash = fileData.hash || crypto.createHash('sha256').update(serverBuffer).digest('hex');
 
-      // 변경 감지
-      if (localExists && localHash === serverHash) {
-        // 변경 없음 - 스킵
-        results.push({ type: 'skip', path: file.path });
-        skipped++;
-        continue;
-      }
+          // 로컬 존재 여부
+          const localExists = fs.existsSync(file.fullPath);
 
-      // 디렉토리 생성
-      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+          // 디렉토리 생성
+          fs.mkdirSync(path.dirname(file.fullPath), { recursive: true });
 
-      // 파일 저장
-      if (encoding === 'base64') {
-        fs.writeFileSync(fullPath, serverBuffer);
-      } else {
-        fs.writeFileSync(fullPath, content, 'utf-8');
-      }
+          // 파일 저장
+          if (encoding === 'base64') {
+            fs.writeFileSync(file.fullPath, serverBuffer);
+          } else {
+            fs.writeFileSync(file.fullPath, content, 'utf-8');
+          }
 
-      if (localExists) {
-        results.push({ type: 'update', path: file.path });
-        updated++;
-      } else {
-        results.push({ type: 'download', path: file.path });
-        downloaded++;
-      }
+          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);
+          // 인덱스에 기록
+          syncedFiles.push({ serverPath: file.path, fullPath: file.fullPath, hash: serverHash });
+
+          // 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++;
+        }
       }
     } catch (e) {
-      results.push({ type: 'fail', path: file.path, error: e.message });
-      failed++;
+      console.error(`[DocuKing] Batch ${batchNum} 네트워크 오류: ${e.message}`);
+      // 배치 실패 시 개별 요청으로 폴백
+      for (const file of batch) {
+        current++;
+        try {
+          const response = await fetch(
+            `${API_ENDPOINT}/files?projectId=${projectId}&path=${encodeURIComponent(file.path)}`,
+            { headers: { 'Authorization': `Bearer ${apiKey}` } }
+          );
+          if (!response.ok) {
+            results.push({ type: 'fail', path: file.path, error: await response.text() });
+            failed++;
+            continue;
+          }
+          const data = await response.json();
+          const content = data.file?.content || data.content || '';
+          const encoding = data.file?.encoding || data.encoding || 'utf-8';
+          let serverBuffer = encoding === 'base64' ? Buffer.from(content, 'base64') : Buffer.from(content, 'utf-8');
+          fs.mkdirSync(path.dirname(file.fullPath), { recursive: true });
+          fs.writeFileSync(file.fullPath, encoding === 'base64' ? serverBuffer : content, encoding === 'base64' ? undefined : 'utf-8');
+          results.push({ type: 'download', path: file.path });
+          downloaded++;
+        } catch (fallbackErr) {
+          results.push({ type: 'fail', path: file.path, error: fallbackErr.message });
+          failed++;
+        }
+      }
     }
   }
 
@@ -1300,6 +1462,16 @@ export async function handlePullInternal(args) {
     }
   }
 
+  // ========================================
+  // 로컬 인덱스 업데이트 및 저장
+  // ========================================
+  if (syncedFiles.length > 0) {
+    updateIndexAfterSync(localIndex, syncedFiles, []);
+    if (saveIndex(localPath, localIndex)) {
+      console.error(`[DocuKing] 로컬 인덱스 업데이트: ${syncedFiles.length}개 파일`);
+    }
+  }
+
   // 상세 결과 구성 (Push 스타일)
   let resultText = `✓ Pull 완료!
 

package/lib/index-cache.js

@@ -0,0 +1,242 @@
+/**
+ * DocuKing MCP - 로컬 인덱스 캐시 모듈
+ *
+ * Git의 .git/index처럼 마지막 동기화 상태를 저장하여
+ * mtime 기반으로 변경된 파일만 빠르게 탐지합니다.
+ *
+ * 효과:
+ * - 변경되지 않은 파일은 해시 계산 스킵
+ * - Pull/Push 시 변경된 파일만 처리
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+const INDEX_VERSION = 1;
+const INDEX_FILENAME = 'index.json';
+
+/**
+ * 인덱스 파일 경로 반환
+ */
+function getIndexPath(localPath) {
+  return path.join(localPath, '.docuking', INDEX_FILENAME);
+}
+
+/**
+ * 로컬 인덱스 로드
+ * @returns {{ version: number, lastSync: string, files: Object }} 인덱스 객체
+ */
+export function loadIndex(localPath) {
+  const indexPath = getIndexPath(localPath);
+
+  try {
+    if (fs.existsSync(indexPath)) {
+      const data = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+
+      // 버전 체크 (호환되지 않으면 초기화)
+      if (data.version !== INDEX_VERSION) {
+        console.error('[DocuKing] 인덱스 버전 불일치, 재생성합니다.');
+        return createEmptyIndex();
+      }
+
+      return data;
+    }
+  } catch (e) {
+    console.error('[DocuKing] 인덱스 로드 실패:', e.message);
+  }
+
+  return createEmptyIndex();
+}
+
+/**
+ * 빈 인덱스 생성
+ */
+function createEmptyIndex() {
+  return {
+    version: INDEX_VERSION,
+    lastSync: null,
+    files: {},
+  };
+}
+
+/**
+ * 인덱스 저장
+ */
+export function saveIndex(localPath, index) {
+  const indexPath = getIndexPath(localPath);
+  const indexDir = path.dirname(indexPath);
+
+  try {
+    if (!fs.existsSync(indexDir)) {
+      fs.mkdirSync(indexDir, { recursive: true });
+    }
+
+    index.lastSync = new Date().toISOString();
+    fs.writeFileSync(indexPath, JSON.stringify(index, null, 2), 'utf-8');
+
+    return true;
+  } catch (e) {
+    console.error('[DocuKing] 인덱스 저장 실패:', e.message);
+    return false;
+  }
+}
+
+/**
+ * 파일 해시 계산
+ */
+export function computeFileHash(filePath, isBinary = false) {
+  try {
+    const buffer = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(buffer).digest('hex');
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * mtime 기반으로 변경된 파일 탐지
+ *
+ * @param {string} localPath - 프로젝트 루트 경로
+ * @param {Object} index - 로컬 인덱스
+ * @param {string[]} filePaths - 검사할 파일 경로 목록 (serverPath 형식)
+ * @param {Function} getFullPath - serverPath → fullPath 변환 함수
+ * @returns {{ changed: Array, unchanged: Array, newFiles: Array, deleted: Array }}
+ */
+export function detectChanges(localPath, index, filePaths, getFullPath) {
+  const result = {
+    changed: [],    // mtime 변경됨 (해시 계산 필요)
+    unchanged: [],  // mtime 동일 (해시 계산 스킵)
+    newFiles: [],   // 인덱스에 없음 (새 파일)
+    deleted: [],    // 로컬에 없음 (삭제됨)
+  };
+
+  for (const serverPath of filePaths) {
+    const fullPath = getFullPath(serverPath);
+
+    // 로컬 파일 존재 여부 확인
+    if (!fs.existsSync(fullPath)) {
+      result.deleted.push(serverPath);
+      continue;
+    }
+
+    // 인덱스에 있는지 확인
+    const cached = index.files[serverPath];
+    if (!cached) {
+      result.newFiles.push(serverPath);
+      continue;
+    }
+
+    // mtime 비교
+    try {
+      const stat = fs.statSync(fullPath);
+      const currentMtime = stat.mtimeMs;
+
+      if (Math.abs(currentMtime - cached.mtime) < 1000) {
+        // mtime 동일 (1초 오차 허용) → 변경 없음
+        result.unchanged.push(serverPath);
+      } else {
+        // mtime 다름 → 변경됨
+        result.changed.push(serverPath);
+      }
+    } catch (e) {
+      // stat 실패 → 변경됨으로 처리
+      result.changed.push(serverPath);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 인덱스에 파일 정보 업데이트
+ */
+export function updateIndexEntry(index, serverPath, fullPath, hash) {
+  try {
+    const stat = fs.statSync(fullPath);
+
+    index.files[serverPath] = {
+      hash,
+      mtime: stat.mtimeMs,
+      size: stat.size,
+    };
+
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * 인덱스에서 파일 정보 삭제
+ */
+export function removeIndexEntry(index, serverPath) {
+  delete index.files[serverPath];
+}
+
+/**
+ * 인덱스의 해시와 비교하여 실제 변경 여부 확인
+ * (mtime 변경됐지만 내용은 같을 수 있음)
+ *
+ * @returns {{ actuallyChanged: Array, sameContent: Array }}
+ */
+export function verifyChanges(index, changedPaths, getFullPath) {
+  const result = {
+    actuallyChanged: [],  // 해시도 다름 (실제 변경)
+    sameContent: [],      // 해시 동일 (mtime만 변경)
+  };
+
+  for (const serverPath of changedPaths) {
+    const fullPath = getFullPath(serverPath);
+    const cached = index.files[serverPath];
+
+    if (!cached) {
+      result.actuallyChanged.push(serverPath);
+      continue;
+    }
+
+    const currentHash = computeFileHash(fullPath);
+
+    if (currentHash === cached.hash) {
+      result.sameContent.push(serverPath);
+    } else {
+      result.actuallyChanged.push(serverPath);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 동기화 후 인덱스 일괄 업데이트
+ *
+ * @param {Object} index - 인덱스 객체
+ * @param {Array} syncedFiles - 동기화된 파일 목록 [{ serverPath, fullPath, hash }]
+ * @param {Array} deletedPaths - 삭제된 파일 경로 목록
+ */
+export function updateIndexAfterSync(index, syncedFiles, deletedPaths = []) {
+  // 동기화된 파일 업데이트
+  for (const file of syncedFiles) {
+    updateIndexEntry(index, file.serverPath, file.fullPath, file.hash);
+  }
+
+  // 삭제된 파일 제거
+  for (const serverPath of deletedPaths) {
+    removeIndexEntry(index, serverPath);
+  }
+}
+
+/**
+ * 인덱스 통계 반환
+ */
+export function getIndexStats(index) {
+  const files = Object.keys(index.files);
+  const totalSize = Object.values(index.files).reduce((sum, f) => sum + (f.size || 0), 0);
+
+  return {
+    fileCount: files.length,
+    totalSize,
+    totalSizeMB: (totalSize / 1024 / 1024).toFixed(2),
+    lastSync: index.lastSync,
+  };
+}

package/package.json

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