Simple Task MCP Server

간단한 작업 관리 시스템을 위한 MCP(Model Context Protocol) 서버입니다. 다른 Task Manager 와 달리 사용과 설치가 매우 간단하고, 직관적이며, 작업 목록을 순차적으로 진행하고 진행 상태를 추적할 수 있습니다.

해야할 일을 text 파일에 차례대로 한 문단씩 기입하고, 차례대로 해당 일을 수행하게 됩니다. 즉 할일 목록 처럼 프롬프트를 여거래 만든 다음에 하나씩 수행하는 일을 합니다. 할일 목록을 수정하거나 추가 하거나 삭제하거나 자유롭게 사용가능하고, 수정된 내용을 바로 적용할 수 있습니다.

🎯 간단한 사용법

"현재 할 일이 뭐지?"

tasks_peek()  # 현재 작업 확인

또는 자연어로: "현재 할 일이 뭐야?", "지금 해야 할 작업은?", "다음에 뭘 해야 해?"

"다음 일을 수행해줘"

tasks_next()  # 다음 작업 가져오기

또는 자연어로: "다음 일을 수행해줘", "다음 작업을 보여줘", "다음 할 일은 뭐야?"

"할일 목록을 보여줘"

show_task_table()  # 전체 작업 목록 확인 (표 형태)

또는 자연어로: "할일 목록을 보여줘", "전체 작업 목록이 뭐야?", "몇 개의 작업이 있어?"

"상세한 할일 목록을 보여줘"

explain_tasks_detailed()  # 전체 내용이 포함된 상세 목록

또는 자연어로: "상세한 할일 목록을 보여줘", "전체 내용과 함께 할일 목록을 보여줘"

"처음부터 다시 시작하고 싶어"

tasks_reset()  # 작업 포인터 리셋

또는 자연어로: "처음부터 다시 시작하고 싶어", "작업을 리셋해줘", "다시 처음부터 시작해"

"특정 작업으로 건너뛰고 싶어"

tasks_goto(3)  # 4번째 작업으로 이동

또는 자연어로: "3번째 작업으로 건너뛰고 싶어", "4번째 작업으로 이동해줘", "작업 3으로 가줘"

"남은 할일을 모두 수행해줘"

tasks_auto()  # 모든 남은 작업 자동 수행

또는 자연어로: "남은 할일을 모두 수행해줘", "모든 일을 다 해줘", "나머지 작업을 한번에 처리해줘"

"특정 개수의 작업을 한번에 수행해줘"

tasks_auto(3)  # 3개 작업을 한번에 수행

또는 자연어로: "5개의 일을 한번에 수행해줘", "3개 작업을 동시에 처리해줘", "다음 2개 작업을 한번에 해줘"

"프로젝트에 .simple 폴더를 만들어줘"

touch_simple()  # .simple 디렉토리 생성

또는 자연어로: "프로젝트에 .simple 폴더를 만들어줘", "작업 폴더를 생성해줘"

"작업을 완료해줘"

tasks_complete(0)  # 0번 작업을 완료로 표시

또는 자연어로: "0번 작업을 완료해줘", "첫 번째 작업을 끝냈어"

"작업을 미완료로 되돌려줘"

tasks_uncomplete(0)  # 0번 작업을 미완료로 되돌리기

또는 자연어로: "0번 작업을 미완료로 되돌려줘", "첫 번째 작업을 다시 하게 해줘"

"작업 상태를 초기화해줘"

tasks_reset_status()  # 모든 작업을 대기 중으로 되돌리기

또는 자연어로: "모든 작업 상태를 초기화해줘", "작업 상태를 리셋해줘"

"작업 목록과 상태를 동기화해줘"

sync_tasks()  # 작업 목록과 상태 강제 동기화

또는 자연어로: "작업 목록과 상태를 동기화해줘", "동기화해줘"

"현재 규칙을 보여줘"

