WorkflowMCP

# WorkflowMCP 사용자 가이드 ## 개요 WorkflowMCP는 소프트웨어 개발 생명주기(SDLC)를 체계적으로 관리하는 AI 통합 프로젝트 관리 시스템입니다. 요구사항 관리부터 작업 추적, 문서 관리까지 개발 프로세스 전반을 하나의 플랫폼에서 관리할 수 있습니다. ## 핵심 특징 ### 🎯 **완전한 SDLC 지원** - **요구사항 관리**: PRD(프로젝트 요구사항 문서) 작성 및 관리 - **프로젝트 계획**: 일정, 진행률, 마일스톤 추적 - **작업 관리**: Kanban 스타일 작업 추적 (대기중 → 진행중 → 완료) - **문서 관리**: 중앙화된 문서 저장소 및 검색 - **대시보드**: 시각적 진행 상황 모니터링 ### 🤖 **AI 기반 워크플로우** - Claude Code와 완전 통합 - MCP(Model Context Protocol)를 통한 자동화 - AI 기반 문서 분석 및 작업 생성 ### 🛠️ **개발자 친화적** - SQLite 기반 로컬 데이터베이스 - 버전 관리 시스템 통합 가능 - 완전한 커스터마이징 지원 - 경량화된 설치 및 설정 --- ## 시스템 구성 ### **핵심 컴포넌트** | 컴포넌트 | 역할 | 접근 방법 | |----------|------|----------| | **SvelteKit 대시보드** | 웹 UI 인터페이스 | `http://localhost:3301` | | **MCP 서버** | AI 연동 및 자동화 | Claude Code 통합 | | **SQLite 데이터베이스** | 데이터 저장소 | `../data/workflow.db` | | **문서 관리 시스템** | 중앙화된 문서 저장 | 대시보드 내 통합 | ### **데이터 구조** ``` WorkflowMCP 데이터베이스 ├── PRDs (프로젝트 요구사항 문서) │ ├── 제목, 설명, 요구사항 목록 │ ├── 인수 조건, 우선순위, 상태 │ └── 생성일, 수정일, 작성자 ├── Plans (계획) │ ├── 제목, 설명, 시작/종료일 │ ├── 진행률, 우선순위, 상태 │ └── 연결된 작업 통계 ├── Tasks (작업) │ ├── 제목, 설명, 상태, 우선순위 │ ├── 마감일, 연결된 계획 │ └── 작업 진행 추적 └── Documents (문서) ├── 제목, 내용, 문서 타입 ├── 카테고리, 태그, 버전 └── 관계 및 링크 추적 ``` --- ## 설치 및 설정 ### **시스템 요구사항** - Node.js v18 이상 - SQLite 3.x - Claude Code (AI 연동용) ### **설치 단계** 1. **프로젝트 복제** ```bash git clone <repository-url> cd workflow-mcp ``` 2. **의존성 설치** ```bash # 루트 디렉토리에서 MCP 서버 의존성 npm install # 대시보드 의존성 cd dashboard npm install ``` 3. **데이터베이스 초기화** ```bash # 데이터베이스 스키마 생성 cd src/database node simple-migrate.js ``` 4. **서버 실행** ```bash # 대시보드 개발 서버 cd dashboard npm run dev ``` 5. **MCP 서버 연동** ```json // .mcp.json 설정 { "mcpServers": { "workflow-mcp": { "command": "node", "args": ["src/index.js"], "env": {} } } } ``` --- ## 기본 사용법 ### **1. 대시보드 접근** 브라우저에서 `http://localhost:3301` 접속하여 메인 대시보드 확인: - **프로젝트 개요**: 전체 통계 및 진행 현황 - **작업 활동 차트**: 일별 작업 생성/완료 추이 - **우선순위 분포**: 작업 우선순위별 현황 - **프로젝트 타임라인**: 간트 차트 형태의 일정 시각화 ### **2. PRD(프로젝트 요구사항 문서) 관리** #### **PRD 생성** 1. 대시보드에서 "PRD 관리" 클릭 2. "새 PRD 작성" 버튼 클릭 3. 기본 정보 입력: - 제목 (필수) - 설명 - 우선순위 (낮음/보통/높음) - 상태 (활성/비활성/완료) 4. 요구사항 추가: - 텍스트 입력 후 "추가" 버튼 - 동적으로 요구사항 목록 관리 - 개별 항목 삭제 가능 5. 인수 조건 추가: - 프로젝트 완료를 위한 구체적 조건 - 테스트 가능한 형태로 작성 권장 #### **PRD 관리** - **상세보기**: PRD 전체 내용 및 연결된 작업 확인 - **편집**: 기존 PRD 내용 수정 - **삭제**: 확인 후 PRD 완전 삭제 - **상태 관리**: 활성 → 비활성 → 완료 워크플로우 ### **3. 작업 관리** #### **Kanban 보드 사용법** 1. "작업 관리" 메뉴 접근 2. 3개 컬럼으로 구성: - **대기중**: 새로 생성된 작업들 - **진행중**: 현재 작업 중인 항목들 - **완료**: 완성된 작업들 3. 작업 상태 변경: - 각 카드의 버튼으로 상태 이동 - 대기중 → 시작 → 진행중 - 진행중 → 완료 또는 대기로 되돌리기 #### **작업 생성** 1. "새 작업 추가" 버튼 클릭 2. 작업 정보 입력: - 제목 (필수) - 상세 설명 - 우선순위 (낮음/보통/높음) - 초기 상태 (대기중/진행중/완료) - 마감 일자 (선택사항) - 연결된 계획 선택 3. 실시간 미리보기로 작업 카드 모양 확인 4. "작업 생성" 버튼으로 완료 #### **작업 세부 관리** - **우선순위별 색상**: 높음(빨강), 보통(노랑), 낮음(초록) - **마감일 표시**: 설정 시 작업 카드에 날짜 표시 - **계획 연결**: 상위 계획과의 관계 표시 - **통계 추적**: 전체/진행중/완료 작업 수 실시간 업데이트 ### **4. 계획 관리** #### **계획 생성 및 관리** 1. `/plans` URL 직접 접근 (메뉴 추가 예정) 2. "새 계획 작성"으로 계획 생성: - 제목, 설명, 우선순위, 상태 - 시작일/종료일 설정 - 진행률 설정 (슬라이더 및 숫자 입력) 3. 계획 카드에서 확인 가능한 정보: - 진행률 시각화 (프로그레스 바) - 연결된 작업 수 및 완료 작업 수 - 시작/종료 날짜 - 생성/수정일 추적 #### **진행률 관리** - **슬라이더 방식**: 5% 단위 조정 - **숫자 직접 입력**: 정확한 값 설정 - **시각적 표시**: 프로그레스 바로 직관적 확인 - **자동 계산**: 연결된 작업 완료율과 연동 (향후 기능) ### **5. 문서 관리** #### **MCP 도구를 통한 문서 관리** Claude Code에서 다음 MCP 도구 사용 가능: ```javascript // 문서 목록 조회 list_documents() // 새 문서 생성 create_document({ title: "프로젝트 기술 문서", content: "상세 내용...", doc_type: "technical", category: "development", tags: "backend,api,database" }) // 문서 검색 search_documents({ query: "API 설계", doc_type: "technical" }) // 문서 업데이트 update_document(1, { content: "수정된 내용...", version: 2 }) // 문서 간 관계 설정 link_documents(1, 2, "references") ``` #### **문서 타입별 관리** - **technical**: 기술 문서, API 명세서 - **requirements**: 요구사항, 기능 명세 - **meeting**: 회의록, 논의 내용 - **guide**: 사용자 가이드, 매뉴얼 - **analysis**: 분석 보고서, 검토 결과 --- ## 기존 프로젝트 도입 가이드 ### **도입 전략** #### **1단계: 점진적 도입 (추천)** **준비 단계 (1-2주)** - WorkflowMCP 설치 및 팀 교육 - 작은 기능 하나로 파일럿 테스트 - 기존 데이터 백업 및 분석 **시범 운영 (3-4주)** - 새로운 작업만 WorkflowMCP에서 관리 - 기존 도구와 병행 사용 - 팀 피드백 수집 및 프로세스 조정 **점진적 전환 (5-8주)** - 진행 중인 작업들 이관 - 문서 관리 시스템 활용 시작 - 워크플로우 최적화 **완전 전환 (9-12주)** - 모든 히스토리 데이터 마이그레이션 - 기존 도구 단계적 중단 - WorkflowMCP 중심 프로세스 정착 #### **2단계: 데이터 마이그레이션** **GitHub Issues에서 이관** ```javascript // GitHub API 활용 예시 const issues = await fetch('https://api.github.com/repos/owner/repo/issues'); // 변환 매핑: // Issue → Task // Label → Priority // Milestone → Plan // Assignee → 담당자 ``` **Jira에서 이관** ``` Epic → PRD (프로젝트 요구사항) Story → Task (작업) Sprint → Plan (계획) Custom Fields → WorkflowMCP 필드 ``` **스프레드시트/Trello에서 이관** ``` CSV Export → 데이터 정제 → WorkflowMCP Import 카드/행 → 작업 변환 리스트/상태 → 상태 매핑 카테고리 → 태그/우선순위 ``` #### **3단계: AI 활용 마이그레이션** **문서 기반 자동 생성** - 기존 기획서 → AI가 요구사항 추출 - 회의록 → AI가 액션 아이템 생성 - 이슈 설명 → AI가 작업으로 구조화 **데이터 정제 및 검증** - 중복 항목 자동 감지 - 누락된 필드 추천 - 관계 설정 제안 ### **도입 성공 요소** #### **팀 차원** - 전체 팀의 합의와 동기부여 - 충분한 교육 기간 확보 - 챔피언(적극 도입자) 확보 - 기존 워크플로우 존중 #### **기술적 차원** - 단계적 마이그레이션 계획 - 롤백 플랜 준비 - 데이터 무결성 검증 - 성능 모니터링 #### **즉시 시작 가능한 영역** 1. **문서 관리**: 리스크 낮고 효과 큼 2. **새 프로젝트**: 기존 작업에 영향 없음 3. **개인 작업**: 팀 협업 전에 개인 숙련도 확보 --- ## 고급 활용 ### **대시보드 커스터마이징** #### **차트 및 시각화** - **Chart.js 활용**: 작업 활동, 우선순위 분포 - **D3.js 간트 차트**: 프로젝트 타임라인 - **실시간 업데이트**: 데이터 변경 시 자동 반영 #### **통계 및 메트릭** ```javascript // 주요 지표 추적 - 전체 작업 수 / 완료 작업 수 - 완료율 계산 및 표시 - 우선순위별 작업 분포 - 일별/주별 작업 생성/완료 추이 - 평균 작업 완료 시간 ``` ### **API 연동 및 자동화** #### **웹훅 활용** ```javascript // Git 커밋과 작업 연동 POST /api/webhooks/git { "commit_message": "feat: 사용자 로그인 기능 완료 (#123)", "task_id": 123, "status": "completed" } // 외부 시스템 알림 POST /api/webhooks/slack { "task_completed": true, "task_title": "사용자 인증 API 구현", "assignee": "개발자명" } ``` #### **배치 처리** ```bash # 주간 리포트 자동 생성 node scripts/weekly-report.js # 데이터 백업 node scripts/backup-database.js # 성능 메트릭 수집 node scripts/collect-metrics.js ``` ### **커스텀 필드 및 워크플로우** #### **데이터베이스 스키마 확장** ```sql -- 커스텀 필드 추가 예시 ALTER TABLE tasks ADD COLUMN story_points INTEGER; ALTER TABLE tasks ADD COLUMN tech_stack TEXT; ALTER TABLE prds ADD COLUMN business_value TEXT; -- 새로운 상태 추가 ALTER TABLE tasks ADD COLUMN sub_status TEXT; ``` #### **커스텀 상태 워크플로우** ``` 기본: 대기중 → 진행중 → 완료 커스터마이징: 대기중 → 분석중 → 개발중 → 테스트중 → 리뷰중 → 완료 ↓ 보류중 → 재개 → 개발중 ``` --- ## 문제 해결 ### **일반적인 문제들** #### **데이터베이스 연결 오류** ``` Error: SQLITE_CANTOPEN: unable to open database file 해결방법: 1. 데이터베이스 경로 확인: ../data/workflow.db 2. 디렉토리 권한 확인 3. 절대 경로 사용 고려 4. 데이터베이스 파일 존재 여부 확인 ``` #### **Chart.js 초기화 실패** ``` Error: Chart.js failed to initialize 해결방법: 1. 빈 데이터 처리 로직 확인 2. Canvas 요소 존재 여부 확인 3. 브라우저 콘솔에서 상세 에러 확인 4. Chart.js 버전 호환성 점검 ``` #### **D3.js 렌더링 오류** ``` Error: <rect> attribute width: A negative value is not valid 해결방법: 1. 날짜 범위 유효성 검사 2. 최소 너비 보장 (Math.max 사용) 3. 데이터 전처리 강화 4. 스케일 함수 검증 ``` #### **MCP 서버 연결 실패** ``` Error: MCP server not responding 해결방법: 1. MCP 서버 프로세스 상태 확인 2. .mcp.json 설정 파일 검증 3. 포트 충돌 여부 확인 4. Claude Code 재시작 ``` ### **성능 최적화** #### **데이터베이스 최적화** ```sql -- 인덱스 추가 CREATE INDEX idx_tasks_status ON tasks(status); CREATE INDEX idx_tasks_priority ON tasks(priority); CREATE INDEX idx_documents_type ON documents(doc_type); -- 쿼리 최적화 EXPLAIN QUERY PLAN SELECT * FROM tasks WHERE status = 'in_progress'; ``` #### **프론트엔드 최적화** ```javascript // 지연 로딩 const LazyChart = lazy(() => import('./Chart.svelte')); // 메모이제이션 $: memoizedData = useMemo(() => processChartData(rawData), [rawData]); // 가상화 (대량 데이터) import { VirtualList } from 'svelte-virtual-list'; ``` --- ## 기존 도구와의 비교 ### **WorkflowMCP vs 기존 솔루션** | 기능 | WorkflowMCP | Jira | GitHub Issues | Trello | |------|------------|------|---------------|--------| | **요구사항 관리** | ✅ 전용 PRD 시스템 | ✅ Epic/Story | ❌ | ❌ | | **작업 추적** | ✅ Kanban 보드 | ✅ 다양한 보드 타입 | ✅ 기본 기능 | ✅ 카드 기반 | | **시각화** | ✅ Chart.js + D3.js | ✅ 고급 리포팅 | ❌ | ❌ | | **문서 관리** | ✅ 통합 시스템 | ✅ Confluence 연동 | ✅ Wiki | ❌ | | **AI 통합** | ✅ Claude 완전 연동 | ❌ | ❌ | ❌ | | **커스터마이징** | ✅ 완전 자유 | ❌ 제한적 | ❌ 제한적 | ❌ 제한적 | | **설치 복잡도** | ✅ 간단 (로컬) | ❌ 복잡 (서버) | ✅ 불필요 (클라우드) | ✅ 불필요 (클라우드) | | **비용** | ✅ 무료 | ❌ 유료 | ✅ 무료/유료 | ✅ 무료/유료 | ### **WorkflowMCP의 독특한 장점** #### **1. AI 기반 워크플로우** - Claude Code와의 완벽한 통합 - 자연어로 작업 생성 및 관리 - 문서에서 자동 요구사항 추출 - 코드 변경과 작업 상태 연동 #### **2. 개발자 중심 설계** - 코드베이스와 함께 버전 관리 - 로컬 환경에서 완전한 통제 - Git 워크플로우와 자연스러운 통합 - CLI 도구와의 연동 가능 #### **3. 경량화된 아키텍처** - SQLite 기반으로 설정 간단 - 외부 의존성 최소화 - 빠른 설치 및 시작 - 리소스 사용량 최소화 #### **4. 완전한 투명성** - 모든 소스 코드 공개 - 데이터 완전 통제 - 커스터마이징 제한 없음 - 벤더 락인 없음 --- ## 로드맵 및 향후 계획 ### **Phase 3: Migration & Integration (예정)** #### **데이터 마이그레이션 도구** - CSV/Excel 일괄 업로드 인터페이스 - GitHub Issues API 커넥터 - Jira REST API 커넥터 - 범용 데이터 가져오기 도구 #### **고급 통합 기능** - Git 커밋 메시지와 작업 자동 연결 - CI/CD 파이프라인 상태 연동 - 슬랙/이메일 알림 시스템 - 웹훅 기반 외부 시스템 연동 #### **고급 분석 및 리포팅** - 번다운/번업 차트 - 속도(Velocity) 측정 및 예측 - 팀 성과 대시보드 - 커스텀 리포트 생성기 ### **Phase 4: Enterprise Features (계획)** #### **멀티 프로젝트 지원** - 프로젝트 간 종속성 관리 - 포트폴리오 레벨 대시보드 - 리소스 할당 최적화 - 교차 프로젝트 리포팅 #### **고급 협업 기능** - 실시간 협업 편집 - 댓글 및 토론 시스템 - @멘션 및 알림 - 권한 및 역할 관리 #### **엔터프라이즈 보안** - SSO(Single Sign-On) 연동 - 감사 로그(Audit Log) - 데이터 암호화 - 백업 및 복구 자동화 --- ## 지원 및 커뮤니티 ### **도움 받기** - **GitHub Issues**: 버그 리포트 및 기능 요청 - **문서**: 상세 API 문서 및 가이드 - **예제**: 실제 사용 사례 및 템플릿 ### **기여하기** - **코드 기여**: Pull Request를 통한 기능 개선 - **문서 작성**: 사용 가이드 및 튜토리얼 - **테스팅**: 다양한 환경에서의 테스트 - **피드백**: 사용자 경험 개선 제안 ### **커뮤니티** - **Discord**: 실시간 질의응답 및 토론 - **포럼**: 심층 토론 및 기술 공유 - **블로그**: 사용 사례 및 모범 사례 공유 --- ## 결론 WorkflowMCP는 **AI 시대에 최적화된 프로젝트 관리 도구**입니다. 전통적인 이슈 트래킹 시스템의 기능을 모두 제공하면서도, Claude와의 완벽한 통합을 통해 **자연어 기반 프로젝트 관리**라는 새로운 패러다임을 제시합니다. ### **WorkflowMCP를 선택해야 하는 이유** 1. **완전한 SDLC 지원**: 요구사항부터 배포까지 전 과정 관리 2. **AI 기반 자동화**: 반복 작업 최소화 및 인사이트 제공 3. **개발자 친화적**: 코드와 함께 성장하는 관리 시스템 4. **완전한 자유도**: 오픈소스 기반 무제한 커스터마이징 5. **경제적**: 라이선스 비용 없는 완전 무료 솔루션 ### **시작하기** **지금 바로 시작할 수 있는 단계:** 1. 기존 프로젝트가 있다면 문서 관리부터 2. 새 프로젝트라면 전체 워크플로우 적용 3. 팀이 있다면 점진적 도입 전략 수립 WorkflowMCP와 함께 **더 스마트하고 효율적인 프로젝트 관리**를 경험해보세요. --- *이 가이드는 WorkflowMCP의 모든 기능을 다루는 종합 매뉴얼입니다. 추가 질문이나 지원이 필요하시면 언제든지 문의해주세요.*