@todoist/comms-mcp 0.0.1 → 11.0.0

package/dist/tools/create-conversation.js

@@ -0,0 +1,75 @@
+import { getFullCommsURL } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { CreateConversationOutputSchema, } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+import { getConversationUrl } from '../utils/url-helpers.js';
+const ArgsSchema = {
+    workspaceId: z.number().describe('The ID of the workspace the conversation belongs to.'),
+    recipients: z
+        .array(z.number())
+        .min(1)
+        .describe('User IDs to include in the direct or group conversation (excluding yourself, who is added automatically). Use get-users to resolve names to IDs.'),
+    content: z
+        .string()
+        .min(1)
+        .describe('The content of the first message to post. Markdown. Mention people with the link syntax [Name](comms-mention://USER_ID) — e.g. [Afzal](comms-mention://29367677) — never @Name or [[Name|id]], which post as literal text. Do not put "@" in the label; the client adds it. Groups use [Name](comms-group-mention://GROUP_ID), channels [#name](comms-channel://CHANNEL_ID), threads [Title](comms-thread://THREAD_ID). Resolve IDs with get-users/get-groups/list-channels first. Everyone in recipients is notified regardless of who is mentioned inline; a mentioned person who is not a participant is not notified.'),
+};
+const createConversation = {
+    name: ToolNames.CREATE_CONVERSATION,
+    description: 'Start a direct or group conversation with one or more users and post an initial message. Reuses the existing conversation if one already exists for the same set of users.',
+    parameters: ArgsSchema,
+    outputSchema: CreateConversationOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    async execute(args, client) {
+        const { workspaceId, recipients, content } = args;
+        // The backend dedupes on the participant set, so this returns the existing
+        // conversation for these users rather than creating a duplicate.
+        const conversation = await client.conversations.getOrCreateConversation({
+            workspaceId,
+            userIds: recipients,
+        });
+        const message = await client.conversationMessages.createMessage({
+            conversationId: conversation.id,
+            content,
+        });
+        const conversationUrl = conversation.url ?? getConversationUrl(conversation.workspaceId, conversation.id);
+        const messageUrl = message.url ??
+            getFullCommsURL({
+                workspaceId: message.workspaceId,
+                conversationId: message.conversationId,
+                messageId: message.id,
+            });
+        const created = message.posted.toISOString();
+        const lines = [
+            `# Conversation Started`,
+            '',
+            `**Conversation ID:** ${conversation.id}`,
+            `**Message ID:** ${message.id}`,
+            `**Participants:** ${conversation.userIds.join(', ')}`,
+            `**Created:** ${created}`,
+            `**URL:** ${conversationUrl}`,
+            '',
+            '## Message',
+            '',
+            content,
+        ];
+        const structuredContent = {
+            type: 'create_conversation_result',
+            success: true,
+            conversationId: conversation.id,
+            messageId: message.id,
+            workspaceId: conversation.workspaceId,
+            content,
+            recipients,
+            participants: conversation.userIds,
+            created,
+            conversationUrl,
+            messageUrl,
+        };
+        return {
+            textContent: lines.join('\n'),
+            structuredContent,
+        };
+    },
+};
+export { createConversation };

