docuking-mcp 2.5.3 → 2.5.5

package/index.js

@@ -10,13 +10,13 @@
  * - yy_All_Docu/_Infra_Config/: 민감 정보 백업 (.env 자동 복사, 팀 공유)
  * - yy_All_Docu/_Private/     : 오너 비공개 폴더 (오너만 접근)
  * - yy_Coworker_{폴더명}/     : 협업자 폴더 (yy_All_Docu와 별도, 동기화 대상)
- * - zz_ai_1_Talk/             : AI 대화록 (킹톡)
- * - zz_ai_2_Todo/             : AI 투두 (킹투두)
- * - zz_ai_3_Plan/             : AI 플랜 (킹플랜)
+ * - zz_ai_1_Talk/             : AI 대화록 (킹톡, Push 대상)
+ * - zz_ai_2_Todo/             : AI 투두 (킹투두, Push 대상)
+ * - zz_ai_3_Plan/             : AI 플랜 (킹플랜, Push 대상)
  *
  * 접두사 규칙:
- * - yy_ : 사람용 폴더 (문서, 협업자)
- * - zz_ : AI용 폴더 (Talk, Todo, Plan)
+ * - yy_ : 사람용 폴더 (문서, 협업자) - Push 대상
+ * - zz_ai_ : AI용 폴더 (Talk, Todo, Plan) - Push 대상
  * - _   : 비공개 폴더 (본인만 접근)
  *
  * 도구:
@@ -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: {
@@ -530,7 +538,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'docuking_talk',
-        description: '의미 있는 대화 내용을 zz_ai_1_Talk/ 폴더에 기록합니다 (로컬 전용, 킹톡). AI가 중요한 논의/결정이라고 판단하거나, 사용자가 "이거 기록해줘"라고 요청할 때 사용.',
+        description: '의미 있는 대화 내용을 zz_ai_1_Talk/ 폴더에 기록합니다 (Push 대상, 킹톡). AI가 중요한 논의/결정이라고 판단하거나, 사용자가 "이거 기록해줘"라고 요청할 때 사용.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -557,7 +565,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'docuking_plan',
-        description: '작업 계획 문서를 zz_ai_3_Plan/ 폴더에 생성/업데이트합니다 (로컬 전용, 킹플랜). 작업 시작 시 계획을 작성하고, 진행하면서 결과를 upsert합니다.',
+        description: '작업 계획 문서를 zz_ai_3_Plan/ 폴더에 생성/업데이트합니다 (Push 대상, 킹플랜). 작업 시작 시 계획을 작성하고, 진행하면서 결과를 upsert합니다.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -626,7 +634,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'docuking_todo',
-        description: `킹투두(King Todo) - 프로젝트 공식 할일을 zz_ai_2_Todo/z_King_Todo.md에 관리합니다 (로컬 전용).
+        description: `킹투두(King Todo) - 프로젝트 공식 할일을 zz_ai_2_Todo/z_King_Todo.md에 관리합니다 (Push 대상).
 
 **AI 내장 TodoWrite와 다름!** 킹투두는 웹에 동기화되고 팀과 공유됩니다.
 
@@ -700,7 +708,7 @@ DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하
 - **로컬**: 사용자의 yy_All_Docu/ 폴더 (동기화 대상)
 - **웹탐색기**: DocuKing 서버의 파일 저장소 (킹폴더)
 - **캔버스**: 선택된 파일을 시각화하는 작업 공간
-- **AI 작업 폴더**: zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ (로컬 전용)
+- **AI 작업 폴더**: zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ (Push 대상)
 
 작동 방식: 로컬 yy_All_Docu/ → Push → 킹폴더 → 캔버스에서 시각화
 
@@ -773,12 +781,12 @@ zz_ai_3_Plan/
 특정 커밋으로 되돌립니다. (웹 탐색기에서 사용 가능)
 
 ### 9. docuking_talk
-의미 있는 대화 내용을 \`zz_ai_1_Talk/\` 폴더에 기록합니다 (로컬 전용, 킹톡).
+의미 있는 대화 내용을 \`zz_ai_1_Talk/\` 폴더에 기록합니다 (Push 대상, 킹톡).
 - AI가 중요한 논의/결정이라고 판단할 때
 - 사용자가 "이거 기록해줘"라고 요청할 때
 
 ### 10. docuking_plan
-작업 계획을 \`zz_ai_3_Plan/\` 폴더에 생성/업데이트합니다 (로컬 전용, 킹플랜).
+작업 계획을 \`zz_ai_3_Plan/\` 폴더에 생성/업데이트합니다 (Push 대상, 킹플랜).
 - 작업 시작 시 계획 생성
 - 진행하면서 단계별 결과 upsert
 - planId로 기존 계획 찾아서 업데이트
@@ -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 대화록 (로컬 전용)
-├── zz_ai_2_Todo/                     ← AI 투두 (로컬 전용)
-└── zz_ai_3_Plan/                     ← AI 플랜 (로컬 전용)
+├── 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 응답 가이드 (중요!)
 
@@ -989,7 +1026,7 @@ AI: (결정이 내려졌으므로 docuking_talk 호출)
     })
 \`\`\`
 
-**저장 위치:** \`zz_ai_1_Talk/YYYY-MM-DD_HHMM__제목.md\` (플랫 구조, 로컬 전용)
+**저장 위치:** \`zz_ai_1_Talk/YYYY-MM-DD_HHMM__제목.md\` (플랫 구조, Push 대상)
 
 ### 작업 계획 관리 (docuking_plan, docuking_done)
 
@@ -1040,7 +1077,7 @@ AI: docuking_done({
     })
 \`\`\`
 
-**저장 위치:** \`zz_ai_3_Plan/YYYY-MM-DD_HHMM__제목__planId.md\` (플랫 구조, 로컬 전용)
+**저장 위치:** \`zz_ai_3_Plan/YYYY-MM-DD_HHMM__제목__planId.md\` (플랫 구조, Push 대상)
 
 **핵심 가치:**
 - AI 세션이 끊겨도 (컴팩션, 세션 종료) 다음 AI가 계획 문서를 보고 이어서 작업 가능
@@ -1116,15 +1153,15 @@ C:\\Projects\\MyApp\\
 ├── src/
 ├── package.json
 ├── yy_All_Docu/          ← 프로젝트 A와 연결 (동기화)
-├── zz_ai_1_Talk/           ← AI 대화록 (로컬 전용)
-├── zz_ai_2_Todo/           ← AI 투두 (로컬 전용)
-└── zz_ai_3_Plan/           ← AI 플랜 (로컬 전용)
+├── zz_ai_1_Talk/           ← AI 대화록 (Push 대상)
+├── zz_ai_2_Todo/           ← AI 투두 (Push 대상)
+└── zz_ai_3_Plan/           ← AI 플랜 (Push 대상)
 
 C:\\Projects\\MyWebsite\\
 ├── pages/
 ├── components/
 ├── yy_All_Docu/          ← 프로젝트 B와 연결
-└── zz_ai_*/              ← 로컬 전용 폴더들
+└── zz_ai_*/              ← AI 작업 폴더들 (Push 대상)
 \`\`\`
 
 **AI가 해야 할 일:**
@@ -1326,9 +1363,9 @@ docuking_init 호출 시 apiKey 파라미터를 포함해주세요.`,
 
 폴더 구조:
 - yy_All_Docu/     : 동기화 대상 (킹폴더)
-- zz_ai_1_Talk/      : AI 대화록 (로컬 전용, 킹톡)
-- zz_ai_2_Todo/      : AI 투두 (로컬 전용, 킹투두)
-- zz_ai_3_Plan/      : AI 플랜 (로컬 전용, 킹플랜)`,
+- zz_ai_1_Talk/      : AI 대화록 (Push 대상, 킹톡)
+- zz_ai_2_Todo/      : AI 투두 (Push 대상, 킹투두)
+- zz_ai_3_Plan/      : AI 플랜 (Push 대상, 킹플랜)`,
         },
       ],
     };
