npm package: @kawoou/kadoc-mcp
Description: MCP client for kadoc-server document management system
Latest version: 0.1.15

# kadoc-mcp

[![npm version](https://badge.fury.io/js/%40kawoou%2Fkadoc-mcp.svg)](https://www.npmjs.com/package/@kawoou/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
```

## 설정

### 자동 설정 (권장)

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

1. `KADOC_SERVER_URL` 환경 변수 설정 (또는 기본값 `http://localhost:3000` 사용)
2. Claude Desktop에서 MCP 실행
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

### 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 객체입니다:
```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. 세션 만료 시 자동 재연결

수동으로 세션 제어:
```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