# Logseq MCP Server

NestJS 기반 Logseq MCP (Model Context Protocol) 서버입니다.

## 📚 문서 가이드

- **[빠른 시작 (QUICKSTART.md)](./QUICKSTART.md)** - 5분 안에 설정하고 실행하기
- **[사용 예시 (EXAMPLES.md)](./EXAMPLES.md)** - 실제 사용 시나리오별 예시 모음
- **[개발 진행 (PROGRESS.md)](./PROGRESS.md)** - 프로젝트 개발 현황 및 로드맵
- **README.md (이 문서)** - 상세한 기능 설명 및 개발자 가이드

**처음 사용하시나요?** → [QUICKSTART.md](./QUICKSTART.md) 부터 시작하세요!

---

## 개요

이 프로젝트는 Logseq HTTP API를 활용하여 AI 에이전트가 Logseq 그래프와 상호작용할 수 있도록 MCP 도구, 리소스, 프롬프트를 제공합니다.

## 주요 기능

### MCP Tools
- **Journal Tool**: 저널 페이지 생성 및 조회
- **Page Tool**: 페이지 CRUD 및 참조 관리
- **Block Tool**: 블록 CRUD 및 참조 관리
- **Search Tool**: 전문 검색 및 그래프 정보 조회
- **Dev Tool**: 프로젝트 개발 기록 관리 (진행 상황, ADR, TODO, 아이디어)

### MCP Resources
- **Concept Documents**: 프로젝트 개념 설계 문서 접근
- **Project Architecture**: 아키텍처 및 구조 정보
- **Tools Reference**: MCP 도구 참조 문서

### MCP Prompts
- **dev-implement-feature**: 새 기능 구현 가이드
- **dev-code-review**: 코드 리뷰 요청
- **dev-debug-issue**: 이슈 디버깅
- **dev-refactor-suggestion**: 리팩토링 제안
- **dev-project-status**: 프로젝트 상태 파악

## 요구사항

- Node.js 18+
- pnpm 10+
- Logseq (HTTP API 활성화 필요)

## 설치

```bash
pnpm install
```

## 환경 설정

`.env.example`을 `.env`로 복사하고 설정을 수정하세요:

```bash
cp .env.example .env
```

```env
# Logseq 연결 설정
LOGSEQ_HOST=127.0.0.1
LOGSEQ_PORT=12315
LOGSEQ_TOKEN=your-api-token

# 프로젝트 설정 (다른 프로젝트에 적용 시 수정)
PROJECT_NAME=my-project    # 개발 기록이 연결될 Logseq 페이지 이름
DOCS_PATH=./docs           # 개념 설계 문서 경로
```

## 다른 프로젝트에 적용

이 MCP 서버는 어떤 프로젝트에도 적용할 수 있습니다:

1. **환경변수 설정**
   ```env
   PROJECT_NAME=your-project-name  # Logseq에서 사용할 프로젝트 페이지
   DOCS_PATH=./your-docs-folder    # 설계 문서 경로
   ```

2. **문서 구조** (선택)
   ```
   your-docs-folder/
   ├── integration/
   │   └── concept-design.md
   ├── architecture/
   │   └── overview.md
   └── ...
   ```

3. **MCP 클라이언트 설정**
   Claude Desktop 등 MCP 클라이언트에서 이 서버를 연결하면 됩니다.

## 실행

```bash
# 개발 모드
pnpm run start:dev

# 프로덕션 모드
pnpm run start:prod

# 빌드
pnpm run build
```

## 테스트

```bash
# 단위 테스트
pnpm run test

# E2E 테스트
pnpm run test:e2e

# 테스트 커버리지
pnpm run test:cov
```

## MCP 도구 목록

### Journal
- `logseq_add_journal_entry`: 저널에 항목 추가
- `logseq_get_today_journal`: 오늘의 저널 조회
- `logseq_get_journal_by_date`: 특정 날짜 저널 조회

### Page
- `logseq_get_page`: 페이지 조회
- `logseq_create_page`: 페이지 생성
- `logseq_get_page_blocks`: 페이지의 블록 목록 조회
- `logseq_get_page_references`: 페이지 참조 조회

### Block
- `logseq_get_block`: 블록 조회
- `logseq_create_block`: 블록 생성
- `logseq_update_block`: 블록 수정
- `logseq_delete_block`: 블록 삭제
- `logseq_get_block_references`: 블록 참조 조회

