docuking-mcp 2.8.0 → 2.9.0

package/handlers/docs.js

@@ -1,12 +1,12 @@
 /**
  * DocuKing MCP - 문서 핸들러 모듈
- * todo, talk, plan, done
+ * todo, talk, plan, done, urgent
  */
 
 import fs from 'fs';
 import path from 'path';
 
-import { getAiBasePath } from '../lib/config.js';
+import { getAiBasePath, parseCoworkerFromApiKey, getApiKey } from '../lib/config.js';
 import { generateDateFileName, generatePlanId, findPlanFiles } from '../lib/utils.js';
 import { handlePush } from './sync.js';
 
@@ -517,3 +517,104 @@ ${artifacts.length > 0 ? `📦 산출물: ${artifacts.length}개` : ''}${pushMes
     ],
   };
 }
+
+/**
+ * docuking_urgent 구현 - 긴급 보고 (킹어전트)
+ * 협업자가 예외 상황 발견 시 xx_Urgent/에 보고
+ */
+export async function handleUrgent(args) {
+  const localPath = args.localPath || process.cwd();
+  const { title, situation, policyGap, suggestion, priority = 'medium' } = args;
+
+  if (!title || !situation) {
+    return {
+      content: [{
+        type: 'text',
+        text: '오류: title과 situation 파라미터가 필요합니다.',
+      }],
+    };
+  }
+
+  // 보고자 정보 (협업자면 폴더명, 오너면 'Owner')
+  const apiKey = getApiKey(localPath);
+  let reporter = 'Owner';
+  if (apiKey) {
+    const { isCoworker, coworkerFolder } = parseCoworkerFromApiKey(apiKey);
+    if (isCoworker && coworkerFolder) {
+      reporter = coworkerFolder;
+    }
+  }
+
+  // xx_Urgent 폴더 경로
+  const urgentBasePath = path.join(localPath, 'xx_Urgent');
+
+  // 폴더 생성
+  if (!fs.existsSync(urgentBasePath)) {
+    fs.mkdirSync(urgentBasePath, { recursive: true });
+  }
+
+  // 날짜 기반 파일명 생성
+  const { fileName, timestamp } = generateDateFileName(`${reporter}_${title}`, 'U');
+  const urgentFilePath = path.join(urgentBasePath, fileName);
+
+  // 우선순위 아이콘
+  const priorityIcons = {
+    high: '🔴',
+    medium: '🟡',
+    low: '🟢',
+  };
+  const priorityIcon = priorityIcons[priority] || '🟡';
+  const priorityText = priority === 'high' ? '긴급 (작업 중단 필요)'
+    : priority === 'medium' ? '중간 (임시 처리 후 진행)'
+    : '낮음 (참고용)';
+
+  // 마크다운 문서 생성
+  const document = `# ${priorityIcon} ${title}
+
+> 보고자: ${reporter}
+> 보고 시간: ${timestamp}
+> 우선순위: ${priorityText}
+
+---
+
+## 발생 상황
+${situation}
+
+${policyGap ? `## 정책 공백
+${policyGap}
+
+` : ''}${suggestion ? `## 제안 사항
+${suggestion}
+
+` : ''}---
+
+## 오너 처리 (아래 작성)
+
+
+
+---
+*이 문서는 협업자 AI가 자동 생성한 긴급 보고입니다.*
+*처리 완료 후 오너가 이 파일을 삭제하면 됩니다.*
+`;
+
+  // 파일 저장
+  fs.writeFileSync(urgentFilePath, document, 'utf-8');
+
+  const relativePath = path.relative(localPath, urgentFilePath).replace(/\\/g, '/');
+
+  return {
+    content: [{
+      type: 'text',
+      text: `${priorityIcon} 긴급 보고 작성 완료!
+
+📋 제목: ${title}
+👤 보고자: ${reporter}
+📁 경로: ${relativePath}
+🕐 시간: ${timestamp}
+⚡ 우선순위: ${priorityText}
+
+💡 Push하면 오너가 Pull 시 자동으로 알림을 받습니다.
+💡 오너가 정책을 업데이트하고 해당 파일을 삭제하면 처리 완료입니다.`,
+    }],
+  };
+}

package/handlers/kingcast.js

@@ -206,31 +206,10 @@ function updateLocalRules(localPath, currentFiles, changes, config) {
   }
 
   // ========================================
