Skip to main content
Glama
deenesjakoruzh
moazhassan751

todo-mcp-server

by moazhassan751
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Todo MCP Server

Model Context Protocol (MCP) 기반으로 Python과 FastMCP를 사용하여 구축된 견고하고 영속적인 작업 관리 서버입니다.

개요

Todo MCP Server는 언어 모델과 AI 에이전트에게 영속적이고 상태를 유지하는 작업 관리 인터페이스를 제공합니다. 공식 Python MCP SDK(FastMCP)를 사용하여 구축되었으며, AI 어시스턴트가 워크플로우 내에서 직접 작업을 생성, 추적, 필터링, 완료할 수 있도록 하는 도구를 노출합니다.

상태는 구조화된 JSON 저장소(tasks.json)에 로컬로 영속화되어, 서버 재시작, 클라이언트 재연결, 다중 턴 에이전트 세션에서도 작업 데이터가 유지됩니다. 통신은 표준 입력/출력(stdio)을 통한 JSON-RPC 2.0을 사용하여 MCP 사양을 따릅니다.

Related MCP server: Task Manager MCP Server

아키텍처 및 데이터 흐름

+-------------------------------------------------------------------+
|                        MCP Host / AI Client                       |
|               (Claude Desktop, Cursor, Antigravity)               |
+-------------------------------------------------------------------+
                                  |
                   JSON-RPC 2.0 over stdin / stdout
                                  v
+-------------------------------------------------------------------+
|                       Todo MCP Server                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   |                       FastMCP Engine                      |   |
|   |  - Protocol negotiation & schema reflection               |   |
|   |  - Tool dispatch & argument validation (Pydantic/Typing)  |   |
|   +-----------------------------------------------------------+   |
|                                 |                                 |
|   +-----------------------------+-----------------------------+   |
|   |                             |                             |   |
|   v                             v                             v   |
| [ add_task ]             [ list_tasks ]             [ complete_task ]
|   |                             |                             |   |
|   +-----------------------------+-----------------------------+   |
|                                 |                                 |
|                                 v                                 |
|   +-----------------------------------------------------------+   |
|   |                    Storage Controller                     |   |
|   |  - Atomic read/write operations                           |   |
|   |  - Schema serialization with ISO 8601 UTC timestamps      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                      Local Storage: tasks.json                    |
+-------------------------------------------------------------------+

도구 참조

서버는 전체 작업 수명주기 관리를 위한 세 가지 고유 도구를 노출합니다.

1. add_task

새 작업 항목을 생성하고 영속적 저장소에 추가합니다.

  • 설명: 할 일 목록에 새 작업을 추가합니다.

  • 매개변수:

    • title (string, 필수): 작업 설명. 길이는 1~200자 사이여야 합니다.

    • priority (string, 선택): 긴급도 수준. 허용 값: "low", "medium", "high". 기본값: "medium".

  • 검증 규칙:

    • 빈 문자열 또는 공백만 있는 문자열은 거부됩니다.

    • 200자를 초과하는 제목은 오류를 반환합니다.

    • 규격에 맞지 않는 우선순위 값은 스키마 검증에 실패합니다.

요청 예시:

{
  "title": "Implement integration test suite",
  "priority": "high"
}

응답 예시:

Task added!
  ID:       1
  Title:    Implement integration test suite
  Priority: high
  Status:   pending

2. list_tasks

완료 상태별 선택적 필터링을 통해 저장된 작업을 검색합니다.

  • 설명: 선택적 상태 필터링을 통해 할 일 목록의 작업을 나열합니다.

  • 매개변수:

    • status (string, 선택): 필터 기준. 허용 값: "all", "pending", "done". 기본값: "all".

  • 형식: 작업 ID, 상태 표시, 우선순위 수준, 제목을 요약한 형식화된 ASCII 표를 반환합니다.

요청 예시:

{
  "status": "pending"
}

응답 예시:

Tasks (pending) — 2 found:

  ID  Status    Priority Title
————  ————————— ———————— ————————————————————————————————————————
   1  pending   high     Implement integration test suite
   2  pending   medium   Update project documentation

3. complete_task

고유 정수 식별자로 기존 작업을 완료 상태로 표시합니다.

  • 설명: 숫자 ID로 작업을 완료 상태로 표시합니다.

  • 매개변수:

    • task_id (integer, 필수): 작업에 할당된 고유 숫자 식별자.

  • 동작:

    • 작업 상태를 "done"으로 업데이트합니다.

    • completed_at 필드를 현재 ISO 8601 UTC 타임스탬프로 설정합니다.

    • 멱등성: 작업이 이미 완료된 경우, 도구는 타임스탬프를 손상시키지 않고 클라이언트에 알립니다.

    • ID가 존재하지 않으면, 현재 유효한 ID 목록과 함께 오류 응답이 반환됩니다.