show_rules()  # 현재 적용되는 규칙 표시

또는 자연어로: "현재 규칙을 보여줘", "적용되는 규칙이 뭐야?"

---

🚀 15개 함수만 알면 끝! 복잡한 설정이나 명령어 없이 간단한 함수 호출만으로 작업을 관리할 수 있습니다.

💡 자연어로도 실행 가능! Cursor나 Claude에서는 "다음 할 일이 뭐야?"라고 말하면 자동으로 tasks_next()가 실행됩니다.

🎉 자동 감지: MCP 서버가 Cursor의 현재 워크스페이스를 자동으로 감지합니다!

🔄 2단계 상태 시스템: 모든 작업은 대기 중([대기]) → 완료(✅) 순서로 진행됩니다!

🔒 자동 보안: 기본 보안 규칙이 자동으로 적용되어 중요한 파일들을 보호합니다!

🔄 자동 동기화: 작업 목록이 변경되면 자동으로 상태와 동기화됩니다!

이게 전부입니다! 복잡한 설정이나 명령어 없이 간단한 함수 호출만으로 작업을 관리할 수 있습니다.

💡 실제 사용 예시

1단계: 작업 파일 작성

# .simple/simple_task.txt
로그인 화면 만들기

대시보드 구현하기

사용자 관리 기능 추가하기

2단계: Cursor에서 사용

# 할일 목록 확인
show_task_table()
# 출력: 
# | 번호 | 상태 | 할일 내용 |
# |------|------|-----------|
# | 0 | [대기] | 로그인 화면 만들기 |
# | 1 | [대기] | 대시보드 구현하기 |
# | 2 | [대기] | 사용자 관리 기능 추가하기 |

# 현재 작업 확인
tasks_peek()
# 출력: 📋 현재 작업 0: 로그인 화면 만들기

# 작업 완료
tasks_complete(0)  # 0번 작업 완료

# 다음 작업 진행
tasks_next()
# 출력: ✅ 작업 0 완료 후 다음 작업으로 진행: 대시보드 구현하기

또는 자연어로:

• "할일 목록을 보여줘" → 자동으로 show_task_table() 실행
• "현재 할 일이 뭐야?" → 자동으로 tasks_peek() 실행
• "다음 할 일을 보여줘" → 자동으로 tasks_next() 실행

3단계: 계속 진행

tasks_next()  # 대시보드 구현하기
tasks_next()  # 사용자 관리 기능 추가하기
# 모든 작업 완료! ✅

자연어로도 가능:

• "0번 작업을 완료해줘" → 0번 작업을 완료로 표시
• "다음 작업을 보여줘" → 대시보드 구현하기
• "그 다음은?" → 사용자 관리 기능 추가하기
• "작업 상태를 초기화해줘" → 모든 작업을 대기 중으로 되돌리기

자동 수행 기능:

# 남은 모든 작업을 한번에 수행
tasks_auto()
# 출력: 🚀 자동으로 모든 남은 작업(2개)을 준비했습니다: [1] 대시보드 구현하기, [2] 사용자 관리 기능 추가하기

# 특정 개수의 작업만 수행
tasks_auto(1)  # 1개 작업만 수행

# 자연어로도 가능
# "남은 할일을 모두 수행해줘" → 모든 작업 한번에 처리
# "5개의 일을 한번에 수행해줘" → 5개 작업 동시 처리

🚀 주요 기능

• 작업 목록 관리: 빈 줄로 구분된 작업들을 순차적으로 처리
• 2단계 상태 시스템: 대기([대기]) → 완료(✅) 상태 추적
• 진행 상태 추적: 현재까지 완료된 작업 인덱스와 상태 저장
• 규칙 적용: 각 작업에 공통 규칙 자동 적용
• MCP 호환: Cursor, Claude 등 MCP를 지원하는 도구들과 연동
• 자연어 실행: 함수명을 몰라도 자연어로 작업 요청 가능
• 자동 수행: 남은 작업들을 한 번에 또는 지정된 개수만큼 자동 처리
• 배치 처리: 여러 작업을 동시에 처리하여 효율성 극대화
• 상태 제어: 개별 작업의 완료, 미완료, 상태 초기화 기능
• 자동 동기화: 작업 목록 변경 시 상태와 자동 동기화
• 해시 기반 상태 관리: 작업 내용 변경 시 자동 감지
• 보안 규칙: 기본 보안 규칙 자동 적용으로 중요 파일 보호

