@todoist/comms-mcp 0.0.0-stage → 11.0.0

package/dist/tools/list-conversations.js

@@ -0,0 +1,212 @@
+import { isNotFound } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { limitedAll } from '../utils/concurrency.js';
+import { resolveUsersWithLog } from '../utils/degrade.js';
+import { ListConversationsOutputSchema } 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 workspace ID to list conversations from.'),
+    includeArchived: z
+        .boolean()
+        .optional()
+        .describe('Whether to include archived conversations. If true, both active and archived conversations are returned. Defaults to false (active conversations only).'),
+    searchText: z
+        .string()
+        .optional()
+        .describe('Optional search text to find group chats by title. Matches whole words in the titles of titled group chats only: direct messages, untitled group chats, and participant names do not match.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Maximum number of search results per page. Only used with searchText. Defaults to 20.'),
+    cursor: z
+        .string()
+        .optional()
+        .describe('Cursor for the next page of search results. Only used with searchText.'),
+};
+// Only resolve names for the first few participants of each conversation. A large
+// group DM would otherwise produce an unbounded participant string; callers that
+// need every participant should load the conversation directly. The full set of
+// participant IDs is still returned in `userIds`.
+const MAX_DISPLAYED_PARTICIPANTS = 5;
+const DEFAULT_SEARCH_LIMIT = 20;
+// Resolve user IDs to names. IDs that can't be resolved are simply absent from
+// the returned map.
+async function resolveParticipantNames(client, workspaceId, userIds) {
+    const users = await resolveUsersWithLog(client, ToolNames.LIST_CONVERSATIONS, 'failed to resolve conversation participant', workspaceId, userIds);
+    const lookup = {};
+    for (const [id, user] of users) {
+        lookup[id] = user.fullName;
+    }
+    return lookup;
+}
+async function searchConversations(client, workspaceId, includeArchived, { searchText, limit, cursor }) {
+    const { items, hasMore, nextCursorMark } = await client.search.search({
+        type: 'conversations',
+        query: searchText,
+        workspaceId,
+        limit,
+        cursor,
+    });
+    const conversationIds = new Set(items.flatMap((hit) => hit.type === 'conversation' && hit.conversationId ? [hit.conversationId] : []));
+    const conversations = await limitedAll([...conversationIds], async (id) => {
+        try {
+            return await client.conversations.getConversation(id);
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return null;
+            }
+            throw error;
+        }
+    });
+    const dropped = conversations.filter((conversation) => conversation === null).length;
+    if (dropped > 0) {
+        console.error(`${ToolNames.LIST_CONVERSATIONS}: dropped search hits for missing conversations`, { dropped, of: conversations.length });
+    }
+    return {
+        conversations: conversations.filter((conversation) => conversation !== null && (includeArchived || !conversation.archived)),
+        hasMore,
+        cursor: nextCursorMark,
+    };
+}
+function getSearchPageOutput(searchPage) {
+    if (!searchPage) {
+        return { lines: [], fields: {} };
+    }
+    const { hasMore, cursor } = searchPage;
+    return {
+        lines: hasMore
+            ? [
+                '## Next Steps',
+                '',
+                'More results available. Use the cursor to fetch the next page.',
+            ]
+            : [],
+        fields: { hasMore, ...(cursor && { cursor }) },
+    };
+}
+async function generateConversationsList(client, workspaceId, includeArchived, search) {
+    // By default only fetch active conversations; optionally include archived ones too
+    let conversations;
+    let searchPage;
+    if (search) {
+        searchPage = await searchConversations(client, workspaceId, includeArchived, search);
+        conversations = searchPage.conversations;
+    }
+    else if (includeArchived) {
+        const [active, archived] = await Promise.all([
+            client.conversations.getConversations({ workspaceId }),
+            client.conversations.getConversations({ workspaceId, archived: true }),
+        ]);
+        conversations = [...active, ...archived];
+    }
+    else {
+        conversations = await client.conversations.getConversations({ workspaceId });
+    }
+    const searchPageOutput = getSearchPageOutput(searchPage);
+    if (conversations.length === 0) {
+        return {
+            textContent: [
+                '# Conversations',
+                '',
+                'No conversations found.',
+                ...(searchPageOutput.lines.length > 0 ? ['', ...searchPageOutput.lines] : []),
+            ].join('\n'),
+            structuredContent: {
+                type: 'list_conversations',
+                workspaceId,
+                conversations: [],
+                totalConversations: 0,
+                ...searchPageOutput.fields,
+            },
+        };
+    }
+    // Only the first few participants of each conversation are displayed, so only
+    // those names need resolving. Collect them into a deduplicated set.
+    const displayUserIdsByConversation = new Map();
+    const idsToResolve = new Set();
+    for (const conversation of conversations) {
+        const displayIds = conversation.userIds.slice(0, MAX_DISPLAYED_PARTICIPANTS);
+        displayUserIdsByConversation.set(conversation.id, displayIds);
+        for (const userId of displayIds) {
+            idsToResolve.add(userId);
+        }
+    }
+    const participantLookup = await resolveParticipantNames(client, workspaceId, Array.from(idsToResolve));
+    // Names for the displayed participants, positionally aligned with the first
+    // entries of the conversation's `userIds`. An ID that couldn't be resolved to a
+    // name falls back to its stringified ID so alignment is preserved.
+    function displayNamesFor(displayIds) {
+        return displayIds.map((id) => participantLookup[id] ?? String(id));
+    }
+    const lines = ['# Conversations', ''];
+    lines.push(`Found ${conversations.length} conversation${conversations.length === 1 ? '' : 's'} in workspace ${workspaceId}:`, '');
+    for (const conversation of conversations) {
+        const conversationUrl = conversation.url ?? getConversationUrl(workspaceId, conversation.id);
+        const heading = conversation.title?.trim()
+            ? conversation.title
+            : `Conversation ${conversation.id}`;
+        lines.push(`## [${heading}](${conversationUrl})`);
+        lines.push(`**ID:** ${conversation.id}`);
+        lines.push(`**Archived:** ${conversation.archived ? 'Yes' : 'No'}`);
+        lines.push(`**Last Active:** ${conversation.lastActive.toISOString()}`);
+        const displayIds = displayUserIdsByConversation.get(conversation.id) ?? [];
+        const displayNames = displayNamesFor(displayIds);
+        const remaining = conversation.userIds.length - displayIds.length;
+        const participantsSummary = remaining > 0
+            ? `${displayNames.join(', ')}, and ${remaining} more`
+            : displayNames.join(', ');
+        lines.push(`**Participants:** ${participantsSummary}`);
+        if (conversation.snippet) {
+            lines.push(`**Snippet:** ${conversation.snippet}`);
+        }
+        lines.push('');
+    }
+    lines.push(...searchPageOutput.lines);
+    const textContent = lines.join('\n');
+    const structuredContent = {
+        type: 'list_conversations',
+        workspaceId,
+        conversations: conversations.map((conversation) => {
+            const displayIds = displayUserIdsByConversation.get(conversation.id) ?? [];
+            const displayNames = displayNamesFor(displayIds);
+            return {
+                id: conversation.id,
+                workspaceId: conversation.workspaceId,
+                ...(conversation.title && { title: conversation.title }),
+                userIds: conversation.userIds,
+                ...(displayNames.length > 0 && { participantNames: displayNames }),
+                archived: conversation.archived,
+                lastActive: conversation.lastActive.toISOString(),
+                ...(conversation.snippet && { snippet: conversation.snippet }),
+                conversationUrl: conversation.url ?? getConversationUrl(workspaceId, conversation.id),
+            };
+        }),
+        totalConversations: conversations.length,
+        ...searchPageOutput.fields,
+    };
+    return { textContent, structuredContent };
+}
+const listConversations = {
+    name: ToolNames.LIST_CONVERSATIONS,
+    description: 'List conversations (direct messages and group chats) in a workspace, or find group chats by title with searchText. Without searchText, returns the first page of conversations. searchText matches whole words in the titles of titled group chats only: direct messages, untitled group chats, and participant names do not match. Its results are paged with limit and cursor, and a page can have fewer results than limit, so follow hasMore. By default returns only active conversations; set includeArchived to true to also include archived conversations. Returns conversation IDs, titles, the full list of participant user IDs (with names resolved for the first few), archive status, last-active timestamps, snippets, and URLs.',
+    parameters: ArgsSchema,
+    outputSchema: ListConversationsOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { workspaceId, includeArchived = false, searchText, limit, cursor } = args;
+        if (!searchText && (limit !== undefined || cursor !== undefined)) {
+            throw new Error('`limit` and `cursor` require `searchText`.');
+        }
+        const result = await generateConversationsList(client, workspaceId, includeArchived, searchText ? { searchText, limit: limit ?? DEFAULT_SEARCH_LIMIT, cursor } : undefined);
+        return {
+            textContent: result.textContent,
+            structuredContent: result.structuredContent,
+        };
+    },
+};
+export { listConversations };

