🚀 DoneTick MCP 서버 (Model Context Protocol SSE)

DoneTick(자체 호스팅 할 일 및 작업 관리)용 **HTTP Server-Sent Events (SSE)**를 구현한 완전하고 프로덕션 준비가 된 Model Context Protocol (MCP) 서버입니다.

Mistral Le Chat, Claude Desktop, LibreChat, n8n, Open WebUI 및 모든 MCP 클라이언트와 호환됩니다.

📋 기능

이 서버는 완료 이력 및 시간 추적을 포함하여 DoneTick API를 포괄하는 57개의 특화된 MCP 도구를 제공합니다. 모든 엔드포인트는 npm run smoke를 통해 실제 인스턴스에서 검증됩니다.

1. 📝 할 일 및 작업 (donetick_*)

• donetick_list_chores: 필터(검색, 프로젝트, 상태)로 작업 목록을 조회합니다.

• donetick_get_chore: 반복 규칙, 담당자, 하위 작업, 라벨, 트리거뿐만 아니라 lastCompletedDate, lastCompletedBy, timeSpentSeconds를 포함한 전체 작업 세부 정보를 제공합니다.

• donetick_create_chore: 마감일, 반복, 우선순위, 포인트, 프로젝트, 하위 작업, 라벨, 알림, 승인 및 센서 트리거로 할 일을 생성합니다.

• donetick_update_chore: 부분 또는 전체 업데이트를 수행합니다. 할 일을 먼저 읽을 수 없으면 무작정 쓰지 않고 중단합니다.

• donetick_complete_chore: 할 일을 완료하고 다음 반복 일정을 예약합니다.

• donetick_undo_chore: 마지막 완료를 실행 취소합니다.

• donetick_delete_chore: 할 일을 영구 삭제합니다(보관을 권장).

• donetick_set_due_date: 마감일을 설정, 변경 또는 삭제합니다.

• donetick_set_priority: 우선순위를 설정합니다 — 1이 가장 높음(P1), 4가 가장 낮음, 0은 없음.

• donetick_skip_chore: 현재 반복을 건너뜁니다.

• donetick_nudge_chore: 담당자에게 알림을 보냅니다.

• donetick_set_chore_notifications: 알림(마감일, 마감 전, 재촉, 완료)을 구성합니다.

• donetick_set_chore_project, donetick_set_chore_assignee: 할 일을 재배정합니다.

2. 📊 완료 이력 (donetick_*)

• donetick_get_chore_history: 하나의 할 일에 대한 모든 완료, 건너뜀, 일정 변경 및 누락 기록을 읽기 쉬운 statusName과 요약과 함께 제공합니다. "완료"와 "수정"을 구분하는 유일한 신뢰할 수 있는 방법입니다 — updatedAt은 둘을 혼동합니다.

• donetick_get_history: 날짜 범위와 상태로 필터링 가능한 서클 전체 활동입니다.

• donetick_modify_history_entry: 완료가 기록된 시점이나 메모를 수정합니다.

• donetick_delete_history_entry: 잘못된 항목을 제거합니다.

3. ⏱️ 시간 추적 (donetick_*)

• donetick_start_chore / donetick_pause_chore: 할 일별 타이머를 실행합니다.

• donetick_get_chore_timer: 총 소요 시간과 각 작업 세션을 제공합니다.

• donetick_reset_chore_timer: 누적 시간을 초기화합니다.

• donetick_adjust_time_session / donetick_delete_time_session: 사후에 이력을 수정합니다.

4. 🧩 하위 작업 (donetick_*)

• donetick_set_subtasks: 전체 목록을 교체합니다. 파괴적이지만 이름 매칭으로 ID와 완료 상태를 보존합니다.

• donetick_add_subtask: 다른 하위 작업은 그대로 두고 하나를 추가합니다.

• donetick_complete_subtask / donetick_uncomplete_subtask: ID 또는 이름으로 하위 작업 하나를 완료 처리합니다.

• donetick_remove_subtask: 목록을 다시 쓰지 않고 하위 작업 하나를 삭제합니다.

참고: 반복 할 일을 완료하면 하위 작업이 완료 처리되는 대신 지워집니다. 이는 다음 발생을 준비하는 DoneTick 자체의 동작입니다.

5. 🗄️ 보관 및 승인 (donetick_*)

• donetick_list_archived_chores, donetick_archive_chore, donetick_unarchive_chore: 삭제의 대안으로 되돌릴 수 있는 방법입니다.

• donetick_approve_chore, donetick_reject_chore: requireApproval이 설정된 할 일의 완료를 검토합니다.

6. 🏷️ 라벨 및 태그 (donetick_*)

• donetick_list_labels: 라벨을 나열하고, 실패 시 할 일에서 추출하는 방식으로 대체합니다.

• donetick_create_label, donetick_update_label, donetick_delete_label: 아래 제한 사항 참조 — JWT가 필요합니다.

• donetick_set_chore_labels, donetick_add_chore_label: 할 일에 라벨을 연결합니다.

7. ⚡ 스마트 사물 및 이벤트 트리거 (donetick_*)

• donetick_list_things, donetick_create_thing, donetick_update_thing, donetick_delete_thing.

• donetick_set_thing_state: 센서 또는 카운터를 업데이트하고 연결된 작업을 자동으로 트리거합니다.

• donetick_get_thing_history: 사물이 가졌던 모든 상태와 시점을 제공합니다.

• donetick_link_thing_chore / donetick_unlink_thing_chore: 트리거 조건(eq, neq, gt, lt, gte, lte).

8. 📁 프로젝트 (donetick_*)

• donetick_list_projects, donetick_create_project, donetick_update_project, donetick_delete_project.

9. 👥 서클, 구성원 및 필터 (donetick_*)

