docuking-mcp 2.5.6 → 2.7.0

package/handlers/sync.js

@@ -0,0 +1,1501 @@
+/**
+ * DocuKing MCP - 동기화 핸들러 모듈
+ * init, push, pull, list, status
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+import {
+  API_ENDPOINT,
+  MAX_FILE_SIZE_MB,
+  MAX_FILE_SIZE_BYTES,
+  parseCoworkerFromApiKey,
+  getLocalConfig,
+  getApiKey,
+  saveLocalConfig,
+  getAiBasePath,
+  getProjectInfo,
+} from '../lib/config.js';
+
+import {
+  FILE_TYPES,
+  getFileType,
+  hasAllDocuFolder,
+  collectEmptyFolders,
+  collectFilesSimple,
+  collectFiles,
+  flattenTree,
+} from '../lib/files.js';
+
+import {
+  updateClaudeMd,
+  setupAutoApproval,
+  updateGitignore,
+} from '../lib/init.js';
+
+import { executeKingcast } from './kingcast.js';
+
+// 레포지토리 매핑 (메모리에 캐시)
+const repoMapping = {};
+
+/**
+ * docuking_init 구현
+ */
+export async function handleInit(args) {
+  const { projectId, projectName, apiKey, localPath } = args;
+
+  // API 키 필수 체크
+  if (!apiKey) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: apiKey가 필요합니다.
+
+docuking_init 호출 시 apiKey 파라미터를 포함해주세요.`,
+        },
+      ],
+    };
+  }
+
+  // Co-worker 권한은 API Key 형식에서 판단
+  const { isCoworker, coworkerFolder } = parseCoworkerFromApiKey(apiKey);
+
+  // .docuking/config.json에 설정 저장
+  saveLocalConfig(localPath, {
+    projectId,
+    projectName,
+    apiKey,
+    isCoworker,
+    coworkerFolder,
+    createdAt: new Date().toISOString(),
+  });
+
+  // 폴더 생성: 오너는 yy_All_Docu/, 협업자는 yy_Coworker_{폴더명}/ (별도)
+  const mainFolderName = 'yy_All_Docu';
+  const mainFolderPath = path.join(localPath, mainFolderName);
+
+  // yy_All_Docu 폴더는 항상 생성
+  if (!fs.existsSync(mainFolderPath)) {
+    fs.mkdirSync(mainFolderPath, { recursive: true });
+  }
+
+  let coworkerFolderName = null;
+  let coworkerFolderPath = null;
+
+  // zz_ai_* 폴더 목록
+  const aiFolders = ['zz_ai_1_Talk', 'zz_ai_2_Todo', 'zz_ai_3_Plan'];
+
+  if (isCoworker) {
+    // 협업자: yy_Coworker_{폴더명}/ 폴더를 yy_All_Docu/ 밖에 별도 생성
+    coworkerFolderName = `yy_Coworker_${coworkerFolder}`;
+    coworkerFolderPath = path.join(localPath, coworkerFolderName);
+    if (!fs.existsSync(coworkerFolderPath)) {
+      fs.mkdirSync(coworkerFolderPath, { recursive: true });
+    }
+    // 협업자 폴더 안에 _Private/ 생성
+    const coworkerPrivatePath = path.join(coworkerFolderPath, '_Private');
+    if (!fs.existsSync(coworkerPrivatePath)) {
+      fs.mkdirSync(coworkerPrivatePath, { recursive: true });
+    }
+    // 협업자 폴더 안에 zz_ai_* 폴더 생성
+    for (const folder of aiFolders) {
+      const folderPath = path.join(coworkerFolderPath, folder);
+      if (!fs.existsSync(folderPath)) {
+        fs.mkdirSync(folderPath, { recursive: true });
+      }
+    }
+  } else {
+    // 오너: yy_All_Docu/ 안에 _Infra_Config/, _Policy/, _Private/ 생성
+    const infraConfigPath = path.join(mainFolderPath, '_Infra_Config');
+    if (!fs.existsSync(infraConfigPath)) {
+      fs.mkdirSync(infraConfigPath, { recursive: true });
+    }
+    const policyPath = path.join(mainFolderPath, '_Policy');
+    if (!fs.existsSync(policyPath)) {
+      fs.mkdirSync(policyPath, { recursive: true });
+    }
+    const ownerPrivatePath = path.join(mainFolderPath, '_Private');
+    if (!fs.existsSync(ownerPrivatePath)) {
+      fs.mkdirSync(ownerPrivatePath, { recursive: true });
+    }
+    // 오너: 루트에 zz_ai_* 폴더 생성
+    for (const folder of aiFolders) {
+      const folderPath = path.join(localPath, folder);
+      if (!fs.existsSync(folderPath)) {
+        fs.mkdirSync(folderPath, { recursive: true });
+      }
+    }
+  }
+
+  // CLAUDE.md 업데이트, 자동 승인 설정, .gitignore 업데이트
+  updateClaudeMd(localPath);
+  setupAutoApproval(localPath);
+  updateGitignore(localPath);
+
+  // 연결 완료 안내 (오너/코워커에 따라 다른 메시지)
+  if (isCoworker) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `DocuKing 연결 완료!
+
+📁 프로젝트: ${projectName}
+📂 ${coworkerFolderName}/ 작업 폴더 생성됨
+🔑 설정: .docuking/config.json
+
+사용법:
+- "가져와" → Pull (오너 문서 + 정책)
+- "올려줘" → Push (내 폴더만)`,
+        },
+      ],
+    };
+  } else {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `DocuKing 연결 완료!
+
+📁 프로젝트: ${projectName}
+📂 yy_All_Docu/ 폴더 생성됨
+🔑 설정: .docuking/config.json
+
+사용법:
+- "올려줘" → Push
+- "가져와" → Pull`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * docuking_push 구현
+ */
+export async function handlePush(args) {
+  // localPath가 없으면 현재 작업 디렉토리 사용
+  const localPath = args.localPath || process.cwd();
+  const { filePath, message, author } = args;
+
+  // 커밋 메시지 필수 체크
+  if (!message || message.trim() === '') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: 커밋 메시지가 필요합니다.
+
+Git처럼 무엇을 변경했는지 명확히 작성해주세요.
+예: "README에 설치 가이드 추가"`,
+        },
+      ],
+    };
+  }
+
+  // 로컬 config에서 API 키 읽기
+  const apiKey = getApiKey(localPath);
+  if (!apiKey) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: API 키를 찾을 수 없습니다.
+먼저 docuking_init을 실행하세요.`,
+        },
+      ],
+    };
+  }
+
+  // 프로젝트 정보 조회 (로컬 config에서)
+  const projectInfo = getProjectInfo(localPath);
+  if (projectInfo.error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: projectInfo.error,
+        },
+      ],
+    };
+  }
+
+  const projectId = projectInfo.projectId;
+  const projectName = projectInfo.projectName;
+
+  // ========================================
+  // 1단계: Pull 먼저 실행 (git pull && git push 패턴)
+  // ========================================
+  let pullResultText = '';
+  try {
+    const pullResult = await handlePullInternal({ localPath, filePath });
+    pullResultText = pullResult.text;
+  } catch (e) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ Pull 실패로 Push를 중단합니다.
+오류: ${e.message}
+
+먼저 Pull 문제를 해결한 후 다시 시도하세요.`,
+        },
+      ],
+    };
+  }
+
+  // ========================================
+  // 2단계: Push 진행
+  // ========================================
+
+  // Co-worker 권한은 API Key 형식에서 판단
+  const { isCoworker, coworkerFolder } = parseCoworkerFromApiKey(apiKey);
+  const coworkerFolderName = isCoworker ? `yy_Coworker_${coworkerFolder}` : null;
+
+  // 작업 폴더 결정: 프로젝트 루트 기준 절대경로 사용
+  // 오너: yy_All_Docu/, zz_ai_*/ 폴더들 Push
+  // 협업자: yy_Coworker_{폴더명}/ 폴더만 Push
+  const mainFolderPath = path.join(localPath, 'yy_All_Docu');
+
+  // Push 대상 폴더 목록 (프로젝트 루트 기준)
+  let pushTargetFolders = [];
+
+  // 디버그: Push 대상 판단 로그
+  console.error(`[DocuKing] Push 권한: isCoworker=${isCoworker}, coworkerFolder=${coworkerFolder}, coworkerFolderName=${coworkerFolderName}`);
+
+  if (isCoworker) {
+    // 협업자: yy_Coworker_{폴더명}/ 폴더만 Push
+    const coworkerPath = path.join(localPath, coworkerFolderName);
+    console.error(`[DocuKing] 협업자 Push 대상 폴더: ${coworkerPath}`);
+    if (!fs.existsSync(coworkerPath)) {
+      fs.mkdirSync(coworkerPath, { recursive: true });
+    }
+    pushTargetFolders.push({ localPath: coworkerPath, serverPrefix: coworkerFolderName });
+
+    // 협업자 폴더 내용 디버그 출력
+    try {
+      const entries = fs.readdirSync(coworkerPath, { withFileTypes: true });
+      console.error(`[DocuKing] 협업자 폴더 내용: ${entries.map(e => e.name + (e.isDirectory() ? '/' : '')).join(', ')}`);
+    } catch (e) {
+      console.error(`[DocuKing] 협업자 폴더 읽기 실패: ${e.message}`);
+    }
+  } else {
+    // 오너: yy_All_Docu/ 폴더 확인
+    if (!fs.existsSync(mainFolderPath)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `오류: yy_All_Docu 폴더가 없습니다.
+docuking_init을 먼저 실행하세요.`,
+          },
+        ],
+      };
+    }
+
+    // 오너 Push 대상: yy_All_Docu/ + zz_ai_*/ 폴더들
+    pushTargetFolders.push({ localPath: mainFolderPath, serverPrefix: 'yy_All_Docu' });
+
+    // zz_ai_* 폴더들 찾기
+    const rootEntries = fs.readdirSync(localPath, { withFileTypes: true });
+    for (const entry of rootEntries) {
+      if (entry.isDirectory() && entry.name.startsWith('zz_ai_')) {
+        const zzPath = path.join(localPath, entry.name);
+        pushTargetFolders.push({ localPath: zzPath, serverPrefix: entry.name });
+      }
+    }
+  }
+
+  // .env 파일 자동 백업: _Infra_Config/ 폴더에 복사
+  // 오너만 가능 (협업자는 _Infra_Config/ 에 접근 불가)
+  if (!isCoworker) {
+    const envFilePath = path.join(localPath, '.env');
+    const infraConfigPath = path.join(mainFolderPath, '_Infra_Config');
+
+    if (fs.existsSync(envFilePath)) {
+      // _Infra_Config 폴더 생성
+      if (!fs.existsSync(infraConfigPath)) {
+        fs.mkdirSync(infraConfigPath, { recursive: true });
+      }
+
+      // .env 파일 복사
+      const envBackupPath = path.join(infraConfigPath, '.env');
+      try {
+        fs.copyFileSync(envFilePath, envBackupPath);
+        console.error(`[DocuKing] .env → _Infra_Config/.env 자동 백업 완료`);
+      } catch (err) {
+        console.error(`[DocuKing] .env 백업 실패: ${err.message}`);
+      }
+    }
+
+    // backend/.env 파일도 백업
+    const backendEnvPath = path.join(localPath, 'backend', '.env');
+    if (fs.existsSync(backendEnvPath)) {
+      if (!fs.existsSync(infraConfigPath)) {
+        fs.mkdirSync(infraConfigPath, { recursive: true });
+      }
+
+      const backendEnvBackupPath = path.join(infraConfigPath, 'backend.env');
+      try {
+        fs.copyFileSync(backendEnvPath, backendEnvBackupPath);
+        console.error(`[DocuKing] backend/.env → _Infra_Config/backend.env 자동 백업 완료`);
+      } catch (err) {
+        console.error(`[DocuKing] backend/.env 백업 실패: ${err.message}`);
+      }
+    }
+
+    // frontend/.env.local 파일도 백업
+    const frontendEnvPath = path.join(localPath, 'frontend', '.env.local');
+    if (fs.existsSync(frontendEnvPath)) {
+      if (!fs.existsSync(infraConfigPath)) {
+        fs.mkdirSync(infraConfigPath, { recursive: true });
+      }
+
+      const frontendEnvBackupPath = path.join(infraConfigPath, 'frontend.env.local');
+      try {
+        fs.copyFileSync(frontendEnvPath, frontendEnvBackupPath);
+        console.error(`[DocuKing] frontend/.env.local → _Infra_Config/frontend.env.local 자동 백업 완료`);
+      } catch (err) {
+        console.error(`[DocuKing] frontend/.env.local 백업 실패: ${err.message}`);
+      }
+    }
+
+    // package.json 파일 백업 (루트)
+    const packageJsonPath = path.join(localPath, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      if (!fs.existsSync(infraConfigPath)) {
+        fs.mkdirSync(infraConfigPath, { recursive: true });
+      }
+
+      const packageJsonBackupPath = path.join(infraConfigPath, 'package.json');
+      try {
+        fs.copyFileSync(packageJsonPath, packageJsonBackupPath);
+        console.error(`[DocuKing] package.json → _Infra_Config/package.json 자동 백업 완료`);
+      } catch (err) {
+        console.error(`[DocuKing] package.json 백업 실패: ${err.message}`);
+      }
+    }
+
+    // backend/package.json 파일도 백업
+    const backendPackageJsonPath = path.join(localPath, 'backend', 'package.json');
+    if (fs.existsSync(backendPackageJsonPath)) {
+      if (!fs.existsSync(infraConfigPath)) {
+        fs.mkdirSync(infraConfigPath, { recursive: true });
+      }
+
+      const backendPackageJsonBackupPath = path.join(infraConfigPath, 'backend.package.json');
+      try {
+        fs.copyFileSync(backendPackageJsonPath, backendPackageJsonBackupPath);
+        console.error(`[DocuKing] backend/package.json → _Infra_Config/backend.package.json 자동 백업 완료`);
+      } catch (err) {
+        console.error(`[DocuKing] backend/package.json 백업 실패: ${err.message}`);
+      }
+    }
+
+    // frontend/package.json 파일도 백업
+    const frontendPackageJsonPath = path.join(localPath, 'frontend', 'package.json');
+    if (fs.existsSync(frontendPackageJsonPath)) {
+      if (!fs.existsSync(infraConfigPath)) {
+        fs.mkdirSync(infraConfigPath, { recursive: true });
+      }
+
+      const frontendPackageJsonBackupPath = path.join(infraConfigPath, 'frontend.package.json');
+      try {
+        fs.copyFileSync(frontendPackageJsonPath, frontendPackageJsonBackupPath);
+        console.error(`[DocuKing] frontend/package.json → _Infra_Config/frontend.package.json 자동 백업 완료`);
+      } catch (err) {
+        console.error(`[DocuKing] frontend/package.json 백업 실패: ${err.message}`);
+      }
+    }
+  }
+
+  // 파일 목록 수집
+  const filesToPush = [];
+  const excludedFiles = []; // 제외된 파일 목록
+  const largeFiles = [];
+  let emptyFolders = []; // 빈 폴더 목록
+
+  if (filePath) {
+    // 특정 파일만 - 첫 번째 대상 폴더에서 찾기
+    const targetFolder = pushTargetFolders[0];
+    const fullPath = path.join(targetFolder.localPath, filePath);
+    if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+      const fileType = getFileType(filePath);
+      if (fileType === 'excluded') {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `오류: ${filePath}는 지원하지 않는 파일 형식입니다.\n\n📦 압축/설치 파일(.zip, .jar, .exe 등)은 DocuKing에 업로드되지 않습니다.\n💡 이런 파일은 별도 공유 방법(Google Drive, NAS 등)을 사용하고,\n   문서에 다운로드 링크나 설치 가이드를 작성하세요.`,
+            },
+          ],
+        };
+      }
+
+      // 서버 경로: 폴더prefix/파일경로 (예: yy_All_Docu/회의록/test.md)
+      const serverFilePath = `${targetFolder.serverPrefix}/${filePath}`;
+      filesToPush.push({ path: filePath, serverPath: serverFilePath, fullPath, fileType });
+    }
+  } else {
+    // 전체 파일 - 모든 대상 폴더에서 수집
+    for (const targetFolder of pushTargetFolders) {
+      if (!fs.existsSync(targetFolder.localPath)) continue;
+
+      const folderFiles = [];
+      collectFilesSimple(targetFolder.localPath, '', folderFiles, excludedFiles, largeFiles);
+
+      // 디버그: 수집된 파일 목록 출력
+      console.error(`[DocuKing] ${targetFolder.serverPrefix}/ 에서 수집된 파일 ${folderFiles.length}개:`);
+      for (const f of folderFiles.slice(0, 10)) {
+        console.error(`  - ${f.path}`);
+      }
+      if (folderFiles.length > 10) {
+        console.error(`  ... 외 ${folderFiles.length - 10}개`);
+      }
+
+      // 서버 경로 추가: prefix/상대경로 (예: yy_All_Docu/회의록/test.md)
+      for (const file of folderFiles) {
+        file.serverPath = `${targetFolder.serverPrefix}/${file.path}`;
+        filesToPush.push(file);
+      }
+
+      // 빈 폴더 수집
+      const folderEmptyDirs = [];
+      collectEmptyFolders(targetFolder.localPath, '', folderEmptyDirs);
+      for (const emptyDir of folderEmptyDirs) {
+        emptyFolders.push({
+          localPath: emptyDir,
+          serverPath: `${targetFolder.serverPrefix}/${emptyDir}`,
+        });
+      }
+    }
+
+    // 대용량 파일 경고
+    if (largeFiles.length > 0) {
+      console.error(`\n[DocuKing] ⚠️ 대용량 파일 ${largeFiles.length}개 제외됨 (${MAX_FILE_SIZE_MB}MB 초과):`);
+      for (const f of largeFiles) {
+        console.error(`  - ${f.path} (${f.sizeMB}MB)`);
+      }
+      console.error(`💡 대용량 파일은 Google Drive, NAS 등 별도 방법으로 공유하세요.\n`);
+    }
+  }
+
+  if (filesToPush.length === 0 && emptyFolders.length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Push할 파일이 없습니다.',
+        },
+      ],
+    };
+  }
+
+  // 총 용량 계산
+  const totalSizeMB = filesToPush.reduce((sum, f) => sum + (f.sizeMB || 0), 0);
+
+  // 파일 업로드 (진행률 표시)
+  const results = [];
+  const total = filesToPush.length;
+  let current = 0;
+  let skipped = 0;
+
+  // 시작 안내 메시지 출력 (AI가 사용자에게 전달할 수 있도록)
+  console.error(`[DocuKing] Push 시작: ${total}개 파일 (총 ${totalSizeMB.toFixed(1)}MB)`);
+  console.error(`[DocuKing] 💡 실시간 진행상황은 DocuKing 웹(https://docuking.ai)에서 확인하세요`);
+
+  // Sync 시작 알림 (웹에서 프로그레스바 표시용)
+  try {
+    await fetch(`${API_ENDPOINT}/projects/${projectId}/sync/start`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ totalFiles: total }),
+    });
+  } catch (e) {
+    console.error('[DocuKing] Sync 시작 알림 실패:', e.message);
+  }
+
+  // 서버에서 파일 해시 조회 (Git 스타일 동기화용)
+  let serverPathToHash = {};
+  let serverHashToPath = {};
+  let serverAllPaths = [];
+  try {
+    const hashResponse = await fetch(
+      `${API_ENDPOINT}/files/hashes-for-sync?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+        },
+      }
+    );
+    if (hashResponse.ok) {
+      const hashData = await hashResponse.json();
+      serverPathToHash = hashData.pathToHash || {};
+      serverHashToPath = hashData.hashToPath || {};
+      serverAllPaths = hashData.allPaths || [];
+    }
+  } catch (e) {
+    // 해시 조회 실패는 무시 (처음 Push하는 경우 등)
+    console.error('[DocuKing] 파일 해시 조회 실패:', e.message);
+  }
+
+  // 처리된 로컬 파일 경로 (서버 삭제용)
+  const processedLocalPaths = new Set();
+  let moved = 0;
+
+  for (const file of filesToPush) {
+    current++;
+    const progress = `${current}/${total}`;
+    const sizeInfo = file.sizeMB >= 1 ? ` (${file.sizeMB.toFixed(1)}MB)` : '';
+    processedLocalPaths.add(file.serverPath);
+
+    // 1MB 이상 파일은 업로드 시작 시 로그 출력 (사용자가 진행 상황 파악 가능)
+    if (file.sizeMB >= 1) {
+      console.error(`[DocuKing] ${progress} 업로드 중: ${file.path}${sizeInfo}`);
+    }
+
+    try {
+      // 파일 해시 계산 (변경 감지)
+      let fileHash;
+      let content;
+      let encoding = 'utf-8';
+
+      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) {
+        const resultText = `${progress} ⊘ ${file.serverPath} (변경 없음)`;
+        results.push(resultText);
+        skipped++;
+        continue;
+      }
+
+      // 2. 같은 해시가 다른 경로에 있음 → Move (경로 변경)
+      const existingPath = serverHashToPath[fileHash];
+      if (existingPath && existingPath !== file.serverPath) {
+        try {
+          const moveResponse = await fetch(`${API_ENDPOINT}/files/move`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+              projectId,
+              oldPath: existingPath,
+              newPath: file.serverPath,
+            }),
+          });
+
+          if (moveResponse.ok) {
+            const resultText = `${progress} ↷ ${existingPath} → ${file.serverPath}`;
+            results.push(resultText);
+            moved++;
+            // 이동된 파일의 해시 맵 업데이트
+            delete serverHashToPath[fileHash];
+            serverHashToPath[fileHash] = file.serverPath;
+            continue;
+          }
+        } catch (e) {
+          console.error(`[DocuKing] Move 실패: ${e.message}, Upload로 대체`);
+        }
+      }
+
+      // 3. 새 파일 또는 내용 변경 → Upload
+
+      // 재시도 로직 (최대 3회)
+      let lastError = null;
+      let success = false;
+      for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+          // 대용량 파일 업로드를 위한 타임아웃 설정 (10분)
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 10 * 60 * 1000); // 10분
+
+          let response;
+          try {
+            response = await fetch(`${API_ENDPOINT}/files/push`, {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+              },
+              body: JSON.stringify({
+                projectId,
+                path: file.serverPath, // 서버 경로 (코워커는 yy_Coworker_{폴더명}/파일경로)
+                content,
+                encoding, // 'utf-8' 또는 'base64'
+                message, // 커밋 메시지
+                author, // 작성자 (optional)
+                fileHash, // 파일 해시 (변경 감지용)
+              }),
+              signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+          } catch (e) {
+            clearTimeout(timeoutId);
+            if (e.name === 'AbortError') {
+              throw new Error(`파일 업로드 타임아웃 (10분 초과): ${file.path}`);
+            }
+            throw e;
+          }
+
+          if (response.ok) {
+            const resultText = attempt > 1
+              ? `${progress} ✓ ${file.path} (재시도 ${attempt}회 성공)`
+              : `${progress} ✓ ${file.path}`;
+            results.push(resultText);
+            success = true;
+            break; // 성공하면 재시도 중단
+          } else {
+            const error = await response.text();
+            lastError = error;
+            // 4xx 에러는 재시도하지 않음 (클라이언트 오류)
+            if (response.status >= 400 && response.status < 500) {
+              throw new Error(error);
+            }
+            // 5xx 에러만 재시도
+            if (attempt < 3) {
+              const waitTime = attempt * 1000; // 1초, 2초, 3초
+              await new Promise(resolve => setTimeout(resolve, waitTime));
+            }
+          }
+        } catch (e) {
+          lastError = e.message;
+          // 네트워크 오류 등은 재시도
+          if (attempt < 3 && !e.message.includes('타임아웃')) {
+            const waitTime = attempt * 1000;
+            await new Promise(resolve => setTimeout(resolve, waitTime));
+          } else {
+            throw e;
+          }
+        }
+      }
+
+      if (!success) {
+        const errorText = `${progress} ✗ ${file.path}: ${lastError}`;
+        results.push(errorText);
+        console.error(errorText);
+      }
+
+      // 진행 상황 업데이트 (매 파일마다 또는 5개마다)
+      if (current % 5 === 0 || current === total || current === 1) {
+        try {
+          await fetch(`${API_ENDPOINT}/projects/${projectId}/sync/progress`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ progress: current }),
+          });
+        } catch (e) {
+          // 진행 상황 업데이트 실패는 무시
+        }
+      }
+    } catch (e) {
+      results.push(`${progress} ✗ ${file.path}: ${e.message}`);
+    }
+  }
+
+  // 4. 서버에만 있고 로컬에 없는 파일 soft-delete (deleted_at 기반)
+  // 단, 협업자 폴더(yy_Coworker_*)는 삭제하지 않음 (오너가 협업자 파일을 삭제하면 안됨)
+  // 기존 hard delete(delete-batch) → soft delete(soft-delete)로 변경
+  // 3일 후 크론잡에서 hard delete 수행
+  let deleted = 0;
+  const deletedFilePaths = [];
+  let protectedFiles = []; // source: 'web' 파일 (보호됨)
+  if (serverAllPaths.length > 0 && !isCoworker) {
+    // 코워커가 아닌 경우에만 삭제 수행 (오너 전용)
+    // yy_Coworker_*로 시작하는 경로는 삭제 대상에서 제외
+    const pathsToDelete = serverAllPaths.filter(p =>
+      !processedLocalPaths.has(p) && !p.startsWith('yy_Coworker_')
+    );
+
+    if (pathsToDelete.length > 0) {
+      try {
+        // soft-delete API 호출 (deleted_at 설정, 3일 후 hard delete)
+        const deleteResponse = await fetch(`${API_ENDPOINT}/files/soft-delete`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            projectId,
+            paths: pathsToDelete,
+          }),
+        });
+
+        if (deleteResponse.ok) {
+          const deleteResult = await deleteResponse.json();
+          deleted = deleteResult.deleted || 0;
+          deletedFilePaths.push(...(deleteResult.deletedPaths || []));
+          protectedFiles = deleteResult.protected || [];
+
+          // 보호된 파일이 있으면 로그 출력
+          if (protectedFiles.length > 0) {
+            console.error(`[DocuKing] 보호된 파일 ${protectedFiles.length}개 (source: web):`, protectedFiles.slice(0, 5));
+          }
+        }
+      } catch (e) {
+        console.error('[DocuKing] 파일 soft-delete 실패:', e.message);
+      }
+    }
+  }
+
+  // 5. 빈 폴더 생성
+  let createdEmptyFolders = 0;
+  if (emptyFolders.length > 0) {
+    for (const folder of emptyFolders) {
+      try {
+        const folderResponse = await fetch(`${API_ENDPOINT}/files`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            projectId,
+            path: folder.serverPath,
+            type: 'folder',
+            name: folder.localPath.split('/').pop(),
+          }),
+        });
+
+        if (folderResponse.ok) {
+          createdEmptyFolders++;
+          console.error(`[DocuKing] 빈 폴더 생성: ${folder.serverPath}`);
+        }
+      } catch (e) {
+        console.error(`[DocuKing] 빈 폴더 생성 실패: ${folder.serverPath} - ${e.message}`);
+      }
+    }
+  }
+
+  // Sync 완료 알림
+  try {
+    await fetch(`${API_ENDPOINT}/projects/${projectId}/sync/complete`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+    });
+  } catch (e) {
+    console.error('[DocuKing] Sync 완료 알림 실패:', e.message);
+  }
+
+  const successCount = results.filter(r => r.includes('✓')).length;
+  const failCount = results.filter(r => r.includes('✗')).length;
+  const skippedCount = skipped; // 이미 계산된 스킵 개수 사용
+  const excludedCount = excludedFiles.length;
+  const movedCount = moved;
+
+  // 요약 정보
+  let summary = `\n📦 커밋 메시지: "${message}"\n\n📊 처리 결과:\n   - 총 파일: ${total}개\n   - 업로드: ${successCount}개\n   - 이동: ${movedCount}개\n   - 삭제: ${deleted}개\n   - 스킵 (변경 없음): ${skippedCount}개\n   - 실패: ${failCount}개`;
+  if (createdEmptyFolders > 0) {
+    summary += `\n   - 빈 폴더 생성: ${createdEmptyFolders}개`;
+  }
+  if (excludedCount > 0) {
+    summary += `\n   - 제외 (압축/설치파일): ${excludedCount}개`;
+  }
+
+  // 상세 결과를 표시 (Git처럼)
+  let resultText = `✓ Push 완료!${summary}`;
+
+  // 업로드된 파일이 있으면 상세 목록 표시
+  if (successCount > 0) {
+    const uploadedFiles = results.filter(r => r.includes('✓') && !r.includes('재시도'));
+    resultText += `\n\n📤 업로드된 파일 (${successCount}개):\n${uploadedFiles.map(r => `   ${r.replace(/^\d+\/\d+ /, '')}`).join('\n')}`;
+  }
+
+  // 이동된 파일이 있으면 표시 (Git 스타일)
+  if (movedCount > 0) {
+    const movedFiles = results.filter(r => r.includes('↷'));
+    resultText += `\n\n↷ 이동된 파일 (${movedCount}개):\n${movedFiles.map(r => `   ${r.replace(/^\d+\/\d+ /, '')}`).join('\n')}`;
+  }
+
+  // 삭제된 파일이 있으면 표시 (soft-delete, 3일 후 영구 삭제)
+  if (deleted > 0) {
+    resultText += `\n\n🗑️ 서버에서 삭제됨 (${deleted}개, 로컬에 없음, 3일 후 영구 삭제):`;
+    deletedFilePaths.slice(0, 20).forEach(f => {
+      resultText += `\n   ✗ ${f}`;
+    });
+    if (deleted > 20) {
+      resultText += `\n   ... 외 ${deleted - 20}개`;
+    }
+  }
+
+  // 보호된 파일이 있으면 표시 (source: 'web')
+  if (protectedFiles.length > 0) {
+    resultText += `\n\n🛡️ 보호된 파일 (${protectedFiles.length}개, 웹에서 생성됨):`;
+    protectedFiles.slice(0, 10).forEach(f => {
+      resultText += `\n   🔒 ${f}`;
+    });
+    if (protectedFiles.length > 10) {
+      resultText += `\n   ... 외 ${protectedFiles.length - 10}개`;
+    }
+    resultText += `\n   💡 웹에서 생성된 파일은 MCP에서 삭제할 수 없습니다.`;
+  }
+
+  // 스킵된 파일이 있으면 표시
+  if (skippedCount > 0) {
+    const skippedFiles = results.filter(r => r.includes('⊘'));
+    resultText += `\n\n⏭️  스킵된 파일 (${skippedCount}개, 변경 없음):\n${skippedFiles.map(r => `   ${r.replace(/^\d+\/\d+ /, '')}`).join('\n')}`;
+  }
+
+  // 실패한 파일이 있으면 표시
+  if (failCount > 0) {
+    const failedFiles = results.filter(r => r.includes('✗'));
+    resultText += `\n\n❌ 실패한 파일 (${failCount}개):\n${failedFiles.map(r => `   ${r.replace(/^\d+\/\d+ /, '')}`).join('\n')}`;
+  }
+
+  // 제외된 파일이 있으면 표시
+  if (excludedCount > 0) {
+    resultText += `\n\n📦 제외된 파일 (${excludedCount}개, 압축/설치파일):\n${excludedFiles.slice(0, 10).map(f => `   ⊖ ${f}`).join('\n')}`;
+    if (excludedCount > 10) {
+      resultText += `\n   ... 외 ${excludedCount - 10}개`;
+    }
+    resultText += `\n\n💡 압축/설치 파일은 DocuKing에 저장되지 않습니다.\n   이런 파일은 별도 공유(Google Drive, NAS 등)를 사용하고,\n   문서에 다운로드 링크나 설치 가이드를 작성하세요.`;
+  }
+
+  resultText += `\n\n🌐 웹 탐색기에서 커밋 히스토리를 확인할 수 있습니다: https://docuking.ai`;
+
+  // Pull 결과가 있으면 앞에 추가
+  let finalText = '';
+  if (pullResultText) {
+    // Pull에서 실제로 받은 파일이 있는 경우만 표시
+    const pullHasChanges = pullResultText.includes('다운로드 (신규):') && !pullResultText.includes('다운로드 (신규): 0개');
+    const pullHasUpdates = pullResultText.includes('업데이트 (변경됨):') && !pullResultText.includes('업데이트 (변경됨): 0개');
+
+    if (pullHasChanges || pullHasUpdates) {
+      finalText = `📥 [1단계] Pull (서버 → 로컬)\n${pullResultText}\n\n${'─'.repeat(50)}\n\n📤 [2단계] Push (로컬 → 서버)\n${resultText}`;
+    } else {
+      // Pull에서 변경 없으면 간단히 표시
+      finalText = `📥 Pull: 변경 없음 (최신 상태)\n\n📤 Push:\n${resultText}`;
+    }
+  } else {
+    finalText = resultText;
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: finalText,
+      },
+    ],
+  };
+}
+
+/**
+ * docuking_pull 내부 구현 (Push에서도 호출)
+ * 반환값: { text: 결과문자열, downloaded, updated, skipped, failed }
+ */
+export async function handlePullInternal(args) {
+  const localPath = args.localPath || process.cwd();
+  const { filePath } = args;
+
+  // 로컬 config에서 API 키 읽기
+  const apiKey = getApiKey(localPath);
+  if (!apiKey) {
+    throw new Error('API 키를 찾을 수 없습니다. 먼저 docuking_init을 실행하세요.');
+  }
+
+  // 프로젝트 정보 조회 (로컬 config에서)
+  const projectInfo = getProjectInfo(localPath);
+  if (projectInfo.error) {
+    throw new Error(projectInfo.error);
+  }
+
+  const projectId = projectInfo.projectId;
+
+  // yy_All_Docu 폴더 (없으면 생성)
+  const mainFolderName = 'yy_All_Docu';
+  const mainFolderPath = path.join(localPath, mainFolderName);
+  if (!fs.existsSync(mainFolderPath)) {
+    fs.mkdirSync(mainFolderPath, { recursive: true });
+  }
+
+  // 파일 목록 조회
+  let files = [];
+  let deletedFiles = []; // 삭제된 파일 목록 (deleted_at 기반)
+
+  try {
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+        },
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+
+    const data = await response.json();
+    files = flattenTree(data.tree || []);
+  } catch (e) {
+    throw new Error(`파일 목록 조회 실패 - ${e.message}`);
+  }
+
+  // 서버에서 삭제된 파일 목록 조회 (deleted_at 기반 동기화)
+  try {
+    const hashResponse = await fetch(
+      `${API_ENDPOINT}/files/hashes-for-sync?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+        },
+      }
+    );
+    if (hashResponse.ok) {
+      const hashData = await hashResponse.json();
+      deletedFiles = hashData.deletedFiles || [];
+    }
+  } catch (e) {
+    console.error('[DocuKing] 삭제 파일 목록 조회 실패:', e.message);
+  }
+
+  if (filePath) {
+    files = files.filter(f => f.path === filePath || f.path.startsWith(filePath + '/'));
+  }
+
+  if (files.length === 0) {
+    // 빈 파일은 에러가 아님 - 정상 결과 반환
+    return {
+      text: 'Pull할 파일이 없습니다.',
+      total: 0,
+      downloaded: 0,
+      updated: 0,
+      skipped: 0,
+      failed: 0,
+    };
+  }
+
+  // 파일 다운로드
+  const results = [];
+  const total = files.length;
+  let current = 0;
+  let downloaded = 0;   // 새로 다운로드
+  let updated = 0;      // 업데이트 (변경됨)
+  let skipped = 0;      // 스킵 (변경 없음)
+  let failed = 0;       // 실패
+
+  for (const file of files) {
+    current++;
+    const progress = `${current}/${total}`;
+
+    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();
+
+      // 서버 경로에 따라 로컬 저장 위치 결정
+      // 프로젝트 루트 기준 절대경로 그대로 사용
+      // - 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('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';
+
+      // 서버 파일 해시 계산
+      let serverBuffer;
+      if (encoding === 'base64') {
+        serverBuffer = Buffer.from(content, 'base64');
+      } else {
+        serverBuffer = Buffer.from(content, 'utf-8');
+      }
+      const serverHash = crypto.createHash('sha256').update(serverBuffer).digest('hex');
+
+      // 로컬 파일 존재 여부 및 해시 비교
+      let localExists = fs.existsSync(fullPath);
+      let localHash = null;
+
+      if (localExists) {
+        try {
+          const localBuffer = fs.readFileSync(fullPath);
+          localHash = crypto.createHash('sha256').update(localBuffer).digest('hex');
+        } catch (e) {
+          localExists = false;
+        }
+      }
+
+      // 변경 감지
+      if (localExists && localHash === serverHash) {
+        // 변경 없음 - 스킵
+        results.push({ type: 'skip', path: file.path });
+        skipped++;
+        continue;
+      }
+
+      // 디렉토리 생성
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+
+      // 파일 저장
+      if (encoding === 'base64') {
+        fs.writeFileSync(fullPath, serverBuffer);
+      } else {
+        fs.writeFileSync(fullPath, content, 'utf-8');
+      }
+
+      if (localExists) {
+        // 기존 파일 업데이트
+        results.push({ type: 'update', path: file.path });
+        updated++;
+      } else {
+        // 새로 다운로드
+        results.push({ type: 'download', path: file.path });
+        downloaded++;
+      }
+    } catch (e) {
+      results.push({ type: 'fail', path: file.path, error: e.message });
+      failed++;
+    }
+  }
+
+  // 상세 결과 구성 (Push 스타일)
+  let resultText = `✓ Pull 완료!
+
+📊 처리 결과:
+   - 총 파일: ${total}개
+   - 다운로드 (신규): ${downloaded}개
+   - 업데이트 (변경됨): ${updated}개
+   - 스킵 (변경 없음): ${skipped}개
+   - 실패: ${failed}개`;
+
+  // 다운로드된 파일 목록
+  const downloadedFiles = results.filter(r => r.type === 'download');
+  if (downloadedFiles.length > 0) {
+    resultText += `\n\n📥 다운로드된 파일 (${downloadedFiles.length}개):`;
+    downloadedFiles.slice(0, 20).forEach(f => {
+      resultText += `\n   ✓ ${f.path}`;
+    });
+    if (downloadedFiles.length > 20) {
+      resultText += `\n   ... 외 ${downloadedFiles.length - 20}개`;
+    }
+  }
+
+  // 업데이트된 파일 목록
+  const updatedFiles = results.filter(r => r.type === 'update');
+  if (updatedFiles.length > 0) {
+    resultText += `\n\n🔄 업데이트된 파일 (${updatedFiles.length}개):`;
+    updatedFiles.slice(0, 20).forEach(f => {
+      resultText += `\n   ↻ ${f.path}`;
+    });
+    if (updatedFiles.length > 20) {
+      resultText += `\n   ... 외 ${updatedFiles.length - 20}개`;
+    }
+  }
+
+  // 스킵된 파일 목록
+  const skippedFiles = results.filter(r => r.type === 'skip');
+  if (skippedFiles.length > 0) {
+    resultText += `\n\n⏭️  스킵된 파일 (${skippedFiles.length}개, 변경 없음):`;
+    skippedFiles.slice(0, 10).forEach(f => {
+      resultText += `\n   ⊘ ${f.path}`;
+    });
+    if (skippedFiles.length > 10) {
+      resultText += `\n   ... 외 ${skippedFiles.length - 10}개`;
+    }
+  }
+
+  // 실패한 파일 목록
+  const failedFiles = results.filter(r => r.type === 'fail');
+  if (failedFiles.length > 0) {
+    resultText += `\n\n❌ 실패한 파일 (${failedFiles.length}개):`;
+    failedFiles.forEach(f => {
+      resultText += `\n   ✗ ${f.path}: ${f.error}`;
+    });
+  }
+
+  resultText += `\n\n🌐 웹 탐색기: https://docuking.ai`;
+
+  // ========================================
+  // 삭제 동기화 (deleted_at 기반)
+  // 서버에서 삭제된 파일이 로컬에 있으면, deletedAt vs localMtime 비교 후 삭제
+  // ========================================
+  let deletedLocally = 0;
+  const deletedLocallyPaths = [];
+
+  if (deletedFiles.length > 0) {
+    for (const deletedFile of deletedFiles) {
+      try {
+        // 서버 경로에 따라 로컬 경로 결정
+        let fullPath;
+        if (deletedFile.path.startsWith('yy_All_Docu/') ||
+            deletedFile.path.startsWith('yy_Coworker_') ||
+            deletedFile.path.startsWith('zz_ai_')) {
+          fullPath = path.join(localPath, deletedFile.path);
+        } else {
+          fullPath = path.join(mainFolderPath, deletedFile.path);
+        }
+
+        // 로컬에 파일이 존재하는지 확인
+        if (!fs.existsSync(fullPath)) {
+          continue; // 로컬에 없으면 스킵
+        }
+
+        // 로컬 파일의 수정 시간 확인
+        const localStat = fs.statSync(fullPath);
+        const localMtime = localStat.mtime;
+        const serverDeletedAt = new Date(deletedFile.deletedAt);
+
+        // deletedAt > localMtime → 삭제가 최신 → 로컬에서 삭제
+        // deletedAt < localMtime → 로컬 수정이 최신 → 유지 (다음 Push에서 부활)
+        if (serverDeletedAt > localMtime) {
+          fs.unlinkSync(fullPath);
+          deletedLocally++;
+          deletedLocallyPaths.push(deletedFile.path);
+          console.error(`[DocuKing] 로컬 삭제 (서버에서 삭제됨): ${deletedFile.path}`);
+
+          // 빈 폴더 정리
+          const parentDir = path.dirname(fullPath);
+          try {
+            const entries = fs.readdirSync(parentDir);
+            if (entries.length === 0) {
+              fs.rmdirSync(parentDir);
+              console.error(`[DocuKing] 빈 폴더 삭제: ${parentDir}`);
+            }
+          } catch (e) {
+            // 폴더 정리 실패는 무시
+          }
+        } else {
+          console.error(`[DocuKing] 로컬 유지 (로컬 수정이 최신): ${deletedFile.path}`);
+        }
+      } catch (e) {
+        console.error(`[DocuKing] 삭제 동기화 실패: ${deletedFile.path} - ${e.message}`);
+      }
+    }
+
+    // 삭제된 파일이 있으면 결과에 추가
+    if (deletedLocally > 0) {
+      resultText += `\n\n🗑️ 로컬에서 삭제됨 (${deletedLocally}개, 서버에서 삭제된 파일):`;
+      deletedLocallyPaths.slice(0, 10).forEach(p => {
+        resultText += `\n   ✗ ${p}`;
+      });
+      if (deletedLocallyPaths.length > 10) {
+        resultText += `\n   ... 외 ${deletedLocallyPaths.length - 10}개`;
+      }
+    }
+  }
+
+  // ========================================
+  // 킹캐스트 실행 (Policy/Config 변경 감지 및 로컬화)
+  // ========================================
+  let kingcastResult = null;
+  try {
+    kingcastResult = await executeKingcast(localPath);
+    // 협업자에게만 킹캐스트 메시지 표시 (오너는 message가 null)
+    if (kingcastResult.success && kingcastResult.hasChanges && kingcastResult.message) {
+      resultText += `\n\n${kingcastResult.message}`;
+      if (kingcastResult.details) {
+        const { added, modified, deleted } = kingcastResult.details;
+        if (added.length > 0) {
+          resultText += `\n   📄 추가: ${added.join(', ')}`;
+        }
+        if (modified.length > 0) {
+          resultText += `\n   ✏️ 수정: ${modified.join(', ')}`;
+        }
+        // 삭제는 협업자에게 알리지 않음 (정책 삭제에 신경 쓸 필요 없음)
+        resultText += `\n\n💡 정책/환경 문서가 .claude/rules/local/에 로컬화되었습니다.`;
+        resultText += `\n   정책 파일의 내용을 읽어 변경사항을 확인하세요.`;
+      }
+    }
+  } catch (e) {
+    console.error('[DocuKing] 킹캐스트 실행 실패:', e.message);
+  }
+
+  // 내부용 객체 반환 (Push에서 사용)
+  return {
+    text: resultText,
+    total,
+    downloaded,
+    updated,
+    skipped,
+    failed,
+    kingcast: kingcastResult,
+  };
+}
+
+/**
+ * docuking_pull 구현 (MCP 도구용 래퍼)
+ */
+export async function handlePull(args) {
+  try {
+    const result = await handlePullInternal(args);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: result.text,
+        },
+      ],
+    };
+  } catch (e) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: ${e.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * docuking_list 구현
+ */
+export async function handleList(args) {
+  const localPath = args.localPath || process.cwd();
+
+  // 로컬 config에서 API 키 읽기
+  const apiKey = getApiKey(localPath);
+  if (!apiKey) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: API 키를 찾을 수 없습니다.
+먼저 docuking_init을 실행하세요.`,
+        },
+      ],
+    };
+  }
+
+  // 프로젝트 정보 조회 (로컬 config에서)
+  const projectInfo = getProjectInfo(localPath);
+  if (projectInfo.error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: projectInfo.error,
+        },
+      ],
+    };
+  }
+
+  const projectId = projectInfo.projectId;
+
+  try {
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+        },
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+
+    const data = await response.json();
+    const files = flattenTree(data.tree || []);
+
+    if (files.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: '서버에 저장된 파일이 없습니다.',
+          },
+        ],
+      };
+    }
+
+    const fileList = files.map(f => `  ${f.path}`).join('\n');
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `서버 파일 목록:\n\n${fileList}`,
+        },
+      ],
+    };
+  } catch (e) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: ${e.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * docuking_status 구현
+ */
+export async function handleStatus(args) {
+  const localPath = args.localPath || process.cwd();
+
+  // 로컬 config에서 API 키 읽기
+  const apiKey = getApiKey(localPath);
+  if (!apiKey) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: API 키를 찾을 수 없습니다.
+먼저 docuking_init을 실행하세요.`,
+        },
+      ],
+    };
+  }
+
+  // 프로젝트 정보 조회 (로컬 config에서)
+  const projectInfo = getProjectInfo(localPath);
+  if (projectInfo.error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: projectInfo.error,
+        },
+      ],
+    };
+  }
+
+  const projectId = projectInfo.projectId;
+  const projectName = projectInfo.projectName;
+
+  // Co-worker 권한은 API Key 형식에서 판단
+  const { isCoworker, coworkerFolder } = parseCoworkerFromApiKey(apiKey);
+  const coworkerFolderName = isCoworker ? `yy_Coworker_${coworkerFolder}` : null;
+
+  // 권한 정보 구성
+  let permissionInfo = '';
+  if (isCoworker) {
+    permissionInfo = `\n\n## 현재 권한: 참여자 (Co-worker)
+- 작업 폴더: ${coworkerFolderName}/
+- 읽기 권한: 전체 문서 (Pull로 yy_All_Docu/ 폴더의 문서 가져오기 가능)
+- 쓰기 권한: ${coworkerFolderName}/ 폴더만
+- 설명: 협업자 폴더에서 작업하면 자동으로 서버에 Push됩니다.`;
+  } else {
+    permissionInfo = `\n\n## 현재 권한: 오너 (Owner)
+- 읽기 권한: 전체 문서
+- 쓰기 권한: yy_All_Docu/ 폴더 전체 (제한 없음)
+- 설명: 프로젝트의 모든 폴더에 Push할 수 있습니다.`;
+  }
+
+  // 서버 파일 목록 조회
+  let serverFiles = [];
+  try {
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+        },
+      }
+    );
+    if (response.ok) {
+      const data = await response.json();
+      serverFiles = flattenTree(data.tree || []);
+    }
+  } catch (e) {
+    console.error('[DocuKing] 파일 목록 조회 실패:', e.message);
+  }
+
+  // 로컬 파일 목록 조회
+  let localFiles = [];
+  let pushableFiles = [];
+  const mainFolderPath = path.join(localPath, 'yy_All_Docu');
+
+  if (isCoworker) {
+    // 협업자: yy_Coworker_{폴더명}/ 폴더에서 파일 수집
+    const coworkerPath = path.join(localPath, coworkerFolderName);
+    if (fs.existsSync(coworkerPath)) {
+      collectFilesSimple(coworkerPath, '', localFiles);
+    }
+    pushableFiles = localFiles; // 협업자는 자기 폴더의 모든 파일 Push 가능
+  } else {
+    // 오너: yy_All_Docu/ + zz_ai_*/ 폴더에서 파일 수집
+    if (fs.existsSync(mainFolderPath)) {
+      collectFilesSimple(mainFolderPath, '', localFiles);
+    }
+    // zz_ai_* 폴더들도 수집
+    const rootEntries = fs.readdirSync(localPath, { withFileTypes: true });
+    for (const entry of rootEntries) {
+      if (entry.isDirectory() && entry.name.startsWith('zz_ai_')) {
+        const zzPath = path.join(localPath, entry.name);
+        collectFilesSimple(zzPath, '', localFiles);
+      }
+    }
+    pushableFiles = localFiles; // 오너는 모든 파일 Push 가능
+  }
+
+  const projectNameInfo = projectName ? ` (${projectName})` : '';
+  const workingFolder = isCoworker ? coworkerFolderName : 'yy_All_Docu';
+  const statusText = `DocuKing 동기화 상태
+
+**프로젝트**: ${projectId}${projectNameInfo}
+**작업 폴더**: ${workingFolder}/
+**로컬 파일**: ${localFiles.length}개
+**서버 파일**: ${serverFiles.length}개
+**Push 가능한 파일**: ${pushableFiles.length}개${permissionInfo}
+
+## 사용 가능한 작업
+- **Push**: docuking_push({ localPath, message: "..." })
+- **Pull**: docuking_pull({ localPath })
+- **목록 조회**: docuking_list({ localPath })`;
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: statusText,
+      },
+    ],
+  };
+}