add_checklist_item

Instructions

Implementation Reference

• src/index.ts:677-723 (handler)

  The core handler function for the 'add_checklist_item' tool. It validates input, reads current task data, creates a new ChecklistItem, inserts it into the checklist at the specified position or appends it, updates metadata/progress, persists to JSON file, and returns success/error response.

  private async addChecklistItem(args: any): Promise<any> {
    if (!args?.task || !args?.detailed_description) {
      throw new McpError(ErrorCode.InvalidParams, 'Task and detailed description are required');
    }
  
    try {
      const taskData = await this.readTaskData();
      
      // Create the new checklist item
      const newItem: ChecklistItem = {
        task: args.task,
        detailed_description: args.detailed_description,
        context_and_plan: args.context_and_plan,
        done: args.done || false
      };
      
      // Add the item to the checklist at the specified position or at the end
      if (args.position !== undefined && args.position >= 0 && args.position <= taskData.checklist.length) {
        taskData.checklist.splice(args.position, 0, newItem);
      } else {
        taskData.checklist.push(newItem);
      }
      
      // Write the updated task data to the file
      await this.writeTaskData(taskData);
      
      return {
        content: [
          {
            type: 'text',
            text: 'Checklist item added successfully.',
          },
        ],
      };
    } catch (error) {
      console.error('Error adding checklist item:', error);
      return {
        content: [
          {
            type: 'text',
            text: `Error adding checklist item: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:203-233 (schema)

  The input schema definition for the 'add_checklist_item' tool, registered in the ListToolsRequestSchema handler. Defines properties like task, detailed_description (required), context_and_plan, done, position.

  {
    name: 'add_checklist_item',
    description: 'Adds a new item to the checklist.',
    inputSchema: {
      type: 'object',
      properties: {
        task: {
          type: 'string',
          description: 'A short yet comprehensive name for the task'
        },
        detailed_description: {
          type: 'string',
          description: 'A longer description about what we want to achieve with this task'
        },
        context_and_plan: {
          type: 'string',
          description: 'Related information, files the agent should read, and more details from other tasks, as well as a detailed plan for this task'
        },
        done: {
          type: 'boolean',
          description: 'Whether the task is already completed',
          default: false
        },
        position: {
          type: 'number',
          description: 'Optional position to insert the task (0-based index). If not provided, the task will be added at the end.'
        }
      },
      required: ['task', 'detailed_description']
    }
  },

• src/index.ts:430-431 (registration)

  The dispatch case in the CallToolRequestSchema handler that routes calls to 'add_checklist_item' to the addChecklistItem method.

  case 'add_checklist_item':
    return await this.addChecklistItem(request.params.arguments);

• src/index.ts:106-418 (registration)

  The ListToolsRequestSchema handler registers the tool by including it in the tools array with name and schema, making it discoverable by MCP clients.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'initialize_task',
        description: 'Creates a new task with the specified description and optional initial checklist items.',
        inputSchema: {
          type: 'object',
          properties: {
            task_description: {
              type: 'string',
              description: 'A medium-level detailed description about the whole task'
            },
            context_for_all_tasks: {
              type: 'string',
              description: 'Information that all tasks in the checklist should include'
            },
            initial_checklist: {
              type: 'array',
              description: 'Optional initial checklist items',
              items: {
                type: 'object',
                properties: {
                  task: {
                    type: 'string',
                    description: 'A short yet comprehensive name for the task'
                  },
                  detailed_description: {
                    type: 'string',
                    description: 'A longer description about what we want to achieve with this task'
                  },
                  context_and_plan: {
                    type: 'string',
                    description: 'Related information, files the agent should read, and more details from other tasks, as well as a detailed plan for this task'
                  },
                  done: {
                    type: 'boolean',
                    description: 'Whether the task is already completed',
                    default: false
                  }
                },
                required: ['task', 'detailed_description']
              }
            },
            metadata: {
              type: 'object',
              description: 'Optional metadata for the task',
              properties: {
                tags: {
                  type: 'array',
                  items: {
                    type: 'string'
                  },
                  description: 'Tags to categorize the task'
                },
                priority: {
                  type: 'string',
                  enum: ['high', 'medium', 'low'],
                  description: 'Priority level of the task'
                },
                estimated_completion_time: {
                  type: 'string',
                  description: 'Estimated completion time (ISO timestamp or duration)'
                }
              }
            }
          },
          required: ['task_description']
        }
      },
      {
        name: 'update_task_description',
        description: 'Updates the main task description.',
        inputSchema: {
          type: 'object',
          properties: {
            task_description: {
              type: 'string',
              description: 'The new task description'
            }
          },
          required: ['task_description']
        }
      },
      {
        name: 'update_context',
        description: 'Updates the context information for all tasks.',
        inputSchema: {
          type: 'object',
          properties: {
            context_for_all_tasks: {
              type: 'string',
              description: 'The new context information for all tasks'
            }
          },
          required: ['context_for_all_tasks']
        }
      },
      {
        name: 'add_checklist_item',
        description: 'Adds a new item to the checklist.',
        inputSchema: {
          type: 'object',
          properties: {
            task: {
              type: 'string',
              description: 'A short yet comprehensive name for the task'
            },
            detailed_description: {
              type: 'string',
              description: 'A longer description about what we want to achieve with this task'
            },
            context_and_plan: {
              type: 'string',
              description: 'Related information, files the agent should read, and more details from other tasks, as well as a detailed plan for this task'
            },
            done: {
              type: 'boolean',
              description: 'Whether the task is already completed',
              default: false
            },
            position: {
              type: 'number',
              description: 'Optional position to insert the task (0-based index). If not provided, the task will be added at the end.'
            }
          },
          required: ['task', 'detailed_description']
        }
      },
      {
        name: 'update_checklist_item',
        description: 'Updates an existing checklist item.',
        inputSchema: {
          type: 'object',
          properties: {
            index: {
              type: 'number',
              description: 'The index of the checklist item to update (0-based)'
            },
            task: {
              type: 'string',
              description: 'A short yet comprehensive name for the task'
            },
            detailed_description: {
              type: 'string',
              description: 'A longer description about what we want to achieve with this task'
            },
            context_and_plan: {
              type: 'string',
              description: 'Related information, files the agent should read, and more details from other tasks, as well as a detailed plan for this task'
            },
            done: {
              type: 'boolean',
              description: 'Whether the task is completed'
            }
          },
          required: ['index']
        }
      },
      {
        name: 'mark_task_done',
        description: 'Marks a checklist item as done.',
        inputSchema: {
          type: 'object',
          properties: {
            index: {
              type: 'number',
              description: 'The index of the checklist item to mark as done (0-based)'
            }
          },
          required: ['index']
        }
      },
      {
        name: 'mark_task_undone',
        description: 'Marks a checklist item as not done.',
        inputSchema: {
          type: 'object',
          properties: {
            index: {
              type: 'number',
              description: 'The index of the checklist item to mark as not done (0-based)'
            }
          },
          required: ['index']
        }
      },
      {
        name: 'remove_checklist_item',
        description: 'Removes a checklist item.',
        inputSchema: {
          type: 'object',
          properties: {
            index: {
              type: 'number',
              description: 'The index of the checklist item to remove (0-based)'
            }
          },
          required: ['index']
        }
      },
      {
        name: 'reorder_checklist_item',
        description: 'Moves a checklist item to a new position.',
        inputSchema: {
          type: 'object',
          properties: {
            from_index: {
              type: 'number',
              description: 'The current index of the checklist item (0-based)'
            },
            to_index: {
              type: 'number',
              description: 'The new index for the checklist item (0-based)'
            }
          },
          required: ['from_index', 'to_index']
        }
      },
      {
        name: 'add_note',
        description: 'Adds a note to the task.',
        inputSchema: {
          type: 'object',
          properties: {
            content: {
              type: 'string',
              description: 'The content of the note'
            }
          },
          required: ['content']
        }
      },
      {
        name: 'add_resource',
        description: 'Adds a resource to the task.',
        inputSchema: {
          type: 'object',
          properties: {
            name: {
              type: 'string',
              description: 'Name of the resource'
            },
            url: {
              type: 'string',
              description: 'URL or file path of the resource'
            },
            description: {
              type: 'string',
              description: 'Description of the resource'
            }
          },
          required: ['name', 'url']
        }
      },
      {
        name: 'update_metadata',
        description: 'Updates the task metadata.',
        inputSchema: {
          type: 'object',
          properties: {
            tags: {
              type: 'array',
              items: {
                type: 'string'
              },
              description: 'Tags to categorize the task'
            },
            priority: {
              type: 'string',
              enum: ['high', 'medium', 'low'],
              description: 'Priority level of the task'
            },
            estimated_completion_time: {
              type: 'string',
              description: 'Estimated completion time (ISO timestamp or duration)'
            }
          }
        }
      },
      {
        name: 'clear_task',
        description: 'Clears the current task data.',
        inputSchema: {
          type: 'object',
          properties: {},
          required: []
        }
      },
      {
        name: 'get_checklist_summary',
        description: 'Returns a summary of the checklist with completion status.',
        inputSchema: {
          type: 'object',
          properties: {
            include_descriptions: {
              type: 'boolean',
              description: 'Whether to include detailed descriptions in the summary',
              default: false
            }
          }
        }
      },
      {
        name: 'get_current_task_details',
        description: 'Retrieves details of the current task (first uncompleted task) with full context. This is the recommended tool to use when working with tasks.',
        inputSchema: {
          type: 'object',
          properties: {},
          required: []
        }
      }
    ],
  }));

• src/index.ts:31-36 (schema)

  TypeScript interface defining the structure of ChecklistItem used by addChecklistItem.

  interface ChecklistItem {
    done: boolean;
    task: string;
    detailed_description: string;
    context_and_plan?: string;
  }