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）中，确保任务数据在服务器重启、客户端重连以及多轮代理会话后依然保留。通信遵循 MCP 规范，通过标准输入/输出（stdio）使用 JSON-RPC 2.0。

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"。

  • 格式： 返回一个格式化的 ASCII 表格，汇总任务 ID、状态指示符、优先级和标题。

示例请求：

{
  "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