task-manager-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트 개요

MCP Task Master는 Trello 스타일의 단순하고 효율적인 작업 관리 도구입니다. 복잡한 LLM 의존적 기능을 제거하고, 순수한 MCP(Model Context Protocol) 기능에 집중하여 진정한 MCP의 효율성을 구현합니다.

🎯 핵심 특징

• 단순함: Trello 수준의 직관적인 CRUD 작업 관리
• 효율성: 19개 도구에서 11개 도구로 축소 (42% 감소)
• 순수 MCP: LLM 분석 대신 MCP 본연의 기능에 집중
• 이중 언어: 한국어/영어 지원
• 실시간 Dashboard: React 기반 웹 인터페이스

핵심 기술 스택

• 언어: TypeScript (ES Module)
• 런타임: Node.js 18+
• 주요 라이브러리:
  • @modelcontextprotocol/sdk: MCP 서버 구현
  • express: 웹 서버 (Dashboard GUI)
  • zod: 데이터 검증 및 스키마 정의
  • uuid: 고유 ID 생성
  • dotenv: 환경 변수 관리

빌드 및 개발 명령어

일반적인 개발 워크플로우

# 의존성 설치
npm install

# TypeScript 컴파일 및 빌드
npm run build

# 개발 모드 실행 (ts-node 사용)
npm run dev

# 프로덕션 실행
npm run start

# 테스트 실행
npm run test

# 테스트 커버리지
npm run test:coverage

특별한 빌드 과정

npm run build 명령어는 다음을 수행합니다:

1. TypeScript 컴파일 (tsc)
2. 템플릿 마크다운 파일들을 dist로 복사 (copyfiles)
3. 정적 웹 파일들을 dist로 복사
4. 실행 파일에 shebang 추가 (node scripts/add-shebang.js)

프로젝트 아키텍처

핵심 디렉토리 구조

src/
├── index.ts                 # MCP 서버 진입점 및 11개 도구 등록
├── models/                  # 단순화된 데이터 모델
│   └── taskModel.ts        # Task 인터페이스 및 CRUD 함수들
├── messages/                # 다국어 메시지 시스템 🆕
│   ├── index.ts           # 언어 감지 및 메시지 로더
│   ├── korean.ts          # 한국어 메시지
│   └── english.ts         # 영어 메시지
├── prompts/                 # 템플릿 파일 저장 (최소화됨)
│   ├── loader.ts          # 템플릿 로딩 시스템
│   └── templates_ko/      # 한국어 템플릿 (Dashboard용만 유지)
├── tools/                   # 11개 MCP 도구 구현체
│   ├── task/              # 7개 핵심 작업 관리 도구
│   │   ├── listTasks.ts      # 작업 목록 조회
│   │   ├── executeTask.ts    # 단순화된 작업 실행 가이드
│   │   ├── deleteTask.ts     # 작업 삭제
│   │   ├── clearAllTasks.ts  # 전체 작업 삭제
│   │   ├── updateTask.ts     # 작업 내용 수정
│   │   ├── queryTask.ts      # 작업 검색
│   │   └── getTaskDetail.ts  # 작업 상세 조회
│   └── dashboard/         # 6개 Dashboard 관리 도구
│       ├── startDashboard.ts     # 대시보드 서버 시작
│       ├── stopDashboard.ts      # 대시보드 서버 정지
│       ├── statusDashboard.ts    # 대시보드 상태 확인
│       ├── listDashboardProjects.ts    # 프로젝트 목록
│       ├── addDashboardProject.ts      # 프로젝트 추가
│       └── createTasksInProject.ts     # 프로젝트 작업 생성
├── types/                   # 단순화된 타입 정의
│   └── index.ts            # Task, TaskStatus 등 핵심 타입만 유지
├── utils/                   # 공통 유틸리티
│   ├── agentMatcher.ts     # AI Agent 매칭 로직
│   ├── fileLoader.ts       # 파일 처리
│   ├── paths.ts           # 경로 관리
│   └── regex.ts           # 정규표현식 패턴
└── web/                    # 웹 서버 (Dashboard용)
    └── webServer.ts        # Express 서버 구현