MCP client for kadoc-server document management system
npm install @kawoou/kadoc-mcp
kadoc-server를 위한 MCP (Model Context Protocol) 클라이언트
- kadoc-server 문서 CRUD 연동
- BM25 전문 검색
- 폴더 관리
- 봉투 암호화 세션 지원 (X25519 + XSalsa20-Poly1305)
- 자동 세션 관리
``bash설치 없이 바로 실행
npx @kawoou/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