-  // 1.5. xx_Infra_Config 파일들을 infra/ 서브폴더로 복사
+  // 1.5. xx_Infra_Config는 복사하지 않음
+  // 이미 Pull 후 xx_Infra_Config/에 존재함
+  // AI가 변경 감지 시 직접 읽고 로컬 환경에 맞게 적용
   // ========================================
-  const infraLocalPath = path.join(localRulesPath, 'infra');
-  if (infraConfigFiles.length > 0) {
-    fs.mkdirSync(infraLocalPath, { recursive: true });
-
-    for (const file of infraConfigFiles) {
-      // xx_Infra_Config/deploy.md → infra/deploy.md
-      const relativePath = file.key.replace('xx_Infra_Config/', '');
-      const targetPath = path.join(infraLocalPath, relativePath);
-
-      // 디렉토리 생성
-      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-
-      // 파일 읽기 및 로컬화
-      try {
-        const content = fs.readFileSync(file.fullPath, 'utf-8');
-        const localizedContent = localizeContent(content, config);
-        fs.writeFileSync(targetPath, localizedContent, 'utf-8');
-        createdFiles.push(`infra/${relativePath}`);
-      } catch (e) {
-        console.error(`[KingCast] 인프라 설정 파일 복사 실패: ${file.key} - ${e.message}`);
-      }
-    }
-  }
 
   // ========================================
   // 2. 협업자용 설정 파일 생성 (_coworker_config.md)
@@ -347,12 +326,14 @@ git checkout -b coworker/${coworkerFolder}
     }
   }
 
-  // 인프라 설정 파일 목록 추가
+  // 인프라 설정 파일 안내 (복사하지 않으므로 원본 경로 표시)
   if (infraConfigFiles.length > 0) {
-    indexContent += '\n## 인프라 설정 (참조용)\n';
+    indexContent += '\n## 인프라 설정 (xx_Infra_Config/)\n';
+    indexContent += '> 아래 파일들은 복사되지 않음. 원본 경로에서 직접 읽을 것.\n';
+    indexContent += '> 변경 감지 시 내용을 읽고 로컬 환경에 맞게 적용 필요.\n\n';
     for (const file of infraConfigFiles) {
       const relativePath = file.key.replace('xx_Infra_Config/', '');
-      indexContent += `- [${relativePath}](./infra/${relativePath})\n`;
+      indexContent += `- xx_Infra_Config/${relativePath}\n`;
     }
   }
 
@@ -381,19 +362,8 @@ git checkout -b coworker/${coworkerFolder}
           }
         }
       }
-      // xx_Infra_Config 삭제
-      if (deletedKey.startsWith('xx_Infra_Config/')) {
-        const relativePath = deletedKey.replace('xx_Infra_Config/', '');
-        const targetPath = path.join(localRulesPath, 'infra', relativePath);
-        if (fs.existsSync(targetPath)) {
-          try {
-            fs.unlinkSync(targetPath);
-            console.error(`[KingCast] 삭제된 인프라 설정 제거: infra/${relativePath}`);
-          } catch (e) {
-            console.error(`[KingCast] 파일 삭제 실패: infra/${relativePath} - ${e.message}`);
-          }
-        }
-      }
+      // xx_Infra_Config는 복사하지 않으므로 삭제 처리 불필요
+      // Pull 시 자동으로 원본 폴더에서 제거됨
     }
   }
 
@@ -503,8 +473,23 @@ export async function executeKingcast(localPath) {
     message += `\n   📄 정책 파일 ${result.policyCount}개 → .claude/rules/local/`;
   }
 
+  // xx_Infra_Config 변경 감지 시 안내
+  const infraChanges = [
+    ...changes.added.filter(k => k.startsWith('xx_Infra_Config/')),
+    ...changes.modified.filter(k => k.startsWith('xx_Infra_Config/')),
+  ];
+  if (infraChanges.length > 0) {
+    message += `\n\n🔧 인프라 설정 변경 (${infraChanges.length}개):`;
+    for (const file of infraChanges) {
+      message += `\n   - ${file}`;
+    }
+    message += `\n\n   → 위 파일을 읽고 로컬 환경에 맞게 적용 필요`;
+    message += `\n   → 예: .env 변수 추가/변경, 배포 설정 확인`;
+  }
+
   // 정책 변경 시 경고 메시지 추가
