@doist/todoist-ai 0.1.0

package/dist/tools/tasks-update-one.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+const ArgsSchema = {
+    id: z.string().min(1).describe("The ID of the task to update."),
+    content: z.string().optional().describe("The new content of the task."),
+    description: z
+        .string()
+        .optional()
+        .describe("The new description of the task."),
+    projectId: z
+        .string()
+        .optional()
+        .describe("The new project ID for the task."),
+    sectionId: z
+        .string()
+        .optional()
+        .describe("The new section ID for the task."),
+    parentId: z
+        .string()
+        .optional()
+        .describe("The new parent task ID (for subtasks)."),
+    priority: z
+        .number()
+        .int()
+        .min(1)
+        .max(4)
+        .optional()
+        .describe("The new priority of the task (1-4)."),
+    dueString: z
+        .string()
+        .optional()
+        .describe("The new due date for the task, in natural language (e.g., 'tomorrow at 5pm')."),
+};
+const tasksUpdateOne = {
+    name: "tasks-update-one",
+    description: "Update an existing task with new values.",
+    parameters: ArgsSchema,
+    async execute(args, client) {
+        const { id, ...updateArgs } = args;
+        return await client.updateTask(id, updateArgs);
+    },
+};
+export { tasksUpdateOne };

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@doist/todoist-ai",
+	"version": "0.1.0",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": ["dist", "src", "package.json", "LICENSE.txt", "README.md"],
+	"exports": {
+		".": "./dist/index.js",
+		"./tools": "./dist/tools/index.js"
+	},
+	"license": "MIT",
+	"description": "A collection of tools for Todoist using AI",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/doist/todoist-ai.git"
+	},
+	"keywords": ["todoist", "ai", "tools"],
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1",
+		"build": "rimraf dist && tsc",
+		"dev": "concurrently \"tsc --watch\" \"nodemon --watch dist --ext js --exec 'npx -y @modelcontextprotocol/inspector npx node dist/main.js'\"",
+		"setup": "cp .env.example .env && npm install && npm run build",
+		"type-check": "tsc --noEmit",
+		"biome:sort-imports": "biome check --formatter-enabled=false --linter-enabled=false --organize-imports-enabled=true --write .",
+		"lint:check": "biome lint",
+		"lint:write": "biome lint --write",
+		"format:check": "biome format",
+		"format:write": "biome format --write",
+		"check": "biome check",
+		"check:fix": "biome check --fix --unsafe",
+		"prepare": "husky"
+	},
+	"dependencies": {
+		"@doist/todoist-api-typescript": "^4.0.4",
+		"@modelcontextprotocol/sdk": "^1.11.1",
+		"date-fns": "^4.1.0",
+		"dotenv": "^16.5.0",
+		"zod": "^3.25.7"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.4",
+		"@types/express": "^5.0.2",
+		"@types/morgan": "^1.9.9",
+		"@types/node": "^22.15.17",
+		"concurrently": "^8.2.2",
+		"express": "^4.19.2",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.0.0",
+		"morgan": "^1.10.0",
+		"nodemon": "^3.1.10",
+		"rimraf": "^6.0.1",
+		"typescript": "^5.8.3"
+	},
+	"lint-staged": {
+		"*": [
+			"biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
+		]
+	}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { getMcpServer } from "./mcp-server.js";

package/src/main.ts

@@ -0,0 +1,26 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import dotenv from "dotenv";
+import { getMcpServer } from "./mcp-server.js";
+
+function main() {
+	const todoistApiKey = process.env.TODOIST_API_KEY;
+	if (!todoistApiKey) {
+		throw new Error("TODOIST_API_KEY is not set");
+	}
+
+	const server = getMcpServer({ todoistApiKey });
+	const transport = new StdioServerTransport();
+	server
+		.connect(transport)
+		.then(() => {
+			// We use console.error because standard I/O is being used for the MCP server communication.
+			console.error("Server started");
+		})
+		.catch((error) => {
+			console.error("Error starting the Todoist MCP server:", error);
+			process.exit(1);
+		});
+}
+
+dotenv.config();
+main();

package/src/mcp-helpers.ts

