docuking-mcp 2.8.1 → 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

@@ -329,8 +329,8 @@ git checkout -b coworker/${coworkerFolder}
   // 인프라 설정 파일 안내 (복사하지 않으므로 원본 경로 표시)
   if (infraConfigFiles.length > 0) {
     indexContent += '\n## 인프라 설정 (xx_Infra_Config/)\n';
-    indexContent += '> 아래 파일들은 복사되지 않습니다. 원본 경로에서 직접 읽으세요.\n';
-    indexContent += '> 변경 감지 시 AI가 내용을 읽고 로컬 환경에 맞게 적용해야 합니다.\n\n';
+    indexContent += '> 아래 파일들은 복사되지 않음. 원본 경로에서 직접 읽을 것.\n';
+    indexContent += '> 변경 감지 시 내용을 읽고 로컬 환경에 맞게 적용 필요.\n\n';
     for (const file of infraConfigFiles) {
       const relativePath = file.key.replace('xx_Infra_Config/', '');
       indexContent += `- xx_Infra_Config/${relativePath}\n`;
@@ -479,12 +479,12 @@ export async function executeKingcast(localPath) {
     ...changes.modified.filter(k => k.startsWith('xx_Infra_Config/')),
   ];
   if (infraChanges.length > 0) {
-    message += `\n\n🔧 인프라 설정 변경 감지 (${infraChanges.length}개):`;
+    message += `\n\n🔧 인프라 설정 변경 (${infraChanges.length}개):`;
     for (const file of infraChanges) {
       message += `\n   - ${file}`;
     }
-    message += `\n\n   👉 AI는 위 파일들을 읽고 로컬 환경에 맞게 적용하세요.`;
-    message += `\n   👉 예: .env 변수 추가/변경, 배포 설정 확인 등`;
+    message += `\n\n   → 위 파일을 읽고 로컬 환경에 맞게 적용 필요`;
+    message += `\n   → 예: .env 변수 추가/변경, 배포 설정 확인`;
   }
 
   // 정책 변경 시 경고 메시지 추가

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: `코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
@@ -683,12 +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. 각 정책 파일을 **읽어서** 내용을 숙지하고 규칙을 따라 작업
-4. **xx_Infra_Config 변경 시**: 원본 경로(xx_Infra_Config/)에서 직접 읽고 로컬 환경에 맞게 적용
-   - 예: .env 변수 추가/수정, 배포 설정 확인 등
+### 킹캐스트 결과 처리
+Pull 결과에 "📢 킹캐스트" 포함 시:
+1. \`.claude/rules/local/00_index.md\` 읽고 정책 목록 확인
+2. 각 정책 파일 **읽어서** 내용 숙지, 규칙 따라 작업
+3. **xx_Infra_Config 변경 시**: 원본 경로에서 직접 읽고 로컬 환경에 맞게 적용
+   - 예: .env 변수 추가/수정, 배포 설정 확인
 
 웹 탐색기: https://docuking.ai
 `;
@@ -735,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

@@ -146,11 +146,11 @@ project/
 - \`.claude/rules/local/*.md\` - 정책 파일 (폴더구조, API규칙 등 민감정보 없음)
 
 ### AI 필독
-- Pull 후 "📢 킹캐스트" 메시지가 표시되면 반드시 확인하세요.
-- \`.claude/rules/local/00_index.md\`를 읽고 정책 문서 목록을 확인하세요.
-- 각 정책 파일의 내용을 읽고 규칙을 따라 작업하세요.
-- **xx_Infra_Config 변경 감지 시**: 해당 파일을 직접 읽고 로컬 환경에 맞게 적용하세요.
-  - 예: .env 변수 추가/수정, 배포 설정 확인 등
+- 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.1",
+  "version": "2.9.0",
   "description": "DocuKing MCP Server - AI 시대의 문서 협업 플랫폼",
   "type": "module",
   "main": "index.js",