MCP 작업 관리자 서버

SQLite 데이터베이스를 사용하여 클라이언트 중심 프로젝트 및 작업 관리를 위한 백엔드 도구를 제공하는 로컬 MCP(Model Context Protocol) 서버입니다.

개요

이 서버는 개별 프로젝트 내에서 구조화된 작업 데이터를 관리해야 하는 로컬 MCP 클라이언트(AI 에이전트 또는 스크립트 등)의 영구 백엔드 역할을 합니다. 데이터 저장을 처리하고 상호 작용을 위한 표준화된 도구 세트를 제공하는 반면, 전략적 워크플로 로직은 클라이언트 내에 상주합니다.

주요 특징:

• 프로젝트 기반: 작업은 개별 프로젝트 내에서 구성됩니다.
• SQLite 지속성: 간단하고 독립적인 데이터 저장소를 위해 로컬 SQLite 파일(기본적으로 ./data/taskmanager.db )을 사용합니다.
• 고객 중심: 고객에게 도구를 제공하며, 작업 흐름을 지시하지 않습니다.
• MCP 준수: 도구 정의 및 커뮤니케이션을 위한 모델 컨텍스트 프로토콜을 준수합니다.
• 업무 관리: 프로젝트 생성, 업무 추가, 업무 나열/표시, 상태 업데이트, 업무를 하위 업무로 확장, 다음에 실행 가능한 업무 식별을 지원합니다.
• 가져오기/내보내기: 프로젝트 데이터를 JSON으로 내보내고 JSON에서 가져와서 새로운 프로젝트를 만들 수 있습니다.

MCP 도구 구현

MCP 클라이언트에서는 다음 도구를 사용할 수 있습니다.

• createProject :
  • 설명: 새로운 빈 프로젝트를 만듭니다.
  • 매개변수: projectName (문자열, 선택 사항, 최대 255)
  • 반환: { project_id: string }
• addTask :
  • 설명: 프로젝트에 새로운 작업을 추가합니다.
  • 매개변수: project_id (문자열, 필수, UUID), description (문자열, 필수, 1-1024), dependencies (문자열[], 선택 사항, 최대 50), priority (enum 'high'|'medium'|'low', 선택 사항, 기본값 'medium'), status (enum 'todo'|'in-progress'|'review'|'done', 선택 사항, 기본값 'todo')
  • 반환: 생성된 작업의 전체 TaskData 객체.
• listTasks :
  • 설명: 선택적 필터링 및 하위 작업 포함 기능을 사용하여 프로젝트의 작업을 나열합니다.
  • 매개변수: project_id (문자열, 필수, UUID), status (열거형 'todo'|'진행 중'|'검토'|'완료', 선택 사항), include_subtasks (부울, 선택 사항, 기본값 false)
  • 반환: TaskData 또는 StructuredTaskData 객체의 배열입니다.
• showTask :
  • 설명: 종속성과 직접 하위 작업을 포함하여 특정 작업에 대한 전체 세부 정보를 검색합니다.
  • 매개변수: project_id (문자열, 필수, UUID), task_id (문자열, 필수)
  • 반환: FullTaskData 객체.
• setTaskStatus :
  • 설명: 하나 이상의 작업 상태를 업데이트합니다.
  • 매개변수: project_id (문자열, 필수, UUID), task_ids (문자열[], 필수, 1-100), status (enum 'todo'|'in-progress'|'review'|'done', 필수)
  • 반환: { success: true, updated_count: number }
• expandTask :
  • 설명: 상위 작업을 하위 작업으로 나누고, 기존 작업을 대체할 수도 있습니다.
  • 매개변수: project_id (문자열, 필수, UUID), task_id (문자열, 필수), subtask_descriptions (문자열[], 필수, 1-20, 각각 1-512), force (부울, 선택 사항, 기본값 false)
  • 반환: 새로운 하위 작업을 포함하여 부모 FullTaskData 객체를 업데이트했습니다.
• getNextTask :
  • 설명: 상태('todo'), 종속성('done'), 우선순위 및 생성 날짜를 기준으로 다음에 실행 가능한 작업을 식별합니다.
  • 매개변수: project_id (문자열, 필수, UUID)
  • 반환: 다음 작업의 FullTaskData 객체 또는 아무것도 준비되지 않은 경우 null 합니다.
