mcp-todoist

Instructions

Implementation Reference

• src/tools/todoist-labels.ts:201-264 (handler)

  Main handler function that parses input, validates requirements, dispatches to specific action handlers (create/get/update/delete/list/rename_shared/remove_shared), adds metadata, and handles errors.

  async execute(input: unknown): Promise<TodoistLabelsOutput> {
    const startTime = Date.now();
  
    try {
      // Validate API token before processing request
      await TokenValidatorSingleton.validateOnce();
  
      // Validate input
      const validatedInput = TodoistLabelsInputSchema.parse(input);
  
      // Validate action-specific required fields
      this.validateActionRequirements(validatedInput);
  
      let result: TodoistLabelsOutput;
  
      // Route to appropriate handler based on action
      switch (validatedInput.action) {
        case 'create':
          result = await this.handleCreate(validatedInput);
          break;
        case 'get':
          result = await this.handleGet(validatedInput);
          break;
        case 'update':
          result = await this.handleUpdate(validatedInput);
          break;
        case 'delete':
          result = await this.handleDelete(validatedInput);
          break;
        case 'list':
          result = await this.handleList(validatedInput);
          break;
        case 'rename_shared':
          result = await this.handleRenameShared(validatedInput);
          break;
        case 'remove_shared':
          result = await this.handleRemoveShared(validatedInput);
          break;
        default:
          throw new ValidationError('Invalid action specified');
      }
  
      // Add operation metadata
      const operationTime = Date.now() - startTime;
      const rateLimitStatus = this.apiService.getRateLimitStatus();
  
      // Use sync rate limiter stats for shared label operations
      const useSync =
        validatedInput.action === 'rename_shared' ||
        validatedInput.action === 'remove_shared';
      const rateLimit = useSync ? rateLimitStatus.sync : rateLimitStatus.rest;
  
      result.metadata = {
        ...result.metadata,
        operation_time: operationTime,
        rate_limit_remaining: rateLimit.remaining,
        rate_limit_reset: new Date(rateLimit.resetTime).toISOString(),
      };
  
      return result;
    } catch (error) {
      return this.handleError(error, Date.now() - startTime);
    }
  }

• src/tools/todoist-labels.ts:16-39 (schema)

  Zod input validation schema defining all parameters and actions for the todoist_labels tool.

  const TodoistLabelsInputSchema = z.object({
    action: z.enum([
      'create',
      'get',
      'update',
      'delete',
      'list',
      'rename_shared',
      'remove_shared',
    ]),
    // Label ID (for get, update, delete)
    label_id: z.string().optional(),
    // Label name (for create, rename_shared, remove_shared)
    name: z.string().max(128).optional(),
    // New name (for rename_shared)
    new_name: z.string().max(128).optional(),
    // Label properties
    color: z.string().optional(),
    order: z.number().optional(),
    is_favorite: z.boolean().optional(),
    // Pagination (for list)
    cursor: z.string().optional(),
    limit: z.number().min(1).max(200).optional(),
  });

• src/tools/todoist-labels.ts:96-153 (schema)

  Static method providing MCP tool definition including name, description, and JSON input schema.

  static getToolDefinition() {
    return {
      name: 'todoist_labels',
      description:
        'label management for Todoist - create, read, update, delete labels with full CRUD operations',
      inputSchema: {
        type: 'object' as const,
        properties: {
          action: {
            type: 'string',
            enum: [
              'create',
              'get',
              'update',
              'delete',
              'list',
              'rename_shared',
              'remove_shared',
            ],
            description: 'Action to perform on labels',
          },
          label_id: {
            type: 'string',
            description: 'Label ID (required for get, update, delete)',
          },
          name: {
            type: 'string',
            description: 'Label name (required for create, rename_shared)',
          },
          new_name: {
            type: 'string',
            description: 'New label name (required for rename_shared)',
          },
          color: {
            type: 'string',
            description: 'Predefined color ID',
          },
          order: {
            type: 'number',
            description: 'Display order',
          },
          is_favorite: {
            type: 'boolean',
            description: 'Mark as favorite',
          },
          cursor: {
            type: 'string',
            description: 'Pagination cursor (for list action)',
          },
          limit: {
            type: 'number',
            description: 'Page size (for list action, default 50, max 200)',
          },
        },
        required: ['action'],
      },
    };
  }

• src/server/impl.ts:59-92 (registration)

  initializeTools method that instantiates TodoistLabelsTool and registers it in the tools Map with key 'todoist_labels'.

  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)

  Includes TodoistLabelsTool.getToolDefinition() in the list of tool definitions returned for listTools request.

  const toolDefinitions = [
    TodoistTasksTool.getToolDefinition(),
    TodoistProjectsTool.getToolDefinition(),
    TodoistSectionsTool.getToolDefinition(),
    TodoistCommentsTool.getToolDefinition(),
    TodoistFiltersTool.getToolDefinition(),
    TodoistRemindersTool.getToolDefinition(),
    TodoistLabelsTool.getToolDefinition(),
    TodoistBulkTasksTool.getToolDefinition(),
  ];