@kydycode/todoist-mcp-server-ext 0.4.0 → 0.5.0

package/README.md

@@ -15,12 +15,13 @@ A comprehensive MCP (Model Context Protocol) server implementation that provides
 * **Optimized API Usage**: Efficient use of Todoist API, including `getTasksByFilter` for robust search and `moveTasks` for semantic task movement.
 * **Better Response Formatting**: Enhanced task, project, and label formatting for better readability, including project names in search results.
 
-### ✨ **Enhanced Task Management (10 Tools)**
+### ✨ **Enhanced Task Management (11 Tools)**
 * **Direct ID-based Operations**: Efficient task operations using task IDs.
 * **Comprehensive Task Creation**: Support for subtasks, labels, projects, sections, priorities.
 * **Quick Add Integration**: Natural language task creation using Todoist's Quick Add.
 * **Advanced Task Search**: Robust keyword search using Todoist's filter engine (`search: your query`).
 * **Task Movement Capabilities**: Move tasks between projects, sections, or make them subtasks.
+* **Bulk Task Operations**: Move multiple tasks with subtasks in a single operation.
 * **Task State Management**: Complete, reopen, and manage task lifecycle.
 * **Detailed Task Output**: Search and get-task operations return more task details.
 
@@ -46,9 +47,15 @@ A comprehensive MCP (Model Context Protocol) server implementation that provides
 * **Flexible Targeting**: Comments can be attached to either tasks or projects.
 * **Paginated Comment Retrieval**: Efficiently browse through comment threads.
 
-## 🛠️ Available Tools (Total 29)
+### ✅ **Completed Tasks History (1 Tool)** 🆕
+* **Sync API Integration**: Access completed task history via Todoist Sync API.
+* **Flexible Filtering**: Filter by project, date range (since/until).
+* **Pagination Support**: Retrieve large histories with limit/offset.
+* **Rich Metadata**: Shows project/section names, note counts, completion timestamps.
 
-### Task Operations (10 tools)
+## 🛠️ Available Tools (Total 31)
+
+### Task Operations (11 tools)
 | Tool                      | Description                                                                         |
 |---------------------------|-------------------------------------------------------------------------------------|
 | `todoist_create_task`     | Create tasks with full options (subtasks, labels, projects, sections, priorities).  |
@@ -61,6 +68,7 @@ A comprehensive MCP (Model Context Protocol) server implementation that provides
 | `todoist_reopen_task`     | Reopen completed task.                                                              |
 | `todoist_search_tasks`    | Search tasks using Todoist's filter engine (e.g., `search: keyword`).              |
 | `todoist_move_task`       | Move a task to a different project, section, or make it a subtask.                  |
+| `todoist_bulk_move_tasks` | Move multiple tasks with their subtasks to a project, section, or parent task.      |
 
 ### Project Operations (5 tools)
 | Tool                       | Description                                                                   |
@@ -97,6 +105,11 @@ A comprehensive MCP (Model Context Protocol) server implementation that provides
 | `todoist_update_comment`   | Update an existing comment by its ID.                           |
 | `todoist_delete_comment`   | Delete a comment by its ID.                                     |
 
+### Completed Tasks Operations (1 tool) 🆕
+| Tool                           | Description                                                     |
+|--------------------------------|-----------------------------------------------------------------|
+| `todoist_get_completed_tasks`  | Get completed tasks history with filtering by project, date range (since/until), and pagination. Uses Todoist Sync API. |
+
 ## 🚀 Installation & Setup
 
 ### Local Development Setup