• exportProject :
  • 설명: 전체 프로젝트 데이터를 JSON 문자열로 내보냅니다.
  • 매개변수: project_id (문자열, 필수, UUID), format (enum 'json', 선택 사항, 기본값 'json')
  • 반환: 프로젝트를 나타내는 JSON 문자열.
• importProject :
  • 설명: 내보낸 JSON 문자열에서 새 프로젝트를 만듭니다.
  • 매개변수: project_data (문자열, 필수, JSON), new_project_name (문자열, 선택, 최대 255)
  • 반환: 새로 생성된 프로젝트의 { project_id: string }
• updateTask :
  • 설명: 기존 작업에 대한 구체적인 세부 정보(설명, 우선순위, 종속성)를 업데이트합니다.
  • 매개변수: project_id (문자열, 필수, UUID), task_id (문자열, 필수, UUID), description (문자열, 선택 사항, 1-1024), priority (enum 'high'|'medium'|'low', 선택 사항), dependencies (string[], 선택 사항, 최대 50, 기존 항목 대체)
  • 반환: 업데이트된 FullTaskData 개체.
• deleteTask :
  • 설명: 하나 이상의 작업(및 계단식으로 해당 하위 작업/종속성 링크)을 삭제합니다.
  • 매개변수: project_id (문자열, 필수, UUID), task_ids (문자열[], 필수, 1-100)
  • 반환: { success: true, deleted_count: number }
• deleteProject :
  • 설명: 프로젝트 및 관련 데이터를 모두 영구적으로 삭제합니다. 주의해서 사용하세요!
  • 매개변수: project_id (문자열, 필수, UUID)
  • 반환: { success: true }

(참고: 자세한 Zod 스키마와 매개변수 설명은 해당 src/tools/*Params.ts 파일을 참조하세요.)

시작하기

1. 필수 구성 요소: Node.js(LTS 권장), npm.
2. 종속성 설치:지엑스피1
3. 개발 모드에서 실행: (자동 재로드를 위해 ts-node 및 nodemon 사용)
   npm run dev
   서버는 stdio를 통해 연결됩니다. 로그(JSON 형식)는 stderr에 출력됩니다. SQLite 데이터베이스는 ./data/taskmanager.db 에 생성/업데이트됩니다.
4. 프로덕션을 위한 빌드:
   npm run build
5. 프로덕션 빌드 실행:
   npm start

구성

• 데이터베이스 경로: SQLite 데이터베이스 파일의 위치는 DATABASE_PATH 환경 변수를 설정하여 변경할 수 있습니다. 기본값은 ./data/taskmanager.db 입니다.
• 로그 수준: 로깅 수준은 LOG_LEVEL 환경 변수(예: debug , info , warn , error )를 사용하여 설정할 수 있습니다. 기본값은 info 입니다.

프로젝트 구조

• /src : 소스 코드.
  • /config : 구성 관리.
  • /db : 데이터베이스 관리자 및 스키마( schema.sql ).
  • /repositories : 데이터 접근 계층(SQLite 상호작용).
  • /services : 핵심 비즈니스 로직.
  • /tools : MCP 도구 정의(*Params.ts) 및 구현(*Tool.ts).
  • /types : 공유 TypeScript 인터페이스(현재 최소한이며, 대부분 저장소/서비스에 있음).
  • /utils : 로깅, 사용자 정의 오류 등
  • createServer.ts : 서버 인스턴스 생성.
  • server.ts : 주요 애플리케이션 진입점.
• /dist : 컴파일된 JavaScript 출력.
• /docs : 프로젝트 문서(PRD, 기능 사양, RFC).
• /data : SQLite 데이터베이스 파일의 기본 위치(자동으로 생성됨).
• tasks.md : 개발을 위한 수동 작업 추적 파일.
• 구성 파일( package.json , tsconfig.json , .eslintrc.json 등)

린팅 및 포맷팅

• 린트: npm run lint
• 형식: npm run format

(코드는 Husky/lint-staged를 통해 커밋 시 자동으로 린트/포맷됩니다).