@todoist/comms-mcp 0.0.1 → 11.0.0

package/dist/tools/load-thread.js

@@ -0,0 +1,175 @@
+import { getFullCommsURL } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { formatAttachmentsLine, normalizeAttachments } from '../utils/attachments.js';
+import { UNKNOWN_USER } from '../utils/constants.js';
+import { resolveUsersWithLog } from '../utils/degrade.js';
+import { LoadThreadOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    threadId: z.string().describe('The thread ID to load.'),
+    newerThanDate: z
+        .string()
+        .optional()
+        .describe('Get comments newer than this date (YYYY-MM-DD format).'),
+    olderThanDate: z
+        .string()
+        .optional()
+        .describe('Get comments older than this date (YYYY-MM-DD format).'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .default(50)
+        .describe('Maximum number of comments to return.'),
+    includeParticipants: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include participant user IDs in the response.'),
+};
+const loadThread = {
+    name: ToolNames.LOAD_THREAD,
+    description: 'Load a thread with its metadata and comments. Supports filtering by timestamp and pagination.',
+    parameters: ArgsSchema,
+    outputSchema: LoadThreadOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { threadId, newerThanDate, olderThanDate, limit, includeParticipants } = args;
+        // Fetch thread metadata and comments in parallel
+        const [thread, comments] = await Promise.all([
+            client.threads.getThread(threadId),
+            client.comments.getComments({
+                threadId,
+                newerThan: newerThanDate ? new Date(newerThanDate) : undefined,
+                olderThan: olderThanDate ? new Date(olderThanDate) : undefined,
+                limit,
+            }),
+        ]);
+        // Collect all unique user IDs
+        const userIds = new Set([thread.creator]);
+        for (const comment of comments) {
+            userIds.add(comment.creator);
+        }
+        if (includeParticipants && thread.participants) {
+            for (const participantId of thread.participants) {
+                userIds.add(participantId);
+            }
+        }
+        // Fetch channel and all user info in parallel
+        const [channel, users] = await Promise.all([
+            client.channels.getChannel(thread.channelId),
+            // IDs that can't be resolved are simply absent from the lookup, so a
+            // single inaccessible user doesn't fail the whole thread.
+            resolveUsersWithLog(client, ToolNames.LOAD_THREAD, 'failed to resolve thread participant', thread.workspaceId, Array.from(userIds)),
+        ]);
+        const userLookup = {};
+        for (const [id, user] of users) {
+            userLookup[id] = user.fullName;
+        }
+        // Build text content
+        const creatorName = userLookup[thread.creator];
+        const lines = [
+            `# Thread: ${thread.title}`,
+            '',
+            `**Thread ID:** ${thread.id}`,
+            `**Channel:** ${channel.name}`,
+            `**Workspace ID:** ${thread.workspaceId}`,
+            `**Creator:** ${creatorName ?? UNKNOWN_USER} (${thread.creator})`,
+            `**Posted:** ${thread.posted.toISOString()}`,
+            `**Comments:** ${thread.commentCount}`,
+            `**Archived:** ${thread.isArchived ? 'Yes' : 'No'}`,
+            `**In Inbox:** ${thread.inInbox ? 'Yes' : 'No'}`,
+            '',
+            '## Content',
+            '',
+            thread.content,
+            '',
+        ];
+        // Normalised once per thread and comment, for both the text and the structured content.
+        const threadAttachments = normalizeAttachments(thread.attachments);
+        const attachmentsByComment = new Map(comments.map((c) => [c.id, normalizeAttachments(c.attachments)]));
+        const threadAttachmentsLine = formatAttachmentsLine(threadAttachments);
+        if (threadAttachmentsLine) {
+            lines.push(threadAttachmentsLine);
+            lines.push('');
+        }
+        lines.push(`## Comments (${comments.length})`);
+        lines.push('');
+        for (const comment of comments) {
+            const commentDate = comment.posted.toISOString();
+            const commentCreatorName = userLookup[comment.creator];
+            lines.push(`### Comment ${comment.id}`);
+            lines.push(`**Creator:** ${commentCreatorName ?? UNKNOWN_USER} (${comment.creator}) | **Posted:** ${commentDate}`);
+            lines.push('');
+            lines.push(comment.content);
+            const commentAttachmentsLine = formatAttachmentsLine(attachmentsByComment.get(comment.id));
+            if (commentAttachmentsLine) {
+                lines.push('');
+                lines.push(commentAttachmentsLine);
+            }
+            lines.push('');
+        }
+        if (includeParticipants && thread.participants) {
+            lines.push('## Participants');
+            lines.push('');
+            const participantList = thread.participants
+                .map((id) => `${userLookup[id] ?? UNKNOWN_USER} (${id})`)
+                .join(', ');
+            lines.push(participantList);
+        }
+        const structuredContent = {
+            type: 'thread_data',
+            thread: {
+                id: thread.id,
+                title: thread.title,
+                content: thread.content,
+                channelId: thread.channelId,
+                channelName: channel.name,
+                workspaceId: thread.workspaceId,
+                creator: thread.creator,
+                creatorName,
+                posted: thread.posted.toISOString(),
+                commentCount: thread.commentCount,
+                isArchived: thread.isArchived,
+                inInbox: thread.inInbox ?? false,
+                participants: includeParticipants ? (thread.participants ?? undefined) : undefined,
+                participantNames: includeParticipants && thread.participants
+                    ? thread.participants
+                        .map((id) => userLookup[id])
+                        .filter((name) => name !== undefined)
+                    : undefined,
+                threadUrl: thread.url ??
+                    getFullCommsURL({
+                        workspaceId: thread.workspaceId,
+                        channelId: thread.channelId,
+                        threadId: thread.id,
+                    }),
+                attachments: threadAttachments,
+            },
+            comments: comments.map((c) => ({
+                id: c.id,
+                content: c.content,
+                creator: c.creator,
+                creatorName: userLookup[c.creator],
+                threadId: c.threadId,
+                posted: c.posted.toISOString(),
+                commentUrl: c.url ??
+                    getFullCommsURL({
+                        workspaceId: c.workspaceId,
+                        channelId: c.channelId,
+                        threadId: c.threadId,
+                        commentId: c.id,
+                    }),
+                attachments: attachmentsByComment.get(c.id),
+            })),
+            totalComments: thread.commentCount,
+        };
+        return {
+            textContent: lines.join('\n'),
+            structuredContent,
+        };
+    },
+};
+export { loadThread };

