# 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