package/dist/tools/create-thread.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+declare const createThread: {
+    name: "create-thread";
+    description: string;
+    parameters: {
+        channelId: z.ZodString;
+        title: z.ZodString;
+        content: z.ZodString;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        displayInInbox: z.ZodOptional<z.ZodBoolean>;
+        groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        notifyAudience: z.ZodOptional<z.ZodEnum<{
+            thread: "thread";
+            channel: "channel";
+        }>>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"create_thread_result">;
+        success: z.ZodBoolean;
+        threadId: z.ZodString;
+        title: z.ZodString;
+        channelId: z.ZodString;
+        workspaceId: z.ZodNumber;
+        content: z.ZodString;
+        creator: z.ZodNumber;
+        created: z.ZodString;
+        threadUrl: z.ZodString;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        notifyAudience: z.ZodOptional<z.ZodEnum<{
+            thread: "thread";
+            channel: "channel";
+        }>>;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: false;
+        idempotentHint: false;
+    };
+    execute(args: {
+        channelId: string;
+        title: string;
+        content: string;
+        recipients?: number[] | undefined;
+        displayInInbox?: boolean | undefined;
+        groups?: string[] | undefined;
+        notifyAudience?: "thread" | "channel" | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: {
+            type: "create_thread_result";
+            success: boolean;
+            threadId: string;
+            title: string;
+            channelId: string;
+            workspaceId: number;
+            content: string;
+            creator: number;
+            created: string;
+            threadUrl: string;
+            recipients?: number[] | undefined;
+            groups?: string[] | undefined;
+            notifyAudience?: "thread" | "channel" | undefined;
+        };
+    }>;
+};
+export { createThread };

package/dist/tools/create-thread.js

@@ -0,0 +1,126 @@
+import { getFullCommsURL, NOTIFY_AUDIENCES } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { CreateThreadOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    channelId: z.string().describe('The ID of the channel to create the thread in.'),
+    title: z.string().min(1).describe('The title of the thread.'),
+    content: z
+        .string()
+        .min(1)
+        .describe('The content/body of the thread. Markdown. Mention people with the link syntax [Name](comms-mention://USER_ID) — e.g. [Afzal](comms-mention://29367677) — never @Name or [[Name|id]], which post as literal text. Do not put "@" in the label; the client adds it. Groups use [Name](comms-group-mention://GROUP_ID), channels [#name](comms-channel://CHANNEL_ID), threads [Title](comms-thread://THREAD_ID). Resolve IDs with get-users/get-groups/list-channels first. Mentioning inline does not notify anyone — also pass mentioned user IDs in recipients and mentioned group IDs in groups.'),
+    recipients: z
+        .array(z.number())
+        .optional()
+        .describe("Optional array of individual user IDs to notify. To notify everyone in the channel, prefer notifyAudience: 'channel' instead of enumerating every member here. If omitted (with no groups and no notifyAudience), Comms applies the channel's defaults, which is everyone in the channel. Note: workspace users who have not joined this channel will not be notified — add their IDs explicitly if you want to reach them."),
+    displayInInbox: z
+        .boolean()
+        .optional()
+        .describe("If true, unarchives the thread after creation so it appears in the author's Inbox. Defaults to false. Can also be enabled for all calls by setting the COMMS_CREATE_THREAD_DISPLAY_IN_INBOX=true environment variable (local MCP only)."),
+    groups: z
+        .array(z.string())
+        .optional()
+        .describe('Optional array of group IDs to notify. Use get-groups to discover group IDs before passing them here.'),
+    notifyAudience: z
+        .enum(NOTIFY_AUDIENCES)
+        .optional()
+        .describe("Optional broader audience to notify in addition to recipients and groups. 'channel' tags the thread with \"Everyone in channel\" — use this to reach everyone instead of listing individual recipients. 'thread' (everyone who has interacted) has no effect when creating a thread, since a new thread has no interactions yet — use it on reply instead."),
+};
+const createThread = {
+    name: ToolNames.CREATE_THREAD,
+    description: 'Create a new thread in a workspace channel. Requires a channel ID, title, and content. Optionally notify specific users or groups.',
+    parameters: ArgsSchema,
+    outputSchema: CreateThreadOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    async execute(args, client) {
+        const { channelId, title, content, recipients, groups, notifyAudience, displayInInbox } = args;
+        const thread = await client.threads.createThread({
+            channelId,
+            title,
+            content,
+            recipients,
+            groups,
+            notifyAudience,
+        });
+        const wantsInboxDisplay = displayInInbox === true ||
+            (displayInInbox === undefined &&
+                process.env.COMMS_CREATE_THREAD_DISPLAY_IN_INBOX === 'true');
+        let displayedInInbox = false;
+        if (wantsInboxDisplay) {
+            // Unarchive so the thread appears in the author's Inbox.
+            // Failure here is non-fatal — the thread itself was created successfully.
+            try {
+                await client.inbox.unarchiveThread(thread.id);
+                displayedInInbox = true;
+            }
+            catch (error) {
+                console.error(`Error unarchiving thread ${thread.id} for Inbox display:`, {
+                    threadId: thread.id,
+                    error,
+                });
+            }
+        }
+        const postedValue = thread.posted;
+        const created = postedValue
+            ? typeof postedValue === 'string'
+                ? new Date(postedValue)
+                : postedValue
+            : new Date();
+        const threadUrl = thread.url ??
+            getFullCommsURL({
+                workspaceId: thread.workspaceId,
+                channelId: thread.channelId,
+                threadId: thread.id,
+            });
+        const inboxNote = displayedInInbox
+            ? '> Thread is in your Inbox (auto-unarchived after creation).'
+            : '> Note: Threads you create do not appear in your own Inbox by default — only recipients see them there. Find the thread in the channel view or via its URL.';
+        // Only 'channel' takes effect at thread creation. 'thread' (everyone who
+        // has interacted) is discarded by the backend — a new thread has no
+        // interactions yet — so it never becomes an applied audience here. Report
+        // the applied audience, not the request, so machine consumers aren't told
+        // an audience was notified when it wasn't.
+        const appliedAudience = notifyAudience === 'channel' ? notifyAudience : undefined;
+        const audienceNote = notifyAudience === 'channel'
+            ? 'Everyone in channel'
+            : notifyAudience === 'thread'
+                ? 'Everyone who has interacted (no effect at thread creation)'
+                : undefined;
+        const lines = [
+            `# Thread Created`,
+            '',
+            `**Title:** ${thread.title}`,
+            `**Thread ID:** ${thread.id}`,
+            `**Channel ID:** ${thread.channelId}`,
+            `**Created:** ${created.toISOString()}`,
+            `**URL:** ${threadUrl}`,
+            ...(audienceNote ? [`**Notified:** ${audienceNote}`] : []),
+            '',
+            '## Content',
+            '',
+            thread.content,
+            '',
+            inboxNote,
+        ];
+        const structuredContent = {
+            type: 'create_thread_result',
+            success: true,
+            threadId: thread.id,
+            title: thread.title,
+            channelId: thread.channelId,
+            workspaceId: thread.workspaceId,
+            content: thread.content,
+            creator: thread.creator,
+            created: created.toISOString(),
+            threadUrl,
+            ...(recipients ? { recipients } : {}),
+            ...(groups ? { groups } : {}),
+            ...(appliedAudience ? { notifyAudience: appliedAudience } : {}),
+        };
+        return {
+            textContent: lines.join('\n'),
+            structuredContent,
+        };
+    },
+};
+export { createThread };

package/dist/tools/delete-object.d.ts

@@ -0,0 +1,44 @@
+import type { CommsApi } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { type DeleteObjectStructured } from '../utils/output-schemas.js';
+declare const deleteObject: {
+    name: "delete-object";
+    description: string;
+    parameters: {
+        targetType: z.ZodEnum<{
+            thread: "thread";
+            comment: "comment";
+            message: "message";
+        }>;
+        targetId: z.ZodString;
+    };
+    outputSchema: {
+        type: z.ZodEnum<{
+            delete_thread_result: "delete_thread_result";
+            delete_comment_result: "delete_comment_result";
+            delete_message_result: "delete_message_result";
+        }>;
+        success: z.ZodBoolean;
+        targetType: z.ZodEnum<{
+            thread: "thread";
+            comment: "comment";
+            message: "message";
+        }>;
+        threadId: z.ZodOptional<z.ZodString>;
+        commentId: z.ZodOptional<z.ZodString>;
+        messageId: z.ZodOptional<z.ZodString>;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: true;
+        idempotentHint: true;
+    };
+    execute(args: {
+        targetType: "thread" | "comment" | "message";
+        targetId: string;
+    }, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: DeleteObjectStructured;
+    }>;
+};
+export { deleteObject };

package/dist/tools/delete-object.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { DeleteObjectOutputSchema, } from '../utils/output-schemas.js';
+import { DeleteTargetTypeSchema } from '../utils/target-types.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    targetType: DeleteTargetTypeSchema.describe('The type of object to delete: thread, comment, or message.'),
+    targetId: z
+        .string()
+        .describe('The ID of the thread, comment, or conversation message to delete.'),
+};
+async function deleteThreadBranch(args, client) {
+    const { targetId } = args;
+    await client.threads.deleteThread(targetId);
+    const lines = [
+        `# Thread Deleted`,
+        '',
+        `**Thread ID:** ${targetId}`,
+        '',
+        'The thread has been permanently deleted.',
+    ];
+    const structuredContent = {
+        type: 'delete_thread_result',
+        success: true,
+        targetType: 'thread',
+        threadId: targetId,
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+async function deleteCommentBranch(args, client) {
+    const { targetId } = args;
+    await client.comments.deleteComment(targetId);
+    const lines = [
+        `# Comment Deleted`,
+        '',
+        `**Comment ID:** ${targetId}`,
+        '',
+        'The comment has been permanently deleted.',
+    ];
+    const structuredContent = {
+        type: 'delete_comment_result',
+        success: true,
+        targetType: 'comment',
+        commentId: targetId,
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+async function deleteMessageBranch(args, client) {
+    const { targetId } = args;
+    await client.conversationMessages.deleteMessage(targetId);
+    const lines = [
+        `# Message Deleted`,
+        '',
+        `**Message ID:** ${targetId}`,
+        '',
+        'The conversation message has been permanently deleted.',
+    ];
+    const structuredContent = {
+        type: 'delete_message_result',
+        success: true,
+        targetType: 'message',
+        messageId: targetId,
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+const deleteObject = {
+    name: ToolNames.DELETE_OBJECT,
+    description: 'Permanently delete a Comms object. `targetType: "thread"` deletes a thread (and all of its comments); `"comment"` deletes a single thread comment; `"message"` deletes a direct/group conversation message. Always pass `targetId`. Deletion is irreversible — confirm with the user before invoking. Note: the Comms API only allows deletion by the object\'s creator or a workspace admin; the call will be rejected otherwise.',
+    parameters: ArgsSchema,
+    outputSchema: DeleteObjectOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    async execute(args, client) {
+        const { targetType } = args;
+        const branch = targetType === 'thread'
+            ? await deleteThreadBranch(args, client)
+            : targetType === 'comment'
+                ? await deleteCommentBranch(args, client)
+                : await deleteMessageBranch(args, client);
+        return {
+            textContent: branch.textContent,
+            structuredContent: branch.structuredContent,
+        };
+    },
+};
+export { deleteObject };

package/dist/tools/fetch-inbox.d.ts

@@ -0,0 +1,91 @@
+import type { InboxThread, UnreadConversation } from '@doist/comms-sdk';
+import { z } from 'zod';
+type FetchInboxStructured = {
+    type: 'inbox_data';
+    workspaceId: number;
+    threads: Array<{
+        id: string;
+        title: string;
+        channelId: string;
+        channelName?: string;
+        creator: number;
+        isUnread: boolean;
+        isArchived: boolean;
+        isStarred: boolean;
+        threadUrl: string;
+    }>;
+    conversations: Array<{
+        id: string;
+        title: string;
+        userIds: number[];
+        participantNames: string[];
+        isUnread: boolean;
+        conversationUrl: string;
+    }>;
+    unreadCount: number;
+    unreadThreads: InboxThread[];
+    unreadConversations: UnreadConversation[];
+    totalThreads: number;
+    totalConversations: number;
+};
+declare const fetchInbox: {
+    name: "fetch-inbox";
+    description: string;
+    parameters: {
+        workspaceId: z.ZodNumber;
+        sinceDate: z.ZodOptional<z.ZodString>;
+        untilDate: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        onlyUnread: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        archiveFilter: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            archived: "archived";
+            all: "all";
+            active: "active";
+        }>>>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"inbox_data">;
+        workspaceId: z.ZodNumber;
+        threads: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            channelId: z.ZodString;
+            channelName: z.ZodOptional<z.ZodString>;
+            creator: z.ZodNumber;
+            isUnread: z.ZodBoolean;
+            isArchived: z.ZodBoolean;
+            isStarred: z.ZodBoolean;
+            threadUrl: z.ZodString;
+        }, z.core.$strip>>;
+        conversations: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            userIds: z.ZodArray<z.ZodNumber>;
+            participantNames: z.ZodArray<z.ZodString>;
+            isUnread: z.ZodBoolean;
+            conversationUrl: z.ZodString;
+        }, z.core.$strip>>;
+        unreadCount: z.ZodNumber;
+        unreadThreads: z.ZodArray<z.ZodAny>;
+        unreadConversations: z.ZodArray<z.ZodAny>;
+        totalThreads: z.ZodNumber;
+        totalConversations: z.ZodNumber;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        workspaceId: number;
+        limit: number;
+        onlyUnread: boolean;
+        archiveFilter: "archived" | "all" | "active";
+        sinceDate?: string | undefined;
+        untilDate?: string | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: FetchInboxStructured;
+    }>;
+};
+export { fetchInbox, type FetchInboxStructured };