Todoist MCP Server

Instructions

Implementation Reference

• src/tools/task-operations.ts:307-346 (handler)

  The completeTaskTool object defines the 'complete_task' tool, including its schema and handler function. The handler calls the completeTask service with the task_id argument, handles errors, and returns the result in MCP content format.

  export const completeTaskTool: Tool = {
    schema: {
      name: 'complete_task',
      description: 'Complete a task by its ID',
      inputSchema: {
        type: 'object',
        properties: {
          task_id: {
            type: 'string',
            description: 'The ID of the task to complete',
          },
        },
        required: ['task_id'],
      },
    },
    handler: async (args: { task_id: string }) => {
      try {
        const result = await completeTask(args.task_id);
        return {
          content: [
            {
              type: 'text',
              text: result,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${
                error instanceof Error ? error.message : 'Unknown error'
              }`,
            },
          ],
        };
      }
    },
  };

• src/tools/task-operations.ts:308-321 (schema)

  Input schema for the 'complete_task' tool, defining the required 'task_id' parameter.

  schema: {
    name: 'complete_task',
    description: 'Complete a task by its ID',
    inputSchema: {
      type: 'object',
      properties: {
        task_id: {
          type: 'string',
          description: 'The ID of the task to complete',
        },
      },
      required: ['task_id'],
    },
  },

• src/handlers/tool-request-handler.ts:50-64 (registration)

  Registration of the 'complete_task' handler in the toolsWithArgs map used by handleToolRequest to dispatch tool calls.

  const toolsWithArgs: Record<string, (args: any) => Promise<ToolResponse>> = {
    get_task_comments: getTaskCommentsTool.handler,
    create_project_label: createProjectLabelTool.handler,
    create_task_comment: createTaskCommentTool.handler,
    update_task: updateTaskTool.handler,
    create_task: createTaskTool.handler,
    move_task: moveTaskTool.handler,
    get_tasks_with_label: getTasksWithLabelTool.handler,
    complete_task: completeTaskTool.handler,
    uncomplete_task: uncompleteTaskTool.handler,
    search_tasks: searchTasksTool.handler,
    search_tasks_using_and: searchTasksUsingAndTool.handler,
    search_tasks_using_or: searchTasksUsingOrTool.handler,
    complete_becky_task: completeBeckyTaskTool.handler,
  };

• src/index.ts:98-98 (registration)

  The completeTaskTool.schema is included in the list of tools returned by the MCP ListTools handler.

  completeTaskTool.schema,

• src/services/tasks/task-update.ts:211-227 (helper)

  The core completeTask helper function that performs the actual Todoist API call to close the task, after validation.

  export async function completeTask(taskId: string): Promise<string> {
    const client = getTodoistClient();
  
    try {
      // Check if task is in a Brian shared project
      await throwIfTaskIsFromBecky(taskId);
  
      if (!client.post) {
        throw new Error('POST method not available on client');
      }
  
      await client.post(`/tasks/${taskId}/close`);
      return 'Task completed successfully';
    } catch (error) {
      throw new Error(`Failed to complete task: ${getErrorMessage(error)}`);
    }
  }