docuking-mcp 2.5.7 → 2.7.0

package/lib/config.js

@@ -0,0 +1,114 @@
+/**
+ * DocuKing MCP - 설정 관리 모듈
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// 환경변수에서 API 엔드포인트 설정
+export const API_ENDPOINT = process.env.DOCUKING_API_ENDPOINT || 'https://docuking.ai/api';
+
+// 파일 크기 제한 (150MB)
+export const MAX_FILE_SIZE_MB = 150;
+export const MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024;
+
+/**
+ * API 키에서 협업자 폴더명 추출
+ * API 키 형식: sk_프로젝트8자_cw_폴더명_랜덤48자(hex)
+ */
+export function parseCoworkerFromApiKey(apiKey) {
+  if (!apiKey) return { isCoworker: false, coworkerFolder: null };
+
+  const cwIndex = apiKey.indexOf('_cw_');
+  if (cwIndex === -1) return { isCoworker: false, coworkerFolder: null };
+
+  const afterCw = apiKey.substring(cwIndex + 4);
+  const lastUnderscore = afterCw.lastIndexOf('_');
+  if (lastUnderscore === -1) return { isCoworker: false, coworkerFolder: null };
+
+  const folderName = afterCw.substring(0, lastUnderscore);
+  return {
+    isCoworker: !!folderName,
+    coworkerFolder: folderName || null,
+  };
+}
+
+/**
+ * 로컬 프로젝트의 .docuking/config.json에서 설정 읽기
+ */
+export function getLocalConfig(localPath) {
+  const configPath = path.join(localPath, '.docuking', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.error('[DocuKing] config.json 파싱 실패:', e.message);
+    return null;
+  }
+}
+
+/**
+ * 로컬 config에서 API 키 가져오기
+ */
+export function getApiKey(localPath) {
+  const config = getLocalConfig(localPath);
+  return config?.apiKey || '';
+}
+
+/**
+ * 로컬 config 저장하기 (.docuking/config.json)
+ */
+export function saveLocalConfig(localPath, config) {
+  const docukingDir = path.join(localPath, '.docuking');
+
+  if (!fs.existsSync(docukingDir)) {
+    fs.mkdirSync(docukingDir, { recursive: true });
+  }
+
+  const configPath = path.join(docukingDir, 'config.json');
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/**
+ * 협업자 여부 및 zz_ai 폴더 기본 경로 반환
+ */
+export function getAiBasePath(localPath) {
+  const config = getLocalConfig(localPath);
+  if (!config || !config.apiKey) {
+    return { isCoworker: false, basePath: localPath, coworkerFolder: null };
+  }
+
+  const apiKey = config.apiKey;
+  const { isCoworker, coworkerFolder } = parseCoworkerFromApiKey(apiKey);
+
+  if (isCoworker && coworkerFolder) {
+    const coworkerFolderPath = path.join(localPath, `yy_Coworker_${coworkerFolder}`);
+    return { isCoworker: true, basePath: coworkerFolderPath, coworkerFolder };
+  }
+
+  return { isCoworker: false, basePath: localPath, coworkerFolder: null };
+}
+
+/**
+ * 프로젝트 정보 조회 (로컬 config에서)
+ */
+export function getProjectInfo(localPath) {
+  const config = getLocalConfig(localPath);
+
+  if (!config || !config.projectId) {
+    return {
+      error: `오류: 이 프로젝트는 DocuKing에 연결되지 않았습니다.
+먼저 docuking_init을 실행하세요.`,
+    };
+  }
+
+  return {
+    projectId: config.projectId,
+    projectName: config.projectName,
+  };
+}

package/lib/files.js

@@ -0,0 +1,212 @@
+/**
+ * DocuKing MCP - 파일 처리 모듈
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { MAX_FILE_SIZE_BYTES, MAX_FILE_SIZE_MB } from './config.js';
+
+// 파일 타입 정의
+export 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',
+    // 디스크 이미지
+    '.iso', '.dmg', '.img', '.vhd', '.vmdk',
+  ],
+};
+
+/**
+ * 파일 확장자로 파일 타입 결정
+ */
+export 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';
+}
+
+/**
+ * yy_All_Docu 폴더 존재 확인
+ */
+export function hasAllDocuFolder(projectPath) {
+  const allDocuPath = path.join(projectPath, 'yy_All_Docu');
+  return fs.existsSync(allDocuPath);
+}
+
+/**
+ * 빈 폴더 수집 (재귀)
+ */
+export function collectEmptyFolders(basePath, relativePath, results) {
+  const fullPath = path.join(basePath, relativePath);
+  if (!fs.existsSync(fullPath)) return;
+
+  const entries = fs.readdirSync(fullPath, { withFileTypes: true });
+
+  const hasFiles = entries.some(e => e.isFile());
+  const subDirs = entries.filter(e => e.isDirectory());
+
+  if (!hasFiles && subDirs.length === 0) {
+    results.push(relativePath);
+  } else {
+    for (const entry of subDirs) {
+      const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      collectEmptyFolders(basePath, entryRelPath, results);
+    }
+  }
+}
+
+/**
+ * 디렉토리 재귀 탐색 (Push용)
+ */
+export function collectFilesSimple(basePath, relativePath, results, excludedFiles = null, largeFiles = null) {
+  const fullPath = path.join(basePath, relativePath);
+  if (!fs.existsSync(fullPath)) return;
+
+  const entries = fs.readdirSync(fullPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const entryRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      collectFilesSimple(basePath, entryRelPath, results, excludedFiles, largeFiles);
+    } else if (entry.isFile()) {
+      const fileType = getFileType(entry.name);
+
+      if (fileType === 'excluded') {
+        console.error(`[DocuKing] 제외됨: ${entryRelPath} (지원하지 않는 파일 형식)`);
+        if (excludedFiles) {
+          excludedFiles.push(entryRelPath);
+        }
+        continue;
+      }
+
+      const fileFullPath = path.join(fullPath, entry.name);
+      const stats = fs.statSync(fileFullPath);
+      const fileSizeMB = stats.size / (1024 * 1024);
+
+      if (stats.size > MAX_FILE_SIZE_BYTES) {
+        console.error(`[DocuKing] ⚠️ 대용량 파일 제외: ${entryRelPath} (${fileSizeMB.toFixed(1)}MB > ${MAX_FILE_SIZE_MB}MB)`);
+        if (largeFiles) {
+          largeFiles.push({ path: entryRelPath, sizeMB: fileSizeMB.toFixed(1) });
+        }
+        continue;
+      }
+
+      results.push({
+        path: entryRelPath,
+        fullPath: fileFullPath,
+        fileType,
+        sizeMB: fileSizeMB,
+      });
+    }
+  }
+}
+
+/**
+ * 디렉토리 재귀 탐색 (기존 호환용)
+ */
+export function collectFiles(basePath, relativePath, results, excludedFiles = null, largeFiles = 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, largeFiles);
+    } else if (entry.isFile()) {
+      const fileType = getFileType(entry.name);
+
+      if (fileType === 'excluded') {
+        console.error(`[DocuKing] 제외됨: ${entryRelPath} (지원하지 않는 파일 형식)`);
+        if (excludedFiles) {
+          excludedFiles.push(entryRelPath);
+        }
+        continue;
+      }
+
+      const fileFullPath = path.join(fullPath, entry.name);
+      const stats = fs.statSync(fileFullPath);
+      const fileSizeMB = stats.size / (1024 * 1024);
+
+      if (stats.size > MAX_FILE_SIZE_BYTES) {
+        console.error(`[DocuKing] ⚠️ 대용량 파일 제외: ${entryRelPath} (${fileSizeMB.toFixed(1)}MB > ${MAX_FILE_SIZE_MB}MB)`);
+        if (largeFiles) {
+          largeFiles.push({ path: entryRelPath, sizeMB: fileSizeMB.toFixed(1) });
+        }
+        continue;
+      }
+
+      results.push({
+        path: entryRelPath,
+        fullPath: fileFullPath,
+        fileType,
+        sizeMB: fileSizeMB,
+      });
+    }
+  }
+}
+
+/**
+ * 트리 구조를 평탄화
+ */
+export 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;
+}

