kadoc-mcp


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

기능

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

설치

``bash


설치 없이 바로 실행

npx @kawoou/kadoc-mcp

또는 글로벌 설치

npm install -g @kawoou/kadoc-mcp
kadoc-mcp
`

설정

$3

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

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

$3

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

`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"
}
`

수동 등록 시:
`bash
curl -X POST http://localhost:3000/auth/register
`
응답의 authKey를 설정 파일에 저장

Claude Desktop 설정

claude_desktop_config.json에 추가:

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

또는 기존 설정 파일 사용 시:
`json
{
"mcpServers": {
"kadoc": {
"command": "npx",
"args": ["@kawoou/kadoc-mcp"],
"env": {
"KADOC_CONFIG": "~/.kadoc.json"
}
}
}
}
`

MCP Tools

$3


| 도구 | 설명 |
|------|------|
| 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 생성

$3


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

metadata는 임의의 키-값 쌍을 저장하는 JSON 객체입니다:
`json
{ "author": "홍길동", "tags": ["회의", "2024"], "priority": "high" }
`

$3


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

$3

| 도구 | 설명 |
|------|------|
| 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. 세션 만료 시 자동 재연결

수동으로 세션 제어:
`typescript
import { KadocClient } from '@kawoou/kadoc-mcp';

const client = new KadocClient(config);

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

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

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

개발

`bash


의존성 설치

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