@kydycode/todoist-mcp-server-ext 0.3.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.
 
@@ -40,9 +41,21 @@ A comprehensive MCP (Model Context Protocol) server implementation that provides
 * **Label Customization**: Set names, colors, favorites, order.
 * **Paginated Label Listing**: Efficiently retrieve all labels.
 
-## 🛠️ Available Tools (Total 24)
+### 💬 **Comment Management (5 Tools)**
+* **Complete Comment CRUD**: Create, read, update, delete comments on tasks and projects.
+* **Attachment Support**: Add file attachments to comments with metadata.
+* **Flexible Targeting**: Comments can be attached to either tasks or projects.
+* **Paginated Comment Retrieval**: Efficiently browse through comment threads.
 
-### Task Operations (10 tools)
+### ✅ **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.
+
+## 🛠️ Available Tools (Total 31)
+
+### Task Operations (11 tools)
 | Tool                      | Description                                                                         |
 |---------------------------|-------------------------------------------------------------------------------------|
 | `todoist_create_task`     | Create tasks with full options (subtasks, labels, projects, sections, priorities).  |
@@ -55,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                                                                   |
@@ -82,6 +96,20 @@ A comprehensive MCP (Model Context Protocol) server implementation that provides
 | `todoist_update_label`   | Update an existing label by its ID (name, color, favorite, order). |
 | `todoist_delete_label`   | Delete a label by its ID.                                          |
 
+### Comment Operations (5 tools)
+| Tool                       | Description                                                     |
+|----------------------------|-----------------------------------------------------------------|
+| `todoist_create_comment`   | Create a new comment on a task or project (with attachments).   |
+| `todoist_get_comment`      | Get a specific comment by its ID.                               |
+| `todoist_get_comments`     | Get comments for a task or project with pagination support.     |
+| `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
@@ -166,13 +194,25 @@ npm install -g @kydycode/todoist-mcp-server-ext@latest
 "Search tasks: search: API deployment"
 ```
 
