@todoist/comms-mcp 0.0.0-stage → 11.0.0

package/dist/tools/search-content.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { degradeAllWithLog, resolveUsersWithLog } from '../utils/degrade.js';
+import { SearchContentOutputSchema } from '../utils/output-schemas.js';
+import { toRawSearchResults, toSearchResultItems } from '../utils/search-results.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    query: z.string().min(1).describe('The search query string.'),
+    workspaceId: z.number().describe('The workspace ID to search in.'),
+    channelIds: z.array(z.string()).optional().describe('Filter by channel IDs.'),
+    authorIds: z.array(z.number()).optional().describe('Filter by author user IDs.'),
+    mentionSelf: z.boolean().optional().describe('Filter by mentions of current user.'),
+    dateFrom: z.string().optional().describe('Start date for filtering (YYYY-MM-DD).'),
+    dateTo: z.string().optional().describe('End date for filtering (YYYY-MM-DD).'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .default(50)
+        .describe('Maximum number of results to return.'),
+    cursor: z.string().optional().describe('Cursor for pagination.'),
+};
+const searchContent = {
+    name: ToolNames.SEARCH_CONTENT,
+    description: 'Search across a workspace for threads, comments, and messages. Supports filtering by channels, authors, dates, and mentions.',
+    parameters: ArgsSchema,
+    outputSchema: SearchContentOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { query, workspaceId, channelIds, authorIds, mentionSelf, dateFrom, dateTo, limit, cursor, } = args;
+        // Perform global workspace search
+        const response = await client.search.search({
+            query,
+            workspaceId,
+            channelIds,
+            authorIds,
+            mentionSelf,
+            dateFrom,
+            dateTo,
+            limit,
+            cursor,
+        });
+        const results = toRawSearchResults(response.items, 'search-content');
+        const hasMore = response.hasMore;
+        const responseCursor = response.nextCursorMark;
+        // Initialize lookup maps
+        const userLookup = {};
+        let channelLookup = {};
+        // Only fetch user and channel info if there are results
+        if (results.length > 0) {
+            // Collect unique user IDs and channel IDs
+            const userIds = new Set();
+            const channelIdSet = new Set();
+            for (const result of results) {
+                userIds.add(result.creatorId);
+                if (result.type === 'thread' && result.channelId) {
+                    channelIdSet.add(result.channelId);
+                }
+            }
+            // Fetch all users and channels in parallel
+            const uniqueUserIds = Array.from(userIds);
+            const uniqueChannelIds = Array.from(channelIdSet);
+            const [users, channels] = await Promise.all([
+                resolveUsersWithLog(client, ToolNames.SEARCH_CONTENT, 'failed to resolve result author', workspaceId, uniqueUserIds),
+                degradeAllWithLog(ToolNames.SEARCH_CONTENT, 'failed to resolve channel', uniqueChannelIds, (id) => client.channels.getChannel(id)),
+            ]);
+            for (const [id, user] of users) {
+                userLookup[id] = user.fullName;
+            }
+            channelLookup = channels.reduce((acc, channel) => {
+                if (channel)
+                    acc[channel.id] = channel.name;
+                return acc;
+            }, {});
+        }
+        // Build text content
+        const lines = [`# Search Results for "${query}"`, ''];
+        lines.push(`**Search Scope:** Workspace ${workspaceId}`);
+        lines.push(`**Results Found:** ${results.length}`);
+        lines.push(`**More Available:** ${hasMore ? 'Yes' : 'No'}`);
+        lines.push('');
+        if (results.length === 0) {
+            lines.push('_No results found_');
+        }
+        else {
+            lines.push('## Results');
+            lines.push('');
+            for (const result of results) {
+                const date = result.created.split('T')[0];
+                const typeLabel = result.type.charAt(0).toUpperCase() + result.type.slice(1);
+                const creatorName = userLookup[result.creatorId];
+                lines.push(`### ${typeLabel} ${result.id}`);
+                lines.push(`**Created:** ${date} | **Creator:** ${creatorName} (${result.creatorId})`);
+                if (result.type === 'thread') {
+                    lines.push(`**Thread:** ${result.threadId}`);
+                    if (result.commentId) {
+                        lines.push(`**Comment:** ${result.commentId}`);
+                    }
+                    if (result.channelId) {
+                        const channelName = channelLookup[result.channelId];
+                        lines.push(`**Channel:** ${channelName} (${result.channelId})`);
+                    }
+                }
+                else {
+                    lines.push(`**Conversation:** ${result.conversationId}`);
+                    lines.push(`**Message:** ${result.messageId}`);
+                }
+                lines.push('');
+                // Truncate long content
+                const contentPreview = result.content.length > 200
+                    ? `${result.content.substring(0, 200)}...`
+                    : result.content;
+                lines.push(contentPreview);
+                lines.push('');
+            }
+        }
+        if (hasMore) {
+            lines.push('## Next Steps');
+            lines.push('');
+            lines.push('More results available. Use the cursor to fetch the next page.');
+        }
+        const structuredContent = {
+            type: 'search_results',
+            query,
+            workspaceId,
+            results: toSearchResultItems(results, { workspaceId, userLookup, channelLookup }),
+            totalResults: results.length,
+            hasMore,
+            cursor: responseCursor,
+        };
+        return {
+            textContent: lines.join('\n'),
+            structuredContent,
+        };
+    },
+};
+export { searchContent };