@@ -193,6 +206,15 @@ npm install -g @kydycode/todoist-mcp-server-ext@latest
 "Update comment {comment_id} with new content"
 ```
 
+### ✅ Completed Tasks History 🆕
+```
+"Show my completed tasks"
+"Get completed tasks from project {project_id}"
+"Show tasks completed since 2024-01-01"
+"Get completed tasks between 2024-01-01 and 2024-01-31"
+"Show last 50 completed tasks"
+```
+
 ## 🆚 Extended vs Original Comparison
 
 | Feature                     | Original                             | Extended Version (`@kydycode/todoist-mcp-server-ext`) |
@@ -201,11 +223,12 @@ npm install -g @kydycode/todoist-mcp-server-ext@latest
 | **MCP SDK Compatibility**   | Older version                        | ✅ Latest MCP SDK 0.5.0+                              |
 | **Error Handling**          | Basic                                | ✅ Comprehensive with detailed messages               |
 | **TypeScript Support**      | Limited                              | ✅ Full type safety                                   |
-| **Task Operations**         | Search-based, limited features       | ✅ 10 Tools: Direct ID-based, `moveTasks`, robust search, QuickAdd, full CRUD-like ops |
+| **Task Operations**         | Search-based, limited features       | ✅ 11 Tools: Direct ID-based, `moveTasks`, bulk move, robust search, QuickAdd, full CRUD-like ops |
 | **Project Management**      | Limited                              | ✅ 5 Tools: Full CRUD operations, sub-projects, pagination |
 | **Section Management**      | Basic                                | ✅ 4 Tools: Complete section operations               |
 | **Label Management**        | Not Available                        | ✅ 5 Tools: Full CRUD operations, pagination          |
 | **Comment Management**      | Not Available                        | ✅ 5 Tools: Full CRUD operations, attachments, pagination |
+| **Completed Tasks History** | Not Available                        | ✅ 1 Tool: Sync API integration, date filtering, pagination |
 | **API Parameter Handling**  | Inconsistent                         | ✅ Proper parameter validation                          |
 | **Response Formatting**     | Basic                                | ✅ Enhanced readability, more details                 |
 | **Build System**            | Issues                               | ✅ Clean compilation                                  |

package/dist/index.js

@@ -650,10 +650,43 @@ const DELETE_COMMENT_TOOL = {
         required: ["commentId"]
     }
 };
+const GET_COMPLETED_TASKS_TOOL = {
+    name: "todoist_get_completed_tasks",
+    description: "Get completed tasks from Todoist with flexible filtering and pagination support. Uses the Todoist Sync API to retrieve task completion history.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: {
+                type: "string",
+                description: "Filter completed tasks by project ID (optional)"
+            },
+            since: {
+                type: "string",
+                description: "ISO 8601 datetime to get tasks completed after this date (e.g., '2024-01-01T00:00:00Z') (optional)"
+            },
+            until: {
+                type: "string",
+                description: "ISO 8601 datetime to get tasks completed before this date (e.g., '2024-12-31T23:59:59Z') (optional)"
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of completed tasks to return (default: 30, max: 200) (optional)"
+            },
+            offset: {
+                type: "number",
+                description: "Number of completed tasks to skip for pagination (default: 0) (optional)"
+            },
+            annotateNotes: {
+                type: "boolean",
+                description: "Include note details in the response (optional)"
+            }
+        }
+    }
+};
 // Server implementation
 const server = new Server({
     name: "todoist-mcp-server-enhanced",
-    version: "0.2.0",
+    version: "0.5.0",
 }, {
     capabilities: {
         tools: {},
@@ -710,6 +743,58 @@ function formatComment(comment) {
     }
     return commentDetails;
 }
+// Helper function to call Todoist Sync API
+async function callSyncAPI(endpoint, params) {
+    const url = `https://api.todoist.com/sync/v9/${endpoint}`;
+    // Build URL-encoded body
+    const formBody = Object.entries(params)
+        .filter(([_, value]) => value !== undefined && value !== null)
+        .map(([key, value]) => {
+        const encodedKey = encodeURIComponent(key);
+        const encodedValue = encodeURIComponent(typeof value === 'object' ? JSON.stringify(value) : String(value));
+        return `${encodedKey}=${encodedValue}`;
+    })
+        .join('&');
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${TODOIST_API_TOKEN}`,
+            'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: formBody,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Sync API error (${response.status}): ${errorText}`);
+    }
+    return response.json();
+}
+// Helper function to format completed task output
+function formatCompletedTask(task, projectName, sectionName) {
+    let taskDetails = `- Task ID: ${task.task_id}`;
+    taskDetails += `\n  Completion ID: ${task.id}`;
+    taskDetails += `\n  Content: ${task.content}`;
+    taskDetails += `\n  Completed At: ${task.completed_at}`;
+    if (projectName) {
+        taskDetails += `\n  Project: ${projectName} (${task.project_id})`;
+    }
+    else if (task.project_id) {
+        taskDetails += `\n  Project ID: ${task.project_id}`;
+    }
+    if (sectionName) {
+        taskDetails += `\n  Section: ${sectionName} (${task.section_id})`;
+    }
+    else if (task.section_id) {
+        taskDetails += `\n  Section ID: ${task.section_id}`;
+    }
+    if (task.note_count > 0) {
+        taskDetails += `\n  Notes: ${task.note_count}`;
+    }
+    if (task.meta_data) {
+        taskDetails += `\n  Metadata: ${JSON.stringify(task.meta_data)}`;
+    }
+    return taskDetails;
+}
 // Type guards for arguments
 function isCreateTaskArgs(args) {
     return (typeof args === "object" &&
@@ -876,6 +961,32 @@ function isUpdateCommentArgs(args) {
         typeof args.commentId === "string" &&
         typeof args.content === "string");
 }
+function isGetCompletedTasksArgs(args) {
+    if (typeof args !== "object" || args === null) {
+        return false;
+    }
+    const typed = args;
+    // All parameters are optional, so check types only if present
+    if (typed.projectId !== undefined && typeof typed.projectId !== "string") {
+        return false;
+    }
+    if (typed.since !== undefined && typeof typed.since !== "string") {
+        return false;
+    }
+    if (typed.until !== undefined && typeof typed.until !== "string") {
+        return false;
+    }
+    if (typed.limit !== undefined && typeof typed.limit !== "number") {
+        return false;
+    }
+    if (typed.offset !== undefined && typeof typed.offset !== "number") {
+        return false;
+    }
+    if (typed.annotateNotes !== undefined && typeof typed.annotateNotes !== "boolean") {
+        return false;
+    }
+    return true;
+}
 // Tool handlers
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
@@ -914,6 +1025,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         GET_COMMENTS_TOOL,
         UPDATE_COMMENT_TOOL,
         DELETE_COMMENT_TOOL,
+        // Completed tasks tool (Sync API)
+        GET_COMPLETED_TASKS_TOOL,
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1583,6 +1696,71 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: `Error deleting comment: ${error.message}` }], isError: true };
             }
         }
