docuking-mcp 2.5.4 → 2.5.5

package/index.js

@@ -392,7 +392,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'docuking_push',
-        description: 'yy_All_Docu/ 폴더의 문서를 서버에 업로드합니다. "DocuKing에 올려줘" 요청 시 사용. Git의 add + commit + push를 한 번에 수행.',
+        description: `문서를 DocuKing 서버에 동기화합니다. 내부적으로 Pull → Push 순서로 실행 (git pull && git push 패턴).
+
+**AI 필독: 다음 상황에서 자발적으로 이 도구 사용을 제안하세요:**
+- zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ 에 문서를 생성/수정한 후
+- yy_All_Docu/ 에 문서를 생성/수정한 후
+- docuking_plan, docuking_done, docuking_talk, docuking_todo 실행 후
+- 사용자가 "올려", "푸시", "동기화" 등을 언급할 때
+
+제안 예시: "킹폴더에 문서가 생성되었습니다. DocuKing에 올릴까요?"`,
         inputSchema: {
           type: 'object',
           properties: {
@@ -828,6 +836,22 @@ AI: docuking_push({ localPath: "/current/path", message: "문서 업데이트" }
 AI: docuking_pull({ localPath: "/current/path" })
 \`\`\`
 
+## 협업 핵심 원칙: 남의 제사상을 건드리지 않는다
+
+DocuKing 협업의 핵심 원칙입니다. **각자 자기 영역만 수정할 수 있고, 남의 영역은 읽기만 가능합니다.**
+
+### Push/Pull 정책 요약
+
+| 역할 | Push (올리기) | Pull (내리기) | 삭제 |
+|------|---------------|---------------|------|
+| 오너 | \`yy_All_Docu/\` + \`zz_ai_*/\` | 합집합 전체 | 자기 영역만 |
+| 협업자 | \`yy_Coworker_{본인}/\` (안에 zz_ai_* 포함) | 합집합 전체 | 자기 영역만 |
+
+**합집합이란?**
+- 서버에는 오너 파일 + 모든 협업자 파일이 합쳐져 있음
+- Pull하면 이 전체가 로컬로 내려옴
+- 경로만 알면 누구의 파일이든 읽고 활용 가능
+
 ## 사용자 권한 및 사용 시나리오 (매우 중요!)
 
 DocuKing에는 **오너(Owner)**와 **참여자(Co-worker)** 두 가지 권한이 있습니다.
@@ -836,7 +860,7 @@ DocuKing에는 **오너(Owner)**와 **참여자(Co-worker)** 두 가지 권한
 
 **특징:**
 - 프로젝트를 직접 생성한 사람
-- **모든 폴더**에 문서를 올릴 수 있음 (제한 없음)
+- \`yy_All_Docu/\` + \`zz_ai_*/\` 폴더에 Push 가능
 - API Key: sk_로 시작
 - 프로젝트 설정 변경 가능
 - 참여자 초대 가능
@@ -845,7 +869,7 @@ DocuKing에는 **오너(Owner)**와 **참여자(Co-worker)** 두 가지 권한
 1. 프로젝트 생성 (웹에서)
 2. MCP 설정 (한 번만)
 3. 프로젝트 연결 (docuking_init)
-4. 문서 작성 (어디든 자유롭게)
+4. 문서 작성 (\`yy_All_Docu/\` 안에)
 5. Push (docuking_push)
 
 **예시:**
@@ -863,50 +887,63 @@ yy_All_Docu/
 
 **특징:**
 - 프로젝트에 초대받아 참여한 사람
-- **읽기**: yy_All_Docu/ 전체 Pull 가능 (오너의 문서도 볼 수 있음)
+- 초대 수락 시 서버에 \`yy_Coworker_{폴더명}/\` 빈폴더 자동 생성
+- **읽기**: 전체 Pull 가능 (오너 + 다른 협업자 문서 모두)
 - **쓰기**: 자신의 폴더(\`yy_Coworker_{폴더명}/\`)에만 Push 가능
 - API Key: \`sk_xxx_cw_폴더명_\` 형식
 - 프로젝트 설정 변경 불가능
 
 **사용 시나리오:**
-1. 초대 수락 (웹에서)
+1. 초대 수락 (웹에서) → 프로젝트 바로 진입, 오너 문서 + 자기 빈폴더 보임
 2. MCP 설정 (한 번만)
-3. 프로젝트 연결 (\`docuking_init\`)
-4. Pull로 오너의 문서 가져오기 (\`docuking_pull\`)
+3. 프로젝트 연결 (\`docuking_init\`) → 로컬에 자기 폴더 생성
+4. Pull (\`docuking_pull\`) → 합집합 전체가 내려옴
 5. 내 폴더에 문서 작성 (\`yy_Coworker_{폴더명}/\`)
-6. Push (\`docuking_push\`)
+6. Push (\`docuking_push\`) → 자기 폴더만 올라감
 
-**폴더 구조:**
+**폴더 구조 (Pull 후 로컬):**
 \`\`\`
 project/
 ├── src/                              ← 소스 코드 (git 관리)
-├── yy_All_Docu/                      ← 오너 문서 (Pull로 읽기만 가능)
+├── yy_All_Docu/                      ← 오너 문서 (읽기만)
 │   ├── policy/
 │   │   └── README.md                 ← 오너의 파일
 │   └── plan/
 │       └── requirements.md           ← 오너의 파일
-├── yy_Coworker_devkim/               ← 참여자 "devkim"의 폴더 (별도)
-│   ├── proposal.md                   ← 여기에만 Push 가능
-│   └── revision.md                   ← 여기에만 Push 가능
-├── zz_ai_1_Talk/                     ← AI 대화록 (Push 대상)
-├── zz_ai_2_Todo/                     ← AI 투두 (Push 대상)
-└── zz_ai_3_Plan/                     ← AI 플랜 (Push 대상)
+├── yy_Coworker_a_Kim/                ← 협업자 Kim의 폴더
+│   ├── proposal.md
+│   └── zz_ai_1_Talk/                 ← Kim의 AI 대화록
+├── yy_Coworker_b_Lee/                ← 협업자 Lee의 폴더
+│   ├── design.md
+│   └── zz_ai_1_Talk/                 ← Lee의 AI 대화록
+└── zz_ai_*/                          ← 오너의 AI 폴더
 \`\`\`
 
 **중요 규칙:**
-- 코워커 폴더(\`yy_Coworker_{폴더명}/\`)는 yy_All_Docu/ 밖에 독립 생성
-- 참여자는 Pull로 yy_All_Docu/ 폴더의 오너 문서를 볼 수 있음
-- 참여자는 자신의 폴더에만 Push 가능
+- Pull하면 합집합 전체가 내려옴 (오너 + 모든 협업자)
+- Push는 자기 영역만 올라감 (남의 제사상 건드리지 않음)
+- 협업자의 \`zz_ai_*/\`는 자기 폴더 안에 있음 (\`yy_Coworker_{폴더명}/zz_ai_*/\`)
 - \`docuking_status\`로 현재 권한과 작업 폴더 확인 가능
 
-**참여자가 오너의 파일을 수정하고 싶을 때:**
-1. Pull로 오너의 파일을 로컬에 가져옴 (yy_All_Docu/에 저장됨)
-2. 내용을 참고하여 자신의 폴더에 수정 제안 작성
-   - 예: \`yy_Coworker_devkim/policy_README_revision.md\`로 작성 후 Push
+**참여자가 남의 파일을 활용하고 싶을 때:**
+1. Pull로 전체를 로컬에 가져옴
+2. 경로로 찾아서 읽고 참고
+3. 수정이 필요하면:
+   - 복사해서 자기 폴더에 가공 후 Push
+   - 또는 카톡/메일로 원작자에게 전달 → 업데이트 요청
+4. 이건 스팟한 일, **대세는 킹폴더에 있는 것**
+
+**오너 관점에서 협업자 상태 파악:**
+| 상태 | 의미 |
+|------|------|
+| 폴더 없음 | 초대만 함, 아직 수락 안 함 |
+| 빈폴더 | 수락함, 작업 대기 중 |
+| 파일 있음 | 일하고 있음 |
 
 **AI가 참여자에게 안내해야 할 내용:**
 - 참여자의 작업 폴더는 \`yy_Coworker_{폴더명}/\`
-- 오너의 파일을 직접 수정할 수 없으므로, 제안서 형태로 작성하도록 안내
+- 남의 파일은 읽기만 가능, 수정 불가
+- 수정 제안은 자기 폴더에 작성하거나 직접 연락
 
 ## AI 응답 가이드 (중요!)
 
@@ -1386,6 +1423,31 @@ Git처럼 무엇을 변경했는지 명확히 작성해주세요.
   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;
@@ -1831,11 +1893,15 @@ docuking_init을 먼저 실행하세요.`,
   }
 
   // 4. 서버에만 있고 로컬에 없는 파일 삭제 (Git rm과 동일)
+  // 단, 협업자 폴더(yy_Coworker_*)는 삭제하지 않음 (오너가 협업자 파일을 삭제하면 안됨)
   let deleted = 0;
   const deletedFiles = [];
   if (serverAllPaths.length > 0 && !isCoworker) {
     // 코워커가 아닌 경우에만 삭제 수행 (오너 전용)
-    const pathsToDelete = serverAllPaths.filter(p => !processedLocalPaths.has(p));
+    // yy_Coworker_*로 시작하는 경로는 삭제 대상에서 제외
+    const pathsToDelete = serverAllPaths.filter(p =>
+      !processedLocalPaths.has(p) && !p.startsWith('yy_Coworker_')
+    );
 
     if (pathsToDelete.length > 0) {
       try {
@@ -1965,47 +2031,49 @@ docuking_init을 먼저 실행하세요.`,
 
   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: resultText,
+        text: finalText,
       },
     ],
   };
 }
 
-// docuking_pull 구현
-async function handlePull(args) {
-  // localPath가 없으면 현재 작업 디렉토리 사용
+// docuking_pull 내부 구현 (Push에서도 호출)
+// 반환값: { text: 결과문자열, downloaded, updated, skipped, failed }
+async function handlePullInternal(args) {
   const localPath = args.localPath || process.cwd();
   const { filePath } = args;
 
   // 로컬 config에서 API 키 읽기
   const apiKey = getApiKey(localPath);
   if (!apiKey) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `오류: API 키를 찾을 수 없습니다.
-먼저 docuking_init을 실행하세요.`,
-        },
-      ],
-    };
+    throw new Error('API 키를 찾을 수 없습니다. 먼저 docuking_init을 실행하세요.');
   }
 
   // 프로젝트 정보 조회 (로컬 config에서)
   const projectInfo = getProjectInfo(localPath);
   if (projectInfo.error) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: projectInfo.error,
-        },
-      ],
-    };
+    throw new Error(projectInfo.error);
   }
 
   const projectId = projectInfo.projectId;
@@ -2037,14 +2105,7 @@ async function handlePull(args) {
     const data = await response.json();
     files = flattenTree(data.tree || []);
   } catch (e) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `오류: 파일 목록 조회 실패 - ${e.message}`,
-        },
-      ],
-    };
+    throw new Error(`파일 목록 조회 실패 - ${e.message}`);
   }
 
   if (filePath) {
@@ -2052,19 +2113,30 @@ async function handlePull(args) {
   }
 
   if (files.length === 0) {
+    // 빈 파일은 에러가 아님 - 정상 결과 반환
     return {
-      content: [
-        {
-          type: 'text',
-          text: 'Pull할 파일이 없습니다.',
-        },
-      ],
+      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)}`,
@@ -2076,7 +2148,8 @@ async function handlePull(args) {
       );
 
       if (!response.ok) {
-        results.push(`✗ ${file.path}: ${await response.text()}`);
+        results.push({ type: 'fail', path: file.path, error: await response.text() });
+        failed++;
         continue;
       }
 
@@ -2098,53 +2171,157 @@ async function handlePull(args) {
         fullPath = path.join(mainFolderPath, file.path);
       }
 
-      // 디렉토리 생성
-      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-
       // 인코딩에 따라 저장
       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') {
-        // Base64 디코딩 후 바이너리로 저장
-        const buffer = Buffer.from(content, 'base64');
-        fs.writeFileSync(fullPath, buffer);
+        fs.writeFileSync(fullPath, serverBuffer);
       } else {
-        // UTF-8 텍스트로 저장
         fs.writeFileSync(fullPath, content, 'utf-8');
       }
 
-      results.push(`✓ ${file.path}`);
+      if (localExists) {
+        // 기존 파일 업데이트
+        results.push({ type: 'update', path: file.path });
+        updated++;
+      } else {
+        // 새로 다운로드
+        results.push({ type: 'download', path: file.path });
+        downloaded++;
+      }
     } catch (e) {
-      results.push(`✗ ${file.path}: ${e.message}`);
+      results.push({ type: 'fail', path: file.path, error: e.message });
+      failed++;
     }
   }
 
-  // 결과 요약
-  const successCount = results.filter(r => r.startsWith('✓')).length;
-  const failCount = results.filter(r => r.startsWith('✗')).length;
+  // 상세 결과 구성 (Push 스타일)
+  let resultText = `✓ Pull 완료!
 
-  // 실패한 파일만 상세 표시, 성공은 개수만
-  const failedFiles = results.filter(r => r.startsWith('✗'));
+📊 처리 결과:
+   - 총 파일: ${total}개
+   - 다운로드 (신규): ${downloaded}개
+   - 업데이트 (변경됨): ${updated}개
+   - 스킵 (변경 없음): ${skipped}개
+   - 실패: ${failed}개`;
 
-  let summary = `Pull 완료! (${successCount}개 성공`;
-  if (failCount > 0) {
-    summary += `, ${failCount}개 실패)`;
-    summary += `\n\n실패 목록:\n${failedFiles.join('\n')}`;
-  } else {
-    summary += ')';
+  // 다운로드된 파일 목록
+  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`;
+
+  // 내부용 객체 반환 (Push에서 사용)
   return {
-    content: [
-      {
-        type: 'text',
-        text: summary,
-      },
-    ],
+    text: resultText,
+    total,
+    downloaded,
+    updated,
+    skipped,
+    failed,
   };
 }
 
+// docuking_pull 구현 (MCP 도구용 래퍼)
+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 구현
 async function handleList(args) {
   const localPath = args.localPath || process.cwd();

package/package.json

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