package/dist/tools/load-conversation.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { type OutputAttachment } from '../utils/output-schemas.js';
+type LoadConversationStructured = {
+    type: 'conversation_data';
+    conversation: {
+        id: string;
+        workspaceId: number;
+        userIds: number[];
+        archived: boolean;
+        lastActive: string;
+        title?: string;
+        conversationUrl: string;
+    };
+    messages: Array<{
+        id: string;
+        content: string;
+        creatorId: number;
+        creatorName?: string;
+        conversationId: string;
+        posted: string;
+        messageUrl: string;
+        attachments?: OutputAttachment[];
+    }>;
+    totalMessages: number;
+};
+declare const loadConversation: {
+    name: "load-conversation";
+    description: string;
+    parameters: {
+        conversationId: z.ZodString;
+        newerThanDate: z.ZodOptional<z.ZodString>;
+        olderThanDate: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        includeParticipants: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"conversation_data">;
+        conversation: z.ZodObject<{
+            id: z.ZodString;
+            workspaceId: z.ZodNumber;
+            userIds: z.ZodArray<z.ZodNumber>;
+            archived: z.ZodBoolean;
+            lastActive: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            conversationUrl: z.ZodString;
+        }, z.core.$strip>;
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            content: z.ZodString;
+            creatorId: z.ZodNumber;
+            creatorName: z.ZodOptional<z.ZodString>;
+            conversationId: z.ZodString;
+            posted: z.ZodString;
+            messageUrl: z.ZodString;
+            attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                attachmentId: z.ZodString;
+                urlType: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                url: z.ZodOptional<z.ZodString>;
+                fileName: z.ZodOptional<z.ZodString>;
+                fileSize: z.ZodOptional<z.ZodNumber>;
+                underlyingType: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodString>;
+                imageWidth: z.ZodOptional<z.ZodNumber>;
+                imageHeight: z.ZodOptional<z.ZodNumber>;
+                duration: z.ZodOptional<z.ZodString>;
+                uploadState: z.ZodOptional<z.ZodString>;
+                video: z.ZodOptional<z.ZodString>;
+                videoType: z.ZodOptional<z.ZodString>;
+                videoAutoPlay: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>>;
+        }, z.core.$strip>>;
+        totalMessages: z.ZodNumber;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        conversationId: string;
+        limit: number;
+        includeParticipants: boolean;
+        newerThanDate?: string | undefined;
+        olderThanDate?: string | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: LoadConversationStructured;
+    }>;
+};
+export { loadConversation, type LoadConversationStructured };

