English | 한국어

MCP Project Manager

Claude Code와 통합된 종합 프로젝트 관리 및 워크플로우 추적 시스템. Model Context Protocol(MCP)을 기반으로 Claude Code 세션, 도구 사용, 에이전트 실행, 프로젝트 작업을 자동으로 캡처하여 중앙 집중식 대시보드와 데이터베이스에 저장합니다.

Fork 정보: 이 프로젝트는 croffasia/mcp-project-manager를 포크하여 3-tier 아키텍처로 확장한 버전입니다.

목차

• 개요
• 주요 기능
• 아키텍처
• 빠른 시작
• 설치
• MCP 클라이언트 설정
• 개발
• 기술 스택
• 라이선스

개요

MCP Project Manager는 Claude Code 워크플로우를 실행 가능한 인사이트로 변환하는 3-tier 시스템입니다. 다음을 자동으로 추적합니다:

• 세션 활동 및 타임라인
• 도구 사용 패턴 및 성능
• 에이전트 실행 및 스킬 호출
• 프로젝트 작업, 마일스톤, 산출물
• 파일 변경 및 코드 메트릭
• 팀 분석 및 인사이트

시각적 대시보드, REST API를 제공하며 MCP를 통해 Claude Desktop과 원활하게 통합됩니다.

핵심 기능

• 자동 이벤트 캡처: 8개의 Claude Code 훅 핸들러가 사용자 개입 없이 세션, 도구, 에이전트, 프롬프트를 자동 캡처
• 실시간 대시보드: WebSocket을 통한 라이브 업데이트, 칸반 보드, 플로우 그래프, 분석 차트
• 플로우 시각화: 에이전트 실행, 도구 호출, 의사결정 플로우의 그래프 기반 뷰
• 스마트 분석: 토큰 사용량, 에이전트 분포, 성공률, 타임라인 인사이트
• 프로젝트 관리: 프로젝트 생성, 작업 추적, 마일스톤 설정, 산출물 관리
• 원커맨드 설치: npx create-mcp-pm이 클론, 빌드, 설정, MCP 등록을 자동 처리

주요 기능

33개의 MCP 도구

플로우 및 세션 추적 (12개)

• flow_session_start / flow_session_end - 세션 생명주기 관리
• flow_task_start / flow_task_end - 작업 실행 추적
• flow_skill_call - 스킬 호출 기록
• flow_error - 오류 이벤트 로깅
• flow_agent_spawn / flow_agent_complete - 에이전트 생명주기
• flow_tool_call - 도구 실행 기록
• flow_file_change - 파일 변경 추적
• flow_commit - Git 커밋 기록
• flow_prompt - 사용자 프롬프트 로깅

프로젝트 관리 CRUD (15개)

• 프로젝트: pm_project_create, pm_project_update, pm_project_delete, pm_project_list, pm_project_get
• 작업: pm_task_create, pm_task_update, pm_task_delete, pm_task_list, pm_task_get
• 마일스톤: pm_milestone_create, pm_milestone_update, pm_milestone_list
• 작업 관리: pm_task_move, pm_task_assign_priority

쿼리 및 분석 (6개)

• pm_dashboard_summary - KPI 요약 및 프로젝트 통계
• pm_timeline - 이벤트 타임라인 조회
• pm_flow_graph - 플로우 그래프 데이터
• pm_analyze_bottleneck - 병목 현상 분석
• pm_suggest_next_task - 다음 작업 제안
• pm_report_generate - 프로젝트 리포트 생성

자체 업데이트 (1개)

• pm_self_update - 설치된 MCP 서버를 최신 버전으로 자동 업데이트

8개의 Claude Code 훅 핸들러

Claude Code 훅을 통한 자동 이벤트 캡처:

훅	이벤트	캡처 내용
session-start	SessionStart	새 세션 초기화
session-end	SessionEnd	세션 완료 및 요약
pre-tool-use	PreToolUse	도구 실행 전
post-tool-use	PostToolUse	도구 완료, 파일 변경
subagent-start	SubagentStart	에이전트 생성
subagent-stop	SubagentStop	에이전트 완료
user-prompt-submit	UserPromptSubmit	사용자 프롬프트 및 쿼리
stop	Stop	우아한 종료

대시보드 기능

핵심 뷰

• 개요 페이지 (/): KPI 카드, 프로젝트 통계, 트렌드 차트 (recharts)
• 프로젝트 페이지 (/projects): 프로젝트 목록 및 진행 상황
• 프로젝트 상세 (/projects/[id]):
  • 7단계 칸반 보드 (할 일/설계/구현/리뷰/테스트/완료/보관)
  • 드래그 앤 드롭 작업 관리 (@dnd-kit)
  • 작업 카드 액션: 편집, 삭제, 실행 시작/중지
  • 작업 실행 추적 (WebSocket 실시간 업데이트)
