Aiya Todo MCP

Aiya Todo MCP

用于管理具有代理AI功能的TODO任务的模型上下文协议（MCP）服务器。此包使LLM能够计划、执行和跟踪具有依赖关系、状态管理和自动化工作流的复杂多步骤任务。

安装

npm install aiya-todo-mcp

用法

作为MCP服务器

直接运行服务器：

npx aiya-todo-mcp

或者将其添加到MCP客户端配置中。服务器提供以下工具：

基本待办事项管理：

• createTodo -创建新的待办事项
• listTodos -使用可选筛选列出所有待办事项
• getTodo -按ID获取特定待办事项
• updateTodo -更新todo的属性
• deleteTodo -按ID删除待办事项

验证系统：

• setVerificationMethod -设置todo的验证方法
• updateVerificationStatus -更新验证状态（待定/已验证/失败）
• getTodosNeedingVerification -获取需要验证的待办事项

代理AI工具：

• createTaskGroup -为复杂的工作流创建具有依赖关系的协调任务组
• getExecutableTasks -根据依赖关系满意度查找准备执行的任务
• updateExecutionStatus -通过验证和自动完成来管理执行状态
• getTaskGroupStatus -获取任务组的执行状态摘要
• resetTaskExecution -使用可选的依赖任务重置功能重置失败的任务

代理AI能力

具有依赖关系的任务组

// Create a multi-step project with dependencies
await createTaskGroup({
  mainTask: {
    title: "Deploy Web Application",
    description: "Complete deployment pipeline"
  },
  subtasks: [
    { title: "Run tests", dependencies: [] },
    { title: "Build application", dependencies: [0] }, // depends on tests
    { title: "Deploy to staging", dependencies: [1] },
    { title: "Run smoke tests", dependencies: [2] },
    { title: "Deploy to production", dependencies: [3] }
  ]
});

执行跟踪

// Get tasks ready to execute
const readyTasks = await getExecutableTasks({ groupId: "deploy-123" });

// Update execution status with state transitions
await updateExecutionStatus({
  todoId: "task-456",
  state: "running"
});

// Handle failures with retry logic
await updateExecutionStatus({
  todoId: "task-456", 
  state: "failed",
  error: "Connection timeout"
});

// Retry failed task (automatically increments attempt count)
await updateExecutionStatus({
  todoId: "task-456",
  state: "pending" // Will retry with attempt count++
});

自动工作流完成

• 当所有子任务完成时，主要任务会自动完成
• 依赖链自动解析
• 失败的任务可以通过尝试跟踪重试
• 线程安全并发执行支持

作为图书馆

在您自己的项目中导入和使用todo管理功能：

import { createTodoManager, Todo } from 'aiya-todo-mcp';

// Create a todo manager with custom file path
const todoManager = createTodoManager('./my-todos.json');

// Initialize (loads existing todos from file)
await todoManager.initialize();

// Create a new todo with execution tracking
const todo = await todoManager.createTodo({ 
  title: 'Process data pipeline',
  executionConfig: {
    toolsRequired: ['dataProcessor', 'validator'],
    retryOnFailure: true
  }
});

// Create task with dependencies
const dependentTask = await todoManager.createTodo({
  title: 'Generate report',
  dependencies: [todo.id], // Depends on data pipeline
  executionStatus: { state: 'pending' }
});

// Get ready tasks (respects dependencies)
const readyTasks = todoManager.getReadyTasks();
console.log(`${readyTasks.length} tasks ready for execution`);

高级用法

要获得更多控制，请使用各个类：

import { TodoManager, TodoPersistence } from 'aiya-todo-mcp';

// Custom persistence layer
const persistence = new TodoPersistence('./custom-path.json');
const manager = new TodoManager(persistence);

await manager.initialize();

// Use validation schemas
import { 
  CreateTodoSchema, 
  SetVerificationMethodSchema,
  UpdateVerificationStatusSchema 
} from 'aiya-todo-mcp';

const result = CreateTodoSchema.parse({ 
  title: 'Valid todo',
  verificationMethod: 'manual-check'
});
const todo = await manager.createTodo(result);

// Set verification method for existing todo
const verificationResult = SetVerificationMethodSchema.parse({
  todoId: todo.id,
  method: 'automated-test',
  notes: 'Run unit tests'
});
await manager.setVerificationMethod(verificationResult);

// Update verification status
const statusUpdate = UpdateVerificationStatusSchema.parse({
  todoId: todo.id,
  status: 'verified',
  notes: 'Tests passed successfully'
});
await manager.updateVerificationStatus(statusUpdate);

api参考

类型

interface Todo {
  id: string;
  title: string;
  description?: string;
  completed: boolean;
  createdAt: Date;
  tags?: string[];
  groupId?: string;
  
  // Verification system
  verificationMethod?: string;
  verificationStatus?: 'pending' | 'verified' | 'failed';
  verificationNotes?: string;
  
  // Agentic AI capabilities
  dependencies?: string[];              // Task dependencies by ID
  executionOrder?: number;              // Order within group (0 = main task)
  executionConfig?: {                   // Configuration for execution
    toolsRequired?: string[];           // MCP tools needed
    params?: Record;       // Parameters for execution
    retryOnFailure?: boolean;           // Whether to retry (default: true)
  };
  executionStatus?: {                   // Current execution state
    state: 'pending' | 'ready' | 'running' | 'completed' | 'failed';
    lastError?: string;                 // Error message if failed
    attempts?: number;                  // Number of execution attempts
  };
}

