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 메서드 추가

1. src/types/mcp-types.ts에 메서드 타입 추가
2. src/server/protocol-handler.ts에 핸들러 구현
3. registerMethodHandler로 등록

Obsidian 연동 확장

1. src/connectors/obsidian-connector.ts 수정
2. 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에 등록해 주세요.