@@ -0,0 +1,76 @@
+import type { TodoistApi } from "@doist/todoist-api-typescript";
+import type {
+	McpServer,
+	ToolCallback,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodTypeAny, z } from "zod";
+import type { TodoistTool } from "./todoist-tool.js";
+
+function textContent(text: string) {
+	return {
+		content: [{ type: "text" as const, text }],
+	};
+}
+
+function jsonContent(data: unknown) {
+	return {
+		content: [
+			{
+				type: "text" as const,
+				mimeType: "application/json",
+				text: JSON.stringify(data, null, 2),
+			},
+		],
+	};
+}
+
+function textOrJsonContent(data: unknown) {
+	return typeof data === "string" ? textContent(data) : jsonContent(data);
+}
+
+function errorContent(error: string) {
+	return {
+		...textContent(error),
+		isError: true,
+	};
+}
+
+/**
+ * Register a Todoist tool in an MCP server.
+ * @param tool - The tool to register.
+ * @param server - The server to register the tool on.
+ * @param client - The Todoist API client to use to execute the tool.
+ */
+function registerTool<Params extends z.ZodRawShape>(
+	tool: TodoistTool<Params>,
+	server: McpServer,
+	client: TodoistApi,
+) {
+	// @ts-ignore I give up
+	const cb: ToolCallback<Params> = async (
+		args: z.objectOutputType<Params, ZodTypeAny>,
+		_context,
+	) => {
+		try {
+			const result = await tool.execute(
+				args as z.infer<z.ZodObject<Params>>,
+				client,
+			);
+			return textOrJsonContent(result);
+		} catch (error) {
+			console.error(`Error executing tool ${tool.name}:`, {
+				args,
+				error,
+			});
+			const message =
+				error instanceof Error
+					? error.message
+					: "An unknown error occurred";
+			return errorContent(message);
+		}
+	};
+
+	server.tool(tool.name, tool.description, tool.parameters, cb);
+}
+
+export { registerTool };

package/src/mcp-server.ts

@@ -0,0 +1,79 @@
+import { TodoistApi } from "@doist/todoist-api-typescript";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTool } from "./mcp-helpers.js";
+
+import { projectsAddOne } from "./tools/projects-add-one.js";
+import { projectsDeleteOne } from "./tools/projects-delete-one.js";
+import { projectsList } from "./tools/projects-list.js";
+import { projectsSearch } from "./tools/projects-search.js";
+import { projectsUpdateOne } from "./tools/projects-update-one.js";
+
+import { sectionsAddOne } from "./tools/sections-add-one.js";
+import { sectionsDeleteOne } from "./tools/sections-delete-one.js";
+import { sectionsSearch } from "./tools/sections-search.js";
+import { sectionsUpdateOne } from "./tools/sections-update-one.js";
+
+import { subtasksListForParentTask } from "./tools/subtasks-list-for-parent-task.js";
+
+import { accountOverview } from "./tools/account-overview.js";
+import { projectOverview } from "./tools/project-overview.js";
+import { tasksAddMultiple } from "./tools/tasks-add-multiple.js";
+import { tasksListByDate } from "./tools/tasks-by-date-range.js";
+import { tasksListForProject } from "./tools/tasks-by-project.js";
+import { tasksCompleteMultiple } from "./tools/tasks-complete-multiple.js";
+import { tasksDeleteOne } from "./tools/tasks-delete-one.js";
+import { tasksListForSection } from "./tools/tasks-list-for-section.js";
+import { tasksListOverdue } from "./tools/tasks-list-overdue.js";
+import { tasksOrganizeMultiple } from "./tools/tasks-organize-multiple.js";
+import { tasksSearch } from "./tools/tasks-search.js";
+import { tasksUpdateOne } from "./tools/tasks-update-one.js";
+
+const instructions = `
+Tools to help you manage your todoist tasks.
+`;
+
+/**
+ * Create the MCP server.
+ * @param todoistApiKey - The API key for the todoist account.
+ * @returns the MCP server.
+ */
+function getMcpServer({ todoistApiKey }: { todoistApiKey: string }) {
+	const server = new McpServer(
+		{ name: "todoist-mcp-server", version: "0.1.0" },
+		{
+			capabilities: {
+				tools: { listChanged: true },
+			},
+			instructions,
+		},
+	);
+
+	const todoist = new TodoistApi(todoistApiKey);
+
+	registerTool(tasksListByDate, server, todoist);
+	registerTool(tasksListOverdue, server, todoist);
+	registerTool(tasksListForProject, server, todoist);
+	registerTool(tasksSearch, server, todoist);
+	registerTool(projectsList, server, todoist);
+	registerTool(tasksAddMultiple, server, todoist);
+	registerTool(tasksUpdateOne, server, todoist);
+	registerTool(tasksDeleteOne, server, todoist);
+	registerTool(tasksCompleteMultiple, server, todoist);
+	registerTool(projectsAddOne, server, todoist);
+	registerTool(projectsUpdateOne, server, todoist);
+	registerTool(sectionsAddOne, server, todoist);
+	registerTool(sectionsUpdateOne, server, todoist);
+	registerTool(tasksOrganizeMultiple, server, todoist);
+	registerTool(subtasksListForParentTask, server, todoist);
+	registerTool(tasksListForSection, server, todoist);
+	registerTool(projectsDeleteOne, server, todoist);
+	registerTool(projectsSearch, server, todoist);
+	registerTool(sectionsDeleteOne, server, todoist);
+	registerTool(sectionsSearch, server, todoist);
+	registerTool(accountOverview, server, todoist);
+	registerTool(projectOverview, server, todoist);
+
+	return server;
+}
+
+export { getMcpServer };

