@doist/todoist-ai 4.16.0 → 4.17.0

package/dist/tools/find-completed-tasks.js

@@ -1,168 +0,0 @@
-import { z } from 'zod';
-import { appendToQuery, resolveResponsibleUser } from '../filter-helpers.js';
-import { getToolOutput } from '../mcp-helpers.js';
-import { mapTask } from '../tool-helpers.js';
-import { ApiLimits } from '../utils/constants.js';
-import { generateLabelsFilter, LabelsSchema } from '../utils/labels.js';
-import { previewTasks, summarizeList } from '../utils/response-builders.js';
-import { ToolNames } from '../utils/tool-names.js';
-const { FIND_TASKS_BY_DATE, GET_OVERVIEW } = ToolNames;
-const ArgsSchema = {
-    getBy: z
-        .enum(['completion', 'due'])
-        .default('completion')
-        .describe('The method to use to get the tasks: "completion" to get tasks by completion date (ie, when the task was actually completed), "due" to get tasks by due date (ie, when the task was due to be completed by).'),
-    since: z
-        .string()
-        .date()
-        .regex(/^\d{4}-\d{2}-\d{2}$/)
-        .describe('The start date to get the tasks for. Format: YYYY-MM-DD.'),
-    until: z
-        .string()
-        .date()
-        .regex(/^\d{4}-\d{2}-\d{2}$/)
-        .describe('The start date to get the tasks for. Format: YYYY-MM-DD.'),
-    workspaceId: z.string().optional().describe('The ID of the workspace to get the tasks for.'),
-    projectId: z
-        .string()
-        .optional()
-        .describe('The ID of the project to get the tasks for. Project ID should be an ID string, or the text "inbox", for inbox tasks.'),
-    sectionId: z.string().optional().describe('The ID of the section to get the tasks for.'),
-    parentId: z.string().optional().describe('The ID of the parent task to get the tasks for.'),
-    responsibleUser: z
-        .string()
-        .optional()
-        .describe('Find tasks assigned to this user. Can be a user ID, name, or email address. Defaults to all collaborators when omitted.'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(ApiLimits.COMPLETED_TASKS_MAX)
-        .default(ApiLimits.COMPLETED_TASKS_DEFAULT)
-        .describe('The maximum number of tasks to return.'),
-    cursor: z
-        .string()
-        .optional()
-        .describe('The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters).'),
-    ...LabelsSchema,
-};
-const findCompletedTasks = {
-    name: ToolNames.FIND_COMPLETED_TASKS,
-    description: 'Get completed tasks (includes all collaborators by default—use responsibleUser to narrow).',
-    parameters: ArgsSchema,
-    async execute(args, client) {
-        const { getBy, labels, labelsOperator, since, until, responsibleUser, projectId, ...rest } = args;
-        // Resolve assignee name to user ID if provided
-        const resolved = await resolveResponsibleUser(client, responsibleUser);
-        const assigneeEmail = resolved?.email;
-        // Build combined filter query (labels + assignment)
-        const labelsFilter = generateLabelsFilter(labels, labelsOperator);
-        let filterQuery = labelsFilter;
-        if (resolved && assigneeEmail) {
-            filterQuery = appendToQuery(filterQuery, `assigned to: ${assigneeEmail}`);
-        }
-        // Get user timezone to convert local dates to UTC
-        const user = await client.getUser();
-        const userGmtOffset = user.tzInfo?.gmtString || '+00:00';
-        // Resolve "inbox" to actual inbox project ID if needed
-        const resolvedProjectId = projectId === 'inbox' ? user.inboxProjectId : projectId;
-        // Convert user's local date to UTC timestamps
-        // This ensures we capture the entire day from the user's perspective
-        const sinceWithOffset = `${since}T00:00:00${userGmtOffset}`;
-        const untilWithOffset = `${until}T23:59:59${userGmtOffset}`;
-        // Parse and convert to UTC
-        const sinceDateTime = new Date(sinceWithOffset).toISOString();
-        const untilDateTime = new Date(untilWithOffset).toISOString();
-        const { items, nextCursor } = getBy === 'completion'
-            ? await client.getCompletedTasksByCompletionDate({
-                ...rest,
-                projectId: resolvedProjectId,
-                since: sinceDateTime,
-                until: untilDateTime,
-                ...(filterQuery ? { filterQuery, filterLang: 'en' } : {}),
-            })
-            : await client.getCompletedTasksByDueDate({
-                ...rest,
-                projectId: resolvedProjectId,
-                since: sinceDateTime,
-                until: untilDateTime,
-                ...(filterQuery ? { filterQuery, filterLang: 'en' } : {}),
-            });
-        const mappedTasks = items.map(mapTask);
-        const textContent = generateTextContent({
-            tasks: mappedTasks,
-            args,
-            nextCursor,
-            assigneeEmail,
-        });
-        return getToolOutput({
-            textContent,
-            structuredContent: {
-                tasks: mappedTasks,
-                nextCursor,
-                totalCount: mappedTasks.length,
-                hasMore: Boolean(nextCursor),
-                appliedFilters: args,
-            },
-        });
-    },
-};
-function generateTextContent({ tasks, args, nextCursor, assigneeEmail, }) {
-    // Generate subject description
-    const getByText = args.getBy === 'completion' ? 'completed' : 'due';
-    const subject = `Completed tasks (by ${getByText} date)`;
-    // Generate filter hints
-    const filterHints = [];
-    filterHints.push(`${getByText} date: ${args.since} to ${args.until}`);
-    if (args.projectId)
-        filterHints.push(`project: ${args.projectId}`);
-    if (args.sectionId)
-        filterHints.push(`section: ${args.sectionId}`);
-    if (args.parentId)
-        filterHints.push(`parent: ${args.parentId}`);
-    if (args.workspaceId)
-        filterHints.push(`workspace: ${args.workspaceId}`);
-    // Add label filter information
-    if (args.labels && args.labels.length > 0) {
-        const labelText = args.labels
-            .map((label) => `@${label}`)
-            .join(args.labelsOperator === 'and' ? ' & ' : ' | ');
-        filterHints.push(`labels: ${labelText}`);
-    }
-    // Add responsible user filter information
-    if (args.responsibleUser) {
-        const email = assigneeEmail || args.responsibleUser;
-        filterHints.push(`assigned to: ${email}`);
-    }
-    // Generate helpful suggestions for empty results
-    const zeroReasonHints = [];
-    if (tasks.length === 0) {
-        zeroReasonHints.push('No tasks completed in this date range');
-        zeroReasonHints.push('Try expanding the date range');
-        if (args.projectId || args.sectionId || args.parentId) {
-            zeroReasonHints.push('Try removing project/section/parent filters');
-        }
-        if (args.getBy === 'due') {
-            zeroReasonHints.push('Try switching to "completion" date instead');
-        }
-    }
-    // Generate contextual next steps
-    const nextSteps = [];
-    if (tasks.length > 0) {
-        nextSteps.push(`Use ${FIND_TASKS_BY_DATE} for active tasks or ${GET_OVERVIEW} for current productivity.`);
-        if (tasks.some((task) => task.recurring)) {
-            nextSteps.push('Recurring tasks will automatically create new instances.');
-        }
-    }
-    return summarizeList({
-        subject,
-        count: tasks.length,
-        limit: args.limit,
-        nextCursor: nextCursor ?? undefined,
-        filterHints,
-        previewLines: previewTasks(tasks, Math.min(tasks.length, args.limit)),
-        zeroReasonHints,
-        nextSteps,
-    });
-}
-export { findCompletedTasks };

package/dist/tools/find-project-collaborators.js

@@ -1,151 +0,0 @@
-import { z } from 'zod';
-import { getToolOutput } from '../mcp-helpers.js';
-import { summarizeList } from '../utils/response-builders.js';
-import { ToolNames } from '../utils/tool-names.js';
-import { userResolver } from '../utils/user-resolver.js';
-const { FIND_PROJECTS, ADD_TASKS, UPDATE_TASKS } = ToolNames;
-const ArgsSchema = {
-    projectId: z.string().min(1).describe('The ID of the project to search for collaborators in.'),
-    searchTerm: z
-        .string()
-        .optional()
-        .describe('Search for a collaborator by name or email (partial and case insensitive match). If omitted, all collaborators in the project are returned.'),
-};
-const findProjectCollaborators = {
-    name: ToolNames.FIND_PROJECT_COLLABORATORS,
-    description: 'Search for collaborators by name or other criteria in a project.',
-    parameters: ArgsSchema,
-    async execute(args, client) {
-        const { projectId, searchTerm } = args;
-        // First, validate that the project exists and get basic info
-        let projectName = projectId;
-        let project;
-        try {
-            project = await client.getProject(projectId);
-            if (!project) {
-                throw new Error(`Project with ID "${projectId}" not found or not accessible`);
-            }
-            projectName = project.name;
-            if (!project.isShared) {
-                const textContent = `Project "${projectName}" is not shared and has no collaborators.\n\n**Next steps:**\n• Share the project to enable collaboration\n• Use ${ADD_TASKS} and ${UPDATE_TASKS} for assignment features once shared`;
-                return getToolOutput({
-                    textContent,
-                    structuredContent: {
-                        collaborators: [],
-                        projectInfo: {
-                            id: projectId,
-                            name: projectName,
-                            isShared: false,
-                        },
-                        totalCount: 0,
-                        appliedFilters: args,
-                    },
-                });
-            }
-        }
-        catch (error) {
-            throw new Error(`Failed to access project "${projectId}": ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-        // Get collaborators for the project
-        const allCollaborators = await userResolver.getProjectCollaborators(client, projectId);
-        if (allCollaborators.length === 0) {
-            const textContent = `Project "${projectName}" has no collaborators or collaborator data is not accessible.\n\n**Next steps:**\n• Check project sharing settings\n• Ensure you have permission to view collaborators\n• Try refreshing or re-sharing the project`;
-            return getToolOutput({
-                textContent,
-                structuredContent: {
-                    collaborators: [],
-                    projectInfo: {
-                        id: projectId,
-                        name: projectName,
-                        isShared: true,
-                    },
-                    totalCount: 0,
-                    appliedFilters: args,
-                },
-            });
-        }
-        // Filter collaborators if search term provided
-        let filteredCollaborators = allCollaborators;
-        if (searchTerm) {
-            const searchLower = searchTerm.toLowerCase().trim();
-            filteredCollaborators = allCollaborators.filter((collaborator) => collaborator.name.toLowerCase().includes(searchLower) ||
-                collaborator.email.toLowerCase().includes(searchLower));
-        }
-        const textContent = generateTextContent({
-            collaborators: filteredCollaborators,
-            projectName,
-            searchTerm,
-            totalAvailable: allCollaborators.length,
-        });
-        return getToolOutput({
-            textContent,
-            structuredContent: {
-                collaborators: filteredCollaborators,
-                projectInfo: {
-                    id: projectId,
-                    name: projectName,
-                    isShared: true,
-                },
-                totalCount: filteredCollaborators.length,
-                totalAvailable: allCollaborators.length,
-                appliedFilters: args,
-            },
-        });
-    },
-};
-function generateTextContent({ collaborators, projectName, searchTerm, totalAvailable, }) {
-    const subject = searchTerm
-        ? `Project collaborators matching "${searchTerm}"`
-        : 'Project collaborators';
-    const filterHints = [];
-    if (searchTerm) {
-        filterHints.push(`matching "${searchTerm}"`);
-    }
-    filterHints.push(`in project "${projectName}"`);
-    let previewLines = [];
-    if (collaborators.length > 0) {
-        previewLines = collaborators.slice(0, 10).map((collaborator) => {
-            const displayName = collaborator.name || 'Unknown Name';
-            const email = collaborator.email || 'No email';
-            return `• ${displayName} (${email}) - ID: ${collaborator.id}`;
-        });
-        if (collaborators.length > 10) {
-            previewLines.push(`... and ${collaborators.length - 10} more`);
-        }
-    }
-    const zeroReasonHints = [];
-    if (collaborators.length === 0) {
-        if (searchTerm) {
-            zeroReasonHints.push(`No collaborators match "${searchTerm}"`);
-            zeroReasonHints.push('Try a broader search term or check spelling');
-            if (totalAvailable > 0) {
-                zeroReasonHints.push(`${totalAvailable} collaborators available without filter`);
-            }
-        }
-        else {
-            zeroReasonHints.push('Project has no collaborators');
-            zeroReasonHints.push('Share the project to add collaborators');
-        }
-    }
-    const nextSteps = [];
-    if (collaborators.length > 0) {
-        nextSteps.push(`Use ${ADD_TASKS} with responsibleUser to assign new tasks`);
-        nextSteps.push(`Use ${UPDATE_TASKS} with responsibleUser to reassign existing tasks`);
-        nextSteps.push('Use collaborator names, emails, or IDs for assignments');
-    }
-    else {
-        nextSteps.push(`Use ${FIND_PROJECTS} to find other projects`);
-        if (searchTerm && totalAvailable > 0) {
-            nextSteps.push('Try searching without filters to see all collaborators');
-        }
-    }
-    return summarizeList({
-        subject,
-        count: collaborators.length,
-        filterHints,
-        previewLines: previewLines.join('\n'),
-        zeroReasonHints,
-        nextSteps,
-    });
-}
-export { findProjectCollaborators };

package/dist/tools/find-projects.js

@@ -1,101 +0,0 @@
-import { z } from 'zod';
-import { getToolOutput } from '../mcp-helpers.js';
-import { mapProject } from '../tool-helpers.js';
-import { ApiLimits } from '../utils/constants.js';
-import { formatProjectPreview, summarizeList } from '../utils/response-builders.js';
-import { ToolNames } from '../utils/tool-names.js';
-const { ADD_PROJECTS, FIND_TASKS } = ToolNames;
-const ArgsSchema = {
-    search: z
-        .string()
-        .optional()
-        .describe('Search for a project by name (partial and case insensitive match). If omitted, all projects are returned.'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(ApiLimits.PROJECTS_MAX)
-        .default(ApiLimits.PROJECTS_DEFAULT)
-        .describe('The maximum number of projects to return.'),
-    cursor: z
-        .string()
-        .optional()
-        .describe('The cursor to get the next page of projects (cursor is obtained from the previous call to this tool, with the same parameters).'),
-};
-const findProjects = {
-    name: ToolNames.FIND_PROJECTS,
-    description: 'List all projects or search for projects by name. If search parameter is omitted, all projects are returned.',
-    parameters: ArgsSchema,
-    async execute(args, client) {
-        const { results, nextCursor } = await client.getProjects({
-            limit: args.limit,
-            cursor: args.cursor ?? null,
-        });
-        const searchLower = args.search ? args.search.toLowerCase() : undefined;
-        const filtered = searchLower
-            ? results.filter((project) => project.name.toLowerCase().includes(searchLower))
-            : results;
-        const projects = filtered.map(mapProject);
-        return getToolOutput({
-            textContent: generateTextContent({
-                projects,
-                args,
-                nextCursor,
-            }),
-            structuredContent: {
-                projects,
-                nextCursor,
-                totalCount: projects.length,
-                hasMore: Boolean(nextCursor),
-                appliedFilters: args,
-            },
-        });
-    },
-};
-function generateTextContent({ projects, args, nextCursor, }) {
-    // Generate subject description
-    const subject = args.search ? `Projects matching "${args.search}"` : 'Projects';
-    // Generate filter hints
-    const filterHints = [];
-    if (args.search) {
-        filterHints.push(`search: "${args.search}"`);
-    }
-    // Generate project preview lines
-    const previewLimit = 10;
-    const previewProjects = projects.slice(0, previewLimit);
-    const previewLines = previewProjects.map(formatProjectPreview).join('\n');
-    const remainingCount = projects.length - previewLimit;
-    const previewWithMore = remainingCount > 0 ? `${previewLines}\n    …and ${remainingCount} more` : previewLines;
-    // Generate helpful suggestions for empty results
-    const zeroReasonHints = [];
-    if (projects.length === 0) {
-        if (args.search) {
-            zeroReasonHints.push('Try broader search terms');
-            zeroReasonHints.push('Check spelling');
-            zeroReasonHints.push('Remove search to see all projects');
-        }
-        else {
-            zeroReasonHints.push('No projects created yet');
-            zeroReasonHints.push(`Use ${ADD_PROJECTS} to create a project`);
-        }
-    }
-    // Generate contextual next steps
-    const nextSteps = [];
-    if (projects.length > 0) {
-        nextSteps.push(`Use ${FIND_TASKS} with projectId to see tasks in specific projects.`);
-        if (projects.some((p) => p.isFavorite)) {
-            nextSteps.push('Favorite projects appear first in most Todoist views.');
-        }
-    }
-    return summarizeList({
-        subject,
-        count: projects.length,
-        limit: args.limit,
-        nextCursor: nextCursor ?? undefined,
-        filterHints,
-        previewLines: previewWithMore,
-        zeroReasonHints,
-        nextSteps,
-    });
-}
-export { findProjects };

package/dist/tools/find-sections.js

@@ -1,101 +0,0 @@
-import { z } from 'zod';
-import { getToolOutput } from '../mcp-helpers.js';
-import { summarizeList } from '../utils/response-builders.js';
-import { ToolNames } from '../utils/tool-names.js';
-const { ADD_SECTIONS, UPDATE_SECTIONS, FIND_TASKS, UPDATE_TASKS, DELETE_OBJECT } = ToolNames;
-const ArgsSchema = {
-    projectId: z
-        .string()
-        .min(1)
-        .describe('The ID of the project to search sections in. Project ID should be an ID string, or the text "inbox", for inbox tasks.'),
-    search: z
-        .string()
-        .optional()
-        .describe('Search for a section by name (partial and case insensitive match). If omitted, all sections in the project are returned.'),
-};
-const findSections = {
-    name: ToolNames.FIND_SECTIONS,
-    description: 'Search for sections by name or other criteria in a project.',
-    parameters: ArgsSchema,
-    async execute(args, client) {
-        // Resolve "inbox" to actual inbox project ID if needed
-        const resolvedProjectId = args.projectId === 'inbox' ? (await client.getUser()).inboxProjectId : args.projectId;
-        const { results } = await client.getSections({
-            projectId: resolvedProjectId,
-        });
-        const searchLower = args.search ? args.search.toLowerCase() : undefined;
-        const filtered = searchLower
-            ? results.filter((section) => section.name.toLowerCase().includes(searchLower))
-            : results;
-        const sections = filtered.map((section) => ({
-            id: section.id,
-            name: section.name,
-        }));
-        const textContent = generateTextContent({
-            sections,
-            projectId: args.projectId,
-            search: args.search,
-        });
-        return getToolOutput({
-            textContent,
-            structuredContent: {
-                sections,
-                totalCount: sections.length,
-                appliedFilters: args,
-            },
-        });
-    },
-};
-function generateTextContent({ sections, projectId, search, }) {
-    const zeroReasonHints = [];
-    if (search) {
-        zeroReasonHints.push('Try broader search terms');
-        zeroReasonHints.push('Check spelling');
-        zeroReasonHints.push('Remove search to see all sections');
-    }
-    else {
-        zeroReasonHints.push('Project has no sections yet');
-        zeroReasonHints.push(`Use ${ADD_SECTIONS} to create sections`);
-    }
-    // Data-driven next steps based on results
-    const nextSteps = [];
-    if (sections.length > 0) {
-        // Suggestions based on number of sections found
-        if (sections.length === 1) {
-            const sectionId = sections[0]?.id;
-            nextSteps.push(`Use ${FIND_TASKS} with sectionId=${sectionId} to see tasks`);
-            nextSteps.push(`Use ${ADD_SECTIONS} to create additional sections for organization`);
-        }
-        else if (sections.length > 8) {
-            nextSteps.push('Consider consolidating sections - many small sections can reduce productivity');
-            nextSteps.push(`Use ${UPDATE_TASKS} to move tasks between sections`);
-            nextSteps.push(`Use ${DELETE_OBJECT} with type=section to delete empty sections`);
-        }
-        else {
-            nextSteps.push(`Use ${FIND_TASKS} with sectionId to see tasks in specific sections`);
-            nextSteps.push(`Use ${UPDATE_SECTIONS} to modify section names`);
-        }
-        // Search-specific suggestions
-        if (search) {
-            nextSteps.push('Remove search parameter to see all sections in this project');
-        }
-    }
-    else {
-        // Empty result suggestions are already handled in zeroReasonHints
-        // No additional nextSteps needed for empty results
-    }
-    const subject = search
-        ? `Sections in project ${projectId} matching "${search}"`
-        : `Sections in project ${projectId}`;
-    const previewLines = sections.length > 0
-        ? sections.map((section) => `    ${section.name} • id=${section.id}`).join('\n')
-        : undefined;
-    return summarizeList({
-        subject,
-        count: sections.length,
-        previewLines,
-        zeroReasonHints,
-        nextSteps,
-    });
-}
-export { findSections };