package/dist/tools/mark-done.d.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { type MarkDoneOp } from '../utils/output-schemas.js';
+import { type MarkDoneType } from '../utils/target-types.js';
+type MarkDoneStructured = {
+    type: 'mark_done_result';
+    itemType: MarkDoneType;
+    mode: 'individual' | 'bulk';
+    completed: string[];
+    failed: Array<{
+        item: string;
+        error: string;
+        opErrors: Array<{
+            op: MarkDoneOp;
+            error: string;
+        }>;
+    }>;
+    warnings: Array<{
+        item: string;
+        op: MarkDoneOp;
+        error: string;
+    }>;
+    totalRequested: number;
+    successCount: number;
+    failureCount: number;
+    operations: {
+        markRead: boolean;
+        archive: boolean;
+        clearUnread: boolean;
+    };
+    selectors?: {
+        workspaceId?: number;
+        channelId?: string;
+    };
+};
+declare const markDone: {
+    name: "mark-done";
+    description: string;
+    parameters: {
+        type: z.ZodEnum<{
+            thread: "thread";
+            conversation: "conversation";
+        }>;
+        ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        workspaceId: z.ZodOptional<z.ZodNumber>;
+        channelId: z.ZodOptional<z.ZodString>;
+        markRead: z.ZodOptional<z.ZodBoolean>;
+        archive: z.ZodOptional<z.ZodBoolean>;
+        clearUnread: z.ZodOptional<z.ZodBoolean>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"mark_done_result">;
+        itemType: z.ZodEnum<{
+            thread: "thread";
+            conversation: "conversation";
+        }>;
+        mode: z.ZodEnum<{
+            individual: "individual";
+            bulk: "bulk";
+        }>;
+        completed: z.ZodArray<z.ZodString>;
+        failed: z.ZodArray<z.ZodObject<{
+            item: z.ZodString;
+            error: z.ZodString;
+            opErrors: z.ZodArray<z.ZodObject<{
+                op: z.ZodEnum<{
+                    markRead: "markRead";
+                    archive: "archive";
+                }>;
+                error: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        warnings: z.ZodArray<z.ZodObject<{
+            item: z.ZodString;
+            op: z.ZodEnum<{
+                markRead: "markRead";
+                archive: "archive";
+            }>;
+            error: z.ZodString;
+        }, z.core.$strip>>;
+        totalRequested: z.ZodNumber;
+        successCount: z.ZodNumber;
+        failureCount: z.ZodNumber;
+        operations: z.ZodObject<{
+            markRead: z.ZodBoolean;
+            archive: z.ZodBoolean;
+            clearUnread: z.ZodBoolean;
+        }, z.core.$strip>;
+        selectors: z.ZodOptional<z.ZodObject<{
+            workspaceId: z.ZodOptional<z.ZodNumber>;
+            channelId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: true;
+        idempotentHint: true;
+    };
+    execute(args: {
+        type: "thread" | "conversation";
+        ids?: string[] | undefined;
+        workspaceId?: number | undefined;
+        channelId?: string | undefined;
+        markRead?: boolean | undefined;
+        archive?: boolean | undefined;
+        clearUnread?: boolean | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: MarkDoneStructured;
+    }>;
+};
+export { markDone, type MarkDoneStructured };

package/dist/tools/mark-done.js

@@ -0,0 +1,275 @@
+import { z } from 'zod';
+import { limitedAll } from '../utils/concurrency.js';
+import { logOperationFailures } from '../utils/degrade.js';
+import { MarkDoneOutputSchema } from '../utils/output-schemas.js';
+import { markConversationFullyRead, markThreadFullyRead } from '../utils/read-position.js';
+import { MarkDoneTypeSchema } from '../utils/target-types.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    type: MarkDoneTypeSchema.describe('The type of items to mark as done: thread or conversation.'),
+    // Individual IDs (thread/conversation IDs are strings)
+    ids: z
+        .array(z.string())
+        .optional()
+        .describe('Specific thread or conversation IDs to mark as done. Use this OR bulk selectors.'),
+    // Bulk selectors (for threads only)
+    workspaceId: z
+        .number()
+        .optional()
+        .describe('Mark all threads in this workspace as done (threads only).'),
+    channelId: z
+        .string()
+        .optional()
+        .describe('Mark all threads in this channel as done (threads only).'),
+    // Operations
+    markRead: z.boolean().optional().describe('Mark items as read (default: true).'),
+    archive: z
+        .boolean()
+        .optional()
+        .describe('Archive items in the inbox (threads only, default: true).'),
+    clearUnread: z
+        .boolean()
+        .optional()
+        .describe('Clear all unread markers for workspace (threads only, requires workspaceId, default: false).'),
+};
+const markDone = {
+    name: ToolNames.MARK_DONE,
+    description: 'Mark threads or conversations as done. Supports individual IDs or bulk operations (mark all in workspace/channel). For threads: can mark as read, archive in inbox, or clear all unread. For conversations: can mark as read and archive.',
+    parameters: ArgsSchema,
+    outputSchema: MarkDoneOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    async execute(args, client) {
+        const { type, ids, workspaceId, channelId, markRead = true, archive = true, clearUnread = false, } = args;
+        const completed = [];
+        const failed = [];
+        const warnings = [];
+        let mode = 'individual';
+        // Validate arguments
+        if (!ids && !workspaceId && !channelId) {
+            throw new Error('Must provide either ids, workspaceId, or channelId');
+        }
+        if (type === 'conversation' && (workspaceId || channelId || clearUnread)) {
+            throw new Error('Bulk operations (workspaceId, channelId, clearUnread) are only supported for threads');
+        }
+        // Reject channel-only bulk archive up front: the SDK's `inbox.archiveAll`
+        // requires a workspaceId, so without one we'd silently drop the archive
+        // step while reporting success — exactly the "lie about state" failure
+        // mode this tool must avoid.
+        if (type === 'thread' && archive && channelId && !workspaceId) {
+            throw new Error('Archiving by channelId requires workspaceId. Pass both, or pass individual `ids` instead.');
+        }
+        try {
+            // Bulk operations (threads only)
+            if (type === 'thread' && (workspaceId || channelId)) {
+                mode = 'bulk';
+                // Clear unread takes precedence; it's strictly workspace-scoped
+                // (the SDK only exposes a workspace-level signature), so we
+                // require workspaceId for it.
+                if (clearUnread && workspaceId) {
+                    await client.threads.clearUnread(workspaceId);
+                }
+                else {
+                    // Mark all read — pass both selectors when both are present
+                    // so the call stays scoped to the channel inside the
+                    // workspace rather than nuking the whole workspace.
+                    if (markRead) {
+                        if (workspaceId && channelId) {
+                            await client.threads.markAllRead({ workspaceId, channelId });
+                        }
+                        else if (workspaceId) {
+                            await client.threads.markAllRead({ workspaceId });
+                        }
+                        else if (channelId) {
+                            await client.threads.markAllRead({ channelId });
+                        }
+                    }
+                    // Archive all (inbox operations). `archiveAll` requires a
+                    // workspaceId; with a channelId also present, pass it via
+                    // `channelIds` so the archive stays scoped to that channel.
+                    // The channel-only case is rejected up front in the
+                    // validation above so this branch is reachable only with
+                    // a workspaceId.
+                    if (archive && workspaceId) {
+                        if (channelId) {
+                            await client.inbox.archiveAll({
+                                workspaceId,
+                                channelIds: [channelId],
+                            });
+                        }
+                        else {
+                            await client.inbox.archiveAll({ workspaceId });
+                        }
+                    }
+                }
+                // We don't get individual IDs back from bulk operations
+                // Just indicate success
+            }
+            else if (ids && ids.length > 0) {
+                // Individual operations - run them in parallel
+                mode = 'individual';
+                // Run each requested operation independently so a failure in
+                // one (e.g. markRead) never prevents the other (e.g. archive)
+                // from running. The `ids` list is user-supplied so it can be
+                // large — `limitedAll` keeps the burst inside the socket pool /
+                // rate limiter.
+                const results = await limitedAll(ids, async (id) => {
+                    const opErrors = [];
+                    const runOp = async (op, fn) => {
+                        try {
+                            await fn();
+                        }
+                        catch (error) {
+                            opErrors.push({
+                                op,
+                                error: error instanceof Error ? error.message : 'Unknown error',
+                            });
+                        }
+                    };
+                    if (type === 'thread') {
+                        if (markRead) {
+                            await runOp('markRead', () => markThreadFullyRead(client, id));
+                        }
+                        if (archive) {
+                            await runOp('archive', () => client.inbox.archiveThread(id));
+                        }
+                    }
+                    else {
+                        if (markRead) {
+                            await runOp('markRead', () => markConversationFullyRead(client, id));
+                        }
+                        if (archive) {
+                            await runOp('archive', () => client.conversations.archiveConversation(id));
+                        }
+                    }
+                    return { id, opErrors };
+                });
+                // "Done" is defined by the archive operation when requested;
+                // otherwise by markRead. If that operation succeeds the item is
+                // completed even if a secondary operation failed — the failure
+                // is surfaced as a non-fatal warning rather than failing the
+                // whole item (and breaking automations whose goal is archiving).
+                const doneOp = archive ? 'archive' : 'markRead';
+                for (const r of results) {
+                    const doneFailure = r.opErrors.find((e) => e.op === doneOp);
+                    if (doneFailure) {
+                        const detail = r.opErrors.map((e) => `${e.op}: ${e.error}`).join('; ');
+                        failed.push({ item: r.id, error: detail, opErrors: r.opErrors });
+                    }
+                    else {
+                        completed.push(r.id);
+                        for (const e of r.opErrors) {
+                            warnings.push({ item: r.id, op: e.op, error: e.error });
+                        }
+                    }
+                }
+                logOperationFailures(ToolNames.MARK_DONE, failed.map(({ item, error }) => ({ item, error })), { warnings, context: { itemType: type } });
+            }
+        }
+        catch (error) {
+            // Bulk operation failed entirely
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Bulk operation failed: ${errorMessage}`);
+        }
+        // Build text content
+        const lines = [
+            `# Mark ${type === 'thread' ? 'Threads' : 'Conversations'} Done`,
+            '',
+        ];
+        lines.push(`**Mode:** ${mode === 'bulk' ? 'Bulk Operation' : 'Individual IDs'}`);
+        if (mode === 'bulk') {
+            if (workspaceId) {
+                lines.push(`**Workspace ID:** ${workspaceId}`);
+            }
+            if (channelId) {
+                lines.push(`**Channel ID:** ${channelId}`);
+            }
+            if (clearUnread) {
+                lines.push('**Operation:** Clear all unread markers');
+            }
+            else {
+                lines.push(`**Mark Read:** ${markRead ? 'Yes' : 'No'}`);
+                lines.push(`**Archive:** ${archive ? 'Yes' : 'No'}`);
+            }
+            lines.push('');
+            lines.push('Bulk operation completed successfully');
+        }
+        else {
+            lines.push(`**Total Requested:** ${ids?.length ?? 0}`);
+            lines.push(`**Successful:** ${completed.length}`);
+            lines.push(`**Failed:** ${failed.length}`);
+            if (warnings.length > 0) {
+                lines.push(`**Warnings:** ${warnings.length}`);
+            }
+            lines.push(`**Mark Read:** ${markRead ? 'Yes' : 'No'}`);
+            lines.push(`**Archive:** ${archive ? 'Yes' : 'No'}`);
+            lines.push('');
+            if (completed.length > 0) {
+                lines.push('## Completed');
+                lines.push('');
+                lines.push(completed.join(', '));
+                lines.push('');
+            }
+            if (failed.length > 0) {
+                lines.push('## Failed');
+                lines.push('');
+                for (const failure of failed) {
+                    lines.push(`- ${type} ${failure.item}: ${failure.error}`);
+                }
+                lines.push('');
+            }
+            if (warnings.length > 0) {
+                lines.push('## Warnings');
+                lines.push('');
+                lines.push(`These ${type}s were marked done (archived), but a secondary operation failed:`);
+                for (const warning of warnings) {
+                    lines.push(`- ${type} ${warning.item} (${warning.op}): ${warning.error}`);
+                }
+                lines.push('');
+            }
+        }
+        // Add next steps
+        lines.push('## Next Steps');
+        lines.push('');
+        if (mode === 'bulk' || (failed.length === 0 && completed.length > 0)) {
+            lines.push(type === 'thread'
+                ? 'Use `fetch-inbox` to see remaining unread threads.'
+                : 'Check your conversations for remaining unread messages.');
+        }
+        else if (failed.length > 0) {
+            lines.push('Review failed items and retry if needed.');
+        }
+        // Warning items are archived but still unread. `fetch-inbox` defaults to
+        // `archiveFilter: "active"` and would hide them, so point callers at the
+        // archived view when they need to inspect or re-read those threads.
+        if (warnings.length > 0 && type === 'thread') {
+            lines.push('Warning threads are archived but still unread — use `fetch-inbox` with `archiveFilter: "all"` or `"archived"` to inspect them.');
+        }
+        const structuredContent = {
+            type: 'mark_done_result',
+            itemType: type,
+            mode,
+            completed,
+            failed,
+            warnings,
+            totalRequested: ids?.length ?? 0,
+            successCount: completed.length,
+            failureCount: failed.length,
+            operations: {
+                markRead,
+                archive,
+                clearUnread,
+            },
+            selectors: workspaceId || channelId
+                ? {
+                    workspaceId,
+                    channelId,
+                }
+                : undefined,
+        };
+        return {
+            textContent: lines.join('\n'),
+            structuredContent,
+        };
+    },
+};
+export { markDone };

package/dist/tools/mark-read.d.ts

@@ -0,0 +1,73 @@
+import type { CommsApi } from '@doist/comms-sdk';
+import { z } from 'zod';
+import type { MarkReadItemType } from '../utils/target-types.js';
+type MarkReadItems = {
+    marked: string[];
+    alreadyRead: string[];
+};
+type MarkReadFailure = {
+    item: string;
+    itemType: MarkReadItemType;
+    error: string;
+};
+type MarkReadStructured = {
+    type: 'mark_read_result';
+    workspaceId: number;
+    mode: 'individual' | 'all';
+    threads: MarkReadItems;
+    conversations: MarkReadItems;
+    failed: MarkReadFailure[];
+    markedCount: number;
+    failureCount: number;
+};
+declare const markRead: {
+    name: "mark-read";
+    description: string;
+    parameters: {
+        workspaceId: z.ZodNumber;
+        threadIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        conversationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        all: z.ZodOptional<z.ZodBoolean>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"mark_read_result">;
+        workspaceId: z.ZodNumber;
+        mode: z.ZodEnum<{
+            individual: "individual";
+            all: "all";
+        }>;
+        threads: z.ZodObject<{
+            marked: z.ZodArray<z.ZodString>;
+            alreadyRead: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        conversations: z.ZodObject<{
+            marked: z.ZodArray<z.ZodString>;
+            alreadyRead: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        failed: z.ZodArray<z.ZodObject<{
+            item: z.ZodString;
+            itemType: z.ZodEnum<{
+                thread: "thread";
+                conversation: "conversation";
+            }>;
+            error: z.ZodString;
+        }, z.core.$strip>>;
+        markedCount: z.ZodNumber;
+        failureCount: z.ZodNumber;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        workspaceId: number;
+        threadIds?: string[] | undefined;
+        conversationIds?: string[] | undefined;
+        all?: boolean | undefined;
+    }, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: MarkReadStructured;
+    }>;
+};
+export { markRead, type MarkReadStructured };