-  if (changes.modified.length > 0) {
+  const policyModified = changes.modified.filter(k => k.startsWith('xx_Policy/'));
+  if (policyModified.length > 0) {
     message += `\n\n⚠️ 중요: 정책이 변경되었습니다!`;
     message += `\n   기존 코드가 새 정책과 맞지 않을 수 있습니다.`;
     message += `\n   변경된 정책 파일을 읽고, 기존 코드에도 새 정책을 적용하세요.`;

package/handlers/sync.js

@@ -91,6 +91,12 @@ docuking_init 호출 시 apiKey 파라미터를 포함해주세요.`,
   // xx_ 시스템 폴더 목록 (오너 전용)
   const systemFolders = ['xx_Infra_Config', 'xx_Policy'];
 
+  // xx_Urgent/ 폴더는 오너/협업자 모두 생성 (공용 긴급 보고 폴더)
+  const urgentFolderPath = path.join(localPath, 'xx_Urgent');
+  if (!fs.existsSync(urgentFolderPath)) {
+    fs.mkdirSync(urgentFolderPath, { recursive: true });
+  }
+
   if (isCoworker) {
     // 협업자: yy_Coworker_{폴더명}/ 폴더를 yy_All_Docu/ 밖에 별도 생성
     coworkerFolderName = `yy_Coworker_${coworkerFolder}`;
@@ -269,7 +275,7 @@ Git처럼 무엇을 변경했는지 명확히 작성해주세요.
   console.error(`[DocuKing] Push 권한: isCoworker=${isCoworker}, coworkerFolder=${coworkerFolder}, coworkerFolderName=${coworkerFolderName}`);
 
   if (isCoworker) {
-    // 협업자: yy_Coworker_{폴더명}/ 폴더만 Push
+    // 협업자: yy_Coworker_{폴더명}/ 폴더 + xx_Urgent/ 폴더 Push
     const coworkerPath = path.join(localPath, coworkerFolderName);
     console.error(`[DocuKing] 협업자 Push 대상 폴더: ${coworkerPath}`);
     if (!fs.existsSync(coworkerPath)) {
@@ -277,6 +283,13 @@ Git처럼 무엇을 변경했는지 명확히 작성해주세요.
     }
     pushTargetFolders.push({ localPath: coworkerPath, serverPrefix: coworkerFolderName });
 
+    // xx_Urgent/ 폴더도 Push 대상에 추가 (협업자도 긴급 보고 가능)
+    const urgentPath = path.join(localPath, 'xx_Urgent');
+    if (fs.existsSync(urgentPath)) {
+      pushTargetFolders.push({ localPath: urgentPath, serverPrefix: 'xx_Urgent' });
+      console.error(`[DocuKing] 협업자 xx_Urgent/ 폴더도 Push 대상에 포함`);
+    }
+
     // 협업자 폴더 내용 디버그 출력
     try {
       const entries = fs.readdirSync(coworkerPath, { withFileTypes: true });
@@ -1257,6 +1270,54 @@ export async function handlePullInternal(args) {
     console.error('[DocuKing] 킹캐스트 실행 실패:', e.message);
   }
 
+  // ========================================
+  // 킹어전트 감지 (xx_Urgent/ 폴더의 긴급 보고 확인)
+  // 오너에게만 알림 (협업자는 자기가 작성한 거니까)
+  // ========================================
+  const { isCoworker } = parseCoworkerFromApiKey(apiKey);
+  if (!isCoworker) {
+    const urgentFolderPath = path.join(localPath, 'xx_Urgent');
+    if (fs.existsSync(urgentFolderPath)) {
+      try {
+        const urgentFiles = fs.readdirSync(urgentFolderPath)
+          .filter(f => f.endsWith('.md') && !f.startsWith('.'));
+
+        if (urgentFiles.length > 0) {
+          resultText += `\n\n🚨 **긴급 보고 ${urgentFiles.length}건 있습니다!**`;
+          resultText += `\n\n협업자들이 정책 예외 상황을 보고했습니다. 확인이 필요합니다:`;
+
+          // 각 보고 파일의 제목과 우선순위 표시
+          for (const file of urgentFiles.slice(0, 5)) {
+            const filePath = path.join(urgentFolderPath, file);
+            try {
+              const content = fs.readFileSync(filePath, 'utf-8');
+              // 제목 추출 (# 으로 시작하는 첫 줄)
+              const titleMatch = content.match(/^# (.+)$/m);
+              const title = titleMatch ? titleMatch[1] : file;
+              // 보고자 추출
+              const reporterMatch = content.match(/> 보고자: (.+)$/m);
+              const reporter = reporterMatch ? reporterMatch[1] : '알 수 없음';
+
+              resultText += `\n   - ${title} (by ${reporter})`;
+            } catch (e) {
+              resultText += `\n   - ${file}`;
+            }
+          }
+
+          if (urgentFiles.length > 5) {
+            resultText += `\n   ... 외 ${urgentFiles.length - 5}건`;
+          }
+
+          resultText += `\n\n📁 경로: xx_Urgent/`;
+          resultText += `\n💡 검토 후 xx_Policy/에 정책 추가 → Push (킹캐스트로 전파)`;
+          resultText += `\n💡 처리 완료 후 해당 보고 파일 삭제 → Push`;
+        }
+      } catch (e) {
+        console.error('[DocuKing] xx_Urgent 폴더 읽기 실패:', e.message);
+      }
+    }
+  }
+
   // 내부용 객체 반환 (Push에서 사용)
   return {
     text: resultText,

package/index.js

@@ -56,6 +56,7 @@ import {
   handleTalk,
   handlePlan,
   handleDone,
+  handleUrgent,
 } from './handlers/docs.js';
 
 import { handleValidate } from './handlers/validate.js';
@@ -443,6 +444,71 @@ init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안
           required: ['localPath', 'action'],
         },
       },
+      {
+        name: 'docuking_urgent',
+        description: `긴급 보고를 xx_Urgent/ 폴더에 작성합니다 (킹어전트).
+
+**AI 필독: 다음 상황에서 자동으로 이 도구를 사용하세요:**
+- 정책(xx_Policy/)에 정의되지 않은 예외 상황 발견 시
+- 코드 작업 중 정책과 충돌하는 상황 발생 시
+- 정책 명확화가 필요한 애매한 상황 발생 시
+- 버그나 이슈 발견 시 (오너에게 보고 필요)
+
+**⚠️ 보고 작성 지침 (매우 중요):**
+오너 AI가 이 보고를 읽고 **추가 질문 없이 바로 이해하고 조치**할 수 있어야 합니다.
+- situation: 구체적인 상황 설명 (어떤 파일에서, 어떤 작업 중, 무엇이 문제인지)
+- policyGap: 어떤 정책이 없거나 불명확한지 명확히 기술
+- suggestion: 구체적인 정책 추가/수정 제안 (예시 포함)
+
+**나쁜 예:** "API 응답 형식이 불명확합니다"
+**좋은 예:** "GET /api/users 엔드포인트 개발 중, 에러 응답 형식이 xx_Policy/03_api_convention.md에 정의되어 있지 않습니다.
+현재 {error: string} 형식을 사용했으나, 다른 API들은 {code: number, message: string} 형식입니다.
+제안: 03_api_convention.md에 '에러 응답 형식: {code: number, message: string, details?: any}' 추가"
+
+**xx_Urgent/ 폴더 특징:**
+- 유일하게 협업자도 쓰기 가능한 xx_ 폴더
+- 오너만 삭제 가능 (처리 완료 표시)
+- Push하면 오너가 Pull 시 자동 알림
+
+**피드백 루프:**
+1. 협업자 AI: 예외 상황 발견 → docuking_urgent 호출
+2. 협업자: Push
+3. 오너: Pull → "긴급 보고 N건 있습니다" 알림
+4. 오너: 검토 후 xx_Policy/ 업데이트 → Push
+5. 킹캐스트: 모든 협업자에게 정책 전파
+6. 오너: xx_Urgent/ 해당 파일 삭제 → Push`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            title: {
+              type: 'string',
+              description: '보고 제목 (예: "API 응답 형식 정책 불명확", "DB 스키마 충돌 발생")',
+            },
+            situation: {
+              type: 'string',
+              description: '발생 상황 설명 (어떤 작업 중 어떤 문제가 발생했는지)',
+            },
+            policyGap: {
+              type: 'string',
+              description: '정책 공백 (어떤 정책이 없거나 불명확한지)',
+            },
+            suggestion: {
+              type: 'string',
+              description: '제안 사항 (이렇게 정책을 추가/수정하면 어떨지)',
+            },
+            priority: {
+              type: 'string',
+              enum: ['high', 'medium', 'low'],
+              description: '우선순위 (high: 작업 중단 필요, medium: 임시 처리 후 진행, low: 참고용)',
+            },
+          },
+          required: ['localPath', 'title', 'situation'],
+        },
+      },
       {
         name: 'docuking_validate',
         description: `코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
@@ -665,8 +731,8 @@ DocuKing 협업의 핵심 원칙입니다. **각자 자기 영역만 수정할
 \`\`\`
 
 ### 킹캐스트 대상 폴더
-- \`xx_Infra_Config/\` - 환경 설정 (.env 백업, 배포 정보 등) → .claude/rules/local/infra/에 로컬화
-- \`xx_Policy/\` - AI 행동 지침 → .claude/rules/local/에 로컬화
+- \`xx_Infra_Config/\` - 환경 설정 (.env 백업, 배포 정보 등) → 변경 감지만 (복사X)
+- \`xx_Policy/\` - AI 행동 지침 → .claude/rules/local/에 복사
 
 ### 정책 파일 작성 템플릿 (오너용)
 \`\`\`
@@ -683,10 +749,12 @@ xx_Policy/
 - \`.claude/rules/local/00_project_overview.md\` - 정책 사본 (변수 치환됨)
 - \`.claude/rules/local/_coworker_config.md\` - 협업자 설정 (협업자만)
 
-### AI 필독: 킹캐스트 후 행동
-1. Pull 후 "📢 킹캐스트" 메시지가 표시되면, 정책 변경이 감지된 것
-2. \`.claude/rules/local/00_index.md\`를 읽고 정책 목록 확인
-3. 각 정책 파일을 **읽어서** 내용을 숙지하고 규칙을 따라 작업
+### 킹캐스트 결과 처리
+Pull 결과에 "📢 킹캐스트" 포함 시:
+1. \`.claude/rules/local/00_index.md\` 읽고 정책 목록 확인
+2. 각 정책 파일 **읽어서** 내용 숙지, 규칙 따라 작업
+3. **xx_Infra_Config 변경 시**: 원본 경로에서 직접 읽고 로컬 환경에 맞게 적용
+   - 예: .env 변수 추가/수정, 배포 설정 확인
 
 웹 탐색기: https://docuking.ai
 `;
@@ -733,6 +801,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await handleDone(args);
       case 'docuking_todo':
         return await handleTodo(args);
+      case 'docuking_urgent':
+        return await handleUrgent(args);
       case 'docuking_validate':
         return await handleValidate(args);
       default:

package/lib/init.js

@@ -126,15 +126,15 @@ project/
 협업자가 Pull할 때 자동으로 \`.claude/rules/local/\`에 로컬화됩니다.
 
 ### 킹캐스트 대상 폴더
-- \`xx_Infra_Config/\` - 환경 설정 (.env 백업, 배포 정보 등) → 로컬화 대상
-- \`xx_Policy/\` - AI 행동 지침 → 로컬화 대상
+- \`xx_Infra_Config/\` - 환경 설정 (.env 백업, 배포 정보 등) → 변경 감지만
+- \`xx_Policy/\` - AI 행동 지침 → .claude/rules/local/에 복사
 
 ### 킹캐스트 동작
 1. Pull 실행
-2. xx_Infra_Config/, xx_Policy/ 폴더 변경 감지
+2. xx_Infra_Config/, xx_Policy/ 폴더 변경 감지 (해시 비교)
 3. \`xx_Policy/\` 파일들을 \`.claude/rules/local/\`에 서브파일 구조로 복사
-4. \`xx_Infra_Config/\` 파일들도 \`.claude/rules/local/infra/\`에 복사 (환경변수, 배포 설정 등)
-5. 협업자의 경우 변수 치환 (폴더명, 브랜치명 등 로컬화)
+4. \`xx_Infra_Config/\` 변경 시 AI에게 알림 (복사X, 원본 경로에서 직접 읽음)
+5. 협업자의 경우 AI가 내용을 읽고 로컬 환경에 맞게 적용
 
 ### Git 제외 정책
 
@@ -146,9 +146,11 @@ project/
 - \`.claude/rules/local/*.md\` - 정책 파일 (폴더구조, API규칙 등 민감정보 없음)
 
 ### AI 필독
-- Pull 후 "📢 킹캐스트" 메시지가 표시되면, 정책 파일의 내용을 읽어 변경사항을 확인하세요.
-- \`.claude/rules/local/00_index.md\`를 읽고 정책 문서 목록을 확인하세요.
-- 각 정책 파일의 내용을 읽고 규칙을 따라 작업하세요.
+- Pull 결과에 "📢 킹캐스트" 포함 시 정책/환경 변경이 있음
+- \`.claude/rules/local/00_index.md\`를 읽고 정책 목록 확인
+- 각 정책 파일 내용을 읽고 규칙 따라 작업
+- **xx_Infra_Config 변경 시**: 원본 경로에서 직접 읽고 로컬 환경에 맞게 적용
+  - 예: .env 변수 추가/수정, 배포 설정 확인
 `;
 
   try {

package/package.json

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