docuking-mcp 1.0.0

package/index.js

@@ -0,0 +1,1594 @@
+#!/usr/bin/env node
+
+/**
+ * DocuKing MCP Server
+ *
+ * AI 시대의 문서 협업 플랫폼 - AI가 문서를 Push/Pull 할 수 있게 해주는 MCP 서버
+ *
+ * 도구:
+ * - docuking_init: 레포 연결, Z_DocuKing/ 폴더 생성
+ * - docuking_push: 로컬 → 서버
+ * - docuking_pull: 서버 → 로컬
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+// 환경변수에서 설정 로드
+const API_KEY = process.env.DOCUKING_API_KEY || '';
+const API_ENDPOINT = process.env.DOCUKING_API_ENDPOINT || 'https://docuking.ai/api';
+const REPOS_JSON = process.env.DOCUKING_REPOS || '{}';
+
+// 레포 매핑 파싱
+// 형식: { "경로": { "id": "프로젝트ID", "name": "프로젝트이름" } }
+// 또는 기존 형식: { "경로": "프로젝트ID" } (하위 호환)
+let repoMapping = {};
+try {
+  const parsed = JSON.parse(REPOS_JSON);
+  // 기존 형식(문자열)과 새 형식(객체) 모두 지원
+  for (const [path, value] of Object.entries(parsed)) {
+    if (typeof value === 'string') {
+      // 기존 형식: "경로": "프로젝트ID"
+      repoMapping[path] = { id: value, name: null };
+    } else if (typeof value === 'object' && value.id) {
+      // 새 형식: "경로": { "id": "...", "name": "..." }
+      repoMapping[path] = value;
+    }
+  }
+} catch (e) {
+  console.error('[DocuKing] DOCUKING_REPOS 파싱 실패:', e.message);
+}
+
+// 프로젝트 정보 조회 (로컬 매핑에서, 서버 호출 없음)
+// Git처럼 사용자가 설정한 매핑을 신뢰
+function getProjectInfo(localPath) {
+  const mapped = repoMapping[localPath];
+  if (!mapped) {
+    return {
+      error: `오류: 이 프로젝트는 DocuKing에 연결되지 않았습니다.
+먼저 docuking_init을 실행하세요.`,
+    };
+  }
+
+  return {
+    projectId: mapped.id,
+    projectName: mapped.name,
+  };
+}
+
+// MCP 서버 생성
+const server = new Server(
+  {
+    name: 'docuking-mcp',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// 도구 목록
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'docuking_init',
+        description: '프로젝트를 DocuKing에 연결합니다. Z_DocuKing/ 폴더를 생성하고 레포 매핑을 추가합니다.\n\n**필수 파라미터:**\n- projectId: 프로젝트 UUID\n- projectName: 프로젝트 이름 (표시용)\n- localPath: 로컬 프로젝트 경로',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: {
+              type: 'string',
+              description: 'DocuKing 프로젝트 ID',
+            },
+            projectName: {
+              type: 'string',
+              description: 'DocuKing 프로젝트 이름 (표시용)',
+            },
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (예: /Users/user/my-project)',
+            },
+          },
+          required: ['projectId', 'projectName', 'localPath'],
+        },
+      },
+      {
+        name: 'docuking_push',
+        description: 'z_DocuKing/ 폴더의 문서를 서버에 업로드합니다. "DocuKing에 올려줘" 요청 시 사용. Git의 add + commit + push를 한 번에 수행.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (레포 매핑에서 projectId 찾음)',
+            },
+            filePath: {
+              type: 'string',
+              description: '푸시할 파일 경로 (Z_DocuKing/ 기준 상대경로). 생략 시 전체 동기화.',
+            },
+            message: {
+              type: 'string',
+              description: '커밋 메시지 (필수). Git 커밋 메시지처럼 명확하고 구체적으로 작성. 예: "README에 설치 가이드 추가"',
+            },
+            author: {
+              type: 'string',
+              description: '작성자 (선택). 생략 시 현재 사용자.',
+            },
+          },
+          required: ['localPath', 'message'],
+        },
+      },
+      {
+        name: 'docuking_pull',
+        description: '서버에서 문서를 다운로드하여 z_DocuKing/ 폴더에 저장합니다. "DocuKing에서 가져와" 요청 시 사용.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            filePath: {
+              type: 'string',
+              description: '풀할 파일 경로 (생략 시 전체 동기화)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_list',
+        description: '서버에 저장된 파일 목록을 조회합니다.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (레포 매핑에서 projectId 찾음)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_status',
+        description: '로컬과 서버의 동기화 상태를 확인합니다. 사용자 권한(오너/참여자), 변경/추가/삭제된 파일 목록 표시.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_log',
+        description: '커밋 히스토리를 조회합니다. Git log와 동일.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            path: {
+              type: 'string',
+              description: '특정 파일/폴더의 히스토리만 조회 (선택)',
+            },
+            limit: {
+              type: 'number',
+              description: '최근 N개 커밋만 조회 (기본값: 20)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_diff',
+        description: '버전 간 차이를 비교합니다.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            path: {
+              type: 'string',
+              description: '파일 경로',
+            },
+            version: {
+              type: 'string',
+              description: '비교할 커밋 ID (선택, 생략 시 최신 vs 이전)',
+            },
+          },
+          required: ['localPath', 'path'],
+        },
+      },
+      {
+        name: 'docuking_rollback',
+        description: '특정 커밋으로 되돌립니다.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            commitId: {
+              type: 'string',
+              description: '되돌릴 커밋 ID',
+            },
+            path: {
+              type: 'string',
+              description: '특정 파일만 롤백 (선택, 생략 시 전체)',
+            },
+          },
+          required: ['localPath', 'commitId'],
+        },
+      },
+    ],
+  };
+});
+
+// Resources 목록
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "docuking://docs/manual",
+        name: "DocuKing 사용 설명서",
+        description: "AI가 DocuKing을 이해하고 사용하기 위한 기초 지식",
+        mimeType: "text/markdown"
+      }
+    ]
+  };
+});
+
+// Resource 읽기
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === "docuking://docs/manual") {
+    const manual = `# DocuKing - AI 시대의 문서 협업 플랫폼 (AI용 매뉴얼)
+
+DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하듯, DocuKing은 문서를 관리합니다.
+
+## 핵심 개념
+
+- **로컬**: 사용자의 z_DocuKing/ 폴더
+- **웹탐색기**: DocuKing 서버의 파일 저장소 (로컬 미러)
+- **캔버스**: 선택된 파일을 시각화하는 작업 공간
+
+작동 방식: 로컬 문서 → Push → 웹탐색기 → 캔버스에서 시각화
+
+## MCP 설정과 프로젝트 연결의 차이 (매우 중요!)
+
+### MCP 설정 (전역, 한 번만)
+- **목적**: MCP 서버를 AI 도구(Cursor, Claude Code 등)에 등록
+- **설정 파일 위치**:
+  - Cursor: \`~/.cursor/mcp.json\` (Windows: \`%USERPROFILE%\\.cursor\\mcp.json\`)
+  - Claude Code: \`~/.claude.json\`
+  - 기타 VSCode 계열: 각각의 설정 파일
+- **설정 내용**: \`docuking\` 서버를 \`mcpServers\` 객체에 추가
+- **재시작 필요**: MCP 설정 파일을 처음 만들었을 때만 필요 (Cursor/Claude Code 재시작)
+- **중요**: 이미 다른 MCP 서버가 설정되어 있으면, 기존 설정을 덮어쓰지 말고 \`docuking\` 항목만 추가해야 함
+
+### 프로젝트 연결 (각 폴더마다)
+- **목적**: 특정 로컬 폴더를 DocuKing 서버의 프로젝트 ID와 연결
+- **실행 방법**: \`docuking_init(projectId, localPath)\` 도구 호출
+- **결과**: 해당 폴더에 \`z_DocuKing/\` 폴더 생성 및 프로젝트 매핑 저장
+- **재시작 불필요**: MCP가 이미 작동 중이면 바로 실행 가능
+- **다중 프로젝트**: 한 컴퓨터에서 여러 폴더를 각각 다른 DocuKing 프로젝트와 연결 가능
+
+**핵심 원칙:**
+1. MCP 설정은 한 번만 (모든 폴더 공통)
+2. 프로젝트 연결은 각 폴더마다 (폴더별로 다른 프로젝트 ID)
+3. 이미 MCP가 작동 중이면 재시작 없이 바로 프로젝트 연결 가능
+
+## MCP 도구 목록
+
+### 1. docuking_init
+프로젝트를 DocuKing에 연결합니다.
+
+### 2. docuking_push
+로컬 문서를 서버에 업로드합니다. Git의 add + commit + push를 한 번에 수행.
+**message 파라미터 필수** (커밋 메시지)
+
+### 3. docuking_pull
+서버 문서를 로컬로 다운로드합니다.
+
+### 4. docuking_list
+서버 파일 목록을 조회합니다.
+
+### 5. docuking_status
+로컬과 서버의 동기화 상태를 확인합니다. 사용자 권한(오너/참여자), 변경/추가/삭제된 파일 목록 표시.
+
+### 6. docuking_log
+커밋 히스토리를 조회합니다. (웹 탐색기에서 사용 가능)
+
+### 7. docuking_diff
+버전 간 차이를 비교합니다. (웹 탐색기에서 사용 가능)
+
+### 8. docuking_rollback
+특정 커밋으로 되돌립니다. (웹 탐색기에서 사용 가능)
+
+## Git과의 유사성
+
+| DocuKing | Git | 설명 |
+|----------|-----|------|
+| docuking_push | git add . && git commit -m "..." && git push | 스테이징 + 커밋 + 푸시 통합 |
+| docuking_pull | git pull | 서버 → 로컬 동기화 |
+| docuking_status | git status | 변경 사항 확인 |
+| docuking_log | git log | 커밋 히스토리 |
+| docuking_diff | git diff | 버전 비교 |
+| docuking_rollback | git revert | 되돌리기 |
+
+**핵심 차이점:**
+- Git은 3단계 (add → commit → push)
+- DocuKing은 1단계 (push만으로 완료, 단 message는 필수)
+- 더 간단하지만 커밋 개념은 동일하게 유지
+
+## 자연어 명령어 매핑
+
+| 사용자 말 | MCP 도구 호출 |
+|----------|--------------|
+| "프로젝트 [ID] 연결해줘" | docuking_init({ projectId, localPath }) |
+| "DocuKing에 올려줘" | docuking_push({ localPath, message: "..." }) |
+| "DocuKing에서 가져와" | docuking_pull({ localPath }) |
+| "DocuKing에 뭐 있어?" | docuking_list({ localPath }) |
+
+## 사용 예시
+
+\`\`\`
+사용자: "프로젝트 3b8f95c1 연결해줘"
+AI: docuking_init({ projectId: "3b8f95c1-f557-4a1d-8f1e-f34adb010256", localPath: "/current/path" })
+
+사용자: "DocuKing에 올려줘"
+AI: "어떤 변경인가요? 커밋 메시지를 알려주세요."
+사용자: "문서 업데이트"
+AI: docuking_push({ localPath: "/current/path", message: "문서 업데이트" })
+
+사용자: "DocuKing에서 가져와"
+AI: docuking_pull({ localPath: "/current/path" })
+\`\`\`
+
+## 사용자 권한 및 사용 시나리오 (매우 중요!)
+
+DocuKing에는 **오너(Owner)**와 **참여자(Co-worker)** 두 가지 권한이 있습니다.
+
+### 오너 (Owner) - 프로젝트 생성자
+
+**특징:**
+- 프로젝트를 직접 생성한 사람
+- **모든 폴더**에 문서를 올릴 수 있음 (제한 없음)
+- API Key: sk_로 시작
+- 프로젝트 설정 변경 가능
+- 참여자 초대 가능
+
+**사용 시나리오:**
+1. 프로젝트 생성 (웹에서)
+2. MCP 설정 (한 번만)
+3. 프로젝트 연결 (docuking_init)
+4. 문서 작성 (어디든 자유롭게)
+5. Push (docuking_push)
+
+**예시:**
+\`\`\`
+z_DocuKing/
+├── 정책/
+│   └── README.md  ← 오너가 작성
+├── 기획/
+│   └── 요구사항.md  ← 오너가 작성
+└── 개발/
+    └── API.md  ← 오너가 작성
+\`\`\`
+
+### 참여자 (Co-worker) - 초대받은 사람
+
+**특징:**
+- 프로젝트에 초대받아 참여한 사람
+- **읽기**: 전체 문서 Pull 가능 (오너의 문서도 볼 수 있음)
+- **쓰기**: 자신의 폴더(\`Co-worker/{이름}/\`)에만 Push 가능
+- API Key: \`sk_cw_\`로 시작
+- 프로젝트 설정 변경 불가능
+
+**사용 시나리오:**
+1. 초대 수락 (웹에서)
+2. MCP 설정 (한 번만)
+3. 프로젝트 연결 (\`docuking_init\`)
+4. Pull로 오너의 문서 가져오기 (\`docuking_pull\`)
+5. 내 폴더에 문서 작성 (\`Co-worker/{이름}/\`)
+6. Push (\`docuking_push\`)
+
+**폴더 구조:**
+\`\`\`
+z_DocuKing/
+├── 정책/
+│   └── README.md  ← 오너의 파일 (읽기만 가능)
+├── 기획/
+│   └── 요구사항.md  ← 오너의 파일 (읽기만 가능)
+└── Co-worker/
+    └── 김개발/  ← 참여자 "김개발"의 폴더
+        ├── 제안서.md  ← 여기에만 Push 가능
+        └── 수정안.md  ← 여기에만 Push 가능
+\`\`\`
+
+**중요 규칙:**
+- 참여자가 오너의 폴더를 Pull해서 가지고 있어도, Push할 때는 자동으로 자신의 폴더만 필터링됨
+- 참여자가 다른 폴더에 Push 시도 시 오류 메시지 표시
+- \`docuking_status\`로 현재 권한 확인 가능
+
+**참여자가 오너의 파일을 수정하고 싶을 때:**
+1. 오너의 파일을 Pull해서 로컬에 가져옴 (예: \`정책/README.md\`)
+2. 로컬에서 수정함 (로컬 파일이므로 수정 가능)
+3. Push 시도 → ❌ 오류 발생: "협업자는 Co-worker/{이름}/ 폴더에만 Push할 수 있습니다"
+4. **해결 방법**: 수정한 내용을 자신의 폴더에 새 파일로 작성
+   - 예: \`정책/README.md\`를 수정했다면
+   - → \`Co-worker/김개발/정책_README_수정제안.md\`로 작성 후 Push
+
+**AI가 참여자에게 안내해야 할 내용:**
+- 참여자가 Push를 요청하면, 파일이 \`Co-worker/{이름}/\` 폴더 안에 있는지 확인
+- 다른 폴더에 있는 파일을 Push하려고 하면, 오류 메시지를 명확히 설명하고 해결 방법 제시
+- 오너의 파일을 수정하고 싶다면, 자신의 폴더에 제안서 형태로 작성하도록 안내
+
+## AI 응답 가이드 (중요!)
+
+### docuking_push 사용 시
+
+**사용자 요청 예시:**
+- "DocuKing에 올려줘"
+- "문서 올려줘"
+- "변경사항 업로드해줘"
+
+**AI가 해야 할 일:**
+1. 커밋 메시지가 없으면 반드시 물어보기: "어떤 변경인가요? 커밋 메시지를 알려주세요."
+2. 메시지를 받으면 docuking_push 호출
+3. **결과를 사용자에게 명확하게 전달:**
+   - 총 파일 개수
+   - 업로드된 파일 개수
+   - 스킵된 파일 개수 (변경 없음)
+   - 실패한 파일 개수 (있을 경우)
+   - 업로드된 파일 목록 표시
+   - 스킵된 파일 목록 표시 (변경 없어서 스킵됨)
+
+**응답 예시:**
+Push 완료! 총 10개 파일 중 3개 업로드, 6개 스킵(변경 없음), 1개 실패
+
+### docuking_pull 사용 시
+
+**사용자 요청 예시:**
+- "DocuKing에서 가져와"
+- "서버에서 문서 가져와"
+- "최신 버전 가져와"
+
+**AI가 해야 할 일:**
+1. docuking_pull 호출
+2. **결과를 사용자에게 명확하게 전달:**
+   - 가져온 파일 개수
+   - 가져온 파일 목록 표시
+   - 실패한 파일이 있으면 표시
+
+### docuking_status 사용 시
+
+**사용자 요청 예시:**
+- "DocuKing 상태 확인"
+- "동기화 상태 보여줘"
+- "변경사항 확인"
+
+**AI가 해야 할 일:**
+1. docuking_status 호출
+2. 결과를 그대로 사용자에게 전달 (권한, 파일 개수, 동기화 상태 등)
+
+### 핵심 원칙 (AI 행동 지침)
+
+1. **프로젝트 = 폴더**: 하나의 폴더가 하나의 프로젝트
+2. **각 폴더마다 z_DocuKing/ 생성**: 여러 폴더를 각각 연결 가능
+3. **현재 열려있는 폴더 기준**: 명령어는 현재 작업 중인 폴더에 적용
+4. **커밋 메시지 필수**: push 시 반드시 message 파라미터 포함
+5. **변경 없는 파일 자동 스킵**: 해시 비교로 변경 감지, 스킵된 파일은 결과에 명시
+6. **진행상태 표시**: 총 개수, 진행 중인 개수, 완료 개수를 명확히 표시
+7. **친절한 응답**: 도구 호출 후 상세한 결과를 사용자에게 전달
+8. **MCP 설정 vs 프로젝트 연결 구분**: MCP 설정은 전역(한 번만), 프로젝트 연결은 각 폴더마다
+9. **재시작 최소화**: 이미 MCP가 작동 중이면 재시작 없이 바로 프로젝트 연결 진행
+10. **기존 설정 보호**: MCP 설정 시 기존 서버 설정을 덮어쓰지 말고 추가만
+
+### MCP 설정 관련 (AI가 처리해야 할 경우)
+
+**사용자 요청 예시:**
+- "MCP 설정해줘"
+- "AI 연결하기"
+- "DocuKing MCP 설정"
+
+**AI가 해야 할 일:**
+1. **먼저 확인**: 이미 MCP가 작동 중인지 확인 (도구 호출 가능 여부로 판단)
+2. **이미 작동 중이면**: "MCP는 이미 설정되어 있습니다. 바로 프로젝트 연결을 진행하겠습니다."라고 안내하고 프로젝트 연결로 진행
+3. **설정이 필요하면**:
+   - 사용자의 AI 도구 종류 확인 (Cursor, Claude Code 등)
+   - 해당 설정 파일 경로 안내
+   - **기존 MCP 서버가 있으면 덮어쓰지 말고 추가만 하도록 명확히 안내**
+   - 설정 완료 후 재시작 안내 (재시작 후 프로젝트 연결 단계로 진행)
+
+**MCP 설정 파일 예시 (기존 서버가 있는 경우):**
+\`\`\`json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"]
+    },
+    "docuking": {
+      "command": "npx",
+      "args": ["-y", "docuking-mcp"],
+      "env": {
+        "DOCUKING_API_KEY": "sk_xxx",
+        "DOCUKING_API_ENDPOINT": "https://docuking.ai/api"
+      }
+    }
+  }
+}
+\`\`\`
+**⚠️ 중요**: 기존 설정을 덮어쓰지 말고 \`docuking\` 항목만 추가해야 함!
+
+### 프로젝트 연결
+
+**사용자 요청 예시:**
+- "이 프로젝트를 DocuKing에 연결해줘. 프로젝트 ID는 [ID]"
+- "프로젝트 [ID] 연결해줘"
+- "이 폴더를 DocuKing에 연결해줘"
+
+**AI가 해야 할 일:**
+1. 현재 폴더 경로 확인 (작업 중인 디렉토리)
+2. 프로젝트 ID 확인 (사용자가 제공하거나 요청)
+3. \`docuking_init(projectId, localPath)\` 호출
+4. 연결 완료 메시지 전달:
+   - "DocuKing 연결 완료! 📁 z_DocuKing/ 폴더가 생성되었습니다."
+   - "이제 'DocuKing에 올려줘' 명령을 사용할 수 있습니다."
+
+**⚠️ 매우 중요:**
+- **MCP가 이미 작동 중이면 재시작 없이 바로 \`docuking_init\`을 호출하면 됩니다**
+- 재시작이 필요한 경우는 MCP 설정 파일을 처음 만들었을 때뿐입니다
+- 사용자가 "재시작이 필요합니다"라고 말해도, 이미 MCP가 작동 중이면 무시하고 바로 프로젝트 연결을 진행하세요
+
+### 여러 프로젝트 관리 (다중 프로젝트)
+
+**핵심 개념:**
+- **프로젝트 = 하나의 폴더**
+- 한 컴퓨터에서 여러 폴더를 각각 다른 DocuKing 프로젝트와 연결 가능
+- 각 폴더마다 \`z_DocuKing/\` 폴더가 독립적으로 생성됨
+
+**예시:**
+\`\`\`
+C:\\Projects\\MyApp\\
+├── src/
+├── package.json
+└── z_DocuKing/          ← 프로젝트 A와 연결
+
+C:\\Projects\\MyWebsite\\
+├── pages/
+├── components/
+└── z_DocuKing/          ← 프로젝트 B와 연결
+
+D:\\Work\\ClientProject\\
+├── docs/
+└── z_DocuKing/          ← 프로젝트 C와 연결
+\`\`\`
+
+**AI가 해야 할 일:**
+- 각 폴더에서 \`docuking_init\`을 호출하면 해당 폴더만 연결됨
+- 다른 폴더로 이동하면 해당 폴더의 \`z_DocuKing/\`가 사용됨
+- 여러 프로젝트를 동시에 관리할 수 있음을 인지하고, 현재 작업 중인 폴더 기준으로 동작
+
+**고급: DOCUKING_REPOS 환경변수 (선택사항)**
+- 여러 프로젝트를 미리 등록하려면 MCP 설정의 \`env\`에 \`DOCUKING_REPOS\` 추가 가능
+- 형식: \`{"경로1":{"id":"프로젝트ID1","name":"프로젝트이름1"},"경로2":{"id":"프로젝트ID2","name":"프로젝트이름2"}}\`
+- 기존 형식도 지원: \`{"경로1":"프로젝트ID1","경로2":"프로젝트ID2"}\` (하위 호환)
+- 이 방법은 선택사항이며, 각 폴더에서 \`docuking_init\`을 실행해도 됨
+
+웹 탐색기: https://docuking.ai
+`;
+
+    return {
+      contents: [{
+        uri: "docuking://docs/manual",
+        mimeType: "text/markdown",
+        text: manual
+      }]
+    };
+  }
+
+  throw new Error("Unknown resource");
+});
+
+// 도구 실행
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'docuking_init':
+        return await handleInit(args);
+      case 'docuking_push':
+        return await handlePush(args);
+      case 'docuking_pull':
+        return await handlePull(args);
+      case 'docuking_list':
+        return await handleList(args);
+      case 'docuking_status':
+        return await handleStatus(args);
+      case 'docuking_log':
+        return await handleLog(args);
+      case 'docuking_diff':
+        return await handleDiff(args);
+      case 'docuking_rollback':
+        return await handleRollback(args);
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: ${error.message}`,
+        },
+      ],
+    };
+  }
+});
+
+// docuking_init 구현
+async function handleInit(args) {
+  const { projectId, projectName, localPath } = args;
+
+  if (!API_KEY) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: DOCUKING_API_KEY가 설정되지 않았습니다.
+
+MCP 설정에 다음을 추가하세요:
+"env": {
+  "DOCUKING_API_KEY": "your-api-key"
+}`,
+        },
+      ],
+    };
+  }
+
+  // z_DocuKing 폴더 생성 (항상 새로 만듦)
+  const folderName = 'z_DocuKing';
+  const docuKingPath = path.join(localPath, folderName);
+
+  if (!fs.existsSync(docuKingPath)) {
+    fs.mkdirSync(docuKingPath, { recursive: true });
+  }
+
+  // JSON 이스케이프 처리
+  const escapedPath = localPath.replace(/\\/g, '\\\\');
+  const repoConfig = `{\\"${escapedPath}\\":{\\"id\\":\\"${projectId}\\",\\"name\\":\\"${projectName}\\"}}`;
+
+  // 연결 완료 안내
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `DocuKing 연결 완료!
+
+📁 프로젝트: ${projectName}
+📂 z_DocuKing/ 폴더가 생성되었습니다.
+
+이제부터 문서 관리는 DocuKing에서 시작합니다:
+- z_DocuKing/ 하위에 문서를 넣으면 DocuKing 서버로 암호화되어 저장됩니다
+- 협업자들과 안전하게 문서를 공유할 수 있습니다
+
+사용법:
+- "DocuKing에 올려줘" → 로컬 문서를 서버에 Push
+- "DocuKing에서 가져와" → 서버 문서를 로컬로 Pull
+
+MCP 설정에 레포 매핑 추가 필요:
+"DOCUKING_REPOS": "${repoConfig}"`,
+      },
+    ],
+  };
+}
+
+// docuking_push 구현
+async function handlePush(args) {
+  const { localPath, filePath, message, author } = args;
+
+  // 커밋 메시지 필수 체크
+  if (!message || message.trim() === '') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: 커밋 메시지가 필요합니다.
+
+Git처럼 무엇을 변경했는지 명확히 작성해주세요.
+예: "README에 설치 가이드 추가"`,
+        },
+      ],
+    };
+  }
+
+  // 프로젝트 정보 조회 (로컬 매핑에서)
+  const projectInfo = getProjectInfo(localPath);
+  if (projectInfo.error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: projectInfo.error,
+        },
+      ],
+    };
+  }
+
+  const projectId = projectInfo.projectId;
+  const projectName = projectInfo.projectName;
+
+  // DocuKing 폴더 찾기
+  const folderName = findDocuKingFolder(localPath);
+  if (!folderName) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: DocuKing 폴더가 없습니다.
+docuking_init을 먼저 실행하세요.`,
+        },
+      ],
+    };
+  }
+  const docuKingPath = path.join(localPath, folderName);
+
+  // Co-worker 권한은 API Key 형식에서 판단 (sk_xxx_cw_이름_)
+  const coworkerMatch = API_KEY.match(/^sk_[a-f0-9]+_cw_([^_]+)_/);
+  const allowedPathPrefix = coworkerMatch ? `Co-worker/${coworkerMatch[1]}/` : null;
+
+  // 파일 목록 수집
+  const filesToPush = [];
+  const excludedFiles = []; // 제외된 파일 목록
+
+  if (filePath) {
+    // 특정 파일만
+    const fullPath = path.join(docuKingPath, 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   문서에 다운로드 링크나 설치 가이드를 작성하세요.`,
+            },
+          ],
+        };
+      }
+
+      // 참여자인 경우 경로 체크
+      if (allowedPathPrefix) {
+        const normalizedPath = filePath.toLowerCase();
+        const normalizedPrefix = allowedPathPrefix.toLowerCase();
+        if (!normalizedPath.startsWith(normalizedPrefix)) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `오류: 협업자는 ${allowedPathPrefix} 폴더에만 Push할 수 있습니다.\n\n요청한 파일: ${filePath}\n허용된 경로: ${allowedPathPrefix}\n\n💡 참고: 오너의 파일을 로컬에서 수정하셨다면, 수정 내용을 ${allowedPathPrefix} 폴더에 새 파일로 작성해주세요.\n예: 정책/README.md를 수정했다면 → ${allowedPathPrefix}정책_README_수정제안.md`,
+              },
+            ],
+          };
+        }
+      }
+
+      filesToPush.push({ path: filePath, fullPath, fileType });
+    }
+  } else {
+    // 전체 파일 - 제외된 파일 목록도 수집
+    collectFiles(docuKingPath, '', filesToPush, excludedFiles);
+
+    // 참여자인 경우 허용된 경로의 파일만 필터링
+    if (allowedPathPrefix) {
+      const normalizedPrefix = allowedPathPrefix.toLowerCase();
+      const filteredFiles = filesToPush.filter(file => {
+        const normalizedPath = file.path.toLowerCase();
+        return normalizedPath.startsWith(normalizedPrefix);
+      });
+
+      if (filteredFiles.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Push할 파일이 없습니다.\n\n협업자는 ${allowedPathPrefix} 폴더에만 Push할 수 있습니다.\n\n현재 폴더 구조를 확인하고, 해당 폴더에 파일을 배치한 후 다시 시도해주세요.`,
+            },
+          ],
+        };
+      }
+
+      // 필터링된 파일로 교체
+      filesToPush.length = 0;
+      filesToPush.push(...filteredFiles);
+
+      console.log(`[DocuKing] 협업자 권한: ${filteredFiles.length}개 파일만 Push (${allowedPathPrefix})`);
+    }
+  }
+
+  if (filesToPush.length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Push할 파일이 없습니다.',
+        },
+      ],
+    };
+  }
+
+  // 파일 업로드 (진행률 표시)
+  const results = [];
+  const total = filesToPush.length;
+  let current = 0;
+  let skipped = 0;
+
+  // 시작 안내 메시지 출력 (AI가 사용자에게 전달할 수 있도록)
+  console.error(`[DocuKing] Push 시작: ${total}개 파일`);
+  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 ${API_KEY}`,
+      },
+      body: JSON.stringify({ totalFiles: total }),
+    });
+  } catch (e) {
+    console.error('[DocuKing] Sync 시작 알림 실패:', e.message);
+  }
+
+  // 서버에서 파일 해시 조회 (변경 감지용)
+  let serverFileHashes = {};
+  try {
+    const hashResponse = await fetch(
+      `${API_ENDPOINT}/files/hashes?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`,
+        },
+      }
+    );
+    if (hashResponse.ok) {
+      const hashData = await hashResponse.json();
+      serverFileHashes = hashData.hashes || {};
+    }
+  } catch (e) {
+    // 해시 조회 실패는 무시 (처음 Push하는 경우 등)
+    console.error('[DocuKing] 파일 해시 조회 실패:', e.message);
+  }
+
+  for (const file of filesToPush) {
+    current++;
+    const progress = `${current}/${total}`;
+
+    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');
+      }
+
+      // 변경 감지: 서버에 같은 해시가 있으면 스킵
+      if (serverFileHashes[file.path] === fileHash) {
+        const resultText = `${progress} ⊘ ${file.path} (변경 없음)`;
+        results.push(resultText);
+        console.log(resultText);
+        skipped++;
+        continue;
+      }
+
+      // 재시도 로직 (최대 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 ${API_KEY}`,
+              },
+              body: JSON.stringify({
+                projectId,
+                path: file.path,
+                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);
+            console.log(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초
+              console.log(`${progress} ⚠ ${file.path}: 재시도 ${attempt}/3 (${waitTime}ms 후)`);
+              await new Promise(resolve => setTimeout(resolve, waitTime));
+            }
+          }
+        } catch (e) {
+          lastError = e.message;
+          // 네트워크 오류 등은 재시도
+          if (attempt < 3 && !e.message.includes('타임아웃')) {
+            const waitTime = attempt * 1000;
+            console.log(`${progress} ⚠ ${file.path}: 재시도 ${attempt}/3 (${waitTime}ms 후) - ${e.message}`);
+            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 ${API_KEY}`,
+            },
+            body: JSON.stringify({ progress: current }),
+          });
+        } catch (e) {
+          // 진행 상황 업데이트 실패는 무시
+        }
+      }
+    } catch (e) {
+      results.push(`${progress} ✗ ${file.path}: ${e.message}`);
+    }
+  }
+
+  // Sync 완료 알림
+  try {
+    await fetch(`${API_ENDPOINT}/projects/${projectId}/sync/complete`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${API_KEY}`,
+      },
+    });
+  } 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;
+
+  // 요약 정보
+  let summary = `\n📦 커밋 메시지: "${message}"\n\n📊 처리 결과:\n   - 총 파일: ${total}개\n   - 업로드: ${successCount}개\n   - 스킵 (변경 없음): ${skippedCount}개\n   - 실패: ${failCount}개`;
+  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')}`;
+  }
+
+  // 스킵된 파일이 있으면 표시
+  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`;
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: resultText,
+      },
+    ],
+  };
+}
+
+// docuking_pull 구현
+async function handlePull(args) {
+  const { localPath, filePath } = args;
+
+  // 프로젝트 정보 조회 (로컬 매핑에서)
+  const projectInfo = getProjectInfo(localPath);
+  if (projectInfo.error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: projectInfo.error,
+        },
+      ],
+    };
+  }
+
+  const projectId = projectInfo.projectId;
+
+  // DocuKing 폴더 찾기 (없으면 기본값으로 생성)
+  let folderName = findDocuKingFolder(localPath);
+  if (!folderName) {
+    folderName = 'z_DocuKing';
+  }
+  const docuKingPath = path.join(localPath, folderName);
+
+  // 파일 목록 조회
+  let files = [];
+
+  try {
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`,
+        },
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+
+    const data = await response.json();
+    files = flattenTree(data.tree || []);
+  } catch (e) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: 파일 목록 조회 실패 - ${e.message}`,
+        },
+      ],
+    };
+  }
+
+  if (filePath) {
+    files = files.filter(f => f.path === filePath || f.path.startsWith(filePath + '/'));
+  }
+
+  if (files.length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Pull할 파일이 없습니다.',
+        },
+      ],
+    };
+  }
+
+  // 파일 다운로드
+  const results = [];
+  for (const file of files) {
+    try {
+      const response = await fetch(
+        `${API_ENDPOINT}/files?projectId=${projectId}&path=${encodeURIComponent(file.path)}`,
+        {
+          headers: {
+            'Authorization': `Bearer ${API_KEY}`,
+          },
+        }
+      );
+
+      if (!response.ok) {
+        results.push(`✗ ${file.path}: ${await response.text()}`);
+        continue;
+      }
+
+      const data = await response.json();
+      const fullPath = path.join(docuKingPath, 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';
+
+      if (encoding === 'base64') {
+        // Base64 디코딩 후 바이너리로 저장
+        const buffer = Buffer.from(content, 'base64');
+        fs.writeFileSync(fullPath, buffer);
+      } else {
+        // UTF-8 텍스트로 저장
+        fs.writeFileSync(fullPath, content, 'utf-8');
+      }
+
+      results.push(`✓ ${file.path}`);
+    } catch (e) {
+      results.push(`✗ ${file.path}: ${e.message}`);
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Pull 완료!\n\n${results.join('\n')}`,
+      },
+    ],
+  };
+}
+
+// docuking_list 구현
+async function handleList(args) {
+  const { localPath } = args;
+
+  // 프로젝트 정보 조회 (로컬 매핑에서)
+  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 ${API_KEY}`,
+        },
+      }
+    );
+
+    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}`,
+        },
+      ],
+    };
+  }
+}
+
+// 파일 타입 정의
+const FILE_TYPES = {
+  // 텍스트 파일 (UTF-8)
+  TEXT: [
+    '.md', '.txt', '.json', '.xml', '.yaml', '.yml',
+    '.html', '.htm', '.css', '.js', '.ts', '.jsx', '.tsx',
+    '.py', '.java', '.go', '.rs', '.rb', '.php', '.c', '.cpp', '.h',
+    '.csv', '.svg', '.sql', '.sh', '.ps1', '.bat', '.cmd',
+    '.env', '.gitignore', '.dockerignore', '.editorconfig',
+    '.properties', '.ini', '.toml', '.conf', '.cfg',
+  ],
+
+  // 바이너리 파일 (Base64)
+  BINARY: [
+    // 이미지
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.tiff',
+    // 오피스
+    '.xlsx', '.xls', '.docx', '.doc', '.pptx', '.ppt',
+    // PDF
+    '.pdf',
+    // 한글
+    '.hwpx', '.hwp',
+  ],
+
+  // 제외 파일 (업로드 거부) - 설치파일/대용량 파일은 별도 공유 권장
+  EXCLUDED: [
+    // 압축/아카이브 (설치파일 포함 가능성 높음)
+    '.zip', '.tar', '.gz', '.tgz', '.7z', '.rar', '.tar.Z',
+    // Java 아카이브
+    '.jar', '.war', '.ear', '.class',
+    // 실행파일
+    '.exe', '.msi', '.dll', '.so', '.dylib', '.com', '.app', '.pkg', '.deb', '.rpm',
+    // macOS 스크립트
+    '.scpt',
+    // 동영상
+    '.mp4', '.avi', '.mov', '.mkv', '.wmv', '.flv', '.webm', '.m4v',
+    // 오디오
+    '.mp3', '.wav', '.flac', '.aac', '.ogg', '.wma', '.m4a',
+    // 디스크 이미지
+    '.iso', '.dmg', '.img', '.vhd', '.vmdk',
+  ],
+};
+
+function getFileType(fileName) {
+  const ext = path.extname(fileName).toLowerCase();
+
+  // .tar.gz, .tar.Z 등 복합 확장자 처리
+  if (fileName.endsWith('.tar.gz') || fileName.endsWith('.tar.Z')) {
+    return 'binary';
+  }
+
+  if (FILE_TYPES.EXCLUDED.includes(ext)) {
+    return 'excluded';
+  }
+  if (FILE_TYPES.BINARY.includes(ext)) {
+    return 'binary';
+  }
+  if (FILE_TYPES.TEXT.includes(ext)) {
+    return 'text';
+  }
+
+  // 알 수 없는 확장자는 바이너리로 처리 (안전)
+  return 'binary';
+}
+
+// 유틸: DocuKing 폴더 찾기 (docuking 포함, 대소문자 무관)
+function findDocuKingFolder(projectPath) {
+  try {
+    const entries = fs.readdirSync(projectPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.toLowerCase().includes('docuking')) {
+        return entry.name;
+      }
+    }
+  } catch (e) {
+    // 디렉토리 읽기 실패
+  }
+  return null;
+}
+
+// 유틸: 디렉토리 재귀 탐색
+// excludedFiles: 제외된 파일 목록을 수집할 배열 (선택)
+function collectFiles(basePath, relativePath, results, excludedFiles = null) {
+  const fullPath = path.join(basePath, relativePath);
+  const entries = fs.readdirSync(fullPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      collectFiles(basePath, entryRelPath, results, excludedFiles);
+    } else if (entry.isFile()) {
+      const fileType = getFileType(entry.name);
+
+      // 제외 파일은 건너뜀 (excludedFiles 배열이 있으면 수집)
+      if (fileType === 'excluded') {
+        console.error(`[DocuKing] 제외됨: ${entryRelPath} (지원하지 않는 파일 형식)`);
+        if (excludedFiles) {
+          excludedFiles.push(entryRelPath);
+        }
+        continue;
+      }
+
+      results.push({
+        path: entryRelPath,
+        fullPath: path.join(fullPath, entry.name),
+        fileType, // 'text' 또는 'binary'
+      });
+    }
+  }
+}
+
+// 유틸: 트리 구조를 평탄화
+function flattenTree(tree, prefix = '') {
+  const results = [];
+
+  for (const item of tree) {
+    const itemPath = prefix ? `${prefix}/${item.name}` : item.name;
+
+    if (item.type === 'file') {
+      results.push({ path: itemPath, name: item.name });
+    } else if (item.children) {
+      results.push(...flattenTree(item.children, itemPath));
+    }
+  }
+
+  return results;
+}
+
+// docuking_status 구현
+async function handleStatus(args) {
+  const { localPath } = args;
+
+  // 프로젝트 정보 조회 (로컬 매핑에서)
+  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 형식에서 판단 (sk_xxx_cw_이름_)
+  const coworkerMatch = API_KEY.match(/^sk_[a-f0-9]+_cw_([^_]+)_/);
+  const isCoworker = !!coworkerMatch;
+  const coworkerName = coworkerMatch ? coworkerMatch[1] : null;
+  const allowedPathPrefix = isCoworker ? `Co-worker/${coworkerName}/` : null;
+
+  // 권한 정보 구성
+  let permissionInfo = '';
+  if (isCoworker) {
+    permissionInfo = `\n\n## 현재 권한: 참여자 (Co-worker)
+- 이름: ${coworkerName}
+- 읽기 권한: 전체 문서 (제한 없음)
+- 쓰기 권한: ${allowedPathPrefix} 폴더만
+- 설명: 다른 폴더의 파일을 Pull해서 가지고 있어도, Push할 때는 자동으로 ${allowedPathPrefix} 폴더의 파일만 Push됩니다.`;
+  } else {
+    permissionInfo = `\n\n## 현재 권한: 오너 (Owner)
+- 읽기 권한: 전체 문서
+- 쓰기 권한: 전체 문서 (제한 없음)
+- 설명: 프로젝트의 모든 폴더에 Push할 수 있습니다.`;
+  }
+
+  // 서버 파일 목록 조회
+  let serverFiles = [];
+  try {
+    const response = await fetch(
+      `${API_ENDPOINT}/files/tree?projectId=${projectId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`,
+        },
+      }
+    );
+    if (response.ok) {
+      const data = await response.json();
+      serverFiles = flattenTree(data.tree || []);
+    }
+  } catch (e) {
+    console.error('[DocuKing] 파일 목록 조회 실패:', e.message);
+  }
+
+  // 로컬 파일 목록 조회
+  const folderName = findDocuKingFolder(localPath);
+  const docuKingPath = folderName ? path.join(localPath, folderName) : null;
+  let localFiles = [];
+  if (docuKingPath && fs.existsSync(docuKingPath)) {
+    collectFiles(docuKingPath, '', localFiles);
+  }
+
+  // 참여자인 경우 Push 가능한 파일만 필터링
+  let pushableFiles = localFiles;
+  if (allowedPathPrefix) {
+    const normalizedPrefix = allowedPathPrefix.toLowerCase();
+    pushableFiles = localFiles.filter(file => {
+      const normalizedPath = file.path.toLowerCase();
+      return normalizedPath.startsWith(normalizedPrefix);
+    });
+  }
+
+  const projectNameInfo = projectName ? ` (${projectName})` : '';
+  const statusText = `DocuKing 동기화 상태
+
+**프로젝트**: ${projectId}${projectNameInfo}
+**로컬 파일**: ${localFiles.length}개
+**서버 파일**: ${serverFiles.length}개${allowedPathPrefix ? `\n**Push 가능한 파일**: ${pushableFiles.length}개 (${allowedPathPrefix})` : ''}${permissionInfo}
+
+## 사용 가능한 작업
+- **Push**: docuking_push({ localPath, message: "..." })
+- **Pull**: docuking_pull({ localPath })
+- **목록 조회**: docuking_list({ localPath })`;
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: statusText,
+      },
+    ],
+  };
+}
+
+// docuking_log 구현
+async function handleLog(args) {
+  const { localPath, path: filePath, limit = 20 } = args;
+
+  const projectId = repoMapping[localPath];
+  if (!projectId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: 이 프로젝트는 DocuKing에 연결되지 않았습니다.`,
+        },
+      ],
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `log 도구는 아직 구현 중입니다.\n\n웹 탐색기(https://docuking.ai)에서 커밋 히스토리를 확인할 수 있습니다.`,
+      },
+    ],
+  };
+}
+
+// docuking_diff 구현
+async function handleDiff(args) {
+  const { localPath, path, version } = args;
+
+  const projectId = repoMapping[localPath];
+  if (!projectId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: 이 프로젝트는 DocuKing에 연결되지 않았습니다.`,
+        },
+      ],
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `diff 도구는 아직 구현 중입니다.\n\n웹 탐색기에서 파일 버전 비교를 사용할 수 있습니다.`,
+      },
+    ],
+  };
+}
+
+// docuking_rollback 구현
+async function handleRollback(args) {
+  const { localPath, commitId, path } = args;
+
+  const projectId = repoMapping[localPath];
+  if (!projectId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: 이 프로젝트는 DocuKing에 연결되지 않았습니다.`,
+        },
+      ],
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `rollback 도구는 아직 구현 중입니다.\n\n웹 탐색기에서 파일 롤백을 사용할 수 있습니다.`,
+      },
+    ],
+  };
+}
+
+// 서버 시작
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[DocuKing MCP] 서버 시작됨');
+}
+
+main().catch(console.error);