# IWL MCP Server

**단일 MCP 서버**로 GitHub(온라인) ↔ Obsidian(로컬 볼트) ↔ Claude Code/ChatGPT 흐름을 연결합니다.

## 🎯 주요 기능

### GitHub 툴
- 브랜치 생성/관리
- 파일 업서트 (생성/수정)
- 커밋 및 PR 생성
- **머지는 수동으로 유지** 🔒

### Obsidian 툴
- 볼트 내 파일 검색/읽기/생성
- IWL 파일명 표준화
- 안전한 볼트 접근 (화이트리스트)

## 📋 IWL 파일명 규칙

```
{카테고리}_{YYYY-MM-DD}_{제목}.md

카테고리:
- 01_기획_전략
- 02_개발_기술
- 03_운영_관리
- 04_자료_리소스
- 99_원본_파일
```

## 🚀 설치 및 실행

### 1. 환경 설정
```bash
# 저장소 클론 후
cd iwl-mcp-server

# 가상환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# 의존성 설치
pip install -e .
```

### 2. 환경변수 설정
```bash
# .env 파일 생성
cp .env.example .env

# .env 파일 편집하여 실제 값 입력
# GITHUB_TOKEN=ghp_your_token_here
# GITHUB_OWNER=your-username
# GITHUB_REPO=iwl-studio
# OBS_VAULT_PATH=/path/to/your/obsidian/vault
# IWL_DEFAULT_AUTHOR=Your-Name
# IWL_DEFAULT_VERSION=v1.0.0
```

### 3. MCP 서버 실행
```bash
# 방법 1: 직접 실행
python -m mcp_server.main

# 방법 2: 설치된 스크립트 사용
iwl-mcp-server

# 방법 3: HTTP 서버 모드 (개발용)
uvicorn mcp_server.main:app --port 27123
```

## 🔌 클라이언트 연결

### Claude Desktop MCP 설정
Claude Desktop의 MCP 설정 파일에 다음 내용 추가:

```json
{
  "mcpServers": {
    "iwl-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "cwd": "/path/to/iwl-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_OWNER": "your-username",
        "GITHUB_REPO": "iwl-studio",
        "OBS_VAULT_PATH": "/path/to/your/obsidian/vault",
        "IWL_DEFAULT_AUTHOR": "Your-Name"
      }
    }
  }
}
```

### Claude Code 연결
```bash
# 로컬 개발용
python -m mcp_server.main
```

### ChatGPT 연결 (HTTP 터널)
```bash
# Cloudflare Tunnel로 외부 노출
cloudflared tunnel --url http://127.0.0.1:27123

# 또는 ngrok 사용
ngrok http 27123
```

## 🔒 보안 정책

- **머지 수동**: 모든 PR은 수동으로 머지
- **볼트 접근 제한**: OBS_VAULT_PATH 외부 접근 금지
- **GitHub 권한**: repo 스코프 토큰 필요

## 🛡️ 검증 레이어

iwl-studio 레포지토리에는 문서 품질을 보장하기 위한 자동 검증 시스템이 구축되어 있습니다.

### 📋 검증 규칙

**검사 대상**: `plans/`, `memos/`, `reviews/`, `logs/`, `docs/` 폴더의 `*.md` 파일

**필수 요소**:
- **출처/근거**: 모든 문서에 참조 자료, 링크 또는 근거가 명시되어야 함
- **결정사항**: 리뷰/계획 문서는 결론이나 결정사항 섹션 필요
- **완성도**: 'TBD', '???', '<!-- todo -->' 등 미완성 표시 제거

### 🏷️ 라벨 흐름

1. **PR 생성** → 자동 검증 실행
2. **검증 실패** → `needs-verification` 라벨 부착 + 상세 피드백
3. **검증 성공** → `verified` 라벨 부착 + `needs-verification` 제거
4. **수동 리뷰** → 최종 승인 후 머지 (기존 정책 유지)

### 🔄 검증 프로세스

```mermaid
graph LR
    A[PR 생성/수정] --> B[자동 검증]
    B --> C{통과?}
    C -->|실패| D[needs-verification 라벨]
    C -->|성공| E[verified 라벨]
    D --> F[문제 수정]
    F --> A
    E --> G[수동 리뷰]
    G --> H[머지]
```

**참고**: 머지는 여전히 수동으로만 가능하며, 검증은 코드 품질 보장을 위한 사전 단계입니다.

### 🛠️ 검증 지원 툴 사용 예

MCP를 통해 문서 검증과 PR 관리를 자동화할 수 있습니다:

```python
# 1. 문서 초안 작성 후 검증
lint_result = obs.lint_markdown("plans/new_feature_plan.md")

# 2. 검증 결과를 바탕으로 PR에 코멘트
if not lint_result["valid"]:
    comment_body = f"""## 📝 문서 품질 검사 결과
    
{lint_result["summary"]}

### 🔧 발견된 문제점:
{chr(10).join(f"- {issue}" for issue in lint_result["issues"])}

### 📊 문서 통계:
- 단어 수: {lint_result["stats"]["word_count"]}개
- 참조 자료: {lint_result["stats"]["source_references"]}개
- 결정사항 섹션: {"✅" if lint_result["stats"]["has_decision_section"] else "❌"}

**다음 단계**: 위 문제점들을 수정한 후 다시 커밋해주세요.
"""
    
    # PR에 검증 결과 코멘트 작성
    gh.comment_pr(123, comment_body)
    
    # needs-verification 라벨 부착
    gh.add_labels(123, ["needs-verification"])

else:
    # 검증 통과 시 성공 메시지
    gh.comment_pr(123, "✅ 문서 품질 검증을 통과했습니다!")
    gh.add_labels(123, ["verified"])
```