요청 예시:

{
  "task_id": 1
}

응답 예시:

Task 1 completed!
  Title:        Implement integration test suite
  Completed at: 2026-08-20T09:46:17.466797+00:00

도구 요약 표

도구

목적

매개변수

반환 유형

add_task

새 작업 생성

title (str, 필수)priority ("low" | "medium" | "high", 기본값: "medium")

string (확인 세부 정보)

list_tasks

저장된 작업 조회

status ("all" | "pending" | "done", 기본값: "all")

string (형식화된 표)

complete_task

작업을 완료로 표시

task_id (int, 필수)

string (완료 상태 및 타임스탬프)

데이터 모델 및 영속성

작업 레코드는 UTF-8 인코딩 JSON 배열로 직렬화됩니다. 기본적으로 레코드는 현재 작업 디렉터리의 tasks.json에 저장됩니다. 저장소 파일 경로는 TODO_FILE 환경 변수를 통해 사용자 지정할 수 있습니다.

스키마 정의

[
  {
    "id": 1,
    "title": "Implement integration test suite",
    "priority": "high",
    "status": "done",
    "created_at": "2026-08-20T09:46:17.362387+00:00",
    "completed_at": "2026-08-20T09:46:17.466797+00:00"
  },
  {
    "id": 2,
    "title": "Update project documentation",
    "priority": "medium",
    "status": "pending",
    "created_at": "2026-08-20T09:46:17.384689+00:00",
    "completed_at": null
  }
]

필드 사양

  • id (integer): 자동 증가하는 양의 정수 식별자.

  • title (string): 작업 설명 문자열 (1-200자).

  • priority (string): 긴급도 분류 ("low", "medium", "high").

  • status (string): 수명주기 단계 ("pending" 또는 "done").

  • created_at (string): 생성 시 기록된 ISO 8601 형식 UTC 타임스탬프.

  • completed_at (string | null): 완료 시 기록된 ISO 8601 형식 UTC 타임스탬프.

요구 사항

  • Python: 버전 3.10 이상

  • 의존성:

    • mcp[cli]>=1.28,<2

설치 및 설정

1. 저장소 복제

git clone https://github.com/moazhassan751/mcp-todo-server.git
cd mcp-todo-server

2. 가상 환경 생성

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

3. 의존성 설치

pip install -r requirements.txt

실행 모드

표준 실행 (stdio)

프로덕션 또는 MCP 호스트 통합을 위해 서버를 직접 실행합니다:

python server.py

개발자 검사 (MCP Inspector)

MCP Inspector는 도구 테스트, 스키마 검사, 요청 시뮬레이션을 위한 대화형 브라우저 기반 인터페이스를 제공합니다:

mcp dev server.py

인스펙터가 실행되어 로컬 인터페이스 URL(일반적으로 http://localhost:6274)을 제공합니다.

클라이언트 통합 가이드

Todo MCP Server를 선호하는 AI 환경에 연결하려면 클라이언트의 MCP 구성 파일에 서버를 구성하세요.

Claude Desktop

Claude Desktop 구성 파일을 편집하세요:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Cursor

프로젝트 또는 전역 디렉터리의 .cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

Antigravity IDE

작업 공간의 .agents/mcp_config.json에 추가하세요:

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}

테스트 및 검증

저장소에는 포괄적인 자동화 테스트 스크립트가 포함되어 있습니다:

표준 테스트 스위트

기본 도구 호출, 매개변수 검증, 출력 형식을 테스트합니다:

python test_server.py

다중 세션 감사 테스트

별도의 클라이언트 연결을 시뮬레이션하고, 세션 간 서버 프로세스를 재시작하며, 영속적 저장소가 상태를 올바르게 유지하는지 검증합니다:

python audit_test.py

프로젝트 구조

mcp-todo-server/
├── server.py           # Core MCP server definition and tool implementations
├── test_server.py      # Automated stdio protocol unit tests
├── audit_test.py       # Multi-session persistence and edge-case verification
├── requirements.txt    # Package dependencies
├── .gitignore          # Version control ignore definitions
└── README.md           # Technical documentation and integration reference

라이선스

이 프로젝트는 오픈 소스이며 MIT 라이선스 아래에서 제공됩니다.

This server cannot be installed

F
license - not found
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Related MCP Servers

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/moazhassan751/mcp-todo-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server