AI代理任务管理服务器

用于AI代理的TodoList MCP服务器

该项目提供了一个模型上下文协议（MCP）服务器，旨在作为大型语言模型（LLM）和人工智能代理的强大外部“工作记忆”或“任务管理器”。它不是直接供人类使用的，而是作为一个关键的后端工具，使人工智能能够可靠地执行复杂的多步骤任务。

人工智能的核心问题

LLM在有限的“上下文窗口”内运行。对于需要多个步骤的复杂任务，他们可能会“忘记”最初的计划，失去对进度的跟踪，或者无法有效地管理状态。该工具直接解决了这一限制。

AI代理的核心价值

通过整合 todolist 服务器，AI代理获得：

• 可靠的状态管理它将一个模糊的、对话式的计划转化为一个结构化的、机器可读的状态机。AI被迫跟踪任务状态(pending, in_progress, completed)，确保没有遗漏任何步骤。
• 持久的“工作记忆”：待办事项列表充当外部可靠的内存存储。AI可以卸载其计划和进度，随时通过以下方式查询 todo_read，并保持正轨，不受其上下文窗口的约束。
• 增强执行可靠性：它鼓励系统 read-modify-write 工作流程，迫使人工智能在继续之前有意识地评估其当前状态。这大大减少了错误和与计划的偏差。
• 透明且可审计的工作流程待办事项列表提供了AI动作的清晰、实时的日志。这种透明度对于调试、监控和建立对代理执行能力的信任非常宝贵。
• 智能自动清除：标记所有任务后 completed，列表会自动重置。这标志着整个任务的成功完成，并为新任务的工作空间做好准备，从而创建一个干净、令人满意的任务循环。

AI代理如何使用此工具

AI代理按照一个简单而强大的循环与服务器交互：

1. 计划和初始化：首先，代理将复杂的用户请求分解为一系列可操作的步骤并使用 todo_write 要填充列表，请将所有任务设置为 pending.
2. 阅读（评估状态）：在采取行动之前，代理人会打电话 todo_read 获取所有任务的当前完成状态。
3. 修改（更新状态）：代理识别下一个任务，将其标记为 in_progress，执行该操作，然后将其标记为 completed。整个状态更新是在本地准备的。
4. 写入（提交状态）：代理人打来电话 todo_write 随着 完整更新列表，将新状态原子性地提交给服务器。

这 read-modify-write 循环确保每一个行动都是深思熟虑的，并基于世界的最新状态。

技术细节

特性

• 内存todo存储 具有基于会话的持久性。
• 智能自动清除 功能。
• 任务验证 防止重复ID。
• 优先级 (high, medium, low)以及状态跟踪。
• 符合MCP标准 无缝集成的工具。

提供的MCP工具

todo_read

返回当前待办事项列表。人工智能应该经常使用它来跟踪进度并决定下一步行动。

# No parameters required
# Returns a list of todo items
todos = todo_read()

todo_write

创建或覆盖整个待办事项列表。这是AI更新任务状态的主要机制。

# Expects a list of todo items
todos = [
    {
        "id": "task-1",
        "content": "Implement user authentication",
        "priority": "high",
        "status": "in_progress"
    },
    {
        "id": "task-2", 
        "content": "Write unit tests for authentication",
        "priority": "medium",
        "status": "pending"
    }
]
todo_write(todos)

所有项目结构

每个todo项目都是一本字典 必须 包含：

• id：任务的唯一字符串标识符。
• content：描述任务的非空字符串。
• priority：其中之一 "high", "medium"，或 "low".
• status：其中之一 "pending", "in_progress"，或 "completed".

设置和配置

需求

• Python 3.12+
• 诗歌（推荐）或pip

安装

# Clone the repository
git clone https://github.com/hicaosen/todolist.git
cd todolist

# Install dependencies
poetry install
# or with pip
pip install -e .

运行服务器

# Using the installed script
todolist-mcp-server

# Or directly with Python
python -m src.server

人工智能的MCP客户端配置

要将此服务器连接到启用MCP的AI客户端，请在配置中添加以下内容：

{
  "mcpServers": {
    "todolist": {
      "command": "uvx",
      "args": [
        "todolist-mcp-server"
      ]
    }
  }
}

发展

代码质量工具

# Lint code
ruff check

# Format code
ruff format

# Type checking
pyright

许可证

该项目根据MIT许可证获得许可。