todoist-mcp

Instructions

Implementation Reference

• src/tools/projects.ts:92-112 (registration)

  Registration and schema for the 'move_projects' tool. Defines input schema (project id/name and target parent_id), sync command type 'project_move', lookup logic for projects, and command args builder that maps to Todoist sync args {id, parent_id}.
  createSyncApiHandler({ name: 'move_projects', description: 'Move a projects to a different parent in Todoist', itemSchema: { id: z.string().optional().describe('ID of the project to move (preferred over name)'), name: z.string().optional().describe('Name of the project to move'), parent_id: z.string().nullable(), }, commandType: 'project_move', idField: 'id', nameField: 'name', lookupPath: '/projects', findByName: (name, items) => items.find(item => item.name.toLowerCase().includes(name.toLowerCase())), buildCommandArgs: (item, itemId) => { return { id: itemId, parent_id: item.parent_id, }; }, });
• src/utils/handlers.ts:358-506 (handler)

  Handler factory createSyncApiHandler that implements the core logic for 'move_projects': parses batch input, resolves project IDs by name using GET /projects, builds 'project_move' SyncCommand objects using custom buildCommandArgs, validates IDs, executes todoistApi.sync, and formats batched results with success summary.
  export function createSyncApiHandler<T extends z.ZodRawShape>(options: { name: string; description: string; itemSchema: T; commandType: string; // The sync command type (e.g., 'item_move') idField: string; nameField?: string; lookupPath?: string; // Configurable path for lookup findByName?: (name: string, items: any[]) => any | undefined; buildCommandArgs: (item: any, itemId: string) => Record<string, any>; validateItem?: (item: any) => { valid: boolean; error?: string }; // Optional validation }) { // eslint-disable-next-line @typescript-eslint/no-unused-vars const batchSchema = z.object({ items: z.array(z.object(options.itemSchema)), }); const handler = async (args: z.infer<typeof batchSchema>): Promise<any> => { const { items } = args; try { // For name lookup if needed let allItems: any[] = []; const needsNameLookup = options.nameField && options.findByName && items.some(item => item[options.nameField!] && !item[options.idField]); if (needsNameLookup) { if (!options.lookupPath) { throw new Error(`Error: lookupPath must be specified for name-based lookup`); } // Generic lookup path for any resource type allItems = await todoistApi.get(options.lookupPath, {}); } // Build commands array for Sync API const commands: SyncCommand[] = []; const failedItems = []; for (const item of items) { // Optional pre-validation if (options.validateItem) { const validation = options.validateItem(item); if (!validation.valid) { failedItems.push({ success: false, error: validation.error || 'Validation failed', item, }); continue; } } let itemId = item[options.idField]; // Lookup by name if needed if (!itemId && item[options.nameField!] && options.findByName) { const searchName = item[options.nameField!]; const matchedItem = options.findByName(searchName, allItems); if (!matchedItem) { failedItems.push({ success: false, error: `Item not found with name: ${searchName}`, item, }); continue; } itemId = matchedItem.id; } if (!itemId) { failedItems.push({ success: false, error: `Either ${options.idField} or ${options.nameField} must be provided`, item, }); continue; } // Apply security validation to itemId before using in sync commands const safeItemId = validatePathParameter(itemId, options.idField); // Use the provided function to build command args with validated ID const commandArgs = options.buildCommandArgs(item, safeItemId); commands.push({ type: options.commandType, uuid: uuidv4(), args: commandArgs, }); } // If all items failed validation, return early if (failedItems.length === items.length) { return { success: false, summary: { total: items.length, succeeded: 0, failed: items.length, }, results: failedItems, }; } // Execute the sync command if any valid commands exist let syncResult = null; if (commands.length > 0) { syncResult = await todoistApi.sync(commands); } // Combine successful and failed results const successfulResults = commands.map(command => ({ success: true, id: command.args.id, command, })); const results = [...successfulResults, ...failedItems]; return { success: failedItems.length === 0, summary: { total: items.length, succeeded: items.length - failedItems.length, failed: failedItems.length, }, results, sync_result: syncResult, }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error), }; } }; return createHandler( options.name, options.description, { items: z.array(z.object(options.itemSchema)) }, handler ); }
• src/utils/handlers.ts:40-77 (helper)

  Generic createHandler utility that wraps the specific handler function, registers it as an MCP tool via server.tool, handles JSON output formatting, and error catching.
  export function createHandler<T extends z.ZodRawShape>( name: string, description: string, paramsSchema: T, handler: (args: HandlerArgs<T>) => Promise<any> ): void { 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}`, }, ], }; } }; // Crazy cast, if you can do it better, please, let me knows server.tool(name, description, paramsSchema, mcpToolCallback as unknown as ToolCallback<T>); }