kadoc-mcp

kadoc-server를 위한 MCP (Model Context Protocol) 클라이언트

기능

• kadoc-server 문서 CRUD 연동
• BM25 전문 검색
• 폴더 관리
• 봉투 암호화 세션 지원 (X25519 + XSalsa20-Poly1305)
• 자동 세션 관리

설치

# 설치 없이 바로 실행
npx @kawoou/kadoc-mcp

# 또는 글로벌 설치
npm install -g @kawoou/kadoc-mcp
kadoc-mcp

설정

자동 설정 (권장)

MCP가 처음 실행될 때 설정 파일이 없으면 자동으로 사용자를 등록하고 ~/.kadoc.json 파일을 생성합니다.

1. KADOC_SERVER_URL 환경 변수 설정 (또는 기본값 http://localhost:3000 사용)
2. Claude Desktop에서 MCP 실행
3. 자동으로 사용자 등록 및 설정 파일 생성 완료

수동 설정

~/.kadoc.json 파일을 직접 생성할 수도 있습니다:

{
  "servers": {
    "default": {
      "url": "http://localhost:3000",
      "auth": {
        "authKey": "your-auth-key-from-register"
      }
    },
    "production": {
      "url": "https://kadoc.example.com",
      "auth": {
        "authKey": "production-auth-key"
      }
    }
  },
  "defaultServer": "default"
}

수동 등록 시:

curl -X POST http://localhost:3000/auth/register

응답의 authKey를 설정 파일에 저장

Claude Desktop 설정

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "kadoc": {
      "command": "npx",
      "args": ["@kawoou/kadoc-mcp"],
      "env": {
        "KADOC_SERVER_URL": "http://localhost:3000"
      }
    }
  }
}

또는 기존 설정 파일 사용 시:

{
  "mcpServers": {
    "kadoc": {
      "command": "npx",
      "args": ["@kawoou/kadoc-mcp"],
      "env": {
        "KADOC_CONFIG": "~/.kadoc.json"
      }
    }
  }
}

MCP Tools

JSON 데이터 관리

| 도구 | 설명 | |------|------| | read_json | JSON 문서 읽기 (path, jsonPath?) | | write_json | JSON 문서 생성/수정 (path, title, data?, jsonPath?, metadata?) | | delete_json | JSON 문서 삭제 (path) | | list_json | JSON 문서 목록 조회 (folder?, cursor?, limit?) | | append_json | JSON 배열에 요소 추가 (path, jsonPath, data) | | transform_json | JSONata 표현식으로 변환 (path, expression, jsonPath?) | | new_json | 자동 ID로 새 문서 생성 (prefix, path?, use_auto_id?, title?, data?, metadata?) |

new_json 도구는 타임스탬프 기반 자동 ID를 생성합니다:

• use_auto_id=true (기본값): prefix_yyyyMMddHHmm_00001 형식
• use_auto_id=false: prefix를 파일명으로 직접 사용
• 동시성 안전한 Lock 기반 ID 생성

문서 관리

| 도구 | 설명 | |------|------| | write_document | 문서 작성 (path, title, content, metadata?) | | update_document | 문서 수정 (path, title?, content?, metadata?) | | read_document | 문서 읽기 (path) | | delete_document | 문서 삭제 (path) | | list_documents | 문서 목록 조회 (folder?, limit?) |

metadata는 임의의 키-값 쌍을 저장하는 JSON 객체입니다:

{ "author": "홍길동", "tags": ["회의", "2024"], "priority": "high" }

검색

| 도구 | 설명 | |------|------| | search | BM25 기반 전문 검색 (query, folder?, limit?) |

폴더 관리

| 도구 | 설명 | |------|------| | create_folder | 폴더 생성 (path) | | list_folders | 폴더 목록 조회 (limit?, sort?, order?) | | delete_folder | 폴더 및 하위 문서 삭제 (path) | | get_index_settings | 인덱스 설정 조회 (path) | | set_index_settings | 인덱스 설정 변경 (path, indexFields?) |

indexFields에 지정된 메타데이터 필드가 검색 인덱스에 포함됩니다. title과 content는 항상 인덱싱되며, 설정 변경 시 폴더 내 문서가 자동 재인덱싱됩니다.

암호화 세션

kadoc-mcp는 자동으로 암호화 세션을 관리합니다:

1. 첫 요청 시 handshake() 호출
2. X25519 ECDH로 shared secret 생성
3. 이후 모든 요청/응답 XSalsa20-Poly1305로 암호화
4. 세션 만료 시 자동 재연결

수동으로 세션 제어:

import { KadocClient } from '@kawoou/kadoc-mcp';

const client = new KadocClient(config);

// 세션 시작
await client.handshake();

// 세션 상태 확인
if (client.hasSession()) {
  // 암호화 통신 중
}

// 세션 종료
await client.endSession();

개발

# 의존성 설치
npm install

# 개발 모드 실행
npm run dev

# 빌드
npm run build

# 테스트
npm test

환경 변수

| 변수 | 설명 | |------|------| | KADOC_SERVER_URL | kadoc-server URL (기본: http://localhost:3000) | | KADOC_CONFIG | 설정 파일 경로 (기본: ~/.kadoc.json) |

프로젝트 구조

src/
├── index.ts           # MCP 서버 엔트리포인트
├── config.ts          # 설정 파일 로더
├── client/
│   └── kadoc-client.ts # HTTP 클라이언트 (암호화 지원)
├── crypto/
│   └── envelope.ts    # 암호화 유틸리티
└── tools/
    ├── json.ts        # JSON MCP 도구
    ├── documents.ts   # 문서 MCP 도구
    ├── folders.ts     # 폴더 MCP 도구
    └── search.ts      # 검색 MCP 도구

라이선스

MIT