### Search
- `logseq_search`: 전문 검색
- `logseq_get_graph_info`: 그래프 정보 조회
- `logseq_get_all_pages`: 모든 페이지 목록 조회

### Dev (개발 기록)
- `dev-log-progress`: 개발 진행 상황 기록
- `dev-decision`: 기술적 결정 사항(ADR) 기록
- `dev-todo`: 개발 TODO 추가
- `dev-idea`: 개발 아이디어 기록
- `dev-get-project-logs`: 프로젝트 개발 로그 조회

## MCP 리소스

| URI | 설명 |
|-----|------|
| `mcp://concepts/logseq-mcp-concept-design` | 핵심 개념 설계 문서 |
| `mcp://concepts/logseq-mcp-user-flows` | 사용자 플로우 문서 |
| `mcp://project/architecture` | 프로젝트 아키텍처 |
| `mcp://project/tools-reference` | MCP 도구 참조 |
| `mcp://concepts/{category}/{document}` | 동적 개념 문서 조회 |

## 동작 원리

### 아키텍처 개요

```
┌─────────────────────────────────────────────────────────────────┐
│                       MCP Client (Claude Desktop 등)            │
│                       - MCP Protocol 통신                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ MCP Protocol (stdio/HTTP)
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                    Logseq MCP Server (NestJS)                   │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐     │
│  │   Tools      │  │  Resources   │  │    Prompts       │     │
│  │  (Actions)   │  │ (Documents)  │  │  (Templates)     │     │
│  └──────┬───────┘  └──────┬───────┘  └──────────────────┘     │
│         │                 │                                    │
│         └─────────┬───────┘                                    │
│                   │                                            │
│         ┌─────────▼────────┐                                   │
│         │  Logseq Client   │                                   │
│         │   (HTTP Wrapper) │                                   │
│         └─────────┬────────┘                                   │
└───────────────────┼────────────────────────────────────────────┘
                    │
                    │ HTTP API (REST)
                    │
┌───────────────────▼────────────────────────────────────────────┐
│                    Logseq Application                           │
│                    - Graph Database                             │
│                    - HTTP API Server (Port 12315)               │
└─────────────────────────────────────────────────────────────────┘
```

### 주요 컴포넌트

1. **MCP Tools** (`src/tools/`)
   - MCP Protocol의 Tool 제공
   - 사용자 요청을 Logseq API 호출로 변환
   - 입력 검증 (Zod 스키마)

2. **MCP Resources** (`src/resources/`)
   - 정적 문서 및 컨텍스트 제공
   - 프로젝트 개념 문서 노출

3. **MCP Prompts** (`src/prompts/`)
   - 개발 워크플로우 템플릿
   - AI 에이전트 가이드라인

4. **Logseq Client** (`src/logseq/`)
   - Logseq HTTP API 래퍼
   - 에러 처리 및 타입 안전성

---

## 따라하기 가이드

### 단계 1: Logseq 설정

