add_todo_task
Add new tasks to an existing TODO list with full markdown support, code examples, and logical sequencing. Use to expand, clarify, or append tasks in project workflows on the Knowledge MCP Server.
Instructions
Add a new task to an existing TODO list with full markdown support.
When to use this tool:
Expanding existing TODO with new tasks
Adding discovered subtasks during work
Including additional requirements
Appending follow-up tasks
Adding clarifications or details
Key features:
Full markdown support in content
Can include code blocks and examples
Auto-incrementing task numbers
Preserves existing task order
Rich formatting capabilities
You should:
Verify TODO exists first
Use clear, actionable task titles (max 200 chars)
Include implementation details in content
Add code examples where helpful
Position task logically in sequence
Keep task scope focused
Use markdown formatting effectively
DO NOT use when:
TODO doesn't exist
Task duplicates existing one
Task is too vague or broad
Returns: {success: bool, task_number: int, message: str, error?: str}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | Full markdown content with implementation details, code examples, etc. | |
| project_id | Yes | The project identifier | |
| title | Yes | Brief task title (max 200 chars, used in filename) | |
| todo_number | Yes | The TODO list number |
Implementation Reference
- Executes the 'add_todo_task' tool logic: validates input, ensures project and TODO exist, generates next task number and filename, creates markdown task file with YAML frontmatter metadata (created/updated timestamps, incomplete status), title header, and optional content, auto-commits changes to git storage.async addTodoTaskAsync(params: { project_id: z.infer<typeof secureProjectIdSchema>; todo_number: z.infer<typeof secureTodoNumberSchema>; title: z.infer<typeof secureTaskTitleSchema>; content?: z.infer<typeof secureTaskContentSchema>; }): Promise<string> { const context = this.createContext('add_todo_task', params); try { const { project_id, todo_number, title, content = '' } = params; const [, projectPath] = await createProjectEntryAsync(this.storagePath, project_id); const todoDir = join(projectPath, 'TODO', todo_number.toString()); // Check if TODO exists try { await access(todoDir); } catch { throw new MCPError(MCPErrorCode.TODO_NOT_FOUND, `TODO #${todo_number} not found`, { project_id, todo_number, traceId: context.traceId, }); } // Get next task number const taskNumber = await this.getNextTaskNumberAsync(todoDir); const taskFilename = `TASK-${taskNumber.toString().padStart(3, '0')}-${slugify(title, { lower: true, strict: true })}.md`; // Create task metadata const metadata: TaskMetadata = { completed: false, created: new Date().toISOString(), updated: new Date().toISOString(), }; // Write task file const frontmatter = yaml.dump(metadata); const taskContent = `---\n${frontmatter}---\n\n# ${title}\n\n${content || ''}`; await writeFile(join(todoDir, taskFilename), taskContent); // Auto-commit await autoCommitAsync(this.storagePath, `Add task "${title}" to TODO #${todo_number}`); this.logSuccess( 'add_todo_task', { project_id, todo_number, task_number: taskNumber }, context ); return this.formatSuccessResponse({ task_number: taskNumber, message: `Added task #${taskNumber} to TODO #${todo_number}`, }); } catch (error) { const mcpError = error instanceof MCPError ? error : new MCPError( MCPErrorCode.FILE_SYSTEM_ERROR, `Failed to add task: ${error instanceof Error ? error.message : String(error)}`, { project_id: params.project_id, todo_number: params.todo_number, traceId: context.traceId, } ); this.logError('add_todo_task', params, mcpError, context); return this.formatErrorResponse(mcpError, context); } }
- src/knowledge-mcp/server.ts:661-685 (registration)Registers the MCP tool 'add_todo_task' with input schema validation, human-readable title and detailed description, delegating execution to TodoToolHandler.addTodoTaskAsync method and formatting response as MCP content.'add_todo_task', { title: 'Add TODO Task', description: TOOL_DESCRIPTIONS.add_todo_task, inputSchema: { project_id: secureProjectIdSchema.describe('The project identifier'), todo_number: secureTodoNumberSchema.describe('The TODO list number'), title: secureTaskTitleSchema.describe('Brief task title (max 200 chars, used in filename)'), content: secureTaskContentSchema.describe( 'Full markdown content with implementation details, code examples, etc.' ), }, }, async (params) => { const result = await todoHandler.addTodoTaskAsync(params); return { content: [ { type: 'text', text: result, }, ], }; } );
- Zod schemas for input validation specific to TODO tasks: secureTodoNumberSchema (positive integer), secureTaskTitleSchema (1-200 chars, trimmed, no null bytes), secureTaskContentSchema (optional up to 100KB markdown, no null bytes). Used in tool inputSchema and method signatures.export const secureTodoNumberSchema = z .number() .int('TODO number must be an integer') .positive('TODO number must be positive') .max(99999, 'TODO number too large'); export const secureTodoDescriptionSchema = z .string() .min(1, 'TODO description cannot be empty') .max(500, 'TODO description too long (max 500 characters)') .refine((val) => !val.includes('\0'), 'TODO description cannot contain null bytes') .refine((val) => val.trim() === val, 'TODO description cannot have leading/trailing spaces'); // Task title for brief identification (used in filenames) export const secureTaskTitleSchema = z .string() .min(1, 'Task title cannot be empty') .max(200, 'Task title too long (max 200 characters)') .refine((val) => !val.includes('\0'), 'Task title cannot contain null bytes') .refine((val) => val.trim() === val, 'Task title cannot have leading/trailing spaces'); // Full markdown content for task details export const secureTaskContentSchema = z .string() .max(100 * 1024, 'Task content too large (max 100KB)') .refine((val) => !val.includes('\0'), 'Task content cannot contain null bytes') .optional();