mcp-todoist

Instructions

Implementation Reference

• src/tools/todoist-filters.ts:174-230 (handler)

  Primary handler: parses input, validates requirements, dispatches to action-specific private handlers (list_filters, get_filter, query_filter, create_filter, update_filter, delete_filter), adds metadata, handles errors.
  async execute(input: unknown): Promise<TodoistFiltersOutput> { const startTime = Date.now(); try { // Validate API token before processing request await TokenValidatorSingleton.validateOnce(); // Validate input const validatedInput = TodoistFiltersInputSchema.parse(input); // Validate action-specific required fields this.validateActionRequirements(validatedInput); let result: TodoistFiltersOutput; // Route to appropriate handler based on action switch (validatedInput.action) { case 'list_filters': result = await this.handleListFilters(validatedInput); break; case 'get_filter': result = await this.handleGetFilter(validatedInput); break; case 'query_filter': result = await this.handleQueryFilter(validatedInput); break; case 'create_filter': result = await this.handleCreateFilter(validatedInput); break; case 'update_filter': result = await this.handleUpdateFilter(validatedInput); break; case 'delete_filter': result = await this.handleDeleteFilter(validatedInput); break; default: throw new ValidationError('Invalid action specified'); } // Add operation metadata const operationTime = Date.now() - startTime; const rateLimitStatus = this.apiService.getRateLimitStatus(); result.metadata = { ...result.metadata, operation_time: operationTime, rate_limit_remaining: rateLimitStatus.rest.remaining, rate_limit_reset: new Date( rateLimitStatus.rest.resetTime ).toISOString(), }; return result; } catch (error) { return this.handleError(error, Date.now() - startTime); } }
• src/tools/todoist-filters.ts:16-35 (schema)

  Zod input validation schema defining parameters for all supported actions.
  const TodoistFiltersInputSchema = z.object({ action: z.enum([ 'list_filters', 'get_filter', 'query_filter', 'create_filter', 'update_filter', 'delete_filter', ]), // Filter ID (for get_filter, query_filter, update_filter, delete_filter) filter_id: z.string().optional(), // Create/Update fields name: z.string().optional(), query: z.string().optional(), color: z.string().optional(), is_favorite: z.boolean().optional(), order: z.number().int().optional(), // Query fields lang: z.string().optional(), });
• src/tools/todoist-filters.ts:96-137 (schema)

  MCP tool definition with name, description, and structured inputSchema for protocol compliance.
  static getToolDefinition() { return { name: 'todoist_filters', description: 'Filter management and task querying for Todoist - query existing filters, retrieve tasks within filters, and manage saved filter criteria', inputSchema: { type: 'object' as const, properties: { action: { type: 'string', enum: [ 'list_filters', 'get_filter', 'query_filter', 'create_filter', 'update_filter', 'delete_filter', ], description: 'Action to perform', }, filter_id: { type: 'string', description: 'Filter ID (required for get_filter/query_filter/update_filter/delete_filter)', }, name: { type: 'string', description: 'Filter name' }, query: { type: 'string', description: 'Filter query (Todoist query syntax)', }, color: { type: 'string', description: 'Filter color' }, is_favorite: { type: 'boolean', description: 'Mark as favorite' }, order: { type: 'number', description: 'Filter order' }, lang: { type: 'string', description: 'Language code for query parsing', }, }, required: ['action'], }, }; }
• src/server/impl.ts:59-92 (registration)

  Tool initialization: instantiates TodoistFiltersTool and registers it in server.tools Map as 'todoist_filters' for execution.
  private initializeTools(): void { try { // Create tool instances with shared API configuration const tasksTools = new TodoistTasksTool(this.config); const projectsTool = new TodoistProjectsTool(this.config); const sectionsTool = new TodoistSectionsTool(this.config); const commentsTool = new TodoistCommentsTool(this.config); const filtersTool = new TodoistFiltersTool(this.config); const remindersTool = new TodoistRemindersTool(this.config); const labelsTool = new TodoistLabelsTool(this.config); const bulkTasksTool = new TodoistBulkTasksTool(this.config); // Register tools in the map this.tools.set('todoist_tasks', tasksTools); this.tools.set('todoist_projects', projectsTool); this.tools.set('todoist_sections', sectionsTool); this.tools.set('todoist_comments', commentsTool); this.tools.set('todoist_filters', filtersTool); this.tools.set('todoist_reminders', remindersTool); this.tools.set('todoist_labels', labelsTool); this.tools.set('todoist_bulk_tasks', bulkTasksTool); logger.info('All tools initialized successfully', { toolCount: this.tools.size, tools: Array.from(this.tools.keys()), }); } catch (error) { logger.error('Failed to initialize tools', { error }); throw new McpError( ErrorCode.InternalError, `Failed to initialize tools: ${error instanceof Error ? error.message : 'Unknown error'}` ); } }
• src/server/impl.ts:102-111 (registration)

  Tool listing handler includes TodoistFiltersTool.getToolDefinition() for MCP list_tools request.
  const toolDefinitions = [ TodoistTasksTool.getToolDefinition(), TodoistProjectsTool.getToolDefinition(), TodoistSectionsTool.getToolDefinition(), TodoistCommentsTool.getToolDefinition(), TodoistFiltersTool.getToolDefinition(), TodoistRemindersTool.getToolDefinition(), TodoistLabelsTool.getToolDefinition(), TodoistBulkTasksTool.getToolDefinition(), ];