docuking-mcp 2.10.0 → 2.11.0

package/README.md

@@ -2,22 +2,42 @@
 
 AI가 문서를 Push/Pull 할 수 있게 해주는 MCP 서버
 
-## 설치
+## 설치 (글로벌 설치 권장)
 
 ```bash
-npx docuking-mcp
+# 1. 글로벌 설치
+npm install -g docuking-mcp
+
+# 2. MCP 등록 (Claude Code)
+claude mcp add docuking -s user -- docuking-mcp
+```
+
+### 업데이트
+
+```bash
+npm update -g docuking-mcp
 ```
 
+> **참고**: MCP는 새 버전이 있으면 첫 도구 호출 시 자동으로 알려줍니다.
+
 ## MCP 설정
 
-### Claude Code
+### Claude Code (CLI로 등록)
+
+```bash
+claude mcp add docuking -s user -- docuking-mcp
+```
+
+### Claude Code (JSON으로 등록)
+
+`~/.claude.json`에 추가:
 
 ```json
 {
   "mcpServers": {
     "docuking": {
-      "command": "npx",
-      "args": ["-y", "docuking-mcp"]
+      "command": "docuking-mcp",
+      "args": []
     }
   }
 }
@@ -31,8 +51,23 @@ npx docuking-mcp
 {
   "mcpServers": {
     "docuking": {
-      "command": "npx",
-      "args": ["-y", "docuking-mcp"]
+      "command": "docuking-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+`~/.gemini/antigravity/mcp_config.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "docuking": {
+      "command": "docuking-mcp",
+      "args": []
     }
   }
 }
@@ -50,28 +85,35 @@ npx docuking-mcp
 | docuking_log | 커밋 히스토리 조회 |
 | docuking_diff | 버전 간 차이 비교 |
 | docuking_rollback | 특정 커밋으로 롤백 |
-| docuking_talk | AI 대화록 저장 (zz_ai_Talk/) |
-| docuking_plan | 작업 계획 관리 (zzz_ai_Plan/) |
+| docuking_talk | AI 대화록 저장 (zz_ai_1_Talk/) |
+| docuking_plan | 작업 계획 관리 (zz_ai_3_Plan/) |
 | docuking_done | 작업 완료 처리 |
-| docuking_todo | 킹투두 관리 (zz_ai_Todo/) |
+| docuking_todo | 킹투두 관리 (zz_ai_2_Todo/) |
+| docuking_urgent | 긴급 보고 (xx_Urgent/) |
+| docuking_delete | 서버 파일 삭제 |
+| docuking_validate | 정책 준수 검증 |
 
 ## 폴더 구조
 
 ```
 프로젝트/
-├── yy_All_Docu/              ← 동기화 대상 (Push/Pull)
-├── yy_Coworker_{이름}/       ← 협업자 작업 폴더 (동기화 대상)
-│   ├── zz_ai_1_Talk/         ← 협업자의 AI 대화록 (동기화 대상)
-│   ├── zz_ai_2_Todo/         ← 협업자의 AI 투두 (동기화 대상)
-│   └── zz_ai_3_Plan/         ← 협업자의 AI 플랜 (동기화 대상)
-├── zz_ai_1_Talk/             ← 오너의 AI 대화록 (동기화 대상)
-├── zz_ai_2_Todo/             ← 오너의 AI 투두 (동기화 대상)
-└── zz_ai_3_Plan/             ← 오너의 AI 플랜 (동기화 대상)
+├── xx_Infra_Config/         ← 시스템 설정 (동기화 대상)
+├── xx_Policy/               ← 정책 문서 (동기화 대상, 킹캐스트)
+├── xx_Urgent/               ← 긴급 보고 (동기화 대상)
+├── yy_All_Docu/             ← 문서 허브 (동기화 대상)
+├── yy_Coworker_{이름}/      ← 협업자 작업 폴더 (동기화 대상)
+│   ├── zz_ai_1_Talk/        ← 협업자의 AI 대화록
+│   ├── zz_ai_2_Todo/        ← 협업자의 AI 투두
+│   └── zz_ai_3_Plan/        ← 협업자의 AI 플랜
+├── zz_ai_1_Talk/            ← 오너의 AI 대화록 (동기화 대상)
+├── zz_ai_2_Todo/            ← 오너의 AI 투두 (동기화 대상)
+└── zz_ai_3_Plan/            ← 오너의 AI 플랜 (동기화 대상)
 ```
 
 **접두사 규칙:**
-- `yy_*`: 사람용 폴더 (동기화 대상)
-- `zz_ai_*`: AI용 폴더 (동기화 대상)
+- `xx_*`: 시스템/인프라 폴더
+- `yy_*`: 사람용 폴더
+- `zz_ai_*`: AI용 폴더
 
 ## 웹사이트
 

package/index.js