package/dist/tools/load-conversation.js

@@ -0,0 +1,128 @@
+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 { LoadConversationOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    conversationId: z.string().describe('The conversation ID to load.'),
+    newerThanDate: z
+        .string()
+        .optional()
+        .describe('Get messages newer than this date (YYYY-MM-DD format).'),
+    olderThanDate: z
+        .string()
+        .optional()
+        .describe('Get messages older than this date (YYYY-MM-DD format).'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .default(50)
+        .describe('Maximum number of messages to return.'),
+    includeParticipants: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include participant user IDs in the response.'),
+};
+const loadConversation = {
+    name: ToolNames.LOAD_CONVERSATION,
+    description: 'Load a conversation (direct message) with its metadata and messages. Supports filtering by timestamp and pagination.',
+    parameters: ArgsSchema,
+    outputSchema: LoadConversationOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { conversationId, newerThanDate, olderThanDate, limit, includeParticipants } = args;
+        // Fetch conversation metadata and messages in parallel
+        const [conversation, messages] = await Promise.all([
+            client.conversations.getConversation(conversationId),
+            client.conversationMessages.getMessages({
+                conversationId,
+                newerThan: newerThanDate ? new Date(newerThanDate) : undefined,
+                olderThan: olderThanDate ? new Date(olderThanDate) : undefined,
+                limit,
+            }),
+        ]);
+        const { userIds } = conversation;
+        // A participant that cannot be resolved is dropped rather than failing the
+        // whole conversation; the message list matters more than every name.
+        const userInfo = await resolveUsersWithLog(client, ToolNames.LOAD_CONVERSATION, 'failed to resolve conversation participant', conversation.workspaceId, userIds);
+        // Build text content
+        const lines = [
+            `# Conversation ${conversationId}`,
+            '',
+            `**Conversation ID:** ${conversation.id}`,
+            ...(conversation.title ? [`**Title:** ${conversation.title}`] : []),
+            `**Workspace ID:** ${conversation.workspaceId}`,
+            `**Archived:** ${conversation.archived ? 'Yes' : 'No'}`,
+            `**Last Active:** ${conversation.lastActive.toISOString()}`,
+            '',
+        ];
+        if (includeParticipants) {
+            lines.push('## Participants');
+            lines.push('');
+            lines.push(conversation.userIds
+                .map((id) => userInfo.get(id)?.fullName ?? UNKNOWN_USER)
+                .join(', '));
+            lines.push('');
+        }
+        lines.push(`## Messages (${messages.length})`);
+        lines.push('');
+        // Normalised once per message, for both the text and the structured content.
+        const attachmentsByMessage = new Map(messages.map((m) => [m.id, normalizeAttachments(m.attachments)]));
+        for (const message of messages) {
+            const messageDate = message.posted.toISOString();
+            lines.push(`### Message ${message.id}`);
+            lines.push(`**Creator:** ${userInfo.get(message.creator)?.fullName ?? UNKNOWN_USER} | **Posted:** ${messageDate}`);
+            lines.push('');
+            lines.push(message.content);
+            const attachmentsLine = formatAttachmentsLine(attachmentsByMessage.get(message.id));
+            if (attachmentsLine) {
+                lines.push('');
+                lines.push(attachmentsLine);
+            }
+            lines.push('');
+        }
+        const structuredContent = {
+            type: 'conversation_data',
+            conversation: {
+                id: conversation.id,
+                title: conversation.title ?? undefined,
+                workspaceId: conversation.workspaceId,
+                userIds: includeParticipants ? conversation.userIds : [],
+                archived: conversation.archived,
+                lastActive: conversation.lastActive.toISOString(),
+                conversationUrl: conversation.url ??
+                    getFullCommsURL({
+                        workspaceId: conversation.workspaceId,
+                        conversationId: conversation.id,
+                    }),
+            },
+            messages: messages.map((m) => ({
+                id: m.id,
+                content: m.content,
+                creatorId: m.creator,
+                creatorName: userInfo.get(m.creator)?.fullName,
+                conversationId: m.conversationId,
+                posted: m.posted.toISOString(),
+                messageUrl: m.url ??
+                    getFullCommsURL({
+                        workspaceId: m.workspaceId,
+                        conversationId: m.conversationId,
+                        messageId: m.id,
+                    }),
+                attachments: attachmentsByMessage.get(m.id),
+            })),
+            totalMessages: conversation.messageCount ?? 0,
+        };
+        return {
+            textContent: lines.join('\n'),
+            structuredContent,
+        };
+    },
+};
+export { loadConversation };

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

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { type OutputAttachment } from '../utils/output-schemas.js';
+type LoadThreadStructured = {
+    type: 'thread_data';
+    thread: {
+        id: string;
+        title: string;
+        content: string;
+        channelId: string;
+        channelName?: string;
+        workspaceId: number;
+        creator: number;
+        creatorName?: string;
+        posted: string;
+        commentCount: number;
+        isArchived: boolean;
+        inInbox: boolean;
+        participants?: number[];
+        participantNames?: string[];
+        threadUrl: string;
+        attachments?: OutputAttachment[];
+    };
+    comments: Array<{
+        id: string;
+        content: string;
+        creator: number;
+        creatorName?: string;
+        threadId: string;
+        posted: string;
+        commentUrl: string;
+        attachments?: OutputAttachment[];
+    }>;
+    totalComments: number;
+};
+declare const loadThread: {
+    name: "load-thread";
+    description: string;
+    parameters: {
+        threadId: z.ZodString;
+        newerThanDate: z.ZodOptional<z.ZodString>;
+        olderThanDate: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        includeParticipants: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"thread_data">;
+        thread: z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            content: z.ZodString;
+            channelId: z.ZodString;
+            channelName: z.ZodOptional<z.ZodString>;
+            workspaceId: z.ZodNumber;
+            creator: z.ZodNumber;
+            creatorName: z.ZodOptional<z.ZodString>;
+            posted: z.ZodString;
+            commentCount: z.ZodNumber;
+            isArchived: z.ZodBoolean;
+            inInbox: z.ZodBoolean;
+            participants: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+            participantNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            threadUrl: z.ZodString;
+            attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                attachmentId: z.ZodString;
+                urlType: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                url: z.ZodOptional<z.ZodString>;
+                fileName: z.ZodOptional<z.ZodString>;
+                fileSize: z.ZodOptional<z.ZodNumber>;
+                underlyingType: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodString>;
+                imageWidth: z.ZodOptional<z.ZodNumber>;
+                imageHeight: z.ZodOptional<z.ZodNumber>;
+                duration: z.ZodOptional<z.ZodString>;
+                uploadState: z.ZodOptional<z.ZodString>;
+                video: z.ZodOptional<z.ZodString>;
+                videoType: z.ZodOptional<z.ZodString>;
+                videoAutoPlay: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>>;
+        }, z.core.$strip>;
+        comments: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            content: z.ZodString;
+            creator: z.ZodNumber;
+            creatorName: z.ZodOptional<z.ZodString>;
+            threadId: z.ZodString;
+            posted: z.ZodString;
+            commentUrl: z.ZodString;
+            attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                attachmentId: z.ZodString;
+                urlType: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                url: z.ZodOptional<z.ZodString>;
+                fileName: z.ZodOptional<z.ZodString>;
+                fileSize: z.ZodOptional<z.ZodNumber>;
+                underlyingType: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodString>;
+                imageWidth: z.ZodOptional<z.ZodNumber>;
+                imageHeight: z.ZodOptional<z.ZodNumber>;
+                duration: z.ZodOptional<z.ZodString>;
+                uploadState: z.ZodOptional<z.ZodString>;
+                video: z.ZodOptional<z.ZodString>;
+                videoType: z.ZodOptional<z.ZodString>;
+                videoAutoPlay: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>>;
+        }, z.core.$strip>>;
+        totalComments: z.ZodNumber;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        threadId: string;
+        limit: number;
+        includeParticipants: boolean;
+        newerThanDate?: string | undefined;
+        olderThanDate?: string | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: LoadThreadStructured;
+    }>;
+};
+export { loadThread, type LoadThreadStructured };