docuking-mcp 2.9.0 → 2.9.2

package/index.js

@@ -1,830 +1,866 @@
-#!/usr/bin/env node
-
-/**
- * DocuKing MCP Server v2.0
- *
- * AI 시대의 문서 협업 플랫폼 - AI가 문서를 Push/Pull 할 수 있게 해주는 MCP 서버
- *
- * 폴더 구조:
- * - xx_Infra_Config/          : 시스템 설정 (.env 백업, 배포 정보 등) - Push 대상
- * - xx_Policy/                : 정책 문서 (AI 행동 지침) - Push 대상, 킹캐스트 대상
- * - yy_All_Docu/              : 문서 동기화 폴더 (Push/Pull 대상)
- * - yy_All_Docu/_Private/     : 오너 비공개 폴더 (오너만 접근)
- * - yy_Coworker_{폴더명}/     : 협업자 폴더 (yy_All_Docu와 별도, 동기화 대상)
- * - zz_ai_1_Talk/             : AI 대화록 (킹톡, Push 대상)
- * - zz_ai_2_Todo/             : AI 투두 (킹투두, Push 대상)
- * - zz_ai_3_Plan/             : AI 플랜 (킹플랜, Push 대상)
- *
- * 접두사 규칙:
- * - xx_ : 시스템용 폴더 (인프라, 정책) - Push 대상
- * - yy_ : 사람용 폴더 (문서, 협업자) - Push 대상
- * - zz_ai_ : AI용 폴더 (Talk, Todo, Plan) - Push 대상
- * - _   : 비공개 폴더 (본인만 접근)
- *
- * 도구:
- * - docuking_init: 레포 연결, yy_All_Docu/ 폴더 생성
- * - docuking_push: 로컬 → 서버 (.env 자동 백업)
- * - docuking_pull: 서버 → 로컬
- */
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
-
-// 핸들러 import
-import {
-  handleInit,
-  handlePush,
-  handlePull,
-  handleList,
-  handleStatus,
-} from './handlers/sync.js';
-
-import {
-  handleLog,
-  handleDiff,
-  handleRollback,
-} from './handlers/version.js';
-
-import {
-  handleTodo,
-  handleTalk,
-  handlePlan,
-  handleDone,
-  handleUrgent,
-} from './handlers/docs.js';
-
-import { handleValidate } from './handlers/validate.js';
-
-// MCP 서버 생성
-const server = new Server(
-  {
-    name: 'docuking-mcp',
-    version: '1.0.0',
-  },
-  {
-    capabilities: {
-      tools: {},
-      resources: {},
-    },
-  }
-);
-
-// 도구 목록
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: 'docuking_init',
-        description: `프로젝트를 DocuKing에 연결합니다. .docuking/config.json에 설정 저장, yy_All_Docu/ 폴더 생성.
-
-**필수 파라미터:**
-- projectId: 프로젝트 UUID
-- projectName: 프로젝트 이름 (표시용)
-- apiKey: API 키 (sk_xxx 형식)
-- localPath: 로컬 프로젝트 경로
-
-**오너 초기화 시:**
-- xx_Infra_Config/, xx_Policy/ 폴더 생성 (시스템 설정)
-- yy_All_Docu/, yy_All_Docu/_Private/ 폴더 생성
-- zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ 폴더 생성
-- CLAUDE.md에 DocuKing 연결 안내 추가
-- 초기화 완료 후 정책 문서 작성 가이드 제공
-
-**협업자 초기화 시:**
-- yy_Coworker_{폴더명}/ 폴더 생성 (안에 _Private/, zz_ai_*/ 포함)
-- CLAUDE.md에 DocuKing 연결 안내 추가
-- "Pull을 실행하세요" 안내 (오너 정책이 킹캐스트로 로컬화됨)
-
-**정책 문서 템플릿 (오너용, xx_Policy/ 폴더에 작성):**
-
-[필수]
-- 00_project_overview.md - 프로젝트 개요, 기술 스택, 팀 구성, 주요 URL
-
-[구조/규칙]
-- 01_folder_structure.md - 폴더 구조 규칙, 파일 명명 규칙
-- 02_naming_convention.md - 변수/함수/클래스 명명 규칙
-- 03_api_convention.md - API 엔드포인트 규칙, 요청/응답 형식, 에러 코드
-
-[데이터베이스]
-- 05_database_schema.md - 테이블/컬럼 명명, 타입 규칙, 필수 컬럼(id, createdAt 등)
-- 06_database_migration.md - 마이그레이션 절차, 브랜치별 스키마 관리, 충돌 해결법
-
-[개발 정책]
-- 10_coding_style.md - 코딩 스타일, 린터 설정, 포매터 규칙
-- 11_git_workflow.md - 브랜치 전략, 커밋 메시지 규칙, PR 규칙
-- 12_testing_policy.md - 테스트 작성 규칙, 커버리지 기준
-- 13_error_handling.md - 에러 처리 패턴, 로깅 규칙
-
-[디자인/UI]
-- 20_design_system.md - 디자인 시스템, 컬러, 타이포그래피
-- 21_component_guide.md - 컴포넌트 작성 규칙, 스타일링 방식
-
-[인프라/보안]
-- 30_deployment.md - 배포 절차, 환경별 설정
-- 31_security_policy.md - 보안 규칙, 인증/인가, 민감정보 처리
-
-[AI 전용]
-- 99_for_claude.md - Claude Code 행동 지침, 금지/필수 사항
-
-init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안할 것.`,
-        inputSchema: {
-          type: 'object',
-          properties: {
-            projectId: {
-              type: 'string',
-              description: 'DocuKing 프로젝트 ID',
-            },
-            projectName: {
-              type: 'string',
-              description: 'DocuKing 프로젝트 이름 (표시용)',
-            },
-            apiKey: {
-              type: 'string',
-              description: 'API 키 (sk_xxx 형식)',
-            },
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로 (예: /Users/user/my-project)',
-            },
-          },
-          required: ['projectId', 'projectName', 'apiKey', 'localPath'],
-        },
-      },
-      {
-        name: 'docuking_push',
-        description: `문서를 DocuKing 서버에 동기화합니다. 내부적으로 Pull → Push 순서로 실행 (git pull && git push 패턴).
-
-**AI 필독: 다음 상황에서 자발적으로 이 도구 사용을 제안하세요:**
-- zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ 에 문서를 생성/수정한 후
-- yy_All_Docu/ 에 문서를 생성/수정한 후
-- docuking_plan, docuking_done, docuking_talk, docuking_todo 실행 후
-- 사용자가 "올려", "푸시", "동기화" 등을 언급할 때
-
-제안 예시: "킹폴더에 문서가 생성되었습니다. DocuKing에 올릴까요?"`,
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로 (레포 매핑에서 projectId 찾음)',
-            },
-            filePath: {
-              type: 'string',
-              description: '푸시할 파일 경로 (Z_DocuKing/ 기준 상대경로). 생략 시 전체 동기화.',
-            },
-            message: {
-              type: 'string',
-              description: '커밋 메시지 (필수). Git 커밋 메시지처럼 명확하고 구체적으로 작성. 예: "README에 설치 가이드 추가"',
-            },
-            author: {
-              type: 'string',
-              description: '작성자 (선택). 생략 시 현재 사용자.',
-            },
-          },
-          required: ['localPath', 'message'],
-        },
-      },
-      {
-        name: 'docuking_pull',
-        description: '서버에서 문서를 다운로드합니다. "DocuKing에서 가져와" 요청 시 사용.\n\n**킹캐스트**: Pull 후 xx_Policy/, xx_Infra_Config/ 폴더 변경이 감지되면 자동으로 .claude/rules/local/에 로컬화됩니다.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            filePath: {
-              type: 'string',
-              description: '풀할 파일 경로 (생략 시 전체 동기화)',
-            },
-          },
-          required: ['localPath'],
-        },
-      },
-      {
-        name: 'docuking_list',
-        description: '서버에 저장된 파일 목록을 조회합니다.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로 (레포 매핑에서 projectId 찾음)',
-            },
-          },
-          required: ['localPath'],
-        },
-      },
-      {
-        name: 'docuking_status',
-        description: '로컬과 서버의 동기화 상태를 확인합니다. 사용자 권한(오너/참여자), 변경/추가/삭제된 파일 목록 표시.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-          },
-          required: ['localPath'],
-        },
-      },
-      {
-        name: 'docuking_log',
-        description: '커밋 히스토리를 조회합니다. Git log와 동일.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            path: {
-              type: 'string',
-              description: '특정 파일/폴더의 히스토리만 조회 (선택)',
-            },
-            limit: {
-              type: 'number',
-              description: '최근 N개 커밋만 조회 (기본값: 20)',
-            },
-          },
-          required: ['localPath'],
-        },
-      },
-      {
-        name: 'docuking_diff',
-        description: '버전 간 차이를 비교합니다.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            path: {
-              type: 'string',
-              description: '파일 경로',
-            },
-            version: {
-              type: 'string',
-              description: '비교할 커밋 ID (선택, 생략 시 최신 vs 이전)',
-            },
-          },
-          required: ['localPath', 'path'],
-        },
-      },
-      {
-        name: 'docuking_rollback',
-        description: '특정 커밋으로 되돌립니다.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            commitId: {
-              type: 'string',
-              description: '되돌릴 커밋 ID',
-            },
-            path: {
-              type: 'string',
-              description: '특정 파일만 롤백 (선택, 생략 시 전체)',
-            },
-          },
-          required: ['localPath', 'commitId'],
-        },
-      },
-      {
-        name: 'docuking_talk',
-        description: '의미 있는 대화 내용을 zz_ai_1_Talk/ 폴더에 기록합니다 (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: '작업 계획 문서를 zz_ai_3_Plan/ 폴더에 생성/업데이트합니다 (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) - 프로젝트 공식 할일을 zz_ai_2_Todo/z_King_Todo.md에 관리합니다 (Push 대상).
-
-**AI 내장 TodoWrite와 다름!** 킹투두는 웹에 동기화되고 팀과 공유됩니다.
-
-**작성 형식:**
-\`\`\`
-1. ✅ **[태그] 키워드** 12.30/12.30
-       설명 (7칸 들여쓰기)
-
-2. ⚙️ **[태그] 키워드** 12.30
-       설명
-\`\`\`
-
-**형식 규칙:**
-- ✅ 완료 / ⚙️ 진행중
-- **[태그] 키워드** 볼드 처리
-- 날짜 1개 = 등록일(진행중), 2개 = 등록일/완료일(완료)
-- 설명은 7칸 들여쓰기 ([ 기호 아래 정렬)
-
-**사용자에게 "킹투두에 등록했습니다" 형식으로 보고하세요.**`,
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            action: {
-              type: 'string',
-              enum: ['add', 'done', 'list'],
-              description: 'add: 할일 추가, done: 완료 표시, list: 목록 조회',
-            },
-            todo: {
-              type: 'string',
-              description: '할일 내용 (add 시 필수). 형식: "[태그] 키워드 - 설명" 예: "[보안] API 인증 강화 - JWT 토큰 검증"',
-            },
-            todoId: {
-              type: 'number',
-              description: '할일 번호 (done 시 필수)',
-            },
-          },
-          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: `코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
-
-**사용 시점:**
-- "정책 검증해줘", "킹밸리데이트", "validate" 요청 시
-- Pull 후 킹캐스트에서 정책 변경 감지 시 (자동 제안)
-- PR/커밋 전 코드 검증 시
-
-**검증 대상:**
-- .claude/rules/local/ 의 정책 파일 기준 (킹캐스트로 로컬화된 정책)
-- xx_Policy/ 정책 파일도 참조
-- 폴더 구조, 명명 규칙, API 규칙, DB 스키마 등
-
-**출력:**
-- 정책별 위반 목록
-- 파일:라인 위치
-- 수정 제안
-
-**예시:**
-\`\`\`
-[위반] 01_folder_structure.md
-  - src/utils/helper.js:1 - utils 폴더에 직접 파일 금지 (하위 폴더로 분류 필요)
-  - src/components/button.tsx:1 - 컴포넌트 파일명은 PascalCase 필수
-
-[위반] 05_database_schema.md
-  - backend/src/entities/user.entity.ts:15 - createdAt 컬럼 누락
-\`\`\``,
-        inputSchema: {
-          type: 'object',
-          properties: {
-            localPath: {
-              type: 'string',
-              description: '로컬 프로젝트 경로',
-            },
-            policy: {
-              type: 'string',
-              description: '특정 정책만 검증 (예: 05_database_schema.md). 생략 시 전체 검증.',
-            },
-            targetPath: {
-              type: 'string',
-              description: '특정 파일/폴더만 검증 (예: src/components). 생략 시 전체.',
-            },
-            autoFix: {
-              type: 'boolean',
-              description: '자동 수정 시도 여부 (기본값: false). 안전한 수정만 자동, 위험한 수정은 제안만.',
-            },
-          },
-          required: ['localPath'],
-        },
-      },
-    ],
-  };
-});
-
-// Resources 목록
-server.setRequestHandler(ListResourcesRequestSchema, async () => {
-  return {
-    resources: [
-      {
-        uri: "docuking://docs/manual",
-        name: "DocuKing 사용 설명서",
-        description: "AI가 DocuKing을 이해하고 사용하기 위한 기초 지식",
-        mimeType: "text/markdown"
-      }
-    ]
-  };
-});
-
-// Resource 읽기
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  if (request.params.uri === "docuking://docs/manual") {
-    const manual = `# DocuKing - AI 시대의 문서 협업 플랫폼 (AI용 매뉴얼)
-
-DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하듯, DocuKing은 문서를 관리합니다.
-
-## 핵심 개념
-
-- **로컬**: 사용자의 yy_All_Docu/ 폴더 (동기화 대상)
-- **웹탐색기**: DocuKing 서버의 파일 저장소 (킹폴더)
-- **캔버스**: 선택된 파일을 시각화하는 작업 공간
-- **AI 작업 폴더**: zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ (Push 대상)
-
-작동 방식: 로컬 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가 작동 중이면 재시작 없이 바로 프로젝트 연결 가능
-
-## .gitignore 설정 (중요!)
-
-DocuKing 문서 폴더는 git에서 제외해야 합니다. 코드는 git으로, 문서는 DocuKing으로 분리 관리합니다.
-
-\`\`\`gitignore
-# DocuKing 문서 폴더 (문서는 DocuKing으로 관리)
-yy_All_Docu/
-zz_ai_1_Talk/
-zz_ai_2_Todo/
-zz_ai_3_Plan/
-\`\`\`
-
-**왜 gitignore에 등록해야 하나요?**
-- 문서와 코드의 버전 관리를 분리
-- git 저장소 크기 최적화 (대용량 문서 제외)
-- DocuKing이 문서 버전 관리를 전담
-
-## MCP 도구 목록
-
-### 1. docuking_init
-프로젝트를 DocuKing에 연결합니다.
-
-### 2. docuking_push
-로컬 문서를 서버에 업로드합니다. Git의 add + commit + push를 한 번에 수행.
-**message 파라미터 필수** (커밋 메시지)
-
-### 3. docuking_pull
-서버 문서를 로컬로 다운로드합니다.
-**킹캐스트**: Pull 후 xx_Policy/, xx_Infra_Config/ 폴더 변경이 감지되면 자동으로 .claude/rules/local/에 로컬화됩니다.
-
-### 4. docuking_list
-서버 파일 목록을 조회합니다.
-
-### 5. docuking_status
-로컬과 서버의 동기화 상태를 확인합니다. 사용자 권한(오너/참여자), 변경/추가/삭제된 파일 목록 표시.
-
-### 6. docuking_log
-커밋 히스토리를 조회합니다. (웹 탐색기에서 사용 가능)
-
-### 7. docuking_diff
-버전 간 차이를 비교합니다. (웹 탐색기에서 사용 가능)
-
-### 8. docuking_rollback
-특정 커밋으로 되돌립니다. (웹 탐색기에서 사용 가능)
-
-### 9. docuking_talk
-의미 있는 대화 내용을 \`zz_ai_1_Talk/\` 폴더에 기록합니다 (Push 대상, 킹톡).
-- AI가 중요한 논의/결정이라고 판단할 때
-- 사용자가 "이거 기록해줘"라고 요청할 때
-
-### 10. docuking_plan
-작업 계획을 \`zz_ai_3_Plan/\` 폴더에 생성/업데이트합니다 (Push 대상, 킹플랜).
-- 작업 시작 시 계획 생성
-- 진행하면서 단계별 결과 upsert
-- planId로 기존 계획 찾아서 업데이트
-
-### 11. docuking_done
-작업 계획을 완료 상태로 변경합니다.
-- planId로 계획 찾기
-- 완료 요약 및 산출물 기록
-
-## Git과의 유사성
-
-| DocuKing | Git | 설명 |
-|----------|-----|------|
-| docuking_push | git add . && git commit -m "..." && git push | 스테이징 + 커밋 + 푸시 통합 |
-| docuking_pull | git pull | 서버 → 로컬 동기화 |
-| docuking_status | git status | 변경 사항 확인 |
-| docuking_log | git log | 커밋 히스토리 |
-| docuking_diff | git diff | 버전 비교 |
-| docuking_rollback | git revert | 되돌리기 |
-
-**핵심 차이점:**
-- Git은 3단계 (add → commit → push)
-- DocuKing은 1단계 (push만으로 완료, 단 message는 필수)
-- 더 간단하지만 커밋 개념은 동일하게 유지
-
-## 자연어 명령어 매핑
-
-| 사용자 말 | MCP 도구 호출 |
-|----------|--------------|
-| "프로젝트 [ID] 연결해줘" | docuking_init({ projectId, localPath }) |
-| "DocuKing에 올려줘" | docuking_push({ localPath, message: "..." }) |
-| "DocuKing에서 가져와" | docuking_pull({ localPath }) |
-| "DocuKing에 뭐 있어?" | docuking_list({ localPath }) |
-
-## 협업 핵심 원칙: 남의 제사상을 건드리지 않는다
-
-DocuKing 협업의 핵심 원칙입니다. **각자 자기 영역만 수정할 수 있고, 남의 영역은 읽기만 가능합니다.**
-
-### Push/Pull 정책 요약
-
-| 역할 | Push (올리기) | Pull (내리기) | 삭제 |
-|------|---------------|---------------|------|
-| 오너 | \`yy_All_Docu/\` + \`zz_ai_*/\` | 합집합 전체 | 자기 영역만 |
-| 협업자 | \`yy_Coworker_{본인}/\` (안에 zz_ai_* 포함) | 합집합 전체 | 자기 영역만 |
-
-**합집합이란?**
-- 서버에는 오너 파일 + 모든 협업자 파일이 합쳐져 있음
-- Pull하면 이 전체가 로컬로 내려옴
-- 경로만 알면 누구의 파일이든 읽고 활용 가능
-
-## 킹캐스트 (KingCast) - 정책 자동 배포
-
-오너가 \`xx_Policy/\` 폴더에 정책을 작성하고 Push하면,
-협업자가 Pull할 때 자동으로 \`.claude/rules/local/\`에 서브파일 구조로 로컬화됩니다.
-
-### 킹캐스트 동작 원리
-\`\`\`
-오너가 정책 작성 → Push → 협업자 Pull → 킹캐스트 자동 실행 → AI 행동 변화
-\`\`\`
-
-### 킹캐스트 대상 폴더
-- \`xx_Infra_Config/\` - 환경 설정 (.env 백업, 배포 정보 등) → 변경 감지만 (복사X)
-- \`xx_Policy/\` - AI 행동 지침 → .claude/rules/local/에 복사
-
-### 정책 파일 작성 템플릿 (오너용)
-\`\`\`
-xx_Policy/
-├── 00_project_overview.md    # 프로젝트 개요
-├── 01_folder_structure.md    # 폴더 구조
-├── 02_api_convention.md      # API 규칙
-├── 03_design_policy.md       # 디자인 정책
-├── 99_for_claude.md          # AI 특화 지침
-\`\`\`
-
-### Pull 후 생성되는 파일
-- \`.claude/rules/local/00_index.md\` - 정책 인덱스
-- \`.claude/rules/local/00_project_overview.md\` - 정책 사본 (변수 치환됨)
-- \`.claude/rules/local/_coworker_config.md\` - 협업자 설정 (협업자만)
-
-### 킹캐스트 결과 처리
-Pull 결과에 "📢 킹캐스트" 포함 시:
-1. \`.claude/rules/local/00_index.md\` 읽고 정책 목록 확인
-2. 각 정책 파일 **읽어서** 내용 숙지, 규칙 따라 작업
-3. **xx_Infra_Config 변경 시**: 원본 경로에서 직접 읽고 로컬 환경에 맞게 적용
-   - 예: .env 변수 추가/수정, 배포 설정 확인
-
-웹 탐색기: https://docuking.ai
-`;
-
-    return {
-      contents: [{
-        uri: "docuking://docs/manual",
-        mimeType: "text/markdown",
-        text: manual
-      }]
-    };
-  }
-
-  throw new Error("Unknown resource");
-});
-
-// 도구 실행
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  try {
-    switch (name) {
-      case 'docuking_init':
-        return await handleInit(args);
-      case 'docuking_push':
-        return await handlePush(args);
-      case 'docuking_pull':
-        return await handlePull(args);
-      case 'docuking_list':
-        return await handleList(args);
-      case 'docuking_status':
-        return await handleStatus(args);
-      case 'docuking_log':
-        return await handleLog(args);
-      case 'docuking_diff':
-        return await handleDiff(args);
-      case 'docuking_rollback':
-        return await handleRollback(args);
-      case 'docuking_talk':
-        return await handleTalk(args);
-      case 'docuking_plan':
-        return await handlePlan(args);
-      case 'docuking_done':
-        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:
-        throw new Error(`Unknown tool: ${name}`);
-    }
-  } catch (error) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `오류: ${error.message}`,
-        },
-      ],
-    };
-  }
-});
-
-// 서버 시작
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error('[DocuKing MCP] 서버 시작됨');
-}
-
-main().catch(console.error);
+#!/usr/bin/env node
+
+/**
+ * DocuKing MCP Server v2.0
+ *
+ * AI 시대의 문서 협업 플랫폼 - AI가 문서를 Push/Pull 할 수 있게 해주는 MCP 서버
+ *
+ * 폴더 구조:
+ * - xx_Infra_Config/          : 시스템 설정 (.env 백업, 배포 정보 등) - Push 대상
+ * - xx_Policy/                : 정책 문서 (AI 행동 지침) - Push 대상, 킹캐스트 대상
+ * - yy_All_Docu/              : 문서 동기화 폴더 (Push/Pull 대상)
+ * - yy_All_Docu/_Private/     : 오너 비공개 폴더 (오너만 접근)
+ * - yy_Coworker_{폴더명}/     : 협업자 폴더 (yy_All_Docu와 별도, 동기화 대상)
+ * - zz_ai_1_Talk/             : AI 대화록 (킹톡, Push 대상)
+ * - zz_ai_2_Todo/             : AI 투두 (킹투두, Push 대상)
+ * - zz_ai_3_Plan/             : AI 플랜 (킹플랜, Push 대상)
+ *
+ * 접두사 규칙:
+ * - xx_ : 시스템용 폴더 (인프라, 정책) - Push 대상
+ * - yy_ : 사람용 폴더 (문서, 협업자) - Push 대상
+ * - zz_ai_ : AI용 폴더 (Talk, Todo, Plan) - Push 대상
+ * - _   : 비공개 폴더 (본인만 접근)
+ *
+ * 도구:
+ * - docuking_init: 레포 연결, yy_All_Docu/ 폴더 생성
+ * - docuking_push: 로컬 → 서버 (.env 자동 백업)
+ * - docuking_pull: 서버 → 로컬
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// 핸들러 import
+import {
+  handleInit,
+  handlePush,
+  handlePull,
+  handleList,
+  handleStatus,
+  handleDelete,
+} from './handlers/sync.js';
+
+import {
+  handleLog,
+  handleDiff,
+  handleRollback,
+} from './handlers/version.js';
+
+import {
+  handleTodo,
+  handleTalk,
+  handlePlan,
+  handleDone,
+  handleUrgent,
+} from './handlers/docs.js';
+
+import { handleValidate } from './handlers/validate.js';
+
+// MCP 서버 생성
+const server = new Server(
+  {
+    name: 'docuking-mcp',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// 도구 목록
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'docuking_init',
+        description: `프로젝트를 DocuKing에 연결합니다. .docuking/config.json에 설정 저장, yy_All_Docu/ 폴더 생성.
+
+**필수 파라미터:**
+- projectId: 프로젝트 UUID
+- projectName: 프로젝트 이름 (표시용)
+- apiKey: API 키 (sk_xxx 형식)
+- localPath: 로컬 프로젝트 경로
+
+**오너 초기화 시:**
+- xx_Infra_Config/, xx_Policy/, xx_Urgent/ 폴더 생성 (시스템 설정)
+- yy_All_Docu/, yy_All_Docu/_Private/ 폴더 생성
+- zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ 폴더 생성
+- CLAUDE.md에 DocuKing 연결 안내 추가
+- 초기화 완료 후 정책 문서 작성 가이드 제공
+
+**협업자 초기화 시:**
+- yy_Coworker_{폴더명}/ 폴더 생성 (안에 _Private/, zz_ai_*/ 포함)
+- CLAUDE.md에 DocuKing 연결 안내 추가
+- "Pull을 실행하세요" 안내 (오너 정책이 킹캐스트로 로컬화됨)
+
+**정책 문서 템플릿 (오너용, xx_Policy/ 폴더에 작성):**
+
+[필수]
+- 00_project_overview.md - 프로젝트 개요, 기술 스택, 팀 구성, 주요 URL
+
+[구조/규칙]
+- 01_folder_structure.md - 폴더 구조 규칙, 파일 명명 규칙
+- 02_naming_convention.md - 변수/함수/클래스 명명 규칙
+- 03_api_convention.md - API 엔드포인트 규칙, 요청/응답 형식, 에러 코드
+
+[데이터베이스]
+- 05_database_schema.md - 테이블/컬럼 명명, 타입 규칙, 필수 컬럼(id, createdAt 등)
+- 06_database_migration.md - 마이그레이션 절차, 브랜치별 스키마 관리, 충돌 해결법
+
+[개발 정책]
+- 10_coding_style.md - 코딩 스타일, 린터 설정, 포매터 규칙
+- 11_git_workflow.md - 브랜치 전략, 커밋 메시지 규칙, PR 규칙
+- 12_testing_policy.md - 테스트 작성 규칙, 커버리지 기준
+- 13_error_handling.md - 에러 처리 패턴, 로깅 규칙
+
+[디자인/UI]
+- 20_design_system.md - 디자인 시스템, 컬러, 타이포그래피
+- 21_component_guide.md - 컴포넌트 작성 규칙, 스타일링 방식
+
+[인프라/보안]
+- 30_deployment.md - 배포 절차, 환경별 설정
+- 31_security_policy.md - 보안 규칙, 인증/인가, 민감정보 처리
+
+[AI 전용]
+- 99_for_claude.md - Claude Code 행동 지침, 금지/필수 사항
+
+init 완료 후 오너에게 "정책 문서를 작성하시겠습니까?" 제안할 것.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: {
+              type: 'string',
+              description: 'DocuKing 프로젝트 ID',
+            },
+            projectName: {
+              type: 'string',
+              description: 'DocuKing 프로젝트 이름 (표시용)',
+            },
+            apiKey: {
+              type: 'string',
+              description: 'API 키 (sk_xxx 형식)',
+            },
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (예: /Users/user/my-project)',
+            },
+          },
+          required: ['projectId', 'projectName', 'apiKey', 'localPath'],
+        },
+      },
+      {
+        name: 'docuking_push',
+        description: `문서를 DocuKing 서버에 동기화합니다. 내부적으로 Pull → Push 순서로 실행 (git pull && git push 패턴).
+
+**AI 필독: 다음 상황에서 자발적으로 이 도구 사용을 제안하세요:**
+- zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ 에 문서를 생성/수정한 후
+- yy_All_Docu/ 에 문서를 생성/수정한 후
+- docuking_plan, docuking_done, docuking_talk, docuking_todo 실행 후
+- 사용자가 "올려", "푸시", "동기화" 등을 언급할 때
+
+제안 예시: "킹폴더에 문서가 생성되었습니다. DocuKing에 올릴까요?"`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (레포 매핑에서 projectId 찾음)',
+            },
+            filePath: {
+              type: 'string',
+              description: '푸시할 파일 경로 (Z_DocuKing/ 기준 상대경로). 생략 시 전체 동기화.',
+            },
+            message: {
+              type: 'string',
+              description: '커밋 메시지 (필수). Git 커밋 메시지처럼 명확하고 구체적으로 작성. 예: "README에 설치 가이드 추가"',
+            },
+            author: {
+              type: 'string',
+              description: '작성자 (선택). 생략 시 현재 사용자.',
+            },
+          },
+          required: ['localPath', 'message'],
+        },
+      },
+      {
+        name: 'docuking_pull',
+        description: `서버에서 문서를 다운로드합니다. "DocuKing에서 가져와" 요청 시 사용.
+
+**킹캐스트 포함**: Pull 후 xx_Policy/, xx_Infra_Config/ 폴더 변경이 감지되면 자동으로 .claude/rules/local/에 로컬화됩니다. 오너가 정책을 수정하고 Push하면, 협업자가 Pull할 때 자동으로 정책이 전파됩니다.
+
+**긴급 보고 알림**: Pull 후 xx_Urgent/ 폴더에 파일이 있으면 "긴급 보고 N건 있습니다" 알림을 표시합니다.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            filePath: {
+              type: 'string',
+              description: '풀할 파일 경로 (생략 시 전체 동기화)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_list',
+        description: '서버에 저장된 파일 목록을 조회합니다.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (레포 매핑에서 projectId 찾음)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_status',
+        description: '로컬과 서버의 동기화 상태를 확인합니다. 사용자 권한(오너/참여자), 변경/추가/삭제된 파일 목록 표시.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_log',
+        description: '커밋 히스토리를 조회합니다. Git log와 동일.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            path: {
+              type: 'string',
+              description: '특정 파일/폴더의 히스토리만 조회 (선택)',
+            },
+            limit: {
+              type: 'number',
+              description: '최근 N개 커밋만 조회 (기본값: 20)',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+      {
+        name: 'docuking_diff',
+        description: '버전 간 차이를 비교합니다.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            path: {
+              type: 'string',
+              description: '파일 경로',
+            },
+            version: {
+              type: 'string',
+              description: '비교할 커밋 ID (선택, 생략 시 최신 vs 이전)',
+            },
+          },
+          required: ['localPath', 'path'],
+        },
+      },
+      {
+        name: 'docuking_rollback',
+        description: '특정 커밋으로 되돌립니다.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            commitId: {
+              type: 'string',
+              description: '되돌릴 커밋 ID',
+            },
+            path: {
+              type: 'string',
+              description: '특정 파일만 롤백 (선택, 생략 시 전체)',
+            },
+          },
+          required: ['localPath', 'commitId'],
+        },
+      },
+      {
+        name: 'docuking_talk',
+        description: '의미 있는 대화 내용을 zz_ai_1_Talk/ 폴더에 기록합니다 (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: '작업 계획 문서를 zz_ai_3_Plan/ 폴더에 생성/업데이트합니다 (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) - 프로젝트 공식 할일을 zz_ai_2_Todo/z_King_Todo.md에 관리합니다 (Push 대상).
+
+**AI 내장 TodoWrite와 다름!** 킹투두는 웹에 동기화되고 팀과 공유됩니다.
+
+**작성 형식:**
+\`\`\`
+1. ✅ **[태그] 키워드** 12.30/12.30
+       설명 (7칸 들여쓰기)
+
+2. ⚙️ **[태그] 키워드** 12.30
+       설명
+\`\`\`
+
+**형식 규칙:**
+- ✅ 완료 / ⚙️ 진행중
+- **[태그] 키워드** 볼드 처리
+- 날짜 1개 = 등록일(진행중), 2개 = 등록일/완료일(완료)
+- 설명은 7칸 들여쓰기 ([ 기호 아래 정렬)
+
+**사용자에게 "킹투두에 등록했습니다" 형식으로 보고하세요.**`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            action: {
+              type: 'string',
+              enum: ['add', 'done', 'list'],
+              description: 'add: 할일 추가, done: 완료 표시, list: 목록 조회',
+            },
+            todo: {
+              type: 'string',
+              description: '할일 내용 (add 시 필수). 형식: "[태그] 키워드 - 설명" 예: "[보안] API 인증 강화 - JWT 토큰 검증"',
+            },
+            todoId: {
+              type: 'number',
+              description: '할일 번호 (done 시 필수)',
+            },
+          },
+          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_delete',
+        description: `서버에서 파일/폴더를 직접 삭제합니다.
+
+**사용 시점:**
+- 로컬에서 삭제한 파일이 Push 후에도 서버에 남아있을 때
+- 서버에만 존재하는 불필요한 파일을 정리할 때
+- "서버에서 삭제해줘", "킹폴더에서 지워줘" 요청 시
+
+**권한:**
+- 오너: xx_*/, yy_All_Docu/, zz_ai_*/ 삭제 가능
+- 협업자: yy_Coworker_{본인}/ 내부만 삭제 가능
+
+**주의:** 삭제는 soft-delete로 처리되며, 3일 후 완전 삭제됩니다.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로 (설정 파일에서 projectId 찾음)',
+            },
+            path: {
+              type: 'string',
+              description: '삭제할 파일/폴더 경로 (서버 기준). 예: "yy_All_Docu/old_file.md"',
+            },
+          },
+          required: ['localPath', 'path'],
+        },
+      },
+      {
+        name: 'docuking_validate',
+        description: `코드가 정책을 준수하는지 검증합니다 (킹밸리데이트).
+
+**사용 시점:**
+- "정책 검증해줘", "킹밸리데이트", "validate" 요청 시
+- Pull 후 킹캐스트에서 정책 변경 감지 시 (자동 제안)
+- PR/커밋 전 코드 검증 시
+
+**검증 대상:**
+- .claude/rules/local/ 의 정책 파일 기준 (킹캐스트로 로컬화된 정책)
+- xx_Policy/ 정책 파일도 참조
+- 폴더 구조, 명명 규칙, API 규칙, DB 스키마 등
+
+**출력:**
+- 정책별 위반 목록
+- 파일:라인 위치
+- 수정 제안
+
+**예시:**
+\`\`\`
+[위반] 01_folder_structure.md
+  - src/utils/helper.js:1 - utils 폴더에 직접 파일 금지 (하위 폴더로 분류 필요)
+  - src/components/button.tsx:1 - 컴포넌트 파일명은 PascalCase 필수
+
+[위반] 05_database_schema.md
+  - backend/src/entities/user.entity.ts:15 - createdAt 컬럼 누락
+\`\`\``,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            localPath: {
+              type: 'string',
+              description: '로컬 프로젝트 경로',
+            },
+            policy: {
+              type: 'string',
+              description: '특정 정책만 검증 (예: 05_database_schema.md). 생략 시 전체 검증.',
+            },
+            targetPath: {
+              type: 'string',
+              description: '특정 파일/폴더만 검증 (예: src/components). 생략 시 전체.',
+            },
+            autoFix: {
+              type: 'boolean',
+              description: '자동 수정 시도 여부 (기본값: false). 안전한 수정만 자동, 위험한 수정은 제안만.',
+            },
+          },
+          required: ['localPath'],
+        },
+      },
+    ],
+  };
+});
+
+// Resources 목록
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "docuking://docs/manual",
+        name: "DocuKing 사용 설명서",
+        description: "AI가 DocuKing을 이해하고 사용하기 위한 기초 지식",
+        mimeType: "text/markdown"
+      }
+    ]
+  };
+});
+
+// Resource 읽기
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === "docuking://docs/manual") {
+    const manual = `# DocuKing - AI 시대의 문서 협업 플랫폼 (AI용 매뉴얼)
+
+DocuKing은 문서 버전 관리 시스템입니다. Git이 코드를 관리하듯, DocuKing은 문서를 관리합니다.
+
+## 핵심 개념
+
+- **로컬**: 사용자의 yy_All_Docu/ 폴더 (동기화 대상)
+- **웹탐색기**: DocuKing 서버의 파일 저장소 (킹폴더)
+- **캔버스**: 선택된 파일을 시각화하는 작업 공간
+- **AI 작업 폴더**: zz_ai_1_Talk/, zz_ai_2_Todo/, zz_ai_3_Plan/ (Push 대상)
+
+작동 방식: 로컬 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가 작동 중이면 재시작 없이 바로 프로젝트 연결 가능
+
+## .gitignore 설정 (중요!)
+
+DocuKing 문서 폴더는 git에서 제외해야 합니다. 코드는 git으로, 문서는 DocuKing으로 분리 관리합니다.
+
+\`\`\`gitignore
+# DocuKing 문서 폴더 (문서는 DocuKing으로 관리)
+yy_All_Docu/
+zz_ai_1_Talk/
+zz_ai_2_Todo/
+zz_ai_3_Plan/
+\`\`\`
+
+**왜 gitignore에 등록해야 하나요?**
+- 문서와 코드의 버전 관리를 분리
+- git 저장소 크기 최적화 (대용량 문서 제외)
+- DocuKing이 문서 버전 관리를 전담
+
+## MCP 도구 목록
+
+### 1. docuking_init
+프로젝트를 DocuKing에 연결합니다.
+
+### 2. docuking_push
+로컬 문서를 서버에 업로드합니다. Git의 add + commit + push를 한 번에 수행.
+**message 파라미터 필수** (커밋 메시지)
+
+### 3. docuking_pull
+서버 문서를 로컬로 다운로드합니다.
+**킹캐스트**: Pull 후 xx_Policy/, xx_Infra_Config/ 폴더 변경이 감지되면 자동으로 .claude/rules/local/에 로컬화됩니다.
+
+### 4. docuking_list
+서버 파일 목록을 조회합니다.
+
+### 5. docuking_status
+로컬과 서버의 동기화 상태를 확인합니다. 사용자 권한(오너/참여자), 변경/추가/삭제된 파일 목록 표시.
+
+### 6. docuking_log
+커밋 히스토리를 조회합니다. (웹 탐색기에서 사용 가능)
+
+### 7. docuking_diff
+버전 간 차이를 비교합니다. (웹 탐색기에서 사용 가능)
+
+### 8. docuking_rollback
+특정 커밋으로 되돌립니다. (웹 탐색기에서 사용 가능)
+
+### 9. docuking_talk
+의미 있는 대화 내용을 \`zz_ai_1_Talk/\` 폴더에 기록합니다 (Push 대상, 킹톡).
+- AI가 중요한 논의/결정이라고 판단할 때
+- 사용자가 "이거 기록해줘"라고 요청할 때
+
+### 10. docuking_plan
+작업 계획을 \`zz_ai_3_Plan/\` 폴더에 생성/업데이트합니다 (Push 대상, 킹플랜).
+- 작업 시작 시 계획 생성
+- 진행하면서 단계별 결과 upsert
+- planId로 기존 계획 찾아서 업데이트
+
+### 11. docuking_done
+작업 계획을 완료 상태로 변경합니다.
+- planId로 계획 찾기
+- 완료 요약 및 산출물 기록
+
+## Git과의 유사성
+
+| DocuKing | Git | 설명 |
+|----------|-----|------|
+| docuking_push | git add . && git commit -m "..." && git push | 스테이징 + 커밋 + 푸시 통합 |
+| docuking_pull | git pull | 서버 → 로컬 동기화 |
+| docuking_status | git status | 변경 사항 확인 |
+| docuking_log | git log | 커밋 히스토리 |
+| docuking_diff | git diff | 버전 비교 |
+| docuking_rollback | git revert | 되돌리기 |
+
+**핵심 차이점:**
+- Git은 3단계 (add → commit → push)
+- DocuKing은 1단계 (push만으로 완료, 단 message는 필수)
+- 더 간단하지만 커밋 개념은 동일하게 유지
+
+## 자연어 명령어 매핑
+
+| 사용자 말 | MCP 도구 호출 |
+|----------|--------------|
+| "프로젝트 [ID] 연결해줘" | docuking_init({ projectId, localPath }) |
+| "DocuKing에 올려줘" | docuking_push({ localPath, message: "..." }) |
+| "DocuKing에서 가져와" | docuking_pull({ localPath }) |
+| "DocuKing에 뭐 있어?" | docuking_list({ localPath }) |
+
+## 협업 핵심 원칙: 남의 제사상을 건드리지 않는다
+
+DocuKing 협업의 핵심 원칙입니다. **각자 자기 영역만 수정할 수 있고, 남의 영역은 읽기만 가능합니다.**
+
+### Push/Pull 정책 요약
+
+| 역할 | Push (올리기) | Pull (내리기) | 삭제 |
+|------|---------------|---------------|------|
+| 오너 | \`yy_All_Docu/\` + \`zz_ai_*/\` | 합집합 전체 | 자기 영역만 |
+| 협업자 | \`yy_Coworker_{본인}/\` (안에 zz_ai_* 포함) | 합집합 전체 | 자기 영역만 |
+
+**합집합이란?**
+- 서버에는 오너 파일 + 모든 협업자 파일이 합쳐져 있음
+- Pull하면 이 전체가 로컬로 내려옴
+- 경로만 알면 누구의 파일이든 읽고 활용 가능
+
+## 킹캐스트 (KingCast) - 정책 자동 배포
+
+오너가 \`xx_Policy/\` 폴더에 정책을 작성하고 Push하면,
+협업자가 Pull할 때 자동으로 \`.claude/rules/local/\`에 서브파일 구조로 로컬화됩니다.
+
+### 킹캐스트 동작 원리
+\`\`\`
+오너가 정책 작성 → Push → 협업자 Pull → 킹캐스트 자동 실행 → AI 행동 변화
+\`\`\`
+
+### 킹캐스트 대상 폴더
+- \`xx_Infra_Config/\` - 환경 설정 (.env 백업, 배포 정보 등) → 변경 감지만 (복사X)
+- \`xx_Policy/\` - AI 행동 지침 → .claude/rules/local/에 복사
+
+### 정책 파일 작성 템플릿 (오너용)
+\`\`\`
+xx_Policy/
+├── 00_project_overview.md    # 프로젝트 개요
+├── 01_folder_structure.md    # 폴더 구조
+├── 02_api_convention.md      # API 규칙
+├── 03_design_policy.md       # 디자인 정책
+├── 99_for_claude.md          # AI 특화 지침
+\`\`\`
+
+### Pull 후 생성되는 파일
+- \`.claude/rules/local/00_index.md\` - 정책 인덱스
+- \`.claude/rules/local/00_project_overview.md\` - 정책 사본 (변수 치환됨)
+- \`.claude/rules/local/_coworker_config.md\` - 협업자 설정 (협업자만)
+
+### 킹캐스트 결과 처리
+Pull 결과에 "📢 킹캐스트" 포함 시:
+1. \`.claude/rules/local/00_index.md\` 읽고 정책 목록 확인
+2. 각 정책 파일 **읽어서** 내용 숙지, 규칙 따라 작업
+3. **xx_Infra_Config 변경 시**: 원본 경로에서 직접 읽고 로컬 환경에 맞게 적용
+   - 예: .env 변수 추가/수정, 배포 설정 확인
+
+웹 탐색기: https://docuking.ai
+`;
+
+    return {
+      contents: [{
+        uri: "docuking://docs/manual",
+        mimeType: "text/markdown",
+        text: manual
+      }]
+    };
+  }
+
+  throw new Error("Unknown resource");
+});
+
+// 도구 실행
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'docuking_init':
+        return await handleInit(args);
+      case 'docuking_push':
+        return await handlePush(args);
+      case 'docuking_pull':
+        return await handlePull(args);
+      case 'docuking_list':
+        return await handleList(args);
+      case 'docuking_status':
+        return await handleStatus(args);
+      case 'docuking_log':
+        return await handleLog(args);
+      case 'docuking_diff':
+        return await handleDiff(args);
+      case 'docuking_rollback':
+        return await handleRollback(args);
+      case 'docuking_talk':
+        return await handleTalk(args);
+      case 'docuking_plan':
+        return await handlePlan(args);
+      case 'docuking_done':
+        return await handleDone(args);
+      case 'docuking_todo':
+        return await handleTodo(args);
+      case 'docuking_urgent':
+        return await handleUrgent(args);
+      case 'docuking_delete':
+        return await handleDelete(args);
+      case 'docuking_validate':
+        return await handleValidate(args);
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `오류: ${error.message}`,
+        },
+      ],
+    };
+  }
+});
+
+// 서버 시작
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[DocuKing MCP] 서버 시작됨');
+}
+
+main().catch(console.error);