docuking-mcp 3.0.0 → 3.6.0

package/index.js

@@ -12,14 +12,14 @@
  * - xy_TalkTodoPlan/          : 오너 AI 기록 (Talk+Todo+Plan 통합) - Push 대상
  * - yy_All_Docu/              : 문서 동기화 폴더 (Push/Pull 대상)
  * - yy_All_Docu/_Private/     : 오너 비공개 폴더 (오너만 접근)
- * - yy_Coworker_{폴더명}/     : 협업자 폴더 (yy_All_Docu와 별도, 동기화 대상)
- * - yy_Coworker_{폴더명}/zz_TalkTodoPlan/ : 협업자 AI 기록
+ * - zz_Coworker_{폴더명}/     : 협업자 폴더 (동기화 대상)
+ * - zz_Coworker_{폴더명}/{폴더명}_TalkTodoPlan/ : 협업자 AI 기록
  *
  * 접두사 규칙:
  * - xx_ : 시스템용 폴더 (인프라, 정책, 긴급)
  * - xy_ : 오너 AI 기록 폴더
- * - yy_ : 사람용 폴더 (문서, 협업자)
- * - zz_ : 협업자 AI 기록 폴더 (협업자 폴더 안에서만 사용)
+ * - yy_ : 오너 문서 폴더
+ * - zz_ : 협업자 폴더
  * - _   : 비공개 폴더 (본인만 접근)
  *
  * 도구:
@@ -55,10 +55,8 @@ import {
 
 import {
   handleTodo,
-  handleTalk,
-  handlePlan,
-  handleDone,
   handleUrgent,
+  handleTalkPlan,
 } from './handlers/docs.js';
 
 import { handleValidate } from './handlers/validate.js';
@@ -105,7 +103,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 - 초기화 완료 후 정책 문서 작성 가이드 제공
 
 **협업자 초기화 시:**
-- yy_Coworker_{폴더명}/ 폴더 생성 (안에 _Private/, zz_TalkTodoPlan/ 포함)
+- zz_Coworker_{폴더명}/ 폴더 생성 (안에 _Private/, {폴더명}_TalkTodoPlan/ 포함)
 - CLAUDE.md에 DocuKing 연결 안내 추가
 - "Pull을 실행하세요" 안내 (오너 정책이 킹캐스트로 로컬화됨)
 
@@ -169,7 +167,7 @@ init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안
         description: `문서를 DocuKing 서버에 동기화합니다. 내부적으로 Pull → Push 순서로 실행 (git pull && git push 패턴).
 
 **AI 필독: 다음 상황에서 자발적으로 이 도구 사용을 제안하세요:**
-- xy_TalkTodoPlan/ (또는 협업자의 zz_TalkTodoPlan/) 에 문서를 생성/수정한 후
+- xy_TalkTodoPlan/ (또는 협업자의 {폴더명}_TalkTodoPlan/) 에 문서를 생성/수정한 후
 - yy_All_Docu/ 에 문서를 생성/수정한 후
 - docuking_plan, docuking_done, docuking_talk, docuking_todo 실행 후
 - 사용자가 "올려", "푸시", "동기화" 등을 언급할 때
@@ -314,102 +312,6 @@ init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안
           required: ['localPath', 'commitId'],
         },
       },
-      {
-        name: 'docuking_talk',
-        description: '의미 있는 대화 내용을 xy_TalkTodoPlan/ 폴더에 기록합니다 (Push 대상, 킹톡). AI가 중요한 논의/결정이라고 판단하거나, 사용자가 "이거 기록해줘"라고 요청할 때 사용.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            title: {
-              type: 'string',
-              description: '대화록 제목 (예: "인증 방식 결정", "API 설계 논의")',
-            },
-            content: {
-              type: 'string',
-              description: '대화 내용 요약 (마크다운 형식)',
-            },
-            tags: {
-              type: 'array',
-              items: { type: 'string' },
-              description: '태그 목록 (예: ["설계", "결정", "API"])',
-            },
-          },
-          required: ['localPath', 'title', 'content'],
-        },
-      },
-      {
-        name: 'docuking_plan',
-        description: '작업 계획 문서를 xy_TalkTodoPlan/ 폴더에 생성/업데이트합니다 (Push 대상, 킹플랜). 작업 시작 시 계획을 작성하고, 진행하면서 결과를 upsert합니다.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            planId: {
-              type: 'string',
-              description: '계획 ID (기존 계획 업데이트 시 사용, 생략하면 새 계획 생성)',
-            },
-            title: {
-              type: 'string',
-              description: '작업 제목 (예: "MCP 활동 로깅 구현")',
-            },
-            goal: {
-              type: 'string',
-              description: '작업 목표',
-            },
-            steps: {
-              type: 'array',
-              items: {
-                type: 'object',
-                properties: {
-                  name: { type: 'string', description: '단계 이름' },
-                  status: { type: 'string', enum: ['pending', 'in_progress', 'done'], description: '상태' },
-                  result: { type: 'string', description: '결과 (완료 시)' },
-                },
-              },
-              description: '작업 단계 목록',
-            },
-            notes: {
-              type: 'string',
-              description: '추가 노트/메모',
-            },
-          },
-          required: ['localPath', 'title'],
-        },
-      },
-      {
-        name: 'docuking_done',
-        description: '작업 계획을 완료 상태로 변경하고 최종 결과를 기록합니다.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            planId: {
-              type: 'string',
-              description: '완료할 계획 ID',
-            },
-            summary: {
-              type: 'string',
-              description: '작업 완료 요약',
-            },
-            artifacts: {
-              type: 'array',
-              items: { type: 'string' },
-              description: '산출물 목록 (파일 경로, URL 등)',
-            },
-          },
-          required: ['localPath', 'planId', 'summary'],
-        },
-      },
       {
         name: 'docuking_todo',
         description: `킹투두(King Todo) - 프로젝트 공식 할일을 xy_TalkTodoPlan/z_King_Todo.md에 관리합니다 (Push 대상).
@@ -521,6 +423,219 @@ init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안
           required: ['localPath', 'title', 'situation'],
         },
       },