package/dist/tools/update-channel.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+declare const updateChannel: {
+    name: "update-channel";
+    description: string;
+    parameters: {
+        channelId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        public: z.ZodOptional<z.ZodBoolean>;
+    };
+    outputSchema: {
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        public: z.ZodBoolean;
+        archived: z.ZodBoolean;
+        created: z.ZodString;
+        channelUrl: z.ZodString;
+        type: z.ZodLiteral<"update_channel_result">;
+        success: z.ZodBoolean;
+        channelId: z.ZodString;
+        workspaceId: z.ZodNumber;
+        creator: z.ZodNumber;
+        userIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        channelId: string;
+        name?: string | undefined;
+        description?: string | null | undefined;
+        public?: boolean | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: {
+            name: string;
+            public: boolean;
+            archived: boolean;
+            created: string;
+            channelUrl: string;
+            type: "update_channel_result";
+            success: boolean;
+            channelId: string;
+            workspaceId: number;
+            creator: number;
+            description?: string | undefined;
+            userIds?: number[] | undefined;
+        };
+    }>;
+};
+export { updateChannel };

package/dist/tools/update-channel.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { UpdateChannelOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+import { getChannelMutationData, getChannelMutationText } from './channel-output.js';
+const ArgsSchema = {
+    channelId: z.string().describe('The channel ID to update.'),
+    name: z.string().min(1).optional().describe('Optional new channel name.'),
+    description: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Optional new channel description. Pass null to clear the description.'),
+    public: z.boolean().optional().describe('Optional visibility update for the channel.'),
+};
+const updateChannel = {
+    name: ToolNames.UPDATE_CHANNEL,
+    description: 'Update a workspace channel. Pass channelId and at least one of name, description, or public. Pass description: null to clear the description.',
+    parameters: ArgsSchema,
+    outputSchema: UpdateChannelOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { channelId, name, description, public: isPublic } = args;
+        if (name === undefined && description === undefined && isPublic === undefined) {
+            throw new Error('At least one of `name`, `description`, or `public` must be provided.');
+        }
+        const updateArgs = {
+            id: channelId,
+            ...(name !== undefined ? { name } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(isPublic !== undefined ? { public: isPublic } : {}),
+        };
+        // The endpoint supports partial updates, but the SDK type currently requires `name`.
+        const channel = await client.channels.updateChannel(updateArgs);
+        const structuredContent = {
+            type: 'update_channel_result',
+            success: true,
+            ...getChannelMutationData(channel),
+        };
+        return {
+            textContent: getChannelMutationText('Channel Updated', channel),
+            structuredContent,
+        };
+    },
+};
+export { updateChannel };

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

@@ -0,0 +1,52 @@
+import { type CommsApi } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { type UpdateObjectStructured } from '../utils/output-schemas.js';
+declare const updateObject: {
+    name: "update-object";
+    description: string;
+    parameters: {
+        targetType: z.ZodEnum<{
+            thread: "thread";
+            comment: "comment";
+            message: "message";
+        }>;
+        targetId: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    };
+    outputSchema: {
+        type: z.ZodEnum<{
+            update_thread_result: "update_thread_result";
+            update_comment_result: "update_comment_result";
+            update_message_result: "update_message_result";
+        }>;
+        success: z.ZodBoolean;
+        content: z.ZodString;
+        workspaceId: z.ZodNumber;
+        lastEdited: z.ZodOptional<z.ZodString>;
+        threadId: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        channelId: z.ZodOptional<z.ZodString>;
+        threadUrl: z.ZodOptional<z.ZodString>;
+        commentId: z.ZodOptional<z.ZodString>;
+        commentUrl: z.ZodOptional<z.ZodString>;
+        messageId: z.ZodOptional<z.ZodString>;
+        conversationId: z.ZodOptional<z.ZodString>;
+        messageUrl: z.ZodOptional<z.ZodString>;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        targetType: "thread" | "comment" | "message";
+        targetId: string;
+        content?: string | undefined;
+        title?: string | undefined;
+    }, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: UpdateObjectStructured;
+    }>;
+};
+export { updateObject };

