# 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. 의존성 설치

```bash
npm install
```

> **Google Calendar 연동을 사용하려면 추가 의존성 설치:**
> ```bash
> npm install googleapis google-auth-library
> ```

### 2. 설정 파일 구성

`config/server-config.json` 파일에서 다음 설정을 확인/수정하세요:

```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. 개발 모드 실행

```bash
npm run dev
```

### 4. 프로덕션 빌드 및 실행

```bash
# TypeScript 컴파일
npm run build

# 서버 시작
npm start
```

## 🌐 API 엔드포인트

### 헬스 체크
```bash
GET http://localhost:8000/health
```

### MCP 엔드포인트
```bash
POST http://localhost:8000/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

### Google Calendar API 엔드포인트
```bash
# 인증 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 앱과 자동 동기화

## 🧪 테스트

### 서버 상태 확인
```bash
curl -X GET http://localhost:4000/health
```

### MCP 초기화 테스트
```bash
curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'
```

### Google Calendar 연동 테스트
```bash
# 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](./USECASE.md) 파일을 참조하세요
- **Google Calendar 연동**: [GOOGLE_CALENDAR_INTEGRATION.md](./GOOGLE_CALENDAR_INTEGRATION.md) 파일을 참조하세요
- **상세 설정 가이드**: [GOOGLE_CALENDAR_SETUP.md](./GOOGLE_CALENDAR_SETUP.md) 파일을 참조하세요

## 📞 지원

문제가 발생하면 GitHub Issues에 등록해 주세요.