📁 파일 구조

프로젝트/
├── .simple/
│   ├── simple_task.txt      # 작업 목록
│   ├── simple_rule.txt      # 공통 규칙 (선택사항)
│   └── simple_state.json    # 진행 상태
└── simple_task_mcp.py       # MCP 서버

🛠️ 설치 방법

1. 가상환경 생성 및 의존성 설치

# 가상환경 생성
python -m venv venv

# 가상환경 활성화 (macOS/Linux)
source venv/bin/activate

# 가상환경 활성화 (Windows)
venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

2. Cursor 설정 (자동 실행)

설정 완료 후 Cursor를 재시작하면 MCP 서버가 자동으로 실행됩니다.

3. 수동 실행 (선택사항)

Cursor 설정 없이 수동으로 실행하려면:

# 기본 실행
python simple_task_mcp.py

# 또는 uv 사용 (권장)
uv run simple_task_mcp.py

📝 설정 파일 작성

1. 작업 파일 생성 (.simple/simple_task.txt)

첫 번째 작업을 작성하세요

두 번째 작업을 작성하세요
여러 줄로 구성 가능합니다

세 번째 작업을 작성하세요

2. 규칙 파일 생성 (.simple/simple_rule.txt)

공통으로 적용할 규칙을 작성하세요
예: 코딩 가이드라인, 작업 원칙 등

🔧 Cursor 설정 (자동 실행)

Cursor에서 MCP 서버를 자동으로 실행하려면 설정에 다음을 추가하세요:

1. Cursor 설정 파일 열기

• macOS: Cmd + , 또는 Cursor > Preferences
• Windows/Linux: Ctrl + , 또는 File > Preferences > Settings

2. MCP 서버 설정 추가

설정에서 mcpServers를 검색하고 다음 JSON을 추가하세요:

macOS/Linux 예제:

