IWL MCP Server

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

🎯 주요 기능

GitHub 툴

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

Obsidian 툴

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

📋 IWL 파일명 규칙

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

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

🚀 설치 및 실행

1. 환경 설정

# 저장소 클론 후
cd iwl-mcp-server

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

# 의존성 설치
pip install -e .

2. 환경변수 설정

# .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 서버 실행

# 방법 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 설정 파일에 다음 내용 추가:

{
  "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 연결

# 로컬 개발용
python -m mcp_server.main

ChatGPT 연결 (HTTP 터널)

# 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. 수동 리뷰 → 최종 승인 후 머지 (기존 정책 유지)

🔄 검증 프로세스

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

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

🛠️ 검증 지원 툴 사용 예

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

# 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 워크플로우

// 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 워크플로우

// 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 테스트 실행

# 종합 테스트 스위트 실행
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 볼트 경로 확인

---

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