@@ -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') {
-        // Base64 디코딩 후 바이너리로 저장
-        const buffer = Buffer.from(content, 'base64');
-        fs.writeFileSync(fullPath, buffer);
+        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 {
-        // 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();
@@ -2368,10 +2545,9 @@ function collectFilesSimple(basePath, relativePath, results, excludedFiles = nul
   }
 }
 
-// 유틸: 디렉토리 재귀 탐색 (기존 호환용)
+// 유틸: 디렉토리 재귀 탐색 (기존 호환용, 현재 미사용)
 // excludedFiles: 제외된 파일 목록을 수집할 배열 (선택)
 // largeFiles: 대용량 파일 목록을 수집할 배열 (선택)
-// zz_* 폴더는 로컬 전용이므로 동기화에서 제외
 function collectFiles(basePath, relativePath, results, excludedFiles = null, largeFiles = null) {
   const fullPath = path.join(basePath, relativePath);
   const entries = fs.readdirSync(fullPath, { withFileTypes: true });
@@ -2380,11 +2556,6 @@ function collectFiles(basePath, relativePath, results, excludedFiles = null, lar
     const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
 
     if (entry.isDirectory()) {
-      // zz_* 폴더는 로컬 전용 (AI 작업 기록 등)이므로 동기화에서 제외
-      if (entry.name.startsWith('zz_')) {
-        console.error(`[DocuKing] 제외됨: ${entryRelPath}/ (zz_* 폴더 - 로컬 전용)`);
-        continue;
-      }
       collectFiles(basePath, entryRelPath, results, excludedFiles, largeFiles);
     } else if (entry.isFile()) {
       const fileType = getFileType(entry.name);

package/package.json

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