@@ -62,11 +62,17 @@ import {
 
 import { handleValidate } from './handlers/validate.js';
 
-// MCP 서버 생성
+// 버전 체크 모듈
+import { checkForUpdates, getVersionWarningMessage, getCurrentVersion } from './lib/version-check.js';
+
+// 세션당 1회 알림 플래그
+let versionWarningShown = false;
+
+// MCP 서버 생성 (package.json에서 버전 읽기)
 const server = new Server(
   {
     name: 'docuking-mcp',
-    version: '1.0.0',
+    version: getCurrentVersion(),
   },
   {
     capabilities: {
@@ -628,29 +634,55 @@ DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하
 
 작동 방식: 로컬 yy_All_Docu/ → 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)\` 도구 호출
-- **결과**: 해당 폴더에 \`yy_All_Docu/\` 폴더 생성 및 프로젝트 매핑 저장
-- **재시작 불필요**: MCP가 이미 작동 중이면 바로 실행 가능
-- **다중 프로젝트**: 한 컴퓨터에서 여러 폴더를 각각 다른 DocuKing 프로젝트와 연결 가능
-
-**핵심 원칙:**
-1. MCP 설정은 한 번만 (모든 폴더 공통)
-2. 프로젝트 연결은 각 폴더마다 (폴더별로 다른 프로젝트 ID)
-3. 이미 MCP가 작동 중이면 재시작 없이 바로 프로젝트 연결 가능
+## MCP 설치 및 설정 (매우 중요!)
+
+### 1단계: 글로벌 설치 (필수)
+\`\`\`bash
+npm install -g docuking-mcp
+\`\`\`
+
+### 2단계: MCP 등록 (AI 도구별)
+
+**Claude Code:**
+\`\`\`bash
+claude mcp add docuking -s user -- docuking-mcp
+\`\`\`
+
+**Cursor:** \`~/.cursor/mcp.json\`에 추가
+\`\`\`json
+{
+  "mcpServers": {
+    "docuking": {
+      "command": "docuking-mcp",
+      "args": []
+    }
+  }
+}
+\`\`\`
+
+**Gemini CLI:** \`~/.gemini/antigravity/mcp_config.json\`에 추가
+\`\`\`json
+{
+  "mcpServers": {
+    "docuking": {
+      "command": "docuking-mcp",
+      "args": []
+    }
+  }
+}
+\`\`\`
+
+### 업데이트
+새 버전이 있으면 첫 도구 호출 시 자동으로 알려줍니다.
+\`\`\`bash
+npm update -g docuking-mcp
+\`\`\`
+
+### MCP 설정 vs 프로젝트 연결
+- **MCP 설정**: 전역, 한 번만 (위의 설치/등록)
+- **프로젝트 연결**: 각 폴더마다 \`docuking_init\` 실행
+- **중요**: 이미 다른 MCP 서버가 있으면 덮어쓰지 말고 \`docuking\` 항목만 추가
+
 
 ## .gitignore 설정 (중요!)
 
@@ -713,13 +745,30 @@ zz_ai_3_Plan/
 - planId로 계획 찾기
 - 완료 요약 및 산출물 기록
 
-### 12. docuking_delete
+### 12. docuking_todo
+킹투두를 관리합니다 (\`zz_ai_2_Todo/z_King_Todo.md\`).
+- action: "add" (추가), "done" (완료), "list" (조회)
+- 프로젝트 공식 할일 목록 (Push하면 웹에서 확인 가능)
+
+### 13. docuking_urgent
+긴급 보고를 \`xx_Urgent/\` 폴더에 작성합니다 (킹어전트).
+- 정책에 없는 예외 상황 발견 시 오너에게 보고
+- 협업자도 xx_Urgent/에 쓰기 가능 (유일한 예외)
+- 오너가 Pull할 때 "긴급 보고 N건" 알림
+
+### 14. docuking_delete
 서버에서 파일/폴더를 직접 삭제합니다.
 - 로컬에서 삭제한 파일이 Push 후에도 서버에 남아있을 때
 - 서버에만 존재하는 불필요한 파일 정리
 - soft-delete 처리 (3일 후 영구 삭제)
 - 권한: 오너는 자기 영역, 협업자는 자기 폴더만
 
+### 15. docuking_validate
+코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
+- .claude/rules/local/ 정책 기준으로 검증
+- 폴더 구조, 명명 규칙, API 규칙 등 체크
+- 위반 목록과 수정 제안 반환
+
 ## Git과의 유사성
 
 | DocuKing | Git | 설명 |
@@ -818,40 +867,75 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
   try {
+    let result;
     switch (name) {
       case 'docuking_init':
-        return await handleInit(args);
+        result = await handleInit(args);
+        break;
       case 'docuking_push':
-        return await handlePush(args);
+        result = await handlePush(args);
+        break;
       case 'docuking_pull':
-        return await handlePull(args);
+        result = await handlePull(args);
+        break;
       case 'docuking_list':
-        return await handleList(args);
+        result = await handleList(args);
+        break;
       case 'docuking_status':
-        return await handleStatus(args);
+        result = await handleStatus(args);
+        break;
       case 'docuking_log':
-        return await handleLog(args);
+        result = await handleLog(args);
+        break;
       case 'docuking_diff':
-        return await handleDiff(args);
+        result = await handleDiff(args);
+        break;
       case 'docuking_rollback':
-        return await handleRollback(args);
+        result = await handleRollback(args);
+        break;
       case 'docuking_talk':
-        return await handleTalk(args);
+        result = await handleTalk(args);
+        break;
       case 'docuking_plan':
-        return await handlePlan(args);
+        result = await handlePlan(args);
+        break;
       case 'docuking_done':
-        return await handleDone(args);
+        result = await handleDone(args);
+        break;
       case 'docuking_todo':
-        return await handleTodo(args);
+        result = await handleTodo(args);
+        break;
       case 'docuking_urgent':
-        return await handleUrgent(args);
+        result = await handleUrgent(args);
+        break;
       case 'docuking_delete':
-        return await handleDelete(args);
+        result = await handleDelete(args);
+        break;
       case 'docuking_validate':
-        return await handleValidate(args);
+        result = await handleValidate(args);
+        break;
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
+
+    // 버전 체크 알림 (세션당 1회)
+    if (!versionWarningShown) {
+      try {
+        const updateInfo = await checkForUpdates();
+        const warning = getVersionWarningMessage(updateInfo);
+        if (warning) {
+          versionWarningShown = true;
+          result.content.push({
+            type: 'text',
+            text: warning
+          });
+        }
+      } catch (e) {
+        // 버전 체크 실패해도 무시 (서버 작동에 영향 없음)
+      }
+    }
+
+    return result;
   } catch (error) {
     return {
       content: [

package/lib/version-check.js

@@ -0,0 +1,119 @@
+/**
+ * DocuKing MCP 버전 체크 모듈
+ *
+ * npm registry에서 최신 버전을 확인하고,
+ * 현재 버전과 비교하여 업데이트 필요 여부를 알려줍니다.
+ */
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// 캐시 (세션 동안 유지)
+let cachedUpdateInfo = null;
+let lastCheckTime = 0;
+const CHECK_INTERVAL = 60 * 60 * 1000; // 1시간
+
+/**
+ * npm registry에서 최신 버전 확인 후 업데이트 필요 여부 반환
+ * - 1시간 캐시
+ * - 네트워크 오류 시 graceful degradation
+ */
+export async function checkForUpdates() {
+  const now = Date.now();
+
+  // 1시간 내 체크했으면 캐시 반환
+  if (cachedUpdateInfo && (now - lastCheckTime) < CHECK_INTERVAL) {
+    return cachedUpdateInfo;
+  }
+
+  try {
+    const current = getCurrentVersion();
+    const latest = await getLatestVersion();
+
+    cachedUpdateInfo = {
+      current,
+      latest,
+      available: compareVersions(latest, current) > 0
+    };
+    lastCheckTime = now;
+
+    if (cachedUpdateInfo.available) {
+      console.error(`[DocuKing MCP] 새 버전 ${latest} 출시! (현재: ${current})`);
+    }
+
+    return cachedUpdateInfo;
+  } catch (error) {
+    // 네트워크 오류 등은 무시 (서버 작동에 영향 없음)
+    console.error('[DocuKing MCP] 버전 체크 실패:', error.message);
+    return { available: false };
+  }
+}
+
+/**
+ * package.json에서 현재 버전 읽기
+ */
+export function getCurrentVersion() {
+  const pkgPath = join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  return pkg.version;
+}
+
+/**
+ * npm registry에서 최신 버전 조회
+ */
+async function getLatestVersion() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000); // 5초 타임아웃
+
+  try {
+    const response = await fetch('https://registry.npmjs.org/docuking-mcp/latest', {
+      signal: controller.signal
+    });
+    const data = await response.json();
+    return data.version;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * 버전 비교 (semver 단순 비교)
+ * @returns 1 if a > b, -1 if a < b, 0 if equal
+ */
+function compareVersions(a, b) {
+  const partsA = a.split('.').map(Number);
+  const partsB = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const numA = partsA[i] || 0;
+    const numB = partsB[i] || 0;
+    if (numA > numB) return 1;
+    if (numA < numB) return -1;
+  }
+  return 0;
+}
+
+/**
+ * AI에게 보여줄 업데이트 경고 메시지 생성
+ */
+export function getVersionWarningMessage(updateInfo) {
+  if (!updateInfo || !updateInfo.available) return null;
+
+  return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ DocuKing MCP 업데이트 필요
+
+현재 버전: ${updateInfo.current}
+최신 버전: ${updateInfo.latest}
+
+업데이트 명령어:
+  npm update -g docuking-mcp
+
+새 버전에서 버그 수정 및 기능 개선이 있습니다.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+}

package/package.json

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