docuking-mcp 2.11.0 → 2.12.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,6 +1221,12 @@ export async function handlePullInternal(args) {
   // Pull 후 mark-as-pulled할 파일 목록 (source: web 파일들)
   const filesToMarkAsPulled = [];
 
+  // ========================================
+  // 로컬 인덱스 로드 (Pull 후 업데이트용)
+  // ========================================
+  const localIndex = loadIndex(localPath);
+  const syncedFiles = []; // 다운로드/업데이트된 파일 목록
+
   for (const file of sortedFiles) {
     current++;
     const progress = `${current}/${total}`;
@@ -1264,6 +1349,9 @@ export async function handlePullInternal(args) {
         downloaded++;
       }
 
+      // 인덱스에 다운로드된 파일 기록
+      syncedFiles.push({ serverPath: file.path, fullPath, hash: serverHash });
+
       // source: 'web' 파일이면 mark-as-pulled 대상
       if (serverMeta && serverMeta.source === 'web') {
         filesToMarkAsPulled.push(file.path);
@@ -1300,6 +1388,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/lib/version-check.js

@@ -110,9 +110,23 @@ export function getVersionWarningMessage(updateInfo) {
 현재 버전: ${updateInfo.current}
 최신 버전: ${updateInfo.latest}
 
-업데이트 명령어:
+【글로벌 설치 사용자】
   npm update -g docuking-mcp
 
+【npx 방식 사용자 (전환 필요)】
+npx 캐시 문제로 글로벌 설치로 전환해야 합니다:
+
+1. 글로벌 설치:
+   npm install -g docuking-mcp
+
+2. MCP 설정 변경:
+   - Claude Code: claude mcp remove docuking && claude mcp add docuking -s user -- docuking-mcp
+   - Cursor/기타: ~/.cursor/mcp.json 등에서 아래와 같이 변경
+     Before: { "command": "npx", "args": ["-y", "docuking-mcp@latest"] }
+     After:  { "command": "docuking-mcp", "args": [] }
+
+3. AI 도구 재시작
+
 새 버전에서 버그 수정 및 기능 개선이 있습니다.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `;

package/package.json

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