**워크플로우 예시**:
1. **문서 초안 저장** → `obs.upsert_markdown()` 또는 Obsidian 직접 작성
2. **품질 검사** → `obs.lint_markdown()` 실행
3. **결과 요약** → `gh.comment_pr()`로 PR에 피드백 남기기  
4. **라벨 관리** → 문제 시 `needs-verification`, 통과 시 `verified` 부착

## 🛠️ 등록된 MCP 도구들 (14개)

### Obsidian 도구 (7개)
| 도구 | 설명 | 주요 매개변수 |
|------|------|---------------|
| `obs.search` | 볼트 내 문서 검색 | `keyword`, `subdir` |
| `obs.read` | 문서 읽기 | `rel_path` |
| `obs.upsert_markdown` | 문서 생성/업데이트 | `rel_path`, `content` |
| `obs.create_iwl_note` | IWL 표준 노트 생성 | `category`, `title`, `body`, `tags`, `ymd` |
| `obs.append_section` | 섹션 추가 | `rel_path`, `heading`, `content` |
| `obs.move` | 파일 이동 | `src_rel_path`, `dst_rel_path` |
| `obs.lint_markdown` | 문서 품질 검사 | `rel_path` |

### GitHub 도구 (7개)  
| 도구 | 설명 | 주요 매개변수 |
|------|------|---------------|
| `gh.create_branch` | 브랜치 생성 | `branch_name`, `from_branch` |
| `gh.upsert_file` | 파일 생성/업데이트 | `branch`, `path`, `content`, `commit_message` |
| `gh.create_pr` | Pull Request 생성 | `branch`, `title`, `body`, `base`, `draft` |
| `gh.get_pr` | PR 정보 조회 | `number` |
| `gh.list_pr` | PR 목록 조회 | `state`, `head`, `base` |
| `gh.add_labels` | PR 라벨 추가 | `number`, `labels` |
| `gh.remove_label` | PR 라벨 제거 | `number`, `label` |
| `gh.comment_pr` | PR 코멘트 작성 | `number`, `body` |

## 📖 사용 가이드

### Obsidian 워크플로우
```json
// 1. IWL 표준 노트 생성
{
  "tool": "obs.create_iwl_note",
  "arguments": {
    "category": "03_운영_관리",
    "title": "주간 회의록",  
    "body": "# 회의 내용\n\n- 안건 1: 프로젝트 진행상황\n- 안건 2: 다음주 계획",
    "tags": ["회의", "운영"],
    "ymd": "2025-08-09"
  }
}

// 2. 문서 검색
{
  "tool": "obs.search",
  "arguments": {
    "keyword": "회의",
    "subdir": "03_운영_관리"
  }
}

// 3. 품질 검사
{
  "tool": "obs.lint_markdown",
  "arguments": {
    "rel_path": "03_운영_관리/03_운영_관리_2025-08-09_주간_회의록.md"
  }
}
```

### GitHub 워크플로우
```json
// 1. 브랜치 생성
{
  "tool": "gh.create_branch",
  "arguments": {
    "branch_name": "feature/weekly-meeting-notes",
    "from_branch": "main"
  }
}

// 2. 파일 업로드
{
  "tool": "gh.upsert_file",
  "arguments": {
    "branch": "feature/weekly-meeting-notes",
    "path": "meetings/2025-08-09_weekly.md",
    "content": "# 주간 회의록\n\n내용...",
    "commit_message": "add weekly meeting notes"
  }
}

// 3. PR 생성  
{
  "tool": "gh.create_pr",
  "arguments": {
    "branch": "feature/weekly-meeting-notes",
    "title": "[Docs] Weekly Meeting Notes",
    "body": "## 변경 요약\n- 주간 회의록 추가\n\n## 근거/출처\n- 팀 회의 진행",
    "base": "main",
    "draft": false
  }
}
```

## 🔄 운영 플로우

1. Obsidian에서 문서 작성
2. MCP를 통해 GitHub에 브랜치/파일 생성
3. PR 자동 생성
4. **사람이 수동으로 리뷰 후 머지** 
5. Obsidian Git 플러그인으로 pull (또는 수동)

## 🧪 테스트 및 검증

### E2E 테스트 실행
```bash
# 종합 테스트 스위트 실행
python test_e2e.py

# 개별 테스트
python test_simple_server.py    # 모듈 임포트 검증
python test_github_tools.py     # GitHub 기능 테스트
python test_obsidian_extended.py # Obsidian 기능 테스트
```

### 테스트 결과 예시
- **전체 테스트**: 41개
- **성공률**: 95.1% (MCP SDK 설치 시 100%)
- **커버리지**: 환경설정, Obsidian 워크플로우, GitHub 시뮬레이션, 통합 테스트, 서버 기동

### 프로덕션 준비 체크리스트
- [ ] 환경변수 설정 완료 (.env 파일)
- [ ] MCP SDK 설치: `pip install mcp`  
- [ ] E2E 테스트 통과 확인
- [ ] Claude Desktop MCP 설정 완료
- [ ] GitHub Personal Access Token 발급
- [ ] Obsidian 볼트 경로 확인

---

**주의**: 머지는 항상 수동으로 진행하여 코드 품질을 유지합니다.