• donetick_get_circle_info, donetick_list_members, donetick_list_filters.

Related MCP server: Deferno MCP Server

📅 날짜 및 우선순위

날짜. DoneTick은 모든 날짜를 Go time.Time에 바인딩하므로 RFC3339만 허용합니다. 커넥터는 추가로 YYYY-MM-DD 및 YYYY-MM-DD HH:mm 형식을 허용하며, DONETICK_TIMEZONE(기본값 UTC) 및 DONETICK_DEFAULT_DUE_TIME(기본값 18:00)으로 해석합니다. "내일 마감"이 UTC 자정이 아닌 합리적인 현지 시간을 의미하도록 하려면 둘 다 설정하세요.

우선순위. DoneTick은 역순으로 계산합니다: 1이 가장 높은 우선순위로 웹 UI에서 빨간색 P1으로 표시되고, 4가 가장 낮습니다. 0은 우선순위 없음을 의미합니다. 2.0.0 이전 버전은 이를 반대로 문서화했으므로 이전 설명을 통해 작성된 할 일은 반전된 값을 가질 수 있습니다.

⚠️ 알려진 제한 사항

• API 키로는 라벨을 생성하거나 편집할 수 없습니다. DoneTick은 다른 모든 라우트와 달리 /api/v1/labels를 JWT 전용 미들웨어 뒤에 마운트합니다. 읽기는 할 일에서 라벨을 추출하는 방식으로 대체되며, 웹 UI에서 관리하세요.

• 임의의 기간을 기록할 수 없습니다. POST /chores/{id}/do는 소요 시간 값을 허용하지 않으며, DoneTick의 수동 기간 핸들러는 정의만 되고 라우팅되지 않습니다. 시작/일시정지를 사용하거나 이후에 세션 경계를 조정하세요.

• 이력 창은 일 단위입니다. DoneTick의 limit은 행 수가 아닌 일 수입니다. since/until은 가져온 후 클라이언트 측에서 적용됩니다.

🔒 보안 및 OWASP 강화

• OWASP A01 및 A07 (접근 제어 및 타이밍 공격): 상수 시간 인증 토큰 검증(crypto.timingSafeEqual).

• OWASP A02 (암호화 실패 및 정보 유출): 로그의 비밀 정보 삭제 및 자격 증명이 없는 안전한 /health 텔레메트리.

• OWASP A03 (인젝션 및 SSRF): 엄격한 프로토콜 검증(http:, https:)으로 프로토콜 인젝션 또는 SSRF(file://, gopher://) 방지.

• OWASP A04 (서비스 거부): 엄격한 JSON 본문 페이로드 제한(1mb) 및 연결 정리 기능이 있는 활성 SSE 세션 상한.

• OWASP A05 (보안 구성 오류): 강화된 HTTP 헤더(X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0, Referrer-Policy: no-referrer, X-Powered-By 비활성화). 루트가 아닌 Docker 실행(USER node).

🐳 Docker 빠른 시작

1. docker-compose.yml 생성

services:
  mcp-donetick:
    image: ghcr.io/bibiwan/mcp_donetick:latest
    container_name: mcp-donetick
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - HOST=0.0.0.0
      - DONETICK_URL=http://donetick:2021
      - DONETICK_TOKEN=
      # Resolves date-only inputs such as "2026-08-30" to a local hour
      - DONETICK_TIMEZONE=Europe/Paris
      - DONETICK_DEFAULT_DUE_TIME=18:00
      - MCP_AUTH_TOKEN=
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

2. 컨테이너 실행

docker compose up -d

🤖 Mistral Le Chat 연결

1. **Mistral Le Chat**에서 설정 ➔ 도구 및 MCP(또는 커넥터)로 이동합니다.

2. **"MCP 서버 추가"**를 클릭합니다.

3. 연결 설정을 입력합니다:

   • 이름: DoneTick

   • URL: https://<your-server-host>:3000/sse

   • 인증: Bearer Token

   • 토큰: <Your DoneTick API Token> (DoneTick ➔ 설정 ➔ API 토큰에서 생성)

4. 저장하고 채팅을 시작하세요!

예시 프롬프트:

• "기한이 지났거나 오늘 마감인 할 일이 무엇인가요?"

• "'에스프레소 머신 청소' 할 일을 다음 일요일, 높은 우선순위로 하위 작업 '그룹헤드 백플러시', '보일러 스케일 제거'와 함께 만들어 줘."

• "할 일 #21을 내 커피 카운터(사물 #11)에 연결해서 카운터가 100 이상이 되면 트리거되게 해 줘."

• "작업 #5를 20포인트로 완료 처리해 줘."

🧪 개발 및 테스트

# Install dependencies
npm install

# Run the test suite with coverage.
# Enforces an 80% floor on statements, branches, functions and lines.
npm test

# Build TypeScript
npm run build

# Start local server
npm start

실시간 스모크 테스트

단위 테스트 스위트는 axios를 모킹하므로 페이로드가 의도한 대로 구성되었음을 증명할 뿐, DoneTick이 이를 수락한다는 것을 증명하지는 않습니다. 릴리스를 태그하기 전에 실제 인스턴스에 대해 스모크 테스트를 실행하세요:

DONETICK_URL=https://donetick.example DONETICK_TOKEN=xxx npm run smoke

[mcp-test] 접두사가 붙은 객체만 생성하고, 커넥터가 사용하는 모든 엔드포인트를 실행하며, 생성한 항목을 삭제하고, 해당 접두사가 없는 항목은 삭제를 거부합니다. 기존 할 일은 절대 수정되지 않습니다.

📄 라이선스

MIT 라이선스. 자유롭게 사용, 수정 및 배포할 수 있습니다.