-### 🗂️ Project, Section, and Label Management
+### 🗂️ Project, Section, Label, and Comment Management
 ```
 "List all my projects"
 "Create project 'Q2 Planning' color:blue favorite:true view:board"
 "Get sections for project {project_id}"
 "Create label 'HighPriority' color:red isFavorite:true"
 "List all labels"
+"Add comment 'Great progress on this task!' to task {task_id}"
+"Get all comments for project {project_id}"
+"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
@@ -183,10 +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

@@ -546,10 +546,147 @@ const SEARCH_TASKS_TOOL = {
         required: ["query"]
     }
 };
+// Comment Management Tools
+const CREATE_COMMENT_TOOL = {
+    name: "todoist_create_comment",
+    description: "Create a new comment on a task or project",
+    inputSchema: {
+        type: "object",
+        properties: {
+            content: {
+                type: "string",
+                description: "The content/text of the comment"
+            },
+            taskId: {
+                type: "string",
+                description: "Task ID to add comment to (provide either taskId or projectId, not both)"
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID to add comment to (provide either taskId or projectId, not both)"
+            },
+            attachment: {
+                type: "object",
+                description: "Optional file attachment (optional)",
+                properties: {
+                    fileName: { type: "string" },
+                    fileType: { type: "string" },
+                    fileUrl: { type: "string" },
+                    resourceType: { type: "string" }
+                }
+            }
+        },
+        required: ["content"]
+    }
+};
+const GET_COMMENT_TOOL = {
+    name: "todoist_get_comment",
+    description: "Get a specific comment by its ID",
+    inputSchema: {
+        type: "object",
+        properties: {
+            commentId: {
+                type: "string",
+                description: "The ID of the comment to retrieve"
+            }
+        },
+        required: ["commentId"]
+    }
+};
+const GET_COMMENTS_TOOL = {
+    name: "todoist_get_comments",
+    description: "Get comments for a task or project with pagination support",
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "Task ID to get comments for (provide either taskId or projectId, not both)"
+            },
+            projectId: {
+                type: "string",
+                description: "Project ID to get comments for (provide either taskId or projectId, not both)"
+            },
+            cursor: {
+                type: "string",
+                description: "Pagination cursor for next page (optional)"
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of comments to return (optional)"
+            }
+        }
+    }
+};
+const UPDATE_COMMENT_TOOL = {
+    name: "todoist_update_comment",
+    description: "Update an existing comment by its ID",
+    inputSchema: {
+        type: "object",
+        properties: {
+            commentId: {
+                type: "string",
+                description: "The ID of the comment to update"
+            },
+            content: {
+                type: "string",
+                description: "New content/text for the comment"
+            }
+        },
+        required: ["commentId", "content"]
+    }
+};
+const DELETE_COMMENT_TOOL = {
+    name: "todoist_delete_comment",
+    description: "Delete a comment by its ID",
+    inputSchema: {
+        type: "object",
+        properties: {
+            commentId: {
+                type: "string",
+                description: "The ID of the comment to delete"
+            }
+        },
+        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: {},
@@ -590,6 +727,74 @@ function formatProject(project) {
 function formatLabel(label) {
     return `- ${label.name} (ID: ${label.id})${label.color ? `\n  Color: ${label.color}` : ''}${label.isFavorite ? `\n  Favorite: Yes` : ''}${label.order ? `\n  Order: ${label.order}` : ''}`;
 }
+// Helper function to format comment output
+function formatComment(comment) {
+    let commentDetails = `- ID: ${comment.id}\n  Content: ${comment.content}`;
+    if (comment.postedAt)
+        commentDetails += `\n  Posted At: ${comment.postedAt}`;
+    if (comment.taskId)
+        commentDetails += `\n  Task ID: ${comment.taskId}`;
+    if (comment.projectId)
+        commentDetails += `\n  Project ID: ${comment.projectId}`;
+    if (comment.attachment) {
+        commentDetails += `\n  Attachment: ${comment.attachment.fileName || 'File'} (${comment.attachment.fileType})`;
+        if (comment.attachment.fileUrl)
+            commentDetails += `\n  File URL: ${comment.attachment.fileUrl}`;
+    }
+    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" &&
@@ -720,6 +925,68 @@ function isUpdateLabelArgs(args) {
         "labelId" in args &&
         typeof args.labelId === "string");
 }
+function isCreateCommentArgs(args) {
+    if (typeof args !== "object" || args === null || !("content" in args) || typeof args.content !== "string") {
+        return false;
+    }
+    const { taskId, projectId } = args;
+    const targets = [taskId, projectId];
+    const providedTargets = targets.filter(target => target !== undefined && target !== null && String(target).trim() !== '');
+    // Exactly one target must be provided and be a non-empty string
+    return providedTargets.length === 1 &&
+        providedTargets.every(target => typeof target === 'string');
+}
+function isCommentIdArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "commentId" in args &&
+        typeof args.commentId === "string");
+}
+function isCommentsArgs(args) {
+    if (typeof args !== "object" || args === null) {
+        return false;
+    }
+    const { taskId, projectId } = args;
+    const targets = [taskId, projectId];
+    const providedTargets = targets.filter(target => target !== undefined && target !== null && String(target).trim() !== '');
+    // Exactly one target must be provided and be a non-empty string, or no targets (for all comments)
+    return providedTargets.length <= 1 &&
+        providedTargets.every(target => typeof target === 'string');
+}
+function isUpdateCommentArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "commentId" in args &&
+        "content" in 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: [
@@ -752,6 +1019,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         GET_LABELS_TOOL,
         UPDATE_LABEL_TOOL,
         DELETE_LABEL_TOOL,
+        // Comment tools
+        CREATE_COMMENT_TOOL,
+        GET_COMMENT_TOOL,
+        GET_COMMENTS_TOOL,
+        UPDATE_COMMENT_TOOL,
+        DELETE_COMMENT_TOOL,
+        // Completed tasks tool (Sync API)
+        GET_COMPLETED_TASKS_TOOL,
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1323,6 +1598,169 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: `Error in bulk moving tasks: ${error.message}` }], isError: true };
             }
         }
+        // Comment operations
+        if (name === "todoist_create_comment") {
+            if (!isCreateCommentArgs(args)) {
+                return { content: [{ type: "text", text: "Invalid arguments for create_comment" }], isError: true };
+            }
+            try {
+                const commentData = { content: args.content };
+                if (args.taskId)
+                    commentData.taskId = args.taskId;
+                if (args.projectId)
+                    commentData.projectId = args.projectId;
+                if (args.attachment)
+                    commentData.attachment = args.attachment;
+                const comment = await todoistClient.addComment(commentData);
+                return {
+                    content: [{ type: "text", text: `Comment created:\n${formatComment(comment)}` }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error creating comment: ${error.message}` }], isError: true };
+            }
+        }
+        if (name === "todoist_get_comment") {
+            if (!isCommentIdArgs(args)) {
+                return { content: [{ type: "text", text: "Invalid arguments for get_comment" }], isError: true };
+            }
+            try {
+                const comment = await todoistClient.getComment(args.commentId);
+                return {
+                    content: [{ type: "text", text: `Comment details:\n${formatComment(comment)}` }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error getting comment: ${error.message}` }], isError: true };
+            }
+        }
+        if (name === "todoist_get_comments") {
+            if (!isCommentsArgs(args)) {
+                return { content: [{ type: "text", text: "Invalid arguments for get_comments. Provide either taskId or projectId, not both." }], isError: true };
+            }
+            try {
+                const params = {};
+                if (args.taskId)
+                    params.taskId = args.taskId;
+                if (args.projectId)
+                    params.projectId = args.projectId;
+                if (args.cursor)
+                    params.cursor = args.cursor;
+                if (args.limit)
+                    params.limit = args.limit;
+                const commentsResponse = await todoistClient.getComments(params);
+                const commentList = commentsResponse.results?.map(formatComment).join('\n\n') || 'No comments found';
+                const nextCursor = commentsResponse.nextCursor ? `\n\nNext cursor for more comments: ${commentsResponse.nextCursor}` : '';
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Comments:\n${commentList}${nextCursor}`
+                        }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error getting comments: ${error.message}` }], isError: true };
+            }
+        }
+        if (name === "todoist_update_comment") {
+            if (!isUpdateCommentArgs(args)) {
+                return { content: [{ type: "text", text: "Invalid arguments for update_comment" }], isError: true };
+            }
+            try {
+                const { commentId, ...updateArgs } = args;
+                const updatedComment = await todoistClient.updateComment(commentId, updateArgs);
+                return {
+                    content: [{ type: "text", text: `Comment updated:\n${formatComment(updatedComment)}` }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error updating comment: ${error.message}` }], isError: true };
+            }
+        }
+        if (name === "todoist_delete_comment") {
+            if (!isCommentIdArgs(args)) {
+                return { content: [{ type: "text", text: "Invalid arguments for delete_comment" }], isError: true };
+            }
+            try {
+                await todoistClient.deleteComment(args.commentId);
+                return {
+                    content: [{ type: "text", text: `Comment ${args.commentId} deleted.` }],
+                    isError: false
+                };
+            }
+            catch (error) {
+                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.3.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",