# Jobs-tools-knowledgeBase

MongoDB Atlas 기반 Notion 스타일 지식베이스 관리 MCP(Model Context Protocol) 도구입니다.

## 🎯 기능

- **사용자 워크스페이스 격리**: 고유 키로 데이터 분리 보안
- **프로젝트 관리**: 여러 프로젝트 생성 및 관리
- **페이지 CRUD**: 마크다운 형식의 페이지 생성/수정/삭제
- **트리 구조**: Notion처럼 부모-자식 계층 구조 지원
- **검색 기능**: 제목과 본문에서 텍스트 검색
- **MongoDB Atlas 무료 티어**: 클라우드 기반, 무료로 사용 가능

## 📦 설치 및 설정

### 1단계: MongoDB Atlas 설정

1. [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) 무료 계정 생성
2. 무료 클러스터 생성 (M0 Sandbox)
3. Database User 생성
4. Network Access에서 현재 IP 추가 (또는 `0.0.0.0/0` 모든 IP 허용)
5. 연결 문자열 복사:
   ```
   mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority
   ```

### 2단계: 환경 변수 설정

프로젝트 루트에 `.env` 파일 생성:

```bash
# User Key (처음에는 비워둠 - 도구가 생성해줍니다)
JOBS_TOOLS_USER_KEY=

# MongoDB Atlas 연결 정보
MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority
MONGODB_DB=jobs_tools_knowledge
```

### 3단계: MCP 설정 파일에 추가

사용 중인 MCP 클라이언트의 설정 파일 또는 프로젝트 루트 `mcp.json`에 다음을 추가하세요:

**macOS (예시)**:
`~/Library/Application Support/YourClient/config.json`

```json
{
  "mcpServers": {
    "knowledgeBase": {
      "command": "npx",
      "args": ["-y", "jobs-tools-knowledgebase"],
      "env": {
        "JOBS_TOOLS_USER_KEY": "",
        "MONGODB_URI": "mongodb+srv://...",
        "MONGODB_DB": "jobs_tools_knowledge"
      }
    }
  }
}
```

**Windows** (예시):
`%APPDATA%\\YourClient\\config.json`

```json
{
  "mcpServers": {
    "knowledgeBase": {
      "command": "npx.cmd",
      "args": ["-y", "jobs-tools-knowledgebase"],
      "env": {
        "JOBS_TOOLS_USER_KEY": "",
        "MONGODB_URI": "mongodb+srv://...",
        "MONGODB_DB": "jobs_tools_knowledge"
      }
    }
  }
}
```

### 4단계: 초기 설정

MCP 클라이언트에서 아래 문구로 초기화하세요:

```
업무 세팅하자
```

→ 사용자 키 생성 → 환경 변수에 저장 → 클라이언트 재시작

```
업무 시작하자
```

→ MongoDB 연결 확인
→ 프로젝트 및 페이지 사용 시작!

#### 처음 실행 시 자동 응답 예시 (env에 키가 없을 때)

처음 채팅을 시작하면 MCP가 `JOBS_TOOLS_USER_KEY` 여부를 확인합니다. 없으면 아래 형식으로 키와 안내 메시지를 반환합니다:

```json
{
  "userKey": "random-0ser-id",
  "message": "새 사용자 키를 발급했습니다. MCP 설정(env)의 JOBS_TOOLS_USER_KEY에 저장한 뒤, 클라이언트를 재시작하고 다시 대화를 시작해주세요."
}
```

OS별 env 저장 위치는 위의 MCP 설정 파일 예시(macOS/Windows)를 참고하세요. 재시작 후에는 키가 자동 인식되며, 이어서 MongoDB 연결 점검과 프로젝트 작업을 진행합니다.

## 🚀 사용법

### 초기 설정

```
업무 세팅하자
```

도구가 사용자 키를 생성하고 반환합니다. 이 키를 MCP 설정의 `JOBS_TOOLS_USER_KEY`에 저장하세요.

### MongoDB 연결 확인

```
MongoDB 연결 상태 확인해줘
```

### 프로젝트 생성

```
"개인 노트" 프로젝트 만들어줘
```

### 프로젝트 목록 조회

```
내 프로젝트 목록 보여줘
```

### 페이지 생성

```
"개인 노트" 프로젝트에 "회의록" 페이지 만들어줘
내용: # 2025-01-15 팀 미팅
- 참석자: A, B, C
- 안건: 프로젝트 계획
```

### 페이지 조회

```
프로젝트 [projectId]의 페이지 [pageId] 내용 보여줘
```

### 트리 구조 조회

```
"개인 노트" 프로젝트의 페이지 구조 보여줘
```

### 페이지 이동

```
페이지 [pageId]를 부모 [parentId] 아래로 이동해줘
```

### 페이지 검색

```
"개인 노트" 프로젝트에서 "회의록" 검색해줘
```

## 📋 API

### Jobs-tools-knowledgeBase-getOrCreateUserKey

사용자 키 가져오기 또는 생성

**입력:** 없음

**출력:**