package/src/todoist-tool.ts

@@ -0,0 +1,42 @@
+import type { TodoistApi } from "@doist/todoist-api-typescript";
+import type { z } from "zod";
+
+/**
+ * A Todoist tool that can be used in an MCP server or other conversational AI interfaces.
+ */
+type TodoistTool<Params extends z.ZodRawShape> = {
+	/**
+	 * The name of the tool.
+	 */
+	name: string;
+
+	/**
+	 * The description of the tool. This is important for the LLM to understand what the tool does,
+	 * and how to use it.
+	 */
+	description: string;
+
+	/**
+	 * The schema of the parameters of the tool.
+	 *
+	 * This is used to validate the parameters of the tool, as well as to let the LLM know what the
+	 * parameters are.
+	 */
+	parameters: Params;
+
+	/**
+	 * The function that executes the tool.
+	 *
+	 * This is the main function that will be called when the tool is used.
+	 *
+	 * @param args - The arguments of the tool.
+	 * @param client - The Todoist API client used to make requests to the Todoist API.
+	 * @returns The result of the tool.
+	 */
+	execute: (
+		args: z.infer<z.ZodObject<Params>>,
+		client: TodoistApi,
+	) => Promise<unknown>;
+};
+
+export type { TodoistTool };

package/src/tools/account-overview.ts

