@todoist/comms-mcp 0.0.1 → 11.0.0

package/dist/tools/get-users.d.ts

@@ -0,0 +1,58 @@
+import { type UserType } from '@doist/comms-sdk';
+import { z } from 'zod';
+type UserData = {
+    id: number;
+    name: string;
+    shortName: string;
+    email?: string;
+    userType?: UserType;
+    removed: boolean;
+    timezone?: string;
+    restricted?: boolean;
+};
+type GetUsersStructured = Record<string, unknown> & {
+    type: 'get_users';
+    workspaceId: number;
+    users: UserData[];
+    totalUsers: number;
+    filteredUsers: number;
+};
+declare const getUsers: {
+    name: "get-users";
+    description: string;
+    parameters: {
+        workspaceId: z.ZodNumber;
+        userIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        searchText: z.ZodOptional<z.ZodString>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"get_users">;
+        workspaceId: z.ZodNumber;
+        users: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            name: z.ZodString;
+            shortName: z.ZodString;
+            email: z.ZodOptional<z.ZodString>;
+            userType: z.ZodOptional<z.ZodString>;
+            removed: z.ZodBoolean;
+            timezone: z.ZodOptional<z.ZodString>;
+            restricted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        totalUsers: z.ZodNumber;
+        filteredUsers: z.ZodNumber;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        workspaceId: number;
+        userIds?: number[] | undefined;
+        searchText?: string | undefined;
+    }, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: GetUsersStructured;
+    }>;
+};
+export { getUsers, type GetUsersStructured };

package/dist/tools/get-users.js

@@ -0,0 +1,107 @@
+import { isRestrictedWorkspaceUser, } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { resolveUsersWithLog } from '../utils/degrade.js';
+import { GetUsersOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+const ArgsSchema = {
+    workspaceId: z.number().describe('The workspace ID to get users from.'),
+    userIds: z
+        .array(z.number())
+        .optional()
+        .describe('Optional array of specific user IDs to fetch. If not provided or empty array, fetches all workspace users.'),
+    searchText: z
+        .string()
+        .optional()
+        .describe('Optional search text to filter users by name or email (case-insensitive).'),
+};
+// A restricted profile carries no email, user type or timezone, so those stay
+// absent rather than being filled with a placeholder.
+function toUserData(user) {
+    const base = {
+        id: user.id,
+        name: user.fullName,
+        shortName: user.shortName,
+        removed: user.removed,
+    };
+    if (isRestrictedWorkspaceUser(user)) {
+        return { ...base, restricted: true };
+    }
+    return {
+        ...base,
+        ...(user.email && { email: user.email }),
+        userType: user.userType,
+        timezone: user.timezone,
+    };
+}
+const getUsers = {
+    name: ToolNames.GET_USERS,
+    description: 'Get users from a workspace. Retrieves all workspace users by default, or specific users if userIds array is provided. Supports optional case-insensitive search filtering by name or email.',
+    parameters: ArgsSchema,
+    outputSchema: GetUsersOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { workspaceId, userIds, searchText } = args;
+        let users;
+        if (!userIds || userIds.length === 0) {
+            users = await client.workspaceUsers.getWorkspaceUsers({ workspaceId });
+        }
+        else {
+            const byId = await resolveUsersWithLog(client, ToolNames.GET_USERS, 'failed to resolve user', workspaceId, userIds);
+            users = userIds.flatMap((id) => byId.get(id) ?? []);
+        }
+        const totalUsers = users.length;
+        // Apply search filter if provided, before building output objects
+        let matchedUsers = users;
+        if (searchText) {
+            const searchLower = searchText.toLowerCase();
+            matchedUsers = users.filter((user) => {
+                const nameMatch = user.fullName.toLowerCase().includes(searchLower);
+                const email = isRestrictedWorkspaceUser(user) ? undefined : user.email;
+                const emailMatch = email?.toLowerCase().includes(searchLower) || false;
+                return nameMatch || emailMatch;
+            });
+        }
+        const filteredUsers = matchedUsers.map(toUserData);
+        // Build text content
+        const lines = ['# Workspace Users', ''];
+        lines.push(`**Workspace ID:** ${workspaceId}`);
+        lines.push(`**Total Users:** ${totalUsers}${searchText ? ` (${filteredUsers.length} matching search)` : ''}`);
+        lines.push('');
+        if (filteredUsers.length === 0) {
+            lines.push('No users found.');
+        }
+        else {
+            for (const user of filteredUsers) {
+                lines.push(`## ${user.name}`);
+                lines.push(`**ID:** ${user.id}`);
+                if (user.email) {
+                    lines.push(`**Email:** ${user.email}`);
+                }
+                if (user.userType) {
+                    lines.push(`**User Type:** ${user.userType}`);
+                }
+                if (user.timezone) {
+                    lines.push(`**Timezone:** ${user.timezone}`);
+                }
+                if (user.restricted) {
+                    lines.push('**Profile:** Restricted, limited visibility of this user');
+                }
+                lines.push(`**Status:** ${user.removed ? 'Removed' : 'Active'}`);
+                lines.push('');
+            }
+        }
+        const textContent = lines.join('\n');
+        const structuredContent = {
+            type: 'get_users',
+            workspaceId,
+            users: filteredUsers,
+            totalUsers,
+            filteredUsers: filteredUsers.length,
+        };
+        return {
+            textContent,
+            structuredContent,
+        };
+    },
+};
+export { getUsers };