package/dist/tools/update-object.js

@@ -0,0 +1,161 @@
+import { getFullCommsURL } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { UpdateObjectOutputSchema, } from '../utils/output-schemas.js';
+import { UpdateTargetTypeSchema } from '../utils/target-types.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    targetType: UpdateTargetTypeSchema.describe('The type of object to update: thread, comment, or message.'),
+    targetId: z
+        .string()
+        .describe('The ID of the thread, comment, or conversation message to update.'),
+    content: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The new content/body. Required for comments and messages; for threads, optional if title is provided. 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. Preserve any existing mention links you are not deliberately changing — rewriting them as plain text drops the mention. Editing sends no notifications: this tool has no recipients/groups/notifyAudience, so a mention added here is rendering only.'),
+    title: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The new title. Only valid when targetType is "thread".'),
+};
+async function updateThreadBranch(args, client) {
+    const { targetId, title, content } = args;
+    if (title === undefined && content === undefined) {
+        throw new Error('At least one of `title` or `content` must be provided.');
+    }
+    const thread = await client.threads.updateThread({ id: targetId, title, content });
+    const threadUrl = thread.url ??
+        getFullCommsURL({
+            workspaceId: thread.workspaceId,
+            channelId: thread.channelId,
+            threadId: thread.id,
+        });
+    const lastEdited = thread.lastEdited ? thread.lastEdited.toISOString() : undefined;
+    const lines = [
+        `# Thread Updated`,
+        '',
+        `**Title:** ${thread.title}`,
+        `**Thread ID:** ${thread.id}`,
+        `**Channel ID:** ${thread.channelId}`,
+        ...(lastEdited ? [`**Last Edited:** ${lastEdited}`] : []),
+        `**URL:** ${threadUrl}`,
+        '',
+        '## Content',
+        '',
+        thread.content,
+    ];
+    const structuredContent = {
+        type: 'update_thread_result',
+        success: true,
+        threadId: thread.id,
+        title: thread.title,
+        channelId: thread.channelId,
+        workspaceId: thread.workspaceId,
+        content: thread.content,
+        threadUrl,
+        lastEdited,
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+async function updateCommentBranch(args, client) {
+    const { targetId, content } = args;
+    if (content === undefined) {
+        throw new Error('`content` is required when targetType is "comment".');
+    }
+    const comment = await client.comments.updateComment({ id: targetId, content });
+    const commentUrl = comment.url ??
+        getFullCommsURL({
+            workspaceId: comment.workspaceId,
+            channelId: comment.channelId,
+            threadId: comment.threadId,
+            commentId: comment.id,
+        });
+    const lastEdited = comment.lastEdited ? comment.lastEdited.toISOString() : undefined;
+    const lines = [
+        `# Comment Updated`,
+        '',
+        `**Comment ID:** ${comment.id}`,
+        `**Thread ID:** ${comment.threadId}`,
+        `**Channel ID:** ${comment.channelId}`,
+        ...(lastEdited ? [`**Last Edited:** ${lastEdited}`] : []),
+        `**URL:** ${commentUrl}`,
+        '',
+        '## Content',
+        '',
+        comment.content,
+    ];
+    const structuredContent = {
+        type: 'update_comment_result',
+        success: true,
+        commentId: comment.id,
+        threadId: comment.threadId,
+        channelId: comment.channelId,
+        workspaceId: comment.workspaceId,
+        content: comment.content,
+        commentUrl,
+        lastEdited,
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+async function updateMessageBranch(args, client) {
+    const { targetId, content } = args;
+    if (content === undefined) {
+        throw new Error('`content` is required when targetType is "message".');
+    }
+    const message = await client.conversationMessages.updateMessage({ id: targetId, content });
+    const messageUrl = message.url ??
+        getFullCommsURL({
+            workspaceId: message.workspaceId,
+            conversationId: message.conversationId,
+            messageId: message.id,
+        });
+    const lastEdited = message.lastEdited ? message.lastEdited.toISOString() : undefined;
+    const lines = [
+        `# Message Updated`,
+        '',
+        `**Message ID:** ${message.id}`,
+        `**Conversation ID:** ${message.conversationId}`,
+        `**Workspace ID:** ${message.workspaceId}`,
+        ...(lastEdited ? [`**Last Edited:** ${lastEdited}`] : []),
+        `**URL:** ${messageUrl}`,
+        '',
+        '## Content',
+        '',
+        message.content,
+    ];
+    const structuredContent = {
+        type: 'update_message_result',
+        success: true,
+        messageId: message.id,
+        conversationId: message.conversationId,
+        workspaceId: message.workspaceId,
+        content: message.content,
+        messageUrl,
+        lastEdited,
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+const updateObject = {
+    name: ToolNames.UPDATE_OBJECT,
+    description: 'Update an existing Comms object. `targetType: "thread"` updates a thread\'s title and/or body; `"comment"` updates a thread comment\'s body; `"message"` updates a direct/group conversation message\'s body. Always pass `targetId`. `content` is required for `"comment"` and `"message"`; for `"thread"` it is optional as long as `title` is provided (i.e. a thread can be renamed without re-sending the body). `title` is only valid when `targetType` is `"thread"`.',
+    parameters: ArgsSchema,
+    outputSchema: UpdateObjectOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { targetType, title } = args;
+        if (targetType !== 'thread' && title !== undefined) {
+            throw new Error('`title` is only valid when targetType is "thread".');
+        }
+        const branch = targetType === 'thread'
+            ? await updateThreadBranch(args, client)
+            : targetType === 'comment'
+                ? await updateCommentBranch(args, client)
+                : await updateMessageBranch(args, client);
+        return {
+            textContent: branch.textContent,
+            structuredContent: branch.structuredContent,
+        };
+    },
+};
+export { updateObject };

package/dist/tools/update-user-info.d.ts

@@ -0,0 +1,55 @@
+import { type CommsApi } from '@doist/comms-sdk';
+import { z } from 'zod';
+declare const updateUserInfo: {
+    name: "update-user-info";
+    description: string;
+    parameters: {
+        name: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+        lang: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            message: z.ZodString;
+            emoji: z.ZodOptional<z.ZodString>;
+            activeUntil: z.ZodOptional<z.ZodString>;
+            pauseNotifications: z.ZodOptional<z.ZodBoolean>;
+            pauseActivity: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"user_info">;
+        userId: z.ZodNumber;
+        name: z.ZodString;
+        shortName: z.ZodString;
+        email: z.ZodString;
+        timezone: z.ZodString;
+        lang: z.ZodString;
+        status: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            emoji: z.ZodOptional<z.ZodString>;
+            activeUntil: z.ZodOptional<z.ZodString>;
+            pauseNotifications: z.ZodBoolean;
+            pauseActivity: z.ZodBoolean;
+        }, z.core.$strip>>;
+    };
+    annotations: {
+        readOnlyHint: false;
+        destructiveHint: true;
+        idempotentHint: true;
+    };
+    execute(args: {
+        name?: string | undefined;
+        timezone?: string | undefined;
+        lang?: string | undefined;
+        status?: {
+            message: string;
+            emoji?: string | undefined;
+            activeUntil?: string | undefined;
+            pauseNotifications?: boolean | undefined;
+            pauseActivity?: boolean | undefined;
+        } | null | undefined;
+    }, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: import("./user-output.js").UserInfoStructured;
+    }>;
+};
+export { updateUserInfo };