{
  "mcpServers": {
    "simple-task-mcp": {
      "name": "Simple Task MCP",
      "command": "/Users/bert/simpletask/venv/bin/python",
      "args": [
        "/Users/bert/simpletask/simple_task_mcp.py",
        "--project-root",
        "."
      ],
      "type": "stdio",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Windows 예제:

{
  "mcpServers": {
    "simple-task-mcp": {
      "name": "Simple Task MCP",
      "command": "D:/drumgit/simple_task_mcp/venv/Scripts/python.exe",
      "args": [
        "D:/drumgit/simple_task_mcp/simple_task_mcp.py",
        "--project-root",
        "."
      ],
      "type": "stdio",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

3. 경로 수정

위 설정에서 다음 경로를 실제 경로로 수정하세요:

• command: 가상환경의 Python 실행 파일 경로
• args: simple_task_mcp.py 파일의 절대 경로

4. 중요: --project-root 설정

⚠️ 필수 설정: args 배열에 반드시 "--project-root", "." 를 포함해야 합니다!

"args": [
  "/path/to/simple_task_mcp.py",
  "--project-root",
  "."
]

이 설정이 없으면:

• .simple 폴더가 MCP 서버 실행 위치에 생성됩니다
• 실제 작업하는 프로젝트 폴더가 아닌 다른 곳에 파일이 생성됩니다
• MCP 도구가 올바른 프로젝트를 찾지 못합니다

이 설정이 있으면:

• .simple 폴더가 현재 Cursor 워크스페이스에 생성됩니다
• simple_task.txt, simple_rule.txt, simple_state.json 파일이 올바른 위치에 생성됩니다

5. 자동 실행 확인

설정 저장 후 Cursor를 재시작하면:

• MCP 서버가 자동으로 백그라운드에서 실행
• 작업 도구들이 자동으로 사용 가능
• 별도 터미널 실행 불필요

자동 감지: MCP 서버가 Cursor의 현재 워크스페이스 루트(CWD)를 자동으로 감지합니다!

🎯 사용 방법

1. 작업 목록 및 상태 확인

show_task_table()         # 모든 작업 목록을 표 형태로 표시 (상태 포함)
explain_tasks_detailed()  # 전체 내용이 포함된 상세 작업 목록
tasks_peek()              # 현재 작업 확인 (진행하지 않음)
tasks_peek_with_rules()   # 현재 작업 확인 (규칙 포함)

2. 작업 상태 제어

tasks_complete(0)         # 0번 작업을 완료로 표시
tasks_uncomplete(0)       # 0번 작업을 미완료로 되돌리기
tasks_reset_status()      # 모든 작업 상태를 대기 중으로 초기화

3. 작업 진행 및 제어

tasks_next()              # 다음 작업 가져오기 및 진행
tasks_next_with_rules()   # 다음 작업 가져오기 및 진행 (규칙 포함)
tasks_reset()             # 처음부터 다시 시작
tasks_goto(2)             # 3번째 작업으로 이동 (0부터 시작)

4. 자동 수행

tasks_auto()              # 남은 모든 작업을 한번에 수행
tasks_auto(3)             # 3개 작업을 한번에 수행

5. 유틸리티

touch_simple()             # .simple 디렉토리 생성
show_rules()               # 현재 적용되는 규칙 표시
sync_tasks()               # 작업 목록과 상태 강제 동기화

📊 상태 파일

simple_state.json 파일에 현재 진행 상태와 작업 상태가 저장됩니다:

{
  "index": 2,
  "completed_tasks": [0, 1],
  "completed_hashes": ["a1b2c3d4", "e5f6g7h8"],
  "task_hashes": {
    "0": "a1b2c3d4",
    "1": "e5f6g7h8",
    "2": "i9j0k1l2"
  }
}

• index: 2는 3번째 작업까지 완료했다는 의미
• completed_tasks: 완료된 작업 번호 목록
• completed_hashes: 완료된 작업의 해시값 목록
• task_hashes: 각 작업의 현재 해시값
• 다음 실행 시 4번째 작업부터 시작

🔄 작업 진행 흐름

1. 초기화: simple_state.json에서 진행 상태와 작업 상태 로드
2. 작업 로딩: simple_task.txt에서 작업 목록 읽기
3. 규칙 적용: simple_rule.txt의 규칙을 각 작업 앞에 추가
4. 상태 관리: 2단계 상태 시스템으로 작업 진행 추적
5. 작업 실행: 순차적으로 작업 진행
6. 상태 저장: 완료된 작업 인덱스와 상태를 simple_state.json에 저장
7. 자동 동기화: 작업 목록 변경 시 상태와 자동 동기화

🎯 2단계 상태 시스템

[대기] 대기 중 (Waiting)

• 작업이 아직 시작되지 않은 상태
• 기본 상태로, 모든 새 작업은 이 상태로 시작
• tasks_complete(index)로 완료로 변경 가능

✅ 완료 (Completed)

• 작업이 성공적으로 완료된 상태
• tasks_complete(index)로 설정
• tasks_uncomplete(index)로 대기 중으로 되돌리기 가능
• tasks_reset_status()로 모든 작업을 대기 중으로 초기화 가능

상태 전환 흐름

대기 중([대기]) ←→ 완료(✅)

🔒 자동 보안 규칙

모든 작업에 자동으로 적용되는 기본 보안 규칙:

# 🚨 기본 보안 규칙 (자동 적용)
# - .simple 폴더와 그 안의 파일들을 절대 삭제하지 마세요
# - simple_task.txt, simple_state.json, simple_rule.txt 등은 보존되어야 합니다
# - 필요하면 다른 방법을 사용하세요 (예: 파일 내용 수정, 새 파일 생성 등)
# - 폴더 구조를 변경하거나 삭제하지 마세요

🚨 문제 해결

MCP 서버 연결 실패

1. 워크스페이스 확인: Cursor에서 올바른 프로젝트 폴더를 열었는지 확인
2. 가상환경 확인: 올바른 Python 경로 사용
3. 파일 경로 확인: .simple 디렉토리와 파일들이 존재하는지 확인
4. Cursor 재시작: 설정 변경 후 Cursor 완전 재시작
5. 설정 확인: mcpServers 설정이 올바른지 확인
6. 자동 생성: .simple 폴더가 없으면 MCP 서버가 자동으로 생성합니다

작업 파일 오류

1. 파일 형식: UTF-8 인코딩으로 저장
2. 구분자: 빈 줄로 작업을 구분
3. 파일 위치: .simple 디렉토리 내에 위치

상태 동기화 문제

1. 자동 동기화: sync_tasks()로 강제 동기화
2. 해시 확인: 작업 내용이 변경되었는지 확인
3. 상태 초기화: tasks_reset_status()로 모든 상태 초기화

🛠️ 전체 도구 목록 (15개)

도구	설명	사용법
show_task_table()	작업 목록을 표 형태로 표시	show_task_table()
explain_tasks_detailed()	상세한 작업 목록 표시	explain_tasks_detailed()
tasks_peek()	현재 작업 확인	tasks_peek()
tasks_peek_with_rules()	현재 작업 확인 (규칙 포함)	tasks_peek_with_rules()
tasks_complete(index)	작업을 완료로 표시	tasks_complete(0)
tasks_uncomplete(index)	작업을 미완료로 되돌리기	tasks_uncomplete(0)
tasks_next()	다음 작업으로 진행	tasks_next()
tasks_next_with_rules()	다음 작업으로 진행 (규칙 포함)	tasks_next_with_rules()
tasks_reset()	처음부터 다시 시작	tasks_reset()
tasks_goto(index)	특정 작업으로 이동	tasks_goto(2)
tasks_auto(count)	자동으로 작업 수행	tasks_auto() 또는 tasks_auto(3)
tasks_reset_status()	모든 작업 상태 초기화	tasks_reset_status()
touch_simple()	.simple 디렉토리 생성	touch_simple()
show_rules()	현재 적용되는 규칙 표시	show_rules()
sync_tasks()	작업 목록과 상태 강제 동기화	sync_tasks()

📚 예시

작업 파일 예시

로그인 화면을 만들어줘

대시보드를 만들어줘

사용자 관리 기능을 추가해줘
- 사용자 목록 조회
- 사용자 정보 수정
- 사용자 삭제

규칙 파일 예시

코딩 가이드라인:
1. 명확하고 읽기 쉬운 코드 작성
2. 에러 처리를 포함한 안전한 코드 작성
3. 적절한 주석과 문서화

🤝 기여하기

버그 리포트나 기능 제안은 이슈로 등록해주세요.

📋 전체 룰 시스템

🎯 룰의 역할

simple_rule.txt 파일에 작성된 룰은 모든 작업에 자동으로 적용됩니다. 각 작업을 실행할 때마다 룰이 자동으로 앞에 추가되어 전달됩니다.

📝 룰 작성 방법

# .simple/simple_rule.txt
코딩 가이드라인:
1. 명확하고 읽기 쉬운 코드 작성
2. 에러 처리를 포함한 안전한 코드 작성
3. 적절한 주석과 문서화
4. 변수명은 누가 봐도 알 수 있게 명확하게 작성
5. 코드 변경이 쉽도록 절차적으로 작성

🔄 룰 적용 과정

1. 작업 로딩: simple_task.txt에서 작업 목록 읽기
2. 룰 로딩: simple_rule.txt에서 공통 룰 읽기
3. 자동 결합: 각 작업 앞에 룰을 자동으로 추가
4. 전달: 룰이 포함된 완전한 작업을 AI에게 전달

💡 실제 예시

작업 파일 (.simple/simple_task.txt):

로그인 화면을 만들어줘

대시보드를 구현해줘

룰 파일 (.simple/simple_rule.txt):

코딩 가이드라인:
- 명확하고 읽기 쉬운 코드 작성
- 에러 처리를 포함한 안전한 코드 작성

최종 전달되는 작업:

코딩 가이드라인:
- 명확하고 읽기 쉬운 코드 작성
- 에러 처리를 포함한 안전한 코드 작성

로그인 화면을 만들어줘

🚀 룰 시스템의 장점

1. 일관성: 모든 작업에 동일한 가이드라인 적용
2. 효율성: 매번 룰을 복사/붙여넣기 할 필요 없음
3. 유지보수: 룰만 수정하면 모든 작업에 자동 반영
4. 품질 향상: AI가 항상 최신 룰을 따라 작업 수행

🔧 룰 변경 시 주의사항

• 룰 파일 수정 후 MCP 서버 재시작 필요
• 룰이 너무 길면 작업 내용이 가려질 수 있음
• 룰과 작업 사이에 적절한 구분을 위한 빈 줄 포함 권장

🔄 자동 동기화 시스템

🎯 동기화의 필요성

작업 목록(simple_task.txt)이 변경되면 기존 상태(simple_state.json)와 불일치가 발생할 수 있습니다.

🚀 자동 동기화 기능

• 해시 기반 감지: 각 작업의 내용을 해시값으로 저장하여 변경 감지
• 자동 상태 조정: 작업이 추가/삭제/수정되면 상태를 자동으로 조정
• 완료 상태 보존: 기존에 완료된 작업은 내용이 동일한 한 완료 상태 유지

💡 동기화 사용법

# 자동 동기화 실행
sync_tasks()

# 또는 자연어로
# "작업 목록과 상태를 동기화해줘"

📊 동기화 결과 예시

🔄 작업 목록과 상태 동기화 완료!

📊 현재 상태:
- 총 작업 수: 5개
- 완료된 작업: 2개
- 현재 인덱스: 2

📋 동기화된 작업 목록:
0. ✅ 로그인 화면 만들기 (해시: a1b2c3d4)
1. ✅ 대시보드 구현하기 (해시: e5f6g7h8)
2. [대기] 사용자 관리 기능 추가하기 (해시: i9j0k1l2)
3. [대기] API 문서 작성하기 (해시: m3n4o5p6)
4. [대기] 테스트 코드 작성하기 (해시: q7r8s9t0)

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

🚀 MIT 라이선스란?

• 자유로운 사용: 사용, 수정, 배포, 상업적 이용 모두 자유
• 저작권 표시 필수: 원작자와 라이선스 정보를 유지해야 함
• 면책 조항: "있는 그대로" 제공, 책임 없음
• 호환성: 다른 라이선스와 잘 섞여서 사용 가능

💡 사용 예시

# 이 코드를 그대로 사용 ✅
# 이 코드를 수정해서 사용 ✅
# 이 코드를 상업적으로 사용 ✅
# 이 코드를 다른 프로젝트에 포함 ✅
# 이 코드를 다른 이름으로 배포 ✅
# 단, 저작권 표시와 라이선스 정보 유지 필요 ⚠️

📝 저작권 표시 요구사항

사용 시 다음 정보를 포함해야 합니다:

• Copyright (c) 2024 Simple Task MCP
• MIT License - see LICENSE file for details

MIT 라이선스는 매우 자유롭지만, 저작권 표시는 필수입니다.