todoist-mcp

Instructions

Implementation Reference

• src/tools/tasks.ts:261-278 (handler)

  Core execution logic of the get_completed_tasks tool: processes input args into params, fetches data via todoistApi.getCompletedTasks, and structures the response.

  async args => {
      const params: Record<string, string> = {};
  
      Object.entries(args).forEach(([key, value]) => {
          if (value !== undefined) {
              params[key] = typeof value === 'number' ? value.toString() : value;
          }
      });
  
      const response = await todoistApi.getCompletedTasks(params);
  
      return {
          completed_tasks: response.items || [],
          projects: response.projects || {},
          sections: response.sections || {},
          total: response.items?.length || 0,
      };
  }

• src/tools/tasks.ts:238-260 (schema)

  Input schema using Zod for validating tool parameters such as project_id, since, until, limit, etc.

  {
      project_id: z.string().optional().describe('Filter by specific project ID'),
      section_id: z.string().optional().describe('Filter by specific section ID'),
      parent_id: z.string().optional().describe('Filter by specific parent task ID'),
      since: z
          .string()
          .optional()
          .describe('Return tasks completed since this date (YYYY-MM-DD format)'),
      until: z
          .string()
          .optional()
          .describe('Return tasks completed until this date (YYYY-MM-DD format)'),
      limit: z
          .number()
          .int()
          .min(1)
          .max(200)
          .optional()
          .default(50)
          .describe('Number of tasks to return (max 200)'),
      offset: z.number().int().min(0).optional().describe('Offset for pagination'),
      annotation_type: z.string().optional().describe('Filter by annotation type'),
  },

• src/tools/tasks.ts:235-279 (registration)

  Registers the get_completed_tasks tool by calling createHandler with name, description, schema, and handler function.

  createHandler(
      'get_completed_tasks',
      'Get completed tasks from Todoist with filtering options',
      {
          project_id: z.string().optional().describe('Filter by specific project ID'),
          section_id: z.string().optional().describe('Filter by specific section ID'),
          parent_id: z.string().optional().describe('Filter by specific parent task ID'),
          since: z
              .string()
              .optional()
              .describe('Return tasks completed since this date (YYYY-MM-DD format)'),
          until: z
              .string()
              .optional()
              .describe('Return tasks completed until this date (YYYY-MM-DD format)'),
          limit: z
              .number()
              .int()
              .min(1)
              .max(200)
              .optional()
              .default(50)
              .describe('Number of tasks to return (max 200)'),
          offset: z.number().int().min(0).optional().describe('Offset for pagination'),
          annotation_type: z.string().optional().describe('Filter by annotation type'),
      },
      async args => {
          const params: Record<string, string> = {};
  
          Object.entries(args).forEach(([key, value]) => {
              if (value !== undefined) {
                  params[key] = typeof value === 'number' ? value.toString() : value;
              }
          });
  
          const response = await todoistApi.getCompletedTasks(params);
  
          return {
              completed_tasks: response.items || [],
              projects: response.projects || {},
              sections: response.sections || {},
              total: response.items?.length || 0,
          };
      }
  );

• src/utils/TodoistClient.ts:138-164 (helper)

  Helper method in TodoistClient that performs the actual API call to retrieve completed tasks using Todoist's sync v9 /completed/get_all endpoint.

  async getCompletedTasks(params: Record<string, string> = {}): Promise<any> {
      const url = `${API_SYNC_BASE_URL}/completed/get_all`;
  
      log(
          `Making completed tasks request to: ${url} with params:`,
          JSON.stringify(params, null, 2)
      );
  
      const formData = new URLSearchParams();
      for (const [key, value] of Object.entries(params)) {
          if (value) {
              formData.append(key, value);
          }
      }
  
      const response = await fetch(url, {
          method: 'POST',
          headers: {
              Authorization: `Bearer ${this.apiToken}`,
              'Content-Type': 'application/x-www-form-urlencoded',
              'X-Request-Id': uuidv4(),
          },
          body: formData.toString(),
      });
  
      return this.handleResponse(response);
  }