@@ -0,0 +1,130 @@
+import type {
+	Project,
+	Section,
+	TodoistApi,
+} from "@doist/todoist-api-typescript";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {};
+
+type ProjectWithChildren = Project & {
+	children: ProjectWithChildren[];
+	childOrder: number;
+};
+
+function buildProjectTree(projects: Project[]): Project[] {
+	// Sort projects by childOrder, then build a tree
+	const byId: Record<string, ProjectWithChildren> = {};
+	for (const p of projects) {
+		byId[p.id] = {
+			...p,
+			children: [],
+			childOrder: (p as { childOrder?: number }).childOrder ?? 0,
+		};
+	}
+	const roots: ProjectWithChildren[] = [];
+	for (const p of projects) {
+		const current = byId[p.id];
+		if (!current) continue;
+		if (p.parentId) {
+			const parent = byId[p.parentId];
+			if (parent) {
+				parent.children.push(current);
+			} else {
+				roots.push(current);
+			}
+		} else {
+			roots.push(current);
+		}
+	}
+	function sortTree(nodes: ProjectWithChildren[]) {
+		nodes.sort((a, b) => a.childOrder - b.childOrder);
+		for (const n of nodes) {
+			sortTree(n.children);
+		}
+	}
+	sortTree(roots);
+	return roots;
+}
+
+async function getSectionsByProject(
+	client: TodoistApi,
+	projectIds: string[],
+): Promise<Record<string, Section[]>> {
+	const result: Record<string, Section[]> = {};
+	await Promise.all(
+		projectIds.map(async (projectId) => {
+			const { results } = await client.getSections({ projectId });
+			result[projectId] = results;
+		}),
+	);
+	return result;
+}
+
+function renderProjectMarkdown(
+	project: ProjectWithChildren,
+	sectionsByProject: Record<string, Section[]>,
+	indent = "",
+): string[] {
+	const lines: string[] = [];
+	lines.push(`${indent}- Project: ${project.name} (id=${project.id})`);
+	const sections = sectionsByProject[project.id] || [];
+	for (const section of sections) {
+		lines.push(`${indent}  - Section: ${section.name} (id=${section.id})`);
+	}
+	for (const child of project.children) {
+		lines.push(
+			...renderProjectMarkdown(child, sectionsByProject, `${indent}  `),
+		);
+	}
+	return lines;
+}
+
+const accountOverview = {
+	name: "account-overview",
+	description:
+		"Get a Markdown overview of all projects (with hierarchy and sections) and the inbox project. Useful in almost any context before engaging with Todoist further.",
+	parameters: ArgsSchema,
+	async execute(_args, client) {
+		const { results: projects } = await client.getProjects({});
+		const inbox = projects.find((p) => p.isInboxProject === true);
+		const nonInbox = projects.filter((p) => p.isInboxProject !== true);
+		const tree = buildProjectTree(nonInbox);
+		const allProjectIds = projects.map((p) => p.id);
+		const sectionsByProject = await getSectionsByProject(
+			client,
+			allProjectIds,
+		);
+
+		const lines: string[] = ["# Personal Projects", ""];
+		if (inbox) {
+			lines.push(`- Inbox Project: ${inbox.name} (id=${inbox.id})`);
+			for (const section of sectionsByProject[inbox.id] || []) {
+				lines.push(`  - Section: ${section.name} (id=${section.id})`);
+			}
+		}
+		if (tree.length) {
+			for (const project of tree as ProjectWithChildren[]) {
+				lines.push(
+					...renderProjectMarkdown(project, sectionsByProject),
+				);
+			}
+		} else {
+			lines.push("_No projects found._");
+		}
+		lines.push("");
+		// Add explanation about nesting if there are nested projects
+		const hasNested = (tree as ProjectWithChildren[]).some(
+			(p) => p.children.length > 0,
+		);
+		if (hasNested) {
+			lines.push(
+				"_Note: Indentation indicates that a project is a sub-project of the one above it. This allows for organizing projects hierarchically, with parent projects containing related sub-projects._",
+				"",
+			);
+		}
+		return lines.join("\n");
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { accountOverview };

package/src/tools/index.ts

@@ -0,0 +1,26 @@
+export { projectsList } from "./projects-list.js";
+export { projectsSearch } from "./projects-search.js";
+export { projectsAddOne } from "./projects-add-one.js";
+export { projectsUpdateOne } from "./projects-update-one.js";
+export { projectsDeleteOne } from "./projects-delete-one.js";
+
+export { sectionsSearch } from "./sections-search.js";
+export { sectionsAddOne } from "./sections-add-one.js";
+export { sectionsUpdateOne } from "./sections-update-one.js";
+export { sectionsDeleteOne } from "./sections-delete-one.js";
+
+export { tasksListByDate } from "./tasks-by-date-range.js";
+export { tasksDeleteOne } from "./tasks-delete-one.js";
+export { tasksCompleteMultiple } from "./tasks-complete-multiple.js";
+export { tasksListForProject } from "./tasks-by-project.js";
+export { tasksListOverdue } from "./tasks-list-overdue.js";
+export { tasksSearch } from "./tasks-search.js";
+export { tasksAddMultiple } from "./tasks-add-multiple.js";
+export { tasksUpdateOne } from "./tasks-update-one.js";
+export { tasksOrganizeMultiple } from "./tasks-organize-multiple.js";
+export { tasksListForSection } from "./tasks-list-for-section.js";
+
+export { subtasksListForParentTask } from "./subtasks-list-for-parent-task.js";
+
+export { accountOverview } from "./account-overview.js";
+export { projectOverview } from "./project-overview.js";

package/src/tools/project-overview.ts

@@ -0,0 +1,130 @@
+import type {
+	Project,
+	Section,
+	TodoistApi,
+} from "@doist/todoist-api-typescript";
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapTask } from "./shared.js";
+
+const ArgsSchema = {
+	projectId: z
+		.string()
+		.min(1)
+		.describe("The ID of the project to get an overview for."),
+};
+
+type MappedTask = ReturnType<typeof mapTask>;
+
+type TaskTreeNode = MappedTask & { children: TaskTreeNode[] };
+
+function buildTaskTree(tasks: MappedTask[]): TaskTreeNode[] {
+	const byId: Record<string, TaskTreeNode> = {};
+	for (const task of tasks) {
+		byId[task.id] = { ...task, children: [] };
+	}
+	const roots: TaskTreeNode[] = [];
+	for (const task of tasks) {
+		const node = byId[task.id];
+		if (!node) continue;
+		if (!task.parentId) {
+			roots.push(node);
+			continue;
+		}
+		const parent = byId[task.parentId];
+		if (parent) {
+			parent.children.push(node);
+		} else {
+			roots.push(node);
+		}
+	}
+	return roots;
+}
+
+function renderTaskTreeMarkdown(tasks: TaskTreeNode[], indent = ""): string[] {
+	const lines: string[] = [];
+	for (const task of tasks) {
+		const idPart = `id=${task.id}`;
+		const duePart = task.dueDate ? `; due=${task.dueDate}` : "";
+		const contentPart = `; content=${task.content}`;
+		lines.push(`${indent}- ${idPart}${duePart}${contentPart}`);
+		if (task.children.length > 0) {
+			lines.push(...renderTaskTreeMarkdown(task.children, `${indent}  `));
+		}
+	}
+	return lines;
+}
+
+async function getAllTasksForProject(
+	client: TodoistApi,
+	projectId: string,
+): Promise<MappedTask[]> {
+	let allTasks: MappedTask[] = [];
+	let cursor: string | undefined = undefined;
+	do {
+		const { results, nextCursor } = await client.getTasks({
+			projectId,
+			limit: 50,
+			cursor: cursor ?? undefined,
+		});
+		allTasks = allTasks.concat(results.map(mapTask));
+		cursor = nextCursor ?? undefined;
+	} while (cursor);
+	return allTasks;
+}
+
+async function getProjectSections(
+	client: TodoistApi,
+	projectId: string,
+): Promise<Section[]> {
+	const { results } = await client.getSections({ projectId });
+	return results;
+}
+
+const projectOverview = {
+	name: "project-overview",
+	description:
+		"Get a Markdown overview of a single project, including its sections and all tasks. Tasks are grouped by section, with tasks not in any section listed first. Each task is listed as '- id=TASKID; due=YYYY-MM-DD; content=TASK CONTENT' (omit due if not present). Subtasks are nested as indented list items.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { projectId } = args;
+		const project: Project = await client.getProject(projectId);
+		const sections = await getProjectSections(client, projectId);
+		const allTasks = await getAllTasksForProject(client, projectId);
+
+		// Group tasks by sectionId
+		const tasksBySection: Record<string, MappedTask[]> = {};
+		for (const section of sections) {
+			tasksBySection[section.id] = [];
+		}
+		const tasksWithoutSection: MappedTask[] = [];
+		for (const task of allTasks) {
+			if (task.sectionId && tasksBySection[task.sectionId]) {
+				// biome-ignore lint/style/noNonNullAssertion: the "if" above ensures that it is defined
+				tasksBySection[task.sectionId]!.push(task);
+			} else {
+				tasksWithoutSection.push(task);
+			}
+		}
+
+		const lines: string[] = [`# ${project.name}`];
+		if (tasksWithoutSection.length > 0) {
+			lines.push("");
+			const tree = buildTaskTree(tasksWithoutSection);
+			lines.push(...renderTaskTreeMarkdown(tree));
+		}
+		for (const section of sections) {
+			lines.push("");
+			lines.push(`## ${section.name}`);
+			const sectionTasks = tasksBySection[section.id];
+			if (!sectionTasks?.length) {
+				continue;
+			}
+			const tree = buildTaskTree(sectionTasks);
+			lines.push(...renderTaskTreeMarkdown(tree));
+		}
+		return lines.join("\n");
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { projectOverview };

package/src/tools/projects-add-one.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapProject } from "./shared.js";
+
+const ArgsSchema = {
+	name: z.string().min(1).describe("The name of the project to add."),
+};
+
+const projectsAddOne = {
+	name: "projects-add-one",
+	description: "Add a new project.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const project = await client.addProject({ name: args.name });
+		return mapProject(project);
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { projectsAddOne };

package/src/tools/projects-delete-one.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	id: z.string().min(1).describe("The ID of the project to delete."),
+};
+
+const projectsDeleteOne = {
+	name: "projects-delete-one",
+	description: "Delete a project by its ID.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		await client.deleteProject(args.id);
+		return { success: true };
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { projectsDeleteOne };