package/dist/tools/get-workspaces.d.ts

@@ -0,0 +1,61 @@
+import type { CommsApi, WorkspacePlan } from '@doist/comms-sdk';
+type WorkspaceData = {
+    id: number;
+    name: string;
+    creator: number;
+    creatorName?: string;
+    created: string;
+    url: string;
+    defaultConversation?: string;
+    defaultConversationTitle?: string;
+    defaultConversationUrl?: string;
+    plan?: WorkspacePlan;
+    avatarId?: string;
+    avatarUrls?: {
+        s35: string;
+        s60: string;
+        s195: string;
+        s640: string;
+    };
+};
+type GetWorkspacesStructured = Record<string, unknown> & {
+    type: 'get_workspaces';
+    workspaces: WorkspaceData[];
+};
+declare const getWorkspaces: {
+    name: "get-workspaces";
+    description: string;
+    parameters: {};
+    outputSchema: {
+        type: import("zod").ZodLiteral<"get_workspaces">;
+        workspaces: import("zod").ZodArray<import("zod").ZodObject<{
+            id: import("zod").ZodNumber;
+            name: import("zod").ZodString;
+            creator: import("zod").ZodNumber;
+            creatorName: import("zod").ZodOptional<import("zod").ZodString>;
+            created: import("zod").ZodString;
+            url: import("zod").ZodURL;
+            defaultConversation: import("zod").ZodOptional<import("zod").ZodString>;
+            defaultConversationTitle: import("zod").ZodOptional<import("zod").ZodString>;
+            defaultConversationUrl: import("zod").ZodOptional<import("zod").ZodURL>;
+            plan: import("zod").ZodOptional<import("zod").ZodString>;
+            avatarId: import("zod").ZodOptional<import("zod").ZodString>;
+            avatarUrls: import("zod").ZodOptional<import("zod").ZodObject<{
+                s35: import("zod").ZodString;
+                s60: import("zod").ZodString;
+                s195: import("zod").ZodString;
+                s640: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>>;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(_args: Record<string, never>, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: GetWorkspacesStructured;
+    }>;
+};
+export { getWorkspaces, type GetWorkspacesStructured };

package/dist/tools/get-workspaces.js

@@ -0,0 +1,120 @@
+import { degradeAllWithLog } from '../utils/degrade.js';
+import { GetWorkspacesOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+import { getConversationUrl, getWorkspaceUrl } from '../utils/url-helpers.js';
+const ArgsSchema = {};
+async function generateWorkspacesList(client) {
+    const workspaces = await client.workspaces.getWorkspaces();
+    if (workspaces.length === 0) {
+        return {
+            textContent: '# Workspaces\n\nNo workspaces found.',
+            structuredContent: {
+                type: 'get_workspaces',
+                workspaces: [],
+            },
+        };
+    }
+    // Collect default conversation IDs (paired with the workspace they belong to)
+    // and unique creator IDs (paired with workspace IDs so we can do per-workspace
+    // user lookups).
+    const defaultConversationPairs = [];
+    const creatorPairs = [];
+    for (const workspace of workspaces) {
+        if (workspace.defaultConversation) {
+            defaultConversationPairs.push({
+                workspaceId: workspace.id,
+                conversationId: workspace.defaultConversation,
+            });
+        }
+        creatorPairs.push({ workspaceId: workspace.id, creatorId: workspace.creator });
+    }
+    // Fetch default conversations
+    const conversationLookup = {};
+    if (defaultConversationPairs.length > 0) {
+        const conversations = await degradeAllWithLog(ToolNames.GET_WORKSPACES, 'failed to resolve default conversation', defaultConversationPairs, ({ conversationId }) => client.conversations.getConversation(conversationId));
+        for (let i = 0; i < defaultConversationPairs.length; i++) {
+            const pair = defaultConversationPairs[i];
+            const conversation = conversations[i];
+            if (pair && conversation) {
+                const title = conversation.title ||
+                    `Conversation with users: ${conversation.userIds.join(', ')}`;
+                conversationLookup[pair.conversationId] = title;
+            }
+        }
+    }
+    // Fetch all workspace creators
+    const creatorLookup = {};
+    if (creatorPairs.length > 0) {
+        const users = await degradeAllWithLog(ToolNames.GET_WORKSPACES, 'failed to resolve workspace creator', creatorPairs, ({ workspaceId, creatorId }) => client.workspaceUsers.getUserById({ workspaceId, userId: creatorId }));
+        for (let i = 0; i < creatorPairs.length; i++) {
+            const pair = creatorPairs[i];
+            const user = users[i];
+            if (pair && user) {
+                creatorLookup[pair.creatorId] = user.fullName;
+            }
+        }
+    }
+    const lines = ['# Workspaces', ''];
+    lines.push(`Found ${workspaces.length} workspace${workspaces.length === 1 ? '' : 's'}:`, '');
+    for (const workspace of workspaces) {
+        const creatorName = creatorLookup[workspace.creator];
+        const defaultConversationTitle = workspace.defaultConversation
+            ? conversationLookup[workspace.defaultConversation]
+            : undefined;
+        lines.push(`## [${workspace.name}](${getWorkspaceUrl(workspace.id)})`);
+        lines.push(`**ID:** ${workspace.id}`);
+        lines.push(`**Creator:** ${creatorName ? `${creatorName} (${workspace.creator})` : workspace.creator}`);
+        lines.push(`**Created:** ${workspace.created.toISOString()}`);
+        if (workspace.defaultConversation) {
+            const conversationUrl = getConversationUrl(workspace.id, workspace.defaultConversation);
+            lines.push(`**Default Conversation:** ${defaultConversationTitle ? `[${defaultConversationTitle}](${conversationUrl}) (${workspace.defaultConversation})` : `[${workspace.defaultConversation}](${conversationUrl})`}`);
+        }
+        if (workspace.plan) {
+            lines.push(`**Plan:** ${workspace.plan}`);
+        }
+        lines.push('');
+    }
+    const textContent = lines.join('\n');
+    const structuredContent = {
+        type: 'get_workspaces',
+        workspaces: workspaces.map((workspace) => ({
+            id: workspace.id,
+            name: workspace.name,
+            creator: workspace.creator,
+            ...(creatorLookup[workspace.creator] && {
+                creatorName: creatorLookup[workspace.creator],
+            }),
+            created: workspace.created.toISOString(),
+            url: getWorkspaceUrl(workspace.id),
+            ...(workspace.defaultConversation && {
+                defaultConversation: workspace.defaultConversation,
+            }),
+            ...(workspace.defaultConversation &&
+                conversationLookup[workspace.defaultConversation] && {
+                defaultConversationTitle: conversationLookup[workspace.defaultConversation],
+            }),
+            ...(workspace.defaultConversation && {
+                defaultConversationUrl: getConversationUrl(workspace.id, workspace.defaultConversation),
+            }),
+            ...(workspace.plan && { plan: workspace.plan }),
+            ...(workspace.avatarId && { avatarId: workspace.avatarId }),
+            ...(workspace.avatarUrls && { avatarUrls: workspace.avatarUrls }),
+        })),
+    };
+    return { textContent, structuredContent };
+}
+const getWorkspaces = {
+    name: ToolNames.GET_WORKSPACES,
+    description: 'Get all workspaces that the user belongs to. Returns a list of workspaces with their IDs, names, creators, creation dates, default conversation, and plan information.',
+    parameters: ArgsSchema,
+    outputSchema: GetWorkspacesOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(_args, client) {
+        const result = await generateWorkspacesList(client);
+        return {
+            textContent: result.textContent,
+            structuredContent: result.structuredContent,
+        };
+    },
+};
+export { getWorkspaces };

package/dist/tools/list-channels.d.ts

@@ -0,0 +1,47 @@
+import type { CommsApi } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { type ChannelListData } from './channel-output.js';
+type ListChannelsStructured = Record<string, unknown> & {
+    type: 'list_channels';
+    workspaceId: number;
+    channels: ChannelListData[];
+    totalChannels: number;
+};
+declare const listChannels: {
+    name: "list-channels";
+    description: string;
+    parameters: {
+        workspaceId: z.ZodNumber;
+        includeArchived: z.ZodOptional<z.ZodBoolean>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"list_channels">;
+        workspaceId: z.ZodNumber;
+        channels: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            public: z.ZodBoolean;
+            archived: z.ZodBoolean;
+            created: z.ZodString;
+            channelUrl: z.ZodString;
+            id: z.ZodString;
+            creatorId: z.ZodNumber;
+            creatorName: z.ZodOptional<z.ZodString>;
+            color: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        totalChannels: z.ZodNumber;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        workspaceId: number;
+        includeArchived?: boolean | undefined;
+    }, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: ListChannelsStructured;
+    }>;
+};
+export { listChannels, type ListChannelsStructured };

package/dist/tools/list-channels.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { resolveUsersWithLog } from '../utils/degrade.js';
+import { ListChannelsOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+import { getChannelListData } from './channel-output.js';
+const ArgsSchema = {
+    workspaceId: z.number().describe('The workspace ID to list channels from.'),
+    includeArchived: z
+        .boolean()
+        .optional()
+        .describe('Whether to include archived channels. If true, both active and archived channels are returned. Defaults to false (active channels only).'),
+};
+async function generateChannelsList(client, workspaceId, includeArchived) {
+    // By default only fetch active channels; optionally include archived ones too
+    let channels;
+    if (includeArchived) {
+        const [active, archived] = await Promise.all([
+            client.channels.getChannels({ workspaceId }),
+            client.channels.getChannels({ workspaceId, archived: true }),
+        ]);
+        channels = [...active, ...archived];
+    }
+    else {
+        channels = await client.channels.getChannels({ workspaceId });
+    }
+    if (channels.length === 0) {
+        return {
+            textContent: '# Channels\n\nNo channels found.',
+            structuredContent: {
+                type: 'list_channels',
+                workspaceId,
+                channels: [],
+                totalChannels: 0,
+            },
+        };
+    }
+    // Collect unique creator IDs and fetch their names
+    const creatorIds = new Set();
+    for (const channel of channels) {
+        creatorIds.add(channel.creator);
+    }
+    // A deleted/inaccessible creator doesn't fail the whole list — the fallback
+    // path (creator ID without a name) is exercised by the text output.
+    const users = await resolveUsersWithLog(client, ToolNames.LIST_CHANNELS, 'failed to resolve channel creator', workspaceId, Array.from(creatorIds));
+    const creatorLookup = {};
+    for (const [id, user] of users) {
+        creatorLookup[id] = user.fullName;
+    }
+    const lines = ['# Channels', ''];
+    lines.push(`Found ${channels.length} channel${channels.length === 1 ? '' : 's'} in workspace ${workspaceId}:`, '');
+    for (const channel of channels) {
+        const creatorName = creatorLookup[channel.creator];
+        const channelData = getChannelListData(channel, creatorName);
+        lines.push(`## [${channelData.name}](${channelData.channelUrl})`);
+        lines.push(`**ID:** ${channel.id}`);
+        lines.push(`**Public:** ${channelData.public ? 'Yes' : 'No'}`);
+        lines.push(`**Archived:** ${channelData.archived ? 'Yes' : 'No'}`);
+        lines.push(`**Creator:** ${creatorName ? `${creatorName} (${channel.creator})` : channel.creator}`);
+        lines.push(`**Created:** ${channelData.created}`);
+        if (channelData.description != null) {
+            lines.push(`**Description:** ${channelData.description}`);
+        }
+        lines.push('');
+    }
+    const textContent = lines.join('\n');
+    const structuredContent = {
+        type: 'list_channels',
+        workspaceId,
+        channels: channels.map((channel) => getChannelListData(channel, creatorLookup[channel.creator])),
+        totalChannels: channels.length,
+    };
+    return { textContent, structuredContent };
+}
+const listChannels = {
+    name: ToolNames.LIST_CHANNELS,
+    description: 'List channels in a workspace. By default returns only active channels; set includeArchived to true to also include archived channels. Returns channel IDs, names, descriptions, visibility (public/private), archive status, creators, creation dates, URLs, and colors.',
+    parameters: ArgsSchema,
+    outputSchema: ListChannelsOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(args, client) {
+        const { workspaceId, includeArchived = false } = args;
+        const result = await generateChannelsList(client, workspaceId, includeArchived);
+        return {
+            textContent: result.textContent,
+            structuredContent: result.structuredContent,
+        };
+    },
+};
+export { listChannels };

package/dist/tools/list-conversations.d.ts

@@ -0,0 +1,66 @@
+import { type CommsApi } from '@doist/comms-sdk';
+import { z } from 'zod';
+type ConversationData = {
+    id: string;
+    workspaceId: number;
+    title?: string;
+    userIds: number[];
+    participantNames?: string[];
+    archived: boolean;
+    lastActive: string;
+    snippet?: string;
+    conversationUrl: string;
+};
+type ListConversationsStructured = Record<string, unknown> & {
+    type: 'list_conversations';
+    workspaceId: number;
+    conversations: ConversationData[];
+    totalConversations: number;
+    hasMore?: boolean;
+    cursor?: string;
+};
+declare const listConversations: {
+    name: "list-conversations";
+    description: string;
+    parameters: {
+        workspaceId: z.ZodNumber;
+        includeArchived: z.ZodOptional<z.ZodBoolean>;
+        searchText: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    };
+    outputSchema: {
+        type: z.ZodLiteral<"list_conversations">;
+        workspaceId: z.ZodNumber;
+        conversations: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            workspaceId: z.ZodNumber;
+            title: z.ZodOptional<z.ZodString>;
+            userIds: z.ZodArray<z.ZodNumber>;
+            participantNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            archived: z.ZodBoolean;
+            lastActive: z.ZodString;
+            snippet: z.ZodOptional<z.ZodString>;
+            conversationUrl: z.ZodString;
+        }, z.core.$strip>>;
+        totalConversations: z.ZodNumber;
+        hasMore: z.ZodOptional<z.ZodBoolean>;
+        cursor: z.ZodOptional<z.ZodString>;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(args: {
+        workspaceId: number;
+        includeArchived?: boolean | undefined;
+        searchText?: string | undefined;
+        limit?: number | undefined;
+        cursor?: string | undefined;
+    }, client: CommsApi): Promise<{
+        textContent: string;
+        structuredContent: ListConversationsStructured;
+    }>;
+};
+export { listConversations, type ListConversationsStructured };