interface CreateTodoRequest {
  title: string;
  description?: string;
  tags?: string[];
  groupId?: string;
  verificationMethod?: string;
}

interface UpdateTodoRequest {
  id: string;
  title?: string;
  description?: string;
  completed?: boolean;
  tags?: string[];
  groupId?: string;
  verificationMethod?: string;
  verificationStatus?: 'pending' | 'verified' | 'failed';
  verificationNotes?: string;
}

类

TodoManager

基本操作：

• initialize() -从持久性加载待办事项
• createTodo(request) -创建新待办事项
• getTodo(id) -按ID获取待办事项
• getAllTodos() -全部获得
• listTodos(request) -列出带有过滤功能的待办事项
• updateTodo(request) -更新待办事项
• deleteTodo(request) -删除待办事项

验证系统：

• setVerificationMethod(request) -设置todo的验证方法
• updateVerificationStatus(request) -更新验证状态
• getTodosNeedingVerification(request) -获取需要验证的待办事项

代理AI方法：

• getReadyTasks(groupId?) -根据依赖关系为执行任务做好准备

ExecutionStateManager

• updateExecutionStatus(todo, request, updateFn) -使用验证更新执行状态
• checkAndCompleteMainTask(groupId, getAllTodos, updateTodo) -自动完成主要任务
• getGroupExecutionStats(groupId, getAllTodos) -获取执行统计数据
• resetFailedTask(todoId, resetDependents, getAllTodos, updateTodo) -重置失败的任务

DependencyResolver

• isTaskReady(todo, allTodos) -检查是否满足任务依赖关系
• getReadyTasks(todos) -筛选已准备好执行的任务
• detectCircularDependencies(todos) -检测循环依赖链
• validateDependencies(todoId, dependencies, allTodos) -验证依赖关系ID

TodoPersistence

• saveTodos(todos, nextId) -将待办事项保存到文件
• loadTodos() -从文件加载待办事项

验证模式

用于请求验证的Zod模式：

基本操作：

• CreateTodoSchema -验证todo创建请求
• UpdateTodoSchema -验证todo更新请求
• DeleteTodoSchema -验证todo删除请求
• GetTodoSchema -验证待办事项请求
• ListTodosSchema -验证待办事项列表请求

验证系统：

• SetVerificationMethodSchema -验证验证方法请求
• UpdateVerificationStatusSchema -验证验证状态更新
• GetTodosNeedingVerificationSchema -验证验证查询

代理AI工具：

• CreateTaskGroupSchema -验证任务组创建
• GetExecutableTasksSchema -验证可执行任务查询
• UpdateExecutionStatusSchema -验证执行状态更新

主要特点

专为LLM任务规划和执行而构建，具有依赖关系管理和状态跟踪功能。任务可以组织成具有依赖关系的组，以正确的顺序自动执行，并在失败时重试。当所有子任务完成时，主要任务会自动完成。

故障排除

常见问题

处于“待定”状态的任务：

• 使用检查是否满足依赖关系 getExecutableTasks
• 验证依赖关系ID是否存在且有效
• 在任务链中查找循环依赖关系

执行状态更新失败：

• 确保有效的状态转换：待定→ 准备→ 跑步→ 已完成/失败
• 使用“挂起”状态重试失败的任务
• 检查同一任务的并发状态更新

主任务未自动完成：

• 验证所有子任务是否具有 executionStatus.state: "completed"
• 检查子任务是否共享相同的任务 groupId 作为主要任务
• 确保主要任务 executionOrder: 0

大型任务组的内存使用情况：

• 使用 limit 参数在 getExecutableTasks 用于批量处理
• 考虑将非常大的组（1000多个任务）分成更小的组
• 监控依赖关系图的复杂性，以避免性能问题

更新日志

v0.4.0-增强型代理工具

• 新: getTaskGroupStatus 工具-获取任务组的执行状态摘要
• 新: resetTaskExecution 工具-使用可选的依赖重置功能重置失败的任务
• 增强：具有组统计和重置功能的ExecutionStateManager
• 添加：更多的执行监控和恢复工具
• 改进的：更好的错误处理和状态转换验证

v0.3.0-完全代理AI功能

• 新：具有依赖关系管理和执行跟踪的代理人工智能系统
• 新: createTaskGroup 工具-创建具有依赖关系的协调任务工作流
• 新: getExecutableTasks 工具-根据依赖关系查找准备执行的任务
• 新: updateExecutionStatus 工具-通过验证管理执行状态
• 新: ExecutionStateManager 类-状态转换和自动完成
• 新: DependencyResolver 类-依赖验证和循环检测
• 增强：Todo模型，带有执行配置、状态和依赖关系字段
• 添加：当所有子任务完成时，自动完成主任务
• 添加：带有尝试计数和错误跟踪的重试逻辑
• 添加：线程安全（？）并发执行状态更新

v0.2.1

• 添加：带有验证元数据的todos验证系统
• 添加：新的MCP工具： setVerificationMethod, updateVerificationStatus, getTodosNeedingVerification
• 增强：Todo模型，带有验证字段（方法、状态、注释）
• 添加：用于验证操作的扩展验证模式
• 添加：验证功能的全面测试覆盖率

v0.1.1

• 固定的：并发todo操作中的竞争条件可能导致数据丢失和ID冲突
• 改进的：添加了写队列机制来序列化文件保存操作

许可证

麻省理工学院