package/lib/index.js

@@ -0,0 +1,41 @@
+/**
+ * DocuKing MCP - 라이브러리 모듈 인덱스
+ */
+
+// 설정 관련
+export {
+  API_ENDPOINT,
+  MAX_FILE_SIZE_MB,
+  MAX_FILE_SIZE_BYTES,
+  parseCoworkerFromApiKey,
+  getLocalConfig,
+  getApiKey,
+  saveLocalConfig,
+  getAiBasePath,
+  getProjectInfo,
+} from './config.js';
+
+// 파일 처리
+export {
+  FILE_TYPES,
+  getFileType,
+  hasAllDocuFolder,
+  collectEmptyFolders,
+  collectFilesSimple,
+  collectFiles,
+  flattenTree,
+} from './files.js';
+
+// 초기화 헬퍼
+export {
+  updateClaudeMd,
+  setupAutoApproval,
+  updateGitignore,
+} from './init.js';
+
+// 유틸리티
+export {
+  generateDateFileName,
+  generatePlanId,
+  findPlanFiles,
+} from './utils.js';

package/lib/init.js

@@ -0,0 +1,270 @@
+/**
+ * DocuKing MCP - 초기화 헬퍼 모듈
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * CLAUDE.md에 DocuKing 섹션 추가
+ */
+export function updateClaudeMd(localPath) {
+  const claudeMdPath = path.join(localPath, 'CLAUDE.md');
+  const marker = '## DocuKing 연결됨';
+  const oldMarker = '## DocuKing AI 작업 기록 (필수)';
+
+  const docukingSection = `
+---
+
+${marker}
+
+### MCP 도구
+| 도구 | 용도 |
+|------|------|
+| docuking_push | 문서 업로드 ("올려줘") |
+| docuking_pull | 문서 다운로드 ("가져와") |
+| docuking_list | 서버 파일 목록 조회 |
+| docuking_status | 동기화 상태 확인 |
+| docuking_log | 커밋 히스토리 조회 |
+| docuking_diff | 버전 간 차이 비교 |
+| docuking_rollback | 특정 커밋으로 되돌림 |
+| docuking_plan | 작업 시작 시 계획 기록 |
+| docuking_done | 작업 완료 시 결과 기록 |
+| docuking_todo | 킹투두 (프로젝트 할일) |
+| docuking_talk | 대화록 저장 |
+
+### 작업 흐름 (필수)
+
+**1단계: Talk 기록 (작업 원인/배경)**
+- 사용자 요청의 배경, 논의 내용을 먼저 기록
+- Plan을 세우기 전에 반드시 Talk로 "왜 이 작업을 하는지" 남김
+
+**2단계: Todo 등록 (할일 등록)**
+- 의미 있는 작업이면 킹투두에 등록
+- 나중에 추적/공유할 가치가 있는 작업
+
+**3단계: Plan 생성 → 작업 → Done 완료**
+- 기존대로 plan → 작업 → done
+
+### Talk 자동 기록 (docuking_talk)
+
+**다음 상황에서 AI가 자동으로 기록:**
+- 설계 방향 결정 (A vs B 선택, "왜 이렇게?")
+- 버그 원인 분석 및 해결책 논의
+- 아키텍처/구조 변경 논의
+- 사용자가 중요한 결정을 내릴 때
+- Plan을 세우게 된 원인/배경 논의
+
+### Todo 자동 등록 (docuking_todo)
+
+**다음 상황에서 AI가 자동으로 등록:**
+- 사용자가 "나중에 해야 할 것" 언급 시
+- 작업 중 발견한 추가 개선사항
+- "TODO", "FIXME" 성격의 발견 사항
+- 의미 있는 작업 시작 시 (추적용)
+
+### 규칙
+1. 동기화 대상: yy_All_Docu/ + zz_ai_*/ 폴더 모두
+2. 킹푸시는 Plan 완료(done) 시 자동 실행
+3. **Talk → Todo → Plan → Done** 순서 준수
+4. Plan 전에 반드시 Talk로 배경 기록
+
+### Git과 킹푸시는 별개
+- **Git 커밋/푸시**: 단위 작업 완료 시 "커밋/푸시할까요?" 제안 (소스 보호)
+- **킹푸시**: Plan 완료(docuking_done) 시 자동 실행 (문서 동기화)
+
+---
+
+## DocuKing 협업 정책 (AI 필독)
+
+### 핵심 원칙: 남의 제사상을 건드리지 않는다
+
+각자 자기 영역만 수정 가능, 남의 영역은 읽기만.
+
+### Push/Pull 정책
+
+| 역할 | Push (올리기) | Pull (내리기) | 삭제 |
+|------|---------------|---------------|------|
+| **오너** | \`yy_All_Docu/\` + \`zz_ai_*/\` | 합집합 전체 | 자기 영역만 |
+| **협업자** | \`yy_Coworker_{본인}/\` (안에 zz_ai_* 포함) | 합집합 전체 | 자기 영역만 |
+
+### 합집합이란?
+- 서버 = 오너 파일 + 모든 협업자 파일
+- Pull하면 전체가 로컬로 내려옴
+- 경로만 알면 누구 파일이든 읽기 가능
+
+### 협업자 참여 흐름
+1. **초대 수락** (웹) → 프로젝트 진입, 자기 빈폴더 생성됨
+2. **MCP init** → 로컬에 자기 폴더 생성
+3. **Pull** → 합집합 전체 내려옴
+4. **작업** → \`yy_Coworker_{본인}/\` 안에서
+5. **Push** → 자기 폴더만 올라감
+
+### 폴더 구조 (Pull 후)
+\`\`\`
+project/
+├── yy_All_Docu/                 ← 오너 문서 (읽기만)
+├── yy_Coworker_a_Kim/           ← 협업자 Kim
+│   ├── 작업문서.md
+│   └── zz_ai_1_Talk/            ← Kim의 AI 기록
+├── yy_Coworker_b_Lee/           ← 협업자 Lee
+└── zz_ai_*/                     ← 오너의 AI 폴더
+\`\`\`
+
+### AI가 협업자에게 안내할 것
+- 작업 폴더: \`yy_Coworker_{폴더명}/\`
+- 남의 파일: 읽기만 가능, 수정 불가
+- 수정 제안: 자기 폴더에 작성 또는 직접 연락
+
+---
+
+## 킹캐스트 (KingCast) - 정책 자동 배포
+
+오너가 \`yy_All_Docu/_Policy/\` 폴더에 정책을 작성하고 Push하면,
+협업자가 Pull할 때 자동으로 \`.claude/rules/local/\`에 로컬화됩니다.
+
+### 킹캐스트 대상 폴더
+- \`yy_All_Docu/_Infra_Config/\` - 환경 설정 (참조용, 로컬화하지 않음)
+- \`yy_All_Docu/_Policy/\` - AI 행동 지침 (로컬화 대상)
+
+### 킹캐스트 동작
+1. Pull 실행
+2. _Infra_Config/, _Policy/ 폴더 변경 감지
+3. \`_Policy/\` 파일들을 \`.claude/rules/local/\`에 서브파일 구조로 복사
+4. 협업자의 경우 변수 치환 (폴더명, 브랜치명 등 로컬화)
+5. \`_Infra_Config/\`는 참조용으로 내려오지만, 협업자가 직접 다룰 정보가 아니므로 로컬화하지 않음
+
+### Git 제외 정책
+
+**Git에서 제외 (민감 정보):**
+- \`.docuking/config.json\` - API 키 포함
+- \`.claude/rules/local/_coworker_config.md\` - 협업자별 로컬 설정
+
+**Git에 포함 (백업 대상):**
+- \`.claude/rules/local/*.md\` - 정책 파일 (폴더구조, API규칙 등 민감정보 없음)
+
+### AI 필독
+- Pull 후 "📢 킹캐스트" 메시지가 표시되면, 정책 파일의 내용을 읽어 변경사항을 확인하세요.
+- \`.claude/rules/local/00_index.md\`를 읽고 정책 문서 목록을 확인하세요.
+- 각 정책 파일의 내용을 읽고 규칙을 따라 작업하세요.
+`;
+
+  try {
+    if (fs.existsSync(claudeMdPath)) {
+      let content = fs.readFileSync(claudeMdPath, 'utf-8');
+
+      if (content.includes(marker)) {
+        return;
+      }
+
+      if (content.includes(oldMarker)) {
+        const oldSectionStart = content.lastIndexOf('---\n\n' + oldMarker);
+        if (oldSectionStart !== -1) {
+          content = content.substring(0, oldSectionStart) + docukingSection;
+          fs.writeFileSync(claudeMdPath, content, 'utf-8');
+          return;
+        }
+      }
+
+      fs.appendFileSync(claudeMdPath, docukingSection, 'utf-8');
+    } else {
+      const newContent = `# Project Instructions
+
+> AI가 이 프로젝트에서 작업할 때 참고할 지침
+${docukingSection}`;
+      fs.writeFileSync(claudeMdPath, newContent, 'utf-8');
+    }
+  } catch (e) {
+    console.error('[DocuKing] CLAUDE.md 업데이트 실패:', e.message);
+  }
+}
+
+/**
+ * IDE별 자동 승인 설정 추가
+ */
+export function setupAutoApproval(localPath) {
+  const claudeSettingsPath = path.join(localPath, '.claude', 'settings.local.json');
+
+  try {
+    let settings = {};
+
+    if (fs.existsSync(claudeSettingsPath)) {
+      const content = fs.readFileSync(claudeSettingsPath, 'utf-8');
+      settings = JSON.parse(content);
+    } else {
+      const claudeDir = path.join(localPath, '.claude');
+      if (!fs.existsSync(claudeDir)) {
+        fs.mkdirSync(claudeDir, { recursive: true });
+      }
+    }
+
+    if (!settings.permissions) settings.permissions = {};
+    if (!settings.permissions.allow) settings.permissions.allow = [];
+
+    let changed = false;
+
+    if (!settings.enableAllProjectMcpServers) {
+      settings.enableAllProjectMcpServers = true;
+      changed = true;
+    }
+
+    const wildcardPermission = 'mcp__docuking__*';
+    if (!settings.permissions.allow.includes(wildcardPermission)) {
+      settings.permissions.allow.push(wildcardPermission);
+      changed = true;
+    }
+
+    if (changed) {
+      fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+    }
+  } catch (e) {
+    console.error('[DocuKing] Claude Code 설정 업데이트 실패:', e.message);
+  }
+}
+
+/**
+ * .gitignore에 DocuKing 폴더 추가
+ *
+ * Git 제외 정책:
+ * - 문서 폴더 (yy_*, zz_*): DocuKing으로 관리하므로 Git 제외
+ * - .docuking/config.json: API 키 포함 (민감)
+ * - _coworker_config.md: 협업자별 로컬 설정 (각자 생성)
+ *
+ * Git 포함 (백업 대상):
+ * - .claude/rules/local/*.md: 정책 파일들 (폴더구조, API규칙 등 - 민감정보 없음)
+ */
+export function updateGitignore(localPath) {
+  const gitignorePath = path.join(localPath, '.gitignore');
+  const marker = '# DocuKing (문서는 DocuKing으로 관리)';
+  const docukingEntries = `
+${marker}
+yy_All_Docu/
+yy_Coworker_*/
+zz_ai_1_Talk/
+zz_ai_2_Todo/
+zz_ai_3_Plan/
+.docuking/config.json
+.claude/rules/local/_coworker_config.md
+`;
+
+  try {
+    if (fs.existsSync(gitignorePath)) {
+      let content = fs.readFileSync(gitignorePath, 'utf-8');
+
+      // 이전 버전에서 .claude/rules/local/ 전체 제외했던 경우, 수정
+      if (content.includes('.claude/rules/local/') && !content.includes('.claude/rules/local/_coworker_config.md')) {
+        content = content.replace('.claude/rules/local/', '.claude/rules/local/_coworker_config.md');
+        fs.writeFileSync(gitignorePath, content, 'utf-8');
+      }
+
+      if (content.includes(marker)) {
+        return; // 이미 마커가 있으면 완료
+      }
+      fs.appendFileSync(gitignorePath, docukingEntries, 'utf-8');
+    } else {
+      fs.writeFileSync(gitignorePath, docukingEntries.trim() + '\n', 'utf-8');
+    }
+  } catch (e) {
+    console.error('[DocuKing] .gitignore 업데이트 실패:', e.message);
+  }
+}