# 빠른 시작 가이드 (Quick Start)
5분 안에 Logseq MCP Server를 실행하고 VS Code의 GitHub Copilot과 연동하는 방법입니다.
---
## ⚡ 빠른 설정 (5분)
### 1️⃣ Logseq 준비 (1분)
```bash
# Logseq가 이미 설치되어 있다고 가정
# 1. Logseq 실행
# 2. Settings (⚙️) → Advanced
# 3. API Server 섹션:
# ✅ Enable HTTP APIs server
# Port: 12315
# 4. "Generate Token" 클릭
# 5. 토큰 복사 (예: a1b2c3d4e5...)
```
### 2️⃣ MCP 서버 빌드 (2분)
```bash
# 프로젝트 디렉토리로 이동
cd /Users/swpark/software-park/ego/logseq-mcp
# 의존성 설치 (처음 한 번만)
pnpm install
# 환경 변수 설정
cat > .env << 'EOF'
LOGSEQ_HOST=127.0.0.1
LOGSEQ_PORT=12315
LOGSEQ_TOKEN=여기에-복사한-토큰-붙여넣기
PROJECT_NAME=ego
DOCS_PATH=../concepts
EOF
# 프로덕션 빌드
pnpm run build
```
✅ **확인**: `dist/main.js` 파일이 생성됨
### 3️⃣ VS Code에서 GitHub Copilot 연동 (2분)
#### 방법 1: 워크스페이스용 MCP 설정 (권장 - 팀 공유 가능)
1. **VS Code 열기**
```bash
code /Users/swpark/software-park/ego
```
2. **프로젝트 루트에 `.vscode/mcp.json` 파일 생성**
```bash
mkdir -p /Users/swpark/software-park/ego/.vscode
cat > /Users/swpark/software-park/ego/.vscode/mcp.json << 'EOF'
{
"servers": {
"logseq-mcp": {
"command": "node",
"args": [
"/Users/swpark/software-park/ego/logseq-mcp/dist/main.js"
],
"env": {
"LOGSEQ_HOST": "127.0.0.1",
"LOGSEQ_PORT": "12315",
"LOGSEQ_TOKEN": "여기에-복사한-토큰-붙여넣기",
"PROJECT_NAME": "ego",
"DOCS_PATH": "/Users/swpark/software-park/ego/concepts"
}
}
}
}
EOF
```
3. **VS Code 재시작** (Cmd+Q 후 재실행)
#### 방법 2: 개인용 전역 설정 (모든 프로젝트에서 사용)
**macOS/Linux:**
```bash
# 설정 디렉토리 생성
mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat
# mcp.json 파일 생성
cat > ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat/mcp.json << 'EOF'
{
"servers": {
"logseq-mcp": {
"command": "node",
"args": [
"/Users/swpark/software-park/ego/logseq-mcp/dist/main.js"
],
"env": {
"LOGSEQ_HOST": "127.0.0.1",
"LOGSEQ_PORT": "12315",
"LOGSEQ_TOKEN": "여기에-복사한-토큰-붙여넣기",
"PROJECT_NAME": "ego",
"DOCS_PATH": "/Users/swpark/software-park/ego/concepts"
}
}
}
}
EOF
```
**Windows:**
```powershell
# %APPDATA%\Code\User\globalStorage\github.copilot-chat\mcp.json 생성
```
---
## 🎯 첫 번째 테스트
VS Code에서 GitHub Copilot Chat을 열고 테스트해보세요!
### 테스트 0: MCP 도구 확인
```
User: @workspace 사용 가능한 MCP 도구 목록 보여줘
```
**기대 결과**:
- `logseq_add_journal_entry`
- `logseq_get_today_journal`
- `logseq_create_page`
- `logseq_search`
- 등 Logseq 관련 도구들이 표시됨
### 테스트 1: Journal 기록
```
User: 오늘 Logseq journal에 "MCP 서버 설정 완료" 라고 기록해줘
```
**기대 결과**:
```
✅ 오늘의 journal에 기록했습니다:
- MCP 서버 설정 완료
```
Logseq를 확인하면 오늘 날짜 journal 페이지에 내용이 추가되어 있음
### 테스트 2: 페이지 검색
```
User: Logseq에서 "MCP" 키워드로 검색해줘
```
**기대 결과**:
```
🔍 검색 결과 (X건):
1. MCP 학습 노트
2. 2024-12-02 Journal - "MCP 서버 설정 완료"
...
```
### 테스트 3: 페이지 생성
```
User: Logseq에 "MCP 학습 노트" 페이지 만들고 "오늘부터 MCP 공부 시작" 내용 추가해줘
```
**기대 결과**:
```
✅ "MCP 학습 노트" 페이지를 생성했습니다.
✅ 내용을 추가했습니다: "오늘부터 MCP 공부 시작"
```
### 테스트 4: 개발 기록 (Dev Tool)
```
User: ego 프로젝트 진행 상황 기록해줘
- MCP 서버 VS Code 연동 완료
- GitHub Copilot으로 테스트 성공
```
**기대 결과**: Logseq의 "ego" 페이지에 진행 상황 기록됨
User: 오늘 journal에 "MCP 서버 설정 완료" 라고 기록해줘
```
**기대 결과**: Logseq의 오늘 날짜 journal 페이지에 내용이 추가됨
### 테스트 2: 페이지 검색
```
User: Logseq에서 "MCP" 검색해줘
```
**기대 결과**: MCP 관련 페이지 및 블록 목록 출력
### 테스트 3: 페이지 생성
```
User: "MCP 학습 노트" 페이지 만들고 "오늘부터 MCP 공부 시작" 내용 추가해줘
```
**기대 결과**: 새 페이지 생성 및 내용 추가 완료
---
## 🛠️ 사용 가능한 기능들
> 💡 **팁**: VS Code Copilot Chat에서 `@workspace` 멘션과 함께 사용하면 더 정확한 결과를 얻을 수 있습니다!
### 📝 Journal 관리
- `오늘 journal 보여줘`
- `journal에 ~ 기록해줘`
- `2024년 12월 2일 journal 보여줘`
### 📄 Page 관리
- `"페이지명" 페이지 만들어줘`
- `"페이지명" 페이지 보여줘`
- `"페이지명" 페이지의 모든 블록 보여줘`
- `"페이지명"을 참조하는 페이지들 찾아줘`
### 🧩 Block 관리
- `블록 [uuid] 보여줘`
- `"페이지명"에 "내용" 블록 추가해줘`
- `블록 [uuid] 삭제해줘`
### 🔍 검색
- `"키워드" 검색해줘`
- `그래프 정보 보여줘`
- `모든 페이지 목록 보여줘`
### 💻 개발 기록 (Dev Tool)
- `프로젝트 진행 상황 기록해줘`
- `기술적 결정 사항 기록해줘`
- `TODO 추가해줘`
- `아이디어 기록해줘`
- `프로젝트 개발 로그 보여줘`
---
## ❌ 문제 해결
### "Connection refused" 에러
```bash
# Logseq HTTP Server 상태 확인
curl http://127.0.0.1:12315/api
# 응답이 없으면:
# 1. Logseq → Settings → Advanced
# 2. "Enable HTTP APIs server" 체크 확인
# 3. Logseq 재시작
```
### "Invalid token" 에러
```bash
# 1. Logseq에서 새 토큰 생성
# Settings → Advanced → API Server → Generate Token
# 2. VS Code settings.json 업데이트
code ~/.config/Code/User/settings.json
# LOGSEQ_TOKEN 값 변경
# 3. VS Code 재시작
```
### VS Code에서 MCP 도구가 안 보임
```bash
# 1. 빌드 확인
cd /Users/swpark/software-park/ego/logseq-mcp
pnpm run build
ls -la dist/main.js # 파일 존재 확인
# 2. mcp.json 파일 확인
cat /Users/swpark/software-park/ego/.vscode/mcp.json
# 또는
cat ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat/mcp.json
# 3. VS Code에서 MCP 서버 상태 확인
# Command Palette (Cmd+Shift+P) → "MCP: Show Installed Servers"
# 4. VS Code Output 패널에서 에러 확인
# View → Output → "GitHub Copilot" 또는 "MCP" 선택
# 5. VS Code 완전 재시작 (Cmd+Q 후 재실행)
```
### GitHub Copilot이 MCP를 지원하지 않는 경우
```bash
# VS Code 버전 확인 (1.85 이상 필요)
code --version
# GitHub Copilot 확장 업데이트
# Extensions → GitHub Copilot → Update
# MCP 기능이 아직 미지원이면 Claude Desktop 사용
# (QUICKSTART.md의 이전 버전 참고)
```
### Port 충돌
---
## 💡 유용한 팁
### VS Code에서 효율적으로 사용하기
```
# 1. Copilot Chat 열기
Cmd+I (Mac) / Ctrl+I (Windows/Linux)
# 2. 워크스페이스 컨텍스트와 함께 사용
@workspace 오늘 작업한 내용 Logseq에 정리해줘
# 3. 파일 컨텍스트와 함께 사용
#file:src/main.ts 이 파일 변경 사항 Logseq에 기록해줘
# 4. 터미널과 연동
터미널에서 실행한 명령어들 journal에 기록해줘
```
### 여러 프로젝트 관리
각 프로젝트에 `.vscode/mcp.json` 파일을 생성하면 프로젝트별로 다른 MCP 설정 사용 가능:
```bash
# Project A
cat > /path/to/project-a/.vscode/mcp.json << 'EOF'
{
"servers": {
"logseq-mcp": {
"command": "node",
"args": ["/Users/swpark/software-park/ego/logseq-mcp/dist/main.js"],
"env": {
"PROJECT_NAME": "project-a",
"LOGSEQ_TOKEN": "${env:LOGSEQ_TOKEN}",
...
}
}
}
}
EOF
# Project B
cat > /path/to/project-b/.vscode/mcp.json << 'EOF'
{
"servers": {
"logseq-mcp": {
"command": "node",
"args": ["/Users/swpark/software-park/ego/logseq-mcp/dist/main.js"],
"env": {
"PROJECT_NAME": "project-b",
"LOGSEQ_TOKEN": "${env:LOGSEQ_TOKEN}",
...
}
}
}
}
EOF
```
### 개발 워크플로우 자동화
VS Code Copilot Chat에서:
```
# 새 기능 개발 시작
오늘부터 사용자 인증 기능 개발 시작
- JWT 기반 인증
- NestJS Guard 사용
이 내용 Logseq ego 프로젝트에 기록해줘
# 코드 리뷰 결과 기록
#file:src/auth/auth.service.ts
이 파일의 주요 개선점을 Logseq에 기록해줘
- 비밀번호 해싱 강도 향상
- 토큰 만료 시간 설정
- 테스트 케이스 추가 필요
### 워크스페이스 레벨 설정 (팀 공유)
```bash
# 프로젝트 루트에 .vscode/mcp.json 생성
mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
"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"
}
}
}
}
EOF
# 팀원들은 각자의 환경 변수에 LOGSEQ_TOKEN만 설정
export LOGSEQ_TOKEN=your-token-here
# 또는 .env 파일 생성
echo "LOGSEQ_TOKEN=your-token-here" > .env
```
# 팀원들은 각자의 .env에 LOGSEQ_TOKEN만 설정
export LOGSEQ_TOKEN=your-token-here
```
### Copilot Chat Agent 활용
```
# MCP 도구 자동 선택
@workspace Logseq에서 "NestJS" 관련 내용 찾고 요약해줘
# 컨텍스트 기반 제안
@workspace 이번 주 작업 내용을 바탕으로 다음 주 계획 세워줘
# 코드와 문서 동기화
@workspace 방금 작성한 코드의 핵심 내용을 Logseq에 기록해줘
```로젝트별 환경 파일 생성
cp .env .env.project-a
cp .env .env.project-b
# 각 환경 파일 수정
# .env.project-a: PROJECT_NAME=project-a
# .env.project-b: PROJECT_NAME=project-b
# Claude 설정에서 여러 MCP 서버 등록
{
"mcpServers": {
"logseq-mcp-project-a": { ... },
"logseq-mcp-project-b": { ... }
}
}
```
### 개발 워크플로우 자동화
Claude에서 프롬프트 활용:
```
# 새 기능 개발 시작
Use prompt: dev-implement-feature
기능명: 사용자 인증
설명: JWT 기반 인증 구현
# 코드 리뷰 요청
Use prompt: dev-code-review
파일: src/auth/auth.service.ts
# 버그 디버깅
Use prompt: dev-debug-issue
문제: 로그인 시 토큰이 만료되지 않음
```
---
## 🤝 도움이 필요하신가요?
- 📖 [상세 문서](./README.md) - 전체 기능 및 API 레퍼런스
- 📋 [사용 예시](./EXAMPLES.md) - 실제 사용 시나리오별 가이드
- 📊 [진행 상황](./PROGRESS.md) - 프로젝트 개발 로드맵
- 🐛 [이슈 리포트](https://github.com/your-repo/issues)
---
## 🔄 Claude Desktop 사용자를 위한 추가 정보
Claude Desktop에서도 동일한 MCP 서버를 사용할 수 있습니다!
```bash
# Claude Desktop 설정 파일 열기 (macOS)
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
```json
{
"mcpServers": {
"logseq-mcp": {
"command": "node",
"args": [
"/Users/swpark/software-park/ego/logseq-mcp/dist/main.js"
],
"env": {
"LOGSEQ_HOST": "127.0.0.1",
"LOGSEQ_PORT": "12315",
"LOGSEQ_TOKEN": "your-token-here",
"PROJECT_NAME": "ego",
"DOCS_PATH": "/Users/swpark/software-park/ego/concepts"
}
}
}
}
```
Claude Desktop 재시작 후 사용 가능합니다!
---
Happy Hacking! 🚀