+      {
+        name: 'docuking_talkplan',
+        description: `톡투플 - 대화 기록 + 구현 계획 + 완료 마킹을 하나의 문서로 관리합니다.
+
+**⚠️ 왜 이 도구가 중요한가? (AI 필독)**
+
+세션이 길어지면 컨텍스트가 **컴팩팅**됩니다.
+컴팩팅 후에는 **이 문서만 남습니다**.
+
+사용자가 500줄, 1000줄 상세하게 설명했는데,
+AI가 50줄로 요약해서 적으면?
+→ 컴팩팅 후 **450~950줄의 맥락이 증발**합니다.
+→ 후임 AI는 **50줄만 보고 작업해야 합니다**.
+→ 사용자가 다시 설명해야 합니다. **고통**.
+
+**따라서 이 문서는 "생존 문서"입니다.**
+컨텍스트가 날아가도 이 문서만 있으면 복구할 수 있어야 합니다.
+
+---
+
+**📝 작성 원칙 (절대 준수)**
+
+1. **원문 보존 원칙**
+   - 사용자의 말을 **그대로** 기록
+   - 요약하지 말 것. 축약하지 말 것.
+   - "사용자가 ~라고 함" 수준 요약 ❌
+   - 사용자의 실제 발언 전체 ✅
+
+2. **기술적 상세 기록**
+   - 파일명, 함수명, 변수명 **모두** 기록
+   - 코드 스니펫이 있으면 **그대로** 포함
+   - 에러 메시지 **전체** 기록
+   - "어떤 에러가 났음" ❌ → 실제 에러 텍스트 ✅
+
+3. **결정 사항과 이유**
+   - 왜 A가 아니라 B를 선택했는지
+   - 사용자가 어떤 제약사항을 언급했는지
+   - 어떤 시도가 실패했고 왜 실패했는지
+
+4. **컨텍스트 흐름**
+   - 대화가 어떻게 전개되었는지
+   - 처음 요청 → 문제 발견 → 해결책 논의 → 결정
+   - 이 흐름이 후임 AI에게도 보여야 함
+
+---
+
+**❌ 나쁜 예 (이렇게 적으면 안 됨):**
+\`\`\`
+사용자가 정렬 문제를 보고했고, numeric 정렬 옵션 추가로 해결하기로 했다.
+\`\`\`
+→ 50자. 컴팩팅 후 맥락 제로.
+
+**✅ 좋은 예 (이렇게 적어야 함):**
+\`\`\`
+## 사용자 보고
+"정렬이 이상해. 1, 10, 2 순서로 나와. 10이 2보다 앞에 있으면 안 되잖아."
+
+## AI 분석
+파일 탐색기의 naturalSort 함수 확인 결과:
+- 현재 localeCompare만 사용 중
+- { numeric: true } 옵션이 없어서 문자열 정렬됨
+- "10"이 "2"보다 앞에 오는 이유: '1' < '2' 문자 비교
+
+## 사용자 추가 요구사항
+"그리고 대소문자 구분도 없애줘. README.md랑 readme.md가 따로 정렬되면 안 돼."
+
+## 결정 사항
+localeCompare 옵션 변경:
+- { numeric: true } 추가 (숫자 정렬)
+- { sensitivity: 'base' } 추가 (대소문자 무시)
+
+## 수정 대상 파일
+1. frontend/src/components/FileExplorer.jsx:142 - naturalSort 함수
+2. backend/src/files/files.service.ts:89 - getFileTree 정렬 로직
+\`\`\`
+→ 상세한 맥락. 컴팩팅 후에도 후임 AI가 이해 가능.
+
+---
+
+**핵심 흐름:**
+1. 대화 시작 → 문서 생성 (tpId 반환)
+2. 대화 진행 → 내용 누적 (append, **원문 그대로!**)
+3. 체크포인트 생기면 → 구현 계획 추가 (checkpoint)
+4. 작업 완료 → 해당 항목 완료 마킹 (markDone)
+
+**사용 예시:**
+\`\`\`javascript
+// 1. 새 문서 생성 - 사용자 원문 포함!
+docuking_talkplan({
+  title: "파일 정렬 개선",
+  append: \`## 사용자 요청
+"정렬이 이상해. 1, 10, 2 순서로 나와..."
+
+## 상황 분석
+현재 FileExplorer.jsx:142의 naturalSort 함수가...\`
+})
+
+// 2. 대화 누적 - 추가 요구사항도 원문 그대로
+docuking_talkplan({
+  tpId: "abc123",
+  append: \`## 추가 요구사항 (13:42)
+사용자: "대소문자 구분도 없애줘. README.md랑 readme.md가 따로..."
+
+## 수정 방향
+sensitivity: 'base' 옵션 추가로 대소문자 무시...\`
+})
+\`\`\`
+
+**append 작성 체크리스트:**
+- [ ] 사용자 발언 원문이 포함되어 있는가?
+- [ ] 파일명, 라인 번호가 구체적으로 있는가?
+- [ ] 왜 이 결정을 했는지 이유가 있는가?
+- [ ] 후임 AI가 이것만 읽고 작업을 이어갈 수 있는가?
+- [ ] 500줄 설명을 50줄로 압축하지 않았는가?
+
+---
+
+**📋 Todo 도출 (중요!)**
+
+대화 중 할 일이 도출되면 **반드시 기록**:
+\`\`\`
+## 도출된 Todo
+- [ ] FileExplorer.jsx:142 - naturalSort에 numeric 옵션 추가
+- [ ] files.service.ts:89 - 백엔드 정렬 로직도 동일하게 수정
+- [ ] 테스트: 1, 2, 10 순서로 정렬되는지 확인
+\`\`\`
+
+킹투두(docuking_todo)에도 등록할 만한 항목이면 별도로 등록.
+
+---
+
+**📐 Plan (구현 계획) 작성 원칙**
+
+checkpoint로 Plan을 추가할 때:
+
+1. **후임 AI가 딴 방향으로 가지 않게** 구체적으로 작성
+   - "정렬 수정" ❌
+   - "FileExplorer.jsx:142의 naturalSort 함수에 { numeric: true, sensitivity: 'base' } 옵션 추가" ✅
+
+2. **수정할 파일과 위치 명시**
+   - 어떤 파일의 어떤 함수/라인인지
+   - 무엇을 어떻게 바꿀 건지
+
+3. **선후관계가 있으면 순서대로**
+   - 1번 완료 후 2번 진행해야 하면 그렇게 기록
+
+**나쁜 Plan:**
+\`\`\`
+- [ ] 프론트 수정
+- [ ] 백엔드 수정
+- [ ] 테스트
+\`\`\`
+
+**좋은 Plan:**
+\`\`\`
+- [ ] frontend/src/components/FileExplorer.jsx:142
+      naturalSort 함수의 localeCompare에 { numeric: true, sensitivity: 'base' } 추가
+- [ ] backend/src/files/files.service.ts:89
+      getFileTree의 sort 로직에 동일한 옵션 적용
+- [ ] 테스트: 웹에서 1, 2, 10, README.md, readme.txt 순서 확인
+\`\`\`
+
+---
+
+**✅ 완료 마킹 (잊지 말 것!)**
+
+작업 완료 후 **반드시** markDone 호출:
+\`\`\`javascript
+// 1번 체크포인트 완료
+docuking_talkplan({ tpId: "abc123", markDone: 1 })
+
+// 여러 개 동시 완료
+docuking_talkplan({ tpId: "abc123", markDone: [1, 2, 3] })
+\`\`\`
+
+**완료 마킹 안 하면:**
+- 후임 AI가 이미 된 작업을 또 함
+- 진행 상황 파악 불가
+- 문서가 신뢰할 수 없는 상태가 됨`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            tpId: {
+              type: 'string',
+              description: 'TalkPlan ID (기존 문서 업데이트 시). 생략하면 새 문서 생성.',
+            },
+            title: {
+              type: 'string',
+              description: '문서 제목 (새 문서 생성 시 필수)',
+            },
+            append: {
+              type: 'string',
+              description: '대화 내용 추가 (축약 금지! 그대로 기록)',
+            },
+            checkpoint: {
+              type: 'string',
+              description: '체크포인트(구현 계획) 추가. 체크박스로 추가됨.',
+            },
+            markDone: {
+              oneOf: [
+                { type: 'number' },
+                { type: 'array', items: { type: 'number' } }
+              ],
+              description: '완료 마킹할 체크포인트 번호 (단일 또는 배열)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
       {
         name: 'docuking_delete',
         description: `서버에서 파일/폴더를 직접 삭제합니다.
@@ -531,8 +646,8 @@ init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안
 - "서버에서 삭제해줘", "킹폴더에서 지워줘" 요청 시
 
 **권한:**
-- 오너: xx_*/, yy_All_Docu/, zz_ai_*/ 삭제 가능
-- 협업자: yy_Coworker_{본인}/ 내부만 삭제 가능
+- 오너: xx_*/, xy_TalkTodoPlan/, yy_All_Docu/ 삭제 가능
+- 협업자: zz_Coworker_{본인}/ 내부만 삭제 가능
 
 **주의:** 삭제는 soft-delete로 처리되며, 3일 후 완전 삭제됩니다.`,
         inputSchema: {
@@ -631,7 +746,7 @@ DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하
 - **로컬**: 사용자의 yy_All_Docu/ 폴더 (동기화 대상)
 - **웹탐색기**: DocuKing 서버의 파일 저장소 (킹폴더)
 - **캔버스**: 선택된 파일을 시각화하는 작업 공간
-- **AI 작업 폴더**: xy_TalkTodoPlan/ (오너) 또는 zz_TalkTodoPlan/ (협업자) - Push 대상
+- **AI 작업 폴더**: xy_TalkTodoPlan/ (오너) 또는 {폴더명}_TalkTodoPlan/ (협업자) - Push 대상
 
 작동 방식: 로컬 yy_All_Docu/ → Push → 킹폴더 → 캔버스에서 시각화
 
@@ -696,7 +811,7 @@ xx_Policy/
 xx_Urgent/
 xy_TalkTodoPlan/
 yy_All_Docu/
-yy_Coworker_*/
+zz_Coworker_*/
 \`\`\`
 
 **왜 gitignore에 등록해야 하나요?**
@@ -732,41 +847,32 @@ yy_Coworker_*/
 ### 8. docuking_rollback
 특정 커밋으로 되돌립니다. (웹 탐색기에서 사용 가능)
 
-### 9. docuking_talk
-의미 있는 대화 내용을 \`xy_TalkTodoPlan/\` 폴더에 기록합니다 (Push 대상, 킹톡).
-- AI가 중요한 논의/결정이라고 판단할 때
-- 사용자가 "이거 기록해줘"라고 요청할 때
-
-### 10. docuking_plan
-작업 계획을 \`xy_TalkTodoPlan/\` 폴더에 생성/업데이트합니다 (Push 대상, 킹플랜).
-- 작업 시작 시 계획 생성
-- 진행하면서 단계별 결과 upsert
-- planId로 기존 계획 찾아서 업데이트
+### 9. docuking_talkplan (톡투플)
+대화 기록 + 구현 계획 + 완료 마킹을 하나의 문서로 관리합니다.
+- 대화 시작 → 문서 생성 (tpId 반환)
+- 대화 진행 → 내용 누적 (append, 축약 금지!)
+- 체크포인트 생기면 → 구현 계획 추가 (checkpoint)
+- 작업 완료 → 해당 항목 완료 마킹 (markDone)
 
-### 11. docuking_done
-작업 계획을 완료 상태로 변경합니다.
-- planId로 계획 찾기
-- 완료 요약 및 산출물 기록
-
-### 12. docuking_todo
+### 10. docuking_todo
 킹투두를 관리합니다 (\`xy_TalkTodoPlan/z_King_Todo.md\`).
 - action: "add" (추가), "done" (완료), "list" (조회)
 - 프로젝트 공식 할일 목록 (Push하면 웹에서 확인 가능)
 
-### 13. docuking_urgent
+### 11. docuking_urgent
 긴급 보고를 \`xx_Urgent/\` 폴더에 작성합니다 (킹어전트).
 - 정책에 없는 예외 상황 발견 시 오너에게 보고
 - 협업자도 xx_Urgent/에 쓰기 가능 (유일한 예외)
 - 오너가 Pull할 때 "긴급 보고 N건" 알림
 
-### 14. docuking_delete
+### 12. docuking_delete
 서버에서 파일/폴더를 직접 삭제합니다.
 - 로컬에서 삭제한 파일이 Push 후에도 서버에 남아있을 때
 - 서버에만 존재하는 불필요한 파일 정리
 - soft-delete 처리 (3일 후 영구 삭제)
 - 권한: 오너는 자기 영역, 협업자는 자기 폴더만
 
-### 15. docuking_validate
+### 13. docuking_validate
 코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
 - .claude/rules/local/ 정책 기준으로 검증
 - 폴더 구조, 명명 규칙, API 규칙 등 체크
@@ -806,8 +912,8 @@ DocuKing 협업의 핵심 원칙입니다. **각자 자기 영역만 수정할
 
 | 역할 | Push (올리기) | Pull (내리기) | 삭제 |
 |------|---------------|---------------|------|
-| 오너 | \`yy_All_Docu/\` + \`zz_ai_*/\` | 합집합 전체 | 자기 영역만 |
-| 협업자 | \`yy_Coworker_{본인}/\` (안에 zz_ai_* 포함) | 합집합 전체 | 자기 영역만 |
+| 오너 | \`xx_*/\` + \`xy_TalkTodoPlan/\` + \`yy_All_Docu/\` | 합집합 전체 | 자기 영역만 |
+| 협업자 | \`zz_Coworker_{본인}/\` | 합집합 전체 | 자기 영역만 |
 
 **합집합이란?**
 - 서버에는 오너 파일 + 모든 협업자 파일이 합쳐져 있음
@@ -896,21 +1002,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'docuking_rollback':
         result = await handleRollback(args);
         break;
-      case 'docuking_talk':
-        result = await handleTalk(args);
-        break;
-      case 'docuking_plan':
-        result = await handlePlan(args);
-        break;
-      case 'docuking_done':
-        result = await handleDone(args);
-        break;
       case 'docuking_todo':
         result = await handleTodo(args);
         break;
       case 'docuking_urgent':
         result = await handleUrgent(args);
         break;
+      case 'docuking_talkplan':
+        result = await handleTalkPlan(args);
+        break;
       case 'docuking_delete':
         result = await handleDelete(args);
         break;

package/lib/config.js

@@ -75,7 +75,9 @@ export function saveLocalConfig(localPath, config) {
 }
 
 /**
- * 협업자 여부 및 zz_ai 폴더 기본 경로 반환
+ * 협업자 여부 및 AI 폴더 기본 경로 반환
+ * - 오너: localPath (xy_TalkTodoPlan)
+ * - 협업자: localPath/zz_Coworker_{폴더명} ({폴더명}_TalkTodoPlan)
  */
 export function getAiBasePath(localPath) {
   const config = getLocalConfig(localPath);
@@ -87,7 +89,7 @@ export function getAiBasePath(localPath) {
   const { isCoworker, coworkerFolder } = parseCoworkerFromApiKey(apiKey);
 
   if (isCoworker && coworkerFolder) {
-    const coworkerFolderPath = path.join(localPath, `yy_Coworker_${coworkerFolder}`);
+    const coworkerFolderPath = path.join(localPath, `zz_Coworker_${coworkerFolder}`);
     return { isCoworker: true, basePath: coworkerFolderPath, coworkerFolder };
   }