create_labels
Create custom labels in Todoist to organize tasks by category, priority, or context for better task management.
Instructions
Create a new personal labels in Todoist
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
Implementation Reference
- src/tools/labels.ts:12-27 (registration)Registration of the 'create_labels' tool using createBatchApiHandler, including input schema for batch creation of Todoist labels.
createBatchApiHandler({ name: 'create_labels', description: 'Create a new personal labels in Todoist', itemSchema: { name: z.string(), order: z.number().int().optional(), color: z .string() .optional() .describe('Refer to the name column in the `utils_get_colors` tool for more info'), is_favorite: z.boolean().optional(), }, method: 'POST', path: '/labels', mode: 'create', }); - src/tools/labels.ts:12-27 (schema)Input schema definition for the 'create_labels' tool: batch of items with name (required), optional order, color, is_favorite.
createBatchApiHandler({ name: 'create_labels', description: 'Create a new personal labels in Todoist', itemSchema: { name: z.string(), order: z.number().int().optional(), color: z .string() .optional() .describe('Refer to the name column in the `utils_get_colors` tool for more info'), is_favorite: z.boolean().optional(), }, method: 'POST', path: '/labels', mode: 'create', }); - src/utils/handlers.ts:150-356 (handler)Core handler logic for batch API operations. For create_labels (mode:'create'), it performs POST requests to Todoist API endpoint '/labels' with batched label data.
export function createBatchApiHandler<T extends z.ZodRawShape>( options: { name: string; description: string; itemSchema: T; method: HttpMethod; mode?: 'read' | 'create' | 'update' | 'delete'; idField?: string; nameField?: string; findByName?: (name: string, items: any[]) => any | undefined; validateItem?: (item: any) => { valid: boolean; error?: string }; } & ( // Or we specify full path | { path: string; basePath?: never; pathSuffix?: never; } // Or we specify base path and path suffix | { path?: never; basePath: string; pathSuffix: string; } ) ) { // Create basic description, we cant properly use 'anyOf' here so for now we will add info to description let finalDescription = options.description; const requiresIdOrName = options.idField && options.nameField && options.mode !== 'create'; if (requiresIdOrName) { const requirementText = `\nEither '${options.idField}' or the '${options.nameField}' to identify the target.`; finalDescription += requirementText; } const itemSchemaObject = z.object(options.itemSchema); const enhancedItemSchema: z.ZodTypeAny = requiresIdOrName ? itemSchemaObject.refine( (data: any) => data[options.idField!] !== undefined || data[options.nameField!] !== undefined, { message: `Either ${options.idField} or ${options.nameField} must be provided`, path: [options.idField!, options.nameField!], } ) : itemSchemaObject; const batchSchema = z.object({ items: z.array(enhancedItemSchema), }); const handler = async (args: z.infer<typeof batchSchema>): Promise<any> => { const { items } = args; // For modes other than create, check if name lookup is needed let allItems: any[] = []; const needsNameLookup = options.mode !== 'create' && options.nameField && options.findByName && items.some(item => item[options.nameField!] && !item[options.idField!]); if (needsNameLookup) { // Determine the base path for fetching all items // Example: /tasks from /tasks/{id} const lookupPath = options.basePath || (options.path ? options.path.split('/{')[0] : ''); allItems = await todoistApi.get(lookupPath, {}); } const results = await Promise.all( items.map(async item => { if (options.validateItem) { const validation = options.validateItem(item); if (!validation.valid) { return { success: false, error: validation.error || 'Validation failed', item, }; } } try { let finalPath = ''; const apiParams = { ...item }; // For modes where need id if (options.mode !== 'create' && options.idField) { let itemId = item[options.idField]; let matchedName = null; let matchedContent = null; // If no ID but name is provided, search by name if (!itemId && item[options.nameField!] && options.findByName) { const searchName = item[options.nameField!]; const matchedItem = options.findByName(searchName, allItems); if (!matchedItem) { return { success: false, error: `Item not found with name: ${searchName}`, item, }; } itemId = matchedItem.id; matchedName = searchName; matchedContent = matchedItem.content; } if (!itemId) { return { success: false, error: `Either ${options.idField} or ${options.nameField} must be provided`, item, }; } // Apply security validation to itemId before using in path const safeItemId = validatePathParameter(itemId, options.idField || 'id'); if (options.basePath && options.pathSuffix) { finalPath = `${options.basePath}${options.pathSuffix.replace('{id}', safeItemId)}`; } else if (options.path) { finalPath = options.path.replace('{id}', safeItemId); } delete apiParams[options.idField]; if (options.nameField) { delete apiParams[options.nameField]; } let result; switch (options.method) { case 'GET': result = await todoistApi.get(finalPath, apiParams); break; case 'POST': result = await todoistApi.post(finalPath, apiParams); break; case 'DELETE': result = await todoistApi.delete(finalPath); break; } const response: any = { success: true, id: itemId, result, }; if (matchedName) { response.found_by_name = matchedName; response.matched_content = matchedContent; } return response; } // Create mode else { finalPath = options.path || options.basePath || ''; let result; switch (options.method) { case 'GET': result = await todoistApi.get(finalPath, apiParams); break; case 'POST': result = await todoistApi.post(finalPath, apiParams); break; case 'DELETE': result = await todoistApi.delete(finalPath); break; } return { success: true, created_item: result, }; } } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error), item, }; } }) ); const successCount = results.filter(r => r.success).length; return { success: successCount === items.length, summary: { total: items.length, succeeded: successCount, failed: items.length - successCount, }, results, }; }; return createHandler(options.name, finalDescription, batchSchema.shape, handler); } - src/utils/handlers.ts:46-73 (helper)Generic MCP tool callback wrapper used by all handlers, including create_labels, which calls the specific handler and formats results or errors.
const mcpToolCallback = async (args: HandlerArgs<T>): Promise<CallToolResult> => { try { const result = await handler(args); return { content: [ { type: 'text', text: JSON.stringify(result ?? null, null, 2).trim(), }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error(`Error in tool ${name}:`, error); return { isError: true, content: [ { type: 'text', text: `Error executing tool '${name}': ${errorMessage}`, }, ], }; } };