+        if (name === "todoist_get_completed_tasks") {
+            if (!isGetCompletedTasksArgs(args)) {
+                return {
+                    content: [{ type: "text", text: "Invalid arguments for get_completed_tasks" }],
+                    isError: true
+                };
+            }
+            try {
+                // Build Sync API parameters
+                const syncParams = {};
+                if (args.projectId)
+                    syncParams.project_id = args.projectId;
+                if (args.since)
+                    syncParams.since = args.since;
+                if (args.until)
+                    syncParams.until = args.until;
+                if (args.limit !== undefined)
+                    syncParams.limit = Math.min(args.limit, 200);
+                if (args.offset !== undefined)
+                    syncParams.offset = args.offset;
+                if (args.annotateNotes)
+                    syncParams.annotate_notes = true;
+                // Call Sync API
+                const response = await callSyncAPI('completed/get_all', syncParams);
+                if (!response.items || response.items.length === 0) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: "No completed tasks found matching the specified criteria"
+                            }],
+                        isError: false
+                    };
+                }
+                // Format completed tasks with project/section names if available
+                const formattedTasks = response.items.map(task => {
+                    const projectName = response.projects?.[task.project_id]?.name;
+                    const sectionName = response.sections?.[task.section_id || '']?.name;
+                    return formatCompletedTask(task, projectName, sectionName);
+                });
+                const taskList = formattedTasks.join('\n\n');
+                // Build pagination info
+                let paginationInfo = '';
+                if (response.has_more || (args.limit && response.items.length === args.limit)) {
+                    const nextOffset = (args.offset || 0) + response.items.length;
+                    paginationInfo = `\n\nPagination: Showing ${response.items.length} task(s). `;
+                    paginationInfo += `Use offset=${nextOffset} to retrieve the next page.`;
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Completed Tasks (${response.items.length} found):\n\n${taskList}${paginationInfo}`
+                        }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error getting completed tasks: ${error.message}`
+                        }],
+                    isError: true
+                };
+            }
+        }
         return {
             content: [{ type: "text", text: `Unknown tool: ${name}` }],
             isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kydycode/todoist-mcp-server-ext",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Extended MCP server for Todoist API integration with enhanced features and improved compatibility",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",