- `userKey`: 사용자 고유 키
- `hint`: 안내 메시지

### Jobs-tools-knowledgeBase-checkMongo

MongoDB 연결 상태 확인

**입력:** 없음

**출력:**

- `ok`: 연결 성공 여부
- `message`: 상태 메시지

### Jobs-tools-knowledgeBase-createProject

프로젝트 생성

**입력:**

- `name` (string, 필수): 프로젝트 이름
- `description` (string, 선택): 프로젝트 설명

**출력:**

- `projectId`: 생성된 프로젝트 ID

### Jobs-tools-knowledgeBase-listProjects

프로젝트 목록 조회

**입력:** 없음

**출력:**

- `projects`: 프로젝트 배열
  - `projectId`: 프로젝트 ID
  - `name`: 프로젝트 이름
  - `description`: 프로젝트 설명
  - `createdAt`: 생성 시간

### Jobs-tools-knowledgeBase-upsertPage

페이지 생성 또는 갱신

**입력:**

- `projectId` (string, 필수): 프로젝트 ID
- `pageId` (string, 선택): 페이지 ID (갱신 시 필요)
- `title` (string, 필수): 페이지 제목
- `content` (string, 필수): 페이지 내용 (마크다운)
- `parentId` (string, 선택): 부모 페이지 ID
- `order` (number, 선택): 정렬 순서
- `tags` (string[], 선택): 태그 배열

**출력:**

- `pageId`: 생성/갱신된 페이지 ID

### Jobs-tools-knowledgeBase-getPage

페이지 조회

**입력:**

- `projectId` (string, 필수): 프로젝트 ID
- `pageId` (string, 필수): 페이지 ID

**출력:**

- `page`: 페이지 정보
  - `pageId`: 페이지 ID
  - `title`: 제목
  - `content`: 내용
  - `parentId`: 부모 페이지 ID
  - `order`: 정렬 순서
  - `tags`: 태그 배열
  - `createdAt`: 생성 시간
  - `updatedAt`: 수정 시간

### Jobs-tools-knowledgeBase-deletePage

페이지 삭제

**입력:**

- `projectId` (string, 필수): 프로젝트 ID
- `pageId` (string, 필수): 페이지 ID

**출력:**

- `deleted`: 삭제 성공 여부

### Jobs-tools-knowledgeBase-getTree

페이지 트리 구조 조회

**입력:**

- `projectId` (string, 필수): 프로젝트 ID

**출력:**

- `tree`: 트리 구조 배열 (재귀적)
  - `pageId`: 페이지 ID
  - `title`: 제목
  - `order`: 정렬 순서
  - `children`: 자식 페이지 배열

### Jobs-tools-knowledgeBase-movePage

페이지 이동

**입력:**

- `projectId` (string, 필수): 프로젝트 ID
- `pageId` (string, 필수): 페이지 ID
- `newParentId` (string, 필수): 새 부모 페이지 ID (루트는 null)
- `newOrder` (number, 선택): 새 정렬 순서

**출력:**

- `moved`: 이동 성공 여부

### Jobs-tools-knowledgeBase-search

페이지 검색 (제목 및 본문)

**입력:**

- `projectId` (string, 필수): 프로젝트 ID
- `query` (string, 필수): 검색어

**출력:**

- `results`: 검색 결과 배열
  - `pageId`: 페이지 ID
  - `title`: 페이지 제목
  - `snippet`: 검색어 주변 텍스트 스니펫

## 🔧 개발자 정보

### 기술 스택

- **언어**: JavaScript (ES Modules)
- **프레임워크**: Model Context Protocol SDK
- **데이터베이스**: MongoDB Atlas
- **스키마 검증**: Zod

### 로컬 개발

```bash
# 저장소 클론
git clone [repository-url]
cd Jobs-tools-knowledgeBase

# 의존성 설치
npm install

# 환경 변수 설정
cp env.example .env
# .env 파일 수정

# 개발 모드 실행
npm run dev
```

### Lint

```bash
npm run lint
npm run lint:fix
```

## 📄 라이선스

MIT License

## ❓ 문제 해결

### 도구가 로드되지 않는 경우

1. MCP 설정 파일의 JSON 문법이 올바른지 확인
2. MCP 클라이언트를 완전히 재시작
3. 터미널에서 `npx -y jobs-tools-knowledgebase` 명령이 작동하는지 확인

### MongoDB 연결 실패

1. MongoDB Atlas에서 IP가 허용되었는지 확인
2. 연결 문자열의 사용자명/비밀번호 확인
3. 네트워크 방화벽 설정 확인

### 사용자 키 관련 오류

1. `JOBS_TOOLS_USER_KEY`가 환경 변수에 설정되었는지 확인
2. 최초 실행 시 `getOrCreateUserKey` 도구로 키 생성
3. 생성된 키를 MCP 설정의 env에 저장 후 재시작

## 🤝 기여

이슈나 풀 리퀘스트를 환영합니다!

## 📞 연락처

- Author: JobsTools
- Repository: [GitHub 링크]