Logseq MCP Server

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

📚 문서 가이드

• 빠른 시작 (QUICKSTART.md) - 5분 안에 설정하고 실행하기
• 사용 예시 (EXAMPLES.md) - 실제 사용 시나리오별 예시 모음
• 개발 진행 (PROGRESS.md) - 프로젝트 개발 현황 및 로드맵
• README.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 활성화 필요)

설치

pnpm install

환경 설정

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

cp .env.example .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. 환경변수 설정

   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 클라이언트에서 이 서버를 연결하면 됩니다.

실행

# 개발 모드
pnpm run start:dev

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

# 빌드
pnpm run build

테스트

# 단위 테스트
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 공식 사이트 에서 다운로드

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. 프로젝트 클론 및 설치

   cd logseq-mcp
   pnpm install
   

2. 환경 변수 설정

   # .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. 서버 시작

   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 파일 복사 및 수정

   # 워크스페이스 설정 (프로젝트별 설정)
   mkdir -p .vscode
   cp logseq-mcp/mcp.json.example .vscode/mcp.json
   
   # mcp.json 수정
   code .vscode/mcp.json
   

2. mcp.json 설정 형식

   {
     "$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. 환경 변수 활용 (팀 공유 시 권장)

   {
     "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"
         }
       }
     }
   }
   

   # 각 팀원이 환경 변수 설정
   export LOGSEQ_TOKEN=your-personal-token
   

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

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

1. Claude Desktop 설정 파일 열기

   # macOS
   open ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # 또는 직접 편집
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. MCP 서버 추가

   {
     "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. 빌드 및 재시작

   # 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: 고급 활용

프로젝트 특화 설정

# 다른 프로젝트에 적용
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" 에러

# Logseq HTTP Server가 실행 중인지 확인
curl http://127.0.0.1:12315/api/health

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

2. "Invalid token" 에러

# 토큰 재생성
# Logseq → Settings → Advanced → API Server → Generate Token

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

3. MCP 도구가 보이지 않음

# 빌드 확인
pnpm run build

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

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

4. 개념 문서를 찾을 수 없음

# 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)

   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)

   @Module({
     imports: [LogseqModule],
     providers: [
       // ... 기존 도구들
       MyNewTool,
     ],
   })
   export class ToolsModule {}
   

3. 테스트 및 빌드

   pnpm run build
   pnpm run start:dev
   

디버깅

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

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

---

🔒 보안 가이드

민감 정보 취급

⚠️ 중요: 다음을 절대 저장소에 커밋하지 마세요

• API 토큰 (LOGSEQ_TOKEN)
• 비밀번호
• 개인 정보 (이메일, 전화번호, 주소)
• 사용자 이름이 포함된 절대 경로

안전한 관리법

1. 환경 변수 사용

   # 로컬 개발
   export LOGSEQ_TOKEN="your-token"
   pnpm run start:dev
   

2. .env 파일 관리

   • .env 파일은 .gitignore에 등록되어 있습니다
   • .env.example만 저장소에 커밋하세요

3. 토큰 노출 시 대응

   • Logseq에서 즉시 토큰 폐기 및 새 토큰 발급
   • 모든 클라이언트에서 새 토큰으로 업데이트

4. 코드 리뷰

   • 절대 경로나 토큰이 로그/에러 메시지에 노출되지 않는지 확인
   • 민감한 데이터는 마스킹하여 로깅

---

라이선스

MIT