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 위키링크 기반 백링크 자동 생성

Related MCP server: Cursor DB MCP Server

🛠 기술 스택

언어: 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에 등록해 주세요.