1. **Logseq 설치**
   - [Logseq 공식 사이트](https://logseq.com/) 에서 다운로드

2. **HTTP Server 활성화**
   ```
   Logseq 실행 → Settings → Advanced → API Server
   ✅ Enable HTTP APIs server
   Port: 12315 (기본값)
   ```

3. **API Token 생성**
   ```
   Settings → Advanced → API Server → Generate Token
   → 토큰 복사 (예: abc123def456...)
   ```

### 단계 2: MCP 서버 설정

1. **프로젝트 클론 및 설치**
   ```bash
   cd logseq-mcp
   pnpm install
   ```

2. **환경 변수 설정**
   ```bash
   # .env 파일 생성
   cat > .env << 'EOF'
   # Logseq 연결 설정
   LOGSEQ_HOST=127.0.0.1
   LOGSEQ_PORT=12315
   LOGSEQ_TOKEN=your-api-token-here
   
   # 프로젝트 설정
   PROJECT_NAME=ego
   DOCS_PATH=../concepts
   EOF
   
   # 실제 토큰으로 교체
   # vi .env 로 LOGSEQ_TOKEN 수정
   ```

3. **서버 시작**
   ```bash
   pnpm run start:dev
   ```

   정상 실행 시 출력:
   ```
   [Nest] 12345  - 12/02/2024, 10:00:00 AM     LOG [NestFactory] Starting Nest application...
   [Nest] 12345  - 12/02/2024, 10:00:00 AM     LOG [InstanceLoader] AppModule dependencies initialized
   [Nest] 12345  - 12/02/2024, 10:00:00 AM     LOG [McpServer] MCP Server started
   ```

### 단계 3: VS Code GitHub Copilot 연동 (권장)

> VS Code 1.85+ 버전과 GitHub Copilot 확장이 필요합니다.

1. **mcp.json 파일 복사 및 수정**
   ```bash
   # 워크스페이스 설정 (프로젝트별 설정)
   mkdir -p .vscode
   cp logseq-mcp/mcp.json.example .vscode/mcp.json
   
   # mcp.json 수정
   code .vscode/mcp.json
   ```

2. **mcp.json 설정 형식**
   ```jsonc
   {
     "$schema": "https://raw.githubusercontent.com/microsoft/vscode/main/extensions/chat/syntaxes/mcp.schema.json",
     "servers": {
       "logseq-mcp": {
         "command": "node",
         "args": [
           "/path/to/logseq-mcp/dist/main.js"
         ],
         "env": {
           "LOGSEQ_HOST": "127.0.0.1",
           "LOGSEQ_PORT": "12315",
           "LOGSEQ_TOKEN": "your-logseq-api-token",
           "PROJECT_NAME": "my-project",
           "DOCS_PATH": "/path/to/docs"
         }
       }
     }
   }
   ```

3. **환경 변수 활용 (팀 공유 시 권장)**
   ```jsonc
   {
     "servers": {
       "logseq-mcp": {
         "command": "node",
         "args": ["${workspaceFolder}/logseq-mcp/dist/main.js"],
         "env": {
           "LOGSEQ_HOST": "127.0.0.1",
           "LOGSEQ_PORT": "12315",
           "LOGSEQ_TOKEN": "${env:LOGSEQ_TOKEN}",
           "PROJECT_NAME": "ego",
           "DOCS_PATH": "${workspaceFolder}/concepts"
         }
       }
     }
   }
   ```
   ```bash
   # 각 팀원이 환경 변수 설정
   export LOGSEQ_TOKEN=your-personal-token
   ```

4. **VS Code 재시작** 후 GitHub Copilot Chat에서 사용

### 단계 4: Claude Desktop 연결 (대안)

1. **Claude Desktop 설정 파일 열기**
   ```bash
   # macOS
   open ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # 또는 직접 편집
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

2. **MCP 서버 추가**
   ```json
   {
     "mcpServers": {
       "logseq-mcp": {
         "command": "node",
         "args": [
           "/path/to/logseq-mcp/dist/main.js"
         ],
         "env": {
           "LOGSEQ_HOST": "127.0.0.1",
           "LOGSEQ_PORT": "12315",
           "LOGSEQ_TOKEN": "your-api-token-here",
           "PROJECT_NAME": "my-project",
           "DOCS_PATH": "/path/to/docs"
         }
       }
     }
   }
   ```

3. **빌드 및 재시작**
   ```bash
   # MCP 서버 빌드
   cd logseq-mcp
   pnpm run build
   
   # Claude Desktop 재시작
   ```

### 단계 5: 실제 사용 예시

Claude Desktop에서 다음과 같이 테스트:

#### 예시 1: 오늘 할 일 기록
```
User: 오늘 journal에 "MCP 서버 설정 완료" 기록해줘

Claude: [logseq_add_journal_entry 호출]
✅ 오늘의 journal에 기록했습니다:
- MCP 서버 설정 완료
```

#### 예시 2: 페이지 생성
```
User: "MCP 학습 노트" 페이지 만들어줘

Claude: [logseq_create_page 호출]
✅ "MCP 학습 노트" 페이지를 생성했습니다.
```

#### 예시 3: 검색
```
User: "NestJS" 관련 내용 찾아줘

Claude: [logseq_search 호출]
📝 검색 결과 (3건):
1. logseq-mcp/README.md - "NestJS 기반 Logseq MCP..."
2. ...
```

#### 예시 4: 개발 기록 (Dev Tool)
```
User: 프로젝트 진행 상황 기록해줘
- MCP 서버 초기 설정 완료
- Claude Desktop 연동 성공

Claude: [dev-log-progress 호출]
✅ ego 프로젝트에 진행 상황을 기록했습니다.
```

### 단계 6: 고급 활용

#### 프로젝트 특화 설정
```bash
# 다른 프로젝트에 적용
cd ~/my-project
cp ~/software-park/ego/logseq-mcp/.env .env.myproject

# .env.myproject 수정
PROJECT_NAME=my-awesome-project
DOCS_PATH=./docs

# 전용 서버 실행
cd ~/software-park/ego/logseq-mcp
DOTENV_CONFIG_PATH=~/my-project/.env.myproject pnpm run start:dev
```

#### 개발 프롬프트 활용
Claude에서 다음 프롬프트 사용:
```
Use prompt: dev-implement-feature
기능: 사용자 인증 추가
```

```
Use prompt: dev-code-review
파일: src/auth/auth.service.ts
```

---

## 트러블슈팅

### 1. "Connection refused" 에러
```bash
# Logseq HTTP Server가 실행 중인지 확인
curl http://127.0.0.1:12315/api/health

# 실패 시: Logseq 설정 확인
# Settings → Advanced → Enable HTTP APIs server ✅
```

### 2. "Invalid token" 에러
```bash
# 토큰 재생성
# Logseq → Settings → Advanced → API Server → Generate Token

# .env 파일 업데이트
LOGSEQ_TOKEN=new-token-here
```

### 3. MCP 도구가 보이지 않음
```bash
# 빌드 확인
pnpm run build

# Claude Desktop 설정 확인
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Claude Desktop 완전 재시작 (강제 종료 후 재실행)
```

### 4. 개념 문서를 찾을 수 없음
```bash
# DOCS_PATH 확인
echo $DOCS_PATH
ls -la "$DOCS_PATH"

# 환경 변수 설정 권장 (절대 경로)
export DOCS_PATH="/path/to/your/docs"
```

---

## 개발자 가이드

### 새로운 Tool 추가하기

1. **Tool 파일 생성** (`src/tools/my-new.tool.ts`)
   ```typescript
   import { Injectable } from '@nestjs/common';
   import { McpTool, ToolResult } from '@rekog/mcp-nest';
   import { z } from 'zod';
   import { LogseqClient } from '../logseq/logseq.client';

   @Injectable()
   export class MyNewTool {
     constructor(private readonly logseq: LogseqClient) {}

     @McpTool({
       name: 'my_new_tool',
       description: '새로운 기능 설명',
       schema: z.object({
         param: z.string().describe('파라미터 설명'),
       }),
     })
     async execute(args: { param: string }): Promise<ToolResult> {
       const result = await this.logseq.someApiCall(args.param);
       return {
         content: [{ type: 'text', text: JSON.stringify(result) }],
       };
     }
   }
   ```

2. **ToolsModule에 등록** (`src/tools/tools.module.ts`)
   ```typescript
   @Module({
     imports: [LogseqModule],
     providers: [
       // ... 기존 도구들
       MyNewTool,
     ],
   })
   export class ToolsModule {}
   ```

3. **테스트 및 빌드**
   ```bash
   pnpm run build
   pnpm run start:dev
   ```

### 디버깅

```bash
# 디버그 모드 실행
pnpm run start:debug

# VS Code에서 디버깅
# .vscode/launch.json에 설정 추가 후 F5
```

---

## 🔒 보안 가이드

### 민감 정보 취급

**⚠️ 중요: 다음을 절대 저장소에 커밋하지 마세요**
- API 토큰 (LOGSEQ_TOKEN)
- 비밀번호
- 개인 정보 (이메일, 전화번호, 주소)
- 사용자 이름이 포함된 절대 경로

### 안전한 관리법

1. **환경 변수 사용**
   ```bash
   # 로컬 개발
   export LOGSEQ_TOKEN="your-token"
   pnpm run start:dev
   ```

2. **.env 파일 관리**
   - `.env` 파일은 `.gitignore`에 등록되어 있습니다
   - `.env.example`만 저장소에 커밋하세요

3. **토큰 노출 시 대응**
   - Logseq에서 즉시 토큰 폐기 및 새 토큰 발급
   - 모든 클라이언트에서 새 토큰으로 업데이트

4. **코드 리뷰**
   - 절대 경로나 토큰이 로그/에러 메시지에 노출되지 않는지 확인
   - 민감한 데이터는 마스킹하여 로깅

---

## 라이선스

MIT