• 타임라인 (/projects/[id]/timeline): 이벤트 시간순 조회
• 플로우 그래프 (/projects/[id]/flow): 에이전트 실행 트리 시각화 (@xyflow/react v12)
• 활동 페이지 (/activities): 이벤트 목록 및 필터링
• 분석 페이지 (/analytics): 작업 완료율, 토큰 사용량, 에이전트 분포, 세션 활동
• 설정 페이지 (/settings): 서비스 상태, 데이터베이스 정보

실시간 업데이트

• WebSocket 기반 라이브 업데이트 (폴링 없음)
• 칸반 보드의 낙관적 업데이트
• 실시간 세션 추적

세션 및 작업 실행

• 세션 생성 및 관리
• 작업 실행 시작/중지
• 작업 단계 추적 (설계/구현/리뷰/테스트)
• 실행 상태 실시간 모니터링

아키텍처

3-Tier 설계

┌─────────────────────────────────────────┐
│         Claude Desktop / Claude Code    │
│              (MCP Client)               │
└──────────────┬──────────────────────────┘
               │
               │ MCP Protocol
               ▼
┌─────────────────────────────────────────┐
│    MCP Server (TypeScript)              │
│  33 Tools + 8 Hook Handlers             │
│  • Flow Events & Sessions               │
│  • Project Management CRUD              │
│  • Analytics & Queries                  │
└──────────────┬──────────────────────────┘
               │
               │ REST API / WebSocket
               ▼
┌─────────────────────────────────────────┐
│   FastAPI Backend (Python 3.14)         │
│   SQLAlchemy ORM + SQLite (WAL)         │
│   • 15 database tables                  │
│   • Real-time WebSocket updates         │
│   • Async/await execution               │
└──────────────┬──────────────────────────┘
               │
               │ WebSocket / HTTP
               ▼
┌─────────────────────────────────────────┐
│    Next.js Dashboard (React 19)         │
│   • Kanban board with drag-and-drop     │
│   • Flow graph visualization            │
│   • Analytics & timeline views          │
│   • Real-time project tracking          │
└─────────────────────────────────────────┘

패키지 구조

packages/
├── mcp-server/    # TypeScript MCP Server (tsup build)
│   └── src/tools/ # 33 MCP tools
│       ├── flow-events.ts, flow-session.ts, flow-agent.ts, flow-tracking.ts
│       ├── pm-project.ts, pm-task.ts, pm-milestone.ts, pm-actions.ts
│       ├── pm-query.ts, pm-analysis.ts, pm-session.ts, pm-update.ts
│       └── index.ts
├── backend/       # FastAPI (Python 3.14) REST API + WebSocket
│   └── app/routes/ # projects, tasks, sessions, milestones, events, analytics, ws, seed, ai, labels
├── dashboard/     # Next.js 15 (App Router) Web Dashboard
│   └── src/app/   # pages: /, activities, analytics, projects, projects/[id] (kanban/timeline/flow), settings
├── cli/           # CLI tools
└── create-mcp-pm/ # Project scaffolding

데이터베이스: SQLite (WAL mode) at ~/.mcp-pm/mcp_pm.db, 15 tables 포트: Backend 48293, Dashboard 48294

빠른 시작

설치

가장 빠른 시작 방법:

# 옵션 1: GitHub에서 직접 설치 (npm 계정 불필요)
curl -fsSL https://raw.githubusercontent.com/skdkfk8758/MCP-ProjectManager/main/scripts/install.sh | bash

# 옵션 2: npx (npm publish 후 사용 가능)
npx create-mcp-pm

이 단일 명령이 다음을 수행합니다:

1. 필수 의존성 확인 (Node.js 20+, Python 3.14+, git)
2. MCP ProjectManager 저장소 클론
3. pnpm을 통한 모든 의존성 설치
4. 모든 패키지 빌드 (MCP Server, CLI, Dashboard, Backend)
5. Python 백엔드 가상 환경 설정
6. Claude Desktop에 MCP 서버 등록
7. Claude Code 훅 핸들러 설치

수동 설정 (개발용)

로컬 개발 시:

# 저장소 클론
git clone https://github.com/skdkfk8758/MCP-ProjectManager.git
cd MCP_ProjectManager

# 의존성 설치
pnpm install

# 모든 패키지 빌드
pnpm build

# Python 백엔드 설정
cd packages/backend
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .
cd ../..

# Claude Desktop 등록 및 훅 설치
mcp-pm setup

# 서비스 시작
mcp-pm start

