MCP Obsidian Server
Windows 10 환경에서 Cursor AI IDE와 연동되는 MCP(Model Context Protocol) 서버입니다. 이 서버는 Obsidian 노트와 Google Calendar를 연결하여 지식 관리 시스템을 구축합니다.
🚀 주요 기능
- MCP 프로토콜 지원: JSON-RPC 기반 통신으로 Cursor AI IDE와 완벽 연동
- Obsidian 연동: 마크다운 파일 읽기/쓰기, 메타데이터 추출, 실시간 동기화
- Google Calendar 연동: ClariVein 시술 후 체계적인 훈련 일정 자동 생성 및 관리
- 노트 검색: Obsidian 노트 전문 검색
- 실시간 동기화: 파일 변경 감지 및 자동 동기화
- 백링크 처리: Obsidian 위키링크 기반 백링크 자동 생성
🛠 기술 스택
- 언어: TypeScript/JavaScript (Node.js)
- 프레임워크: Express.js
- 외부 API: Google Calendar API
- 파일 감지: Chokidar
- 마크다운 파싱: Gray-matter, Remark
- 로깅: Winston
- 프로토콜: JSON-RPC (MCP)
📁 프로젝트 구조
mcp-obsidian-server/
├── src/
│ ├── server/ # MCP 서버 메인 로직
│ │ ├── mcp-server.ts # ✅ Express 서버 및 MCP 엔드포인트
│ │ ├── message-handler.ts # ✅ MCP 메시지 처리
│ │ ├── protocol-handler.ts # ✅ MCP 프로토콜 처리
│ │ └── calendar-routes.ts # 🆕 Google Calendar API 라우터
│ ├── connectors/ # 외부 시스템 연동
│ │ ├── obsidian-connector.ts # ✅ Obsidian Vault 연동
│ │ └── google-calendar-connector.ts # 🆕 Google Calendar 연동
│ ├── services/ # 비즈니스 로직
│ │ ├── search-service.ts # ✅ Obsidian 검색 서비스
│ │ ├── ai-service.ts # ✅ AI 서비스
│ │ └── calendar-training-service.ts # 🆕 훈련 일정 관리 서비스
│ ├── types/ # TypeScript 타입 정의
│ │ ├── mcp-types.ts # ✅ MCP 프로토콜 타입
│ │ ├── obsidian-types.ts # ✅ Obsidian 타입
│ │ └── google-calendar-types.ts # 🆕 Google Calendar 타입
│ └── utils/ # 유틸리티 함수
│ ├── file-watcher.ts # ✅ 파일 변경 감지
│ ├── markdown-parser.ts # ✅ 마크다운 파싱
│ └── logger.ts # ✅ 로깅 유틸리티
├── config/ # 설정 파일
│ ├── server-config.json # ✅ 서버 설정
│ └── credentials/ # 🔐 민감한 정보 (Git 제외)
├── logs/ # 로그 파일 (자동 생성)
├── dist/ # 빌드 결과물 (자동 생성)
├── package.json # ✅ 의존성 및 스크립트
├── tsconfig.json # ✅ TypeScript 설정
├── .gitignore # ✅ Git 제외 파일
└── README.md # 프로젝트 문서
🔧 설치 및 실행
1. 의존성 설치
npm install
Google Calendar 연동을 사용하려면 추가 의존성 설치:
npm install googleapis google-auth-library
2. 설정 파일 구성
config/server-config.json 파일에서 다음 설정을 확인/수정하세요:
{
"server": {
"port": 8000,
"host": "localhost",
"logLevel": "info"
},
"obsidian": {
"vaultPath": "/path/to/your/obsidian/vault",
"watchForChanges": true,
"ignorePatterns": [
".obsidian/**",
"*.temp",
"*.tmp",
"*.log"
],
"includeAttachments": false,
"maxFileSize": 10485760
},
"googleCalendar": {
"clientId": "YOUR_GOOGLE_CLIENT_ID",
"clientSecret": "YOUR_GOOGLE_CLIENT_SECRET",
"redirectUri": "http://localhost:8000/auth/google/callback",
"defaultTrainingTime": "07:00",
"defaultLocations": {
"gym": "헬스장",
"park": "공원",
"hospital": "병원"
}
}
}
3. 개발 모드 실행
npm run dev
4. 프로덕션 빌드 및 실행
# TypeScript 컴파일
npm run build
# 서버 시작
npm start
🌐 API 엔드포인트
헬스 체크
GET http://localhost:8000/health
MCP 엔드포인트
POST http://localhost:8000/mcp
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {}
}
Google Calendar API 엔드포인트
# 인증 URL 생성
GET http://localhost:8000/api/calendar/auth/url
# 훈련 일정 생성
POST http://localhost:8000/api/calendar/training/schedule
Content-Type: application/json
{
"operationDate": "2024-01-01",
"currentDaysSinceOperation": 8,
"trainingTime": "07:00",
"location": {
"gym": "스포츠센터",
"park": "한강공원",
"hospital": "강남병원"
},
"includeWeekends": true,
"includeMedicalSchedule": true
}
📋 MCP 메서드
기본 메서드
initialize: 서버 초기화 및 기능 목록 반환shutdown: 서버 종료exit: 프로세스 종료
커스텀 메서드
search_notes: 노트 검색get_note: 노트 조회update_note: 노트 업데이트create_note: 노트 생성delete_note: 노트 삭제get_recent_notes: 최근 노트 조회get_all_notes: 전체 노트 조회
🔍 구현된 기능
✅ Obsidian Connector
- Vault 스캔: 재귀적 마크다운 파일 스캔
- 메타데이터 추출: Frontmatter, 태그, 링크 파싱
- 실시간 감지: 파일 추가/변경/삭제 자동 감지
- 백링크 처리: 위키링크 기반 백링크 자동 생성
- CRUD 작업: 노트 생성, 읽기, 업데이트, 삭제
- 검색: 제목, 태그, 콘텐츠, 메타데이터 기반 검색
✅ Search Service
- 노트 검색: Obsidian 노트 전문 검색
- 결과 랭킹: 관련성 점수 기반 정렬
- 필터링: 태그별, 날짜별 필터
- 스니펫: 검색 결과 컨텍스트 추출
✅ File Watcher
- 실시간 감지: Chokidar 기반 파일 시스템 감시
- 이벤트 처리: 추가/변경/삭제 이벤트 콜백
- 성능 최적화: 디바운싱 및 폴링 설정
- 에러 처리: 파일 접근 오류 복구
✅ 로깅 시스템
- 다중 출력: 콘솔 및 파일 로깅
- 레벨별 관리: error, warn, info, debug
- MCP 전용: 요청/응답/에러 로깅
- 구조화: JSON 형태 로그 저장
🆕 Google Calendar 연동
- 자동 훈련 일정: ClariVein 시술 후 12주간 체계적 훈련 일정 생성
- 의료 검진 일정: 초음파 검사, 상담 등 의료 일정 자동 추가
- 단계별 운동: 저충격유산소 → 조깅도입 → 연속달리기 → 구조화운동 → 마라톤훈련
- 스마트 알림: 훈련 30분 전, 의료 일정 하루 전 알림
- 진행 추적: 훈련 완료 표시 및 노트 추가
- OAuth2 인증: Google 계정 연동 및 토큰 관리
- 모바일 동기화: Google Calendar 앱과 자동 동기화
🧪 테스트
서버 상태 확인
curl -X GET http://localhost:4000/health
MCP 초기화 테스트
curl -X POST http://localhost:4000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {}
}'
Google Calendar 연동 테스트
# 1. 인증 URL 생성
curl -X GET http://localhost:4000/api/calendar/auth/url
# 2. 인증 상태 확인
curl -X GET http://localhost:4000/api/calendar/auth/status
# 3. 훈련 일정 생성 (인증 후)
curl -X POST http://localhost:4000/api/calendar/training/schedule \
-H "Content-Type: application/json" \
-d '{
"operationDate": "2024-01-01",
"currentDaysSinceOperation": 8,
"trainingTime": "07:00",
"location": {
"gym": "스포츠센터",
"park": "한강공원",
"hospital": "강남병원"
},
"includeWeekends": true,
"includeMedicalSchedule": true
}'
📊 로그
로그는 logs/ 디렉토리에 저장됩니다:
combined.log: 전체 로그error.log: 에러 로그만
로그 레벨은 config/server-config.json에서 설정할 수 있습니다.
🔧 개발 가이드
새로운 MCP 메서드 추가
src/types/mcp-types.ts에 메서드 타입 추가src/server/protocol-handler.ts에 핸들러 구현registerMethodHandler로 등록
Obsidian 연동 확장
src/connectors/obsidian-connector.ts수정src/types/obsidian-types.ts에 타입 추가
🚨 주의사항
- Obsidian Vault 경로: 설정 파일에서 올바른 Obsidian Vault 경로를 지정해야 합니다
- 파일 권한: Obsidian Vault 디렉토리에 읽기/쓰기 권한이 필요합니다
- 메모리 사용량: 대용량 Vault의 경우 충분한 메모리를 확보하세요
🔄 다음 단계
- MCP 커스텀 메서드 구현
- Cursor AI IDE 연동 설정
- 성능 최적화
- 에러 처리 강화
- 테스트 코드 작성
- 문서화 완성
📄 라이선스
ISC
🤝 기여
이슈와 풀 리퀘스트를 환영합니다.
📖 사용 가이드
- 기본 사용법: USECASE.md 파일을 참조하세요
- Google Calendar 연동: GOOGLE_CALENDAR_INTEGRATION.md 파일을 참조하세요
- 상세 설정 가이드: GOOGLE_CALENDAR_SETUP.md 파일을 참조하세요
📞 지원
문제가 발생하면 GitHub Issues에 등록해 주세요.