대시보드 접속

실행 후:

• 대시보드: http://localhost:48294
• 백엔드 API: http://localhost:48293
• API 문서: http://localhost:48293/docs

데모 데이터

데모 데이터를 시드하여 모든 대시보드 기능을 즉시 확인:

# 데모 데이터 시드 (3 프로젝트, 26 작업, 분석 데이터, 에이전트 통계)
bash scripts/seed-demo.sh

# 모든 데이터 초기화
bash scripts/seed-demo.sh reset

# 또는 API 직접 호출
curl -X POST http://localhost:48293/api/seed/demo
curl -X POST http://localhost:48293/api/seed/reset

MCP 클라이언트 설정

Claude Desktop

~/.claude/settings.local.json에 다음 추가:

{
  "mcpServers": {
    "mcp-project-manager": {
      "command": "node",
      "args": ["/Users/carpdm/Documents/mcp_servers/MCP_ProjectManager/packages/mcp-server/dist/index.js"]
    }
  }
}

Claude Code

훅 핸들러는 mcp-pm setup 실행 시 자동 등록됩니다.

Cursor / VS Code

MCP 확장 프로그램 설치 후 위와 동일한 설정 사용.

개발

요구사항

• Node.js 20.0.0 이상
• Python 3.14 이상
• pnpm 9.0.0 이상
• git

빌드 명령어

# 모든 패키지 빌드
pnpm turbo build

# 개별 패키지 빌드
pnpm build -F @mcp-pm/server
pnpm build -F @mcp-pm/backend
pnpm build -F @mcp-pm/dashboard
pnpm build -F @mcp-pm/cli

# 개발 모드 (watch)
pnpm dev

# 린팅
pnpm lint

# 빌드 아티팩트 정리
pnpm clean

개발 워크플로우

백엔드 시작

cd packages/backend
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python main.py
# http://localhost:48293에서 실행

대시보드 시작

cd packages/dashboard
pnpm dev
# http://localhost:48294에서 실행

MCP 서버 (로컬 테스트용)

cd packages/mcp-server
pnpm dev

주요 개발 노트

• 비동기 Python: 백엔드는 SQLAlchemy 비동기 ORM 사용. 데이터베이스 호출 시 항상 await
• Greenlet 요구사항: aiosqlite + SQLAlchemy 비동기 호환성을 위해 필수
• Next.js 15 라우트: 동적 라우트 params는 Promise. use()로 언래핑 필요
• 훅 핸들러: packages/mcp-server/src/hooks/에 위치. Claude Code 차단 방지를 위한 fire-and-forget 패턴
• TypeScript Strict: TypeScript strict 모드 사용. pnpm lint로 확인

기술 스택

레이어	기술
MCP Server	TypeScript, @modelcontextprotocol/sdk, tsup
Backend	Python 3.14, FastAPI, SQLAlchemy (async), aiosqlite, greenlet
Dashboard	Next.js 15 (App Router), React 19, TanStack Query, @dnd-kit, @xyflow/react, recharts, Tailwind CSS, date-fns
Build	pnpm workspaces, Turborepo
DB	SQLite (WAL mode)

CLI 명령어

mcp-pm CLI를 통한 프로젝트 관리:

# 전체 설정: 환경 확인, 빌드, 서비스 시작, MCP 등록
mcp-pm setup

# 서비스 시작 (백엔드 + 대시보드)
mcp-pm start [service]     # service: backend, dashboard, 또는 all (기본값)

# 모든 실행 중인 서비스 중지
mcp-pm stop

# 서비스 상태, 빌드, 훅, 데이터베이스 확인
mcp-pm status

# 이 프로젝트의 MCP 서버 및 훅을 Claude Desktop에서 제거
mcp-pm teardown

문서

• 도구 레퍼런스 - 33개 MCP 도구 상세 설명
• 프롬프트 가이드 - Claude와 함께 사용하기 위한 프롬프트 예제
• 아키텍처 문서 - 시스템 설계 및 데이터 플로우

라이선스

MIT License - 자세한 내용은 LICENSE 파일 참조

Copyright (c) 2025 MCP Project Manager Contributors

감사의 글

다음 기술로 구축되었습니다:

• Model Context Protocol by Anthropic
• TypeScript
• FastAPI
• Next.js
• React
• TailwindCSS
• SQLAlchemy

지원

이슈 및 질문:

• GitHub Issues: https://github.com/skdkfk8758/MCP-ProjectManager/issues
• Discussions: https://github.com/skdkfk8758/MCP-ProjectManager/discussions

---

시작할 준비가 되셨나요? npx create-mcp-pm을 실행하여 Claude Code 워크플로우 추적을 시작하세요!