@todoist/comms-mcp 0.0.1 → 11.0.0

package/dist/utils/output-schemas.js

@@ -0,0 +1,657 @@
+import { ChannelSchema, CommentSchema, ConversationMessageSchema, ConversationSchema, InboxThreadSchema, NOTIFY_AUDIENCES, SearchResultSchema, ThreadSchema, UnreadConversationSchema, UnreadThreadSchema, UserSchema, WorkspaceSchema, WorkspaceUserSchema, } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { MarkReadItemTypeSchema } from './target-types.js';
+// Re-export SDK schemas for direct use
+export { ChannelSchema, CommentSchema, ConversationMessageSchema, ConversationSchema, InboxThreadSchema, SearchResultSchema, ThreadSchema, UnreadConversationSchema, UnreadThreadSchema, UserSchema, WorkspaceSchema, WorkspaceUserSchema, };
+// Custom schemas for tool-specific structured outputs.
+//
+// ID typing in the Comms API:
+//   - channel/thread/comment/conversation/message/group IDs are opaque
+//     base58-encoded UUIDv7 strings.
+//   - workspaceId and userId are numeric.
+/**
+ * Schema for a Comms attachment as returned by the API, mirroring the SDK's
+ * `AttachmentSchema` field-for-field.
+ *
+ * The SDK ships its own bundled copy of zod, so composing the SDK's
+ * `AttachmentSchema` directly into the output schemas below trips TypeScript's
+ * portable-type-name check (TS2883). To keep the real field types in structured
+ * output we model the same shape here in the project's zod, and bind it to the
+ * SDK's `Attachment` type so the two can't silently drift. `looseObject`
+ * preserves the SDK's `$loose` behaviour: fields the API adds forward-pass
+ * untouched without an MCP release.
+ *
+ * Note: an attachment's `url` points at the Comms file store and currently
+ * requires a browser session cookie to download — there is no OAuth-authenticated
+ * attachment download endpoint on the public Comms REST API today.
+ */
+const AttachmentSchema = z.looseObject({
+    attachmentId: z.string(),
+    urlType: z.string(),
+    title: z.string().optional(),
+    url: z.string().optional(),
+    fileName: z.string().optional(),
+    fileSize: z.number().optional(),
+    underlyingType: z.string().optional(),
+    description: z.string().optional(),
+    image: z.string().optional(),
+    imageWidth: z.number().optional(),
+    imageHeight: z.number().optional(),
+    duration: z.string().optional(),
+    uploadState: z.string().optional(),
+    video: z.string().optional(),
+    videoType: z.string().optional(),
+    videoAutoPlay: z.boolean().optional(),
+});
+/**
+ * Schema for load-thread tool output
+ */
+export const LoadThreadOutputSchema = z.object({
+    type: z.literal('thread_data'),
+    thread: z.object({
+        id: z.string(),
+        title: z.string(),
+        content: z.string(),
+        channelId: z.string(),
+        channelName: z.string().optional(),
+        workspaceId: z.number(),
+        creator: z.number(),
+        creatorName: z.string().optional(),
+        posted: z.string(),
+        commentCount: z.number(),
+        isArchived: z.boolean(),
+        inInbox: z.boolean(),
+        participants: z.array(z.number()).optional(),
+        participantNames: z.array(z.string()).optional(),
+        threadUrl: z.string(),
+        attachments: z.array(AttachmentSchema).optional(),
+    }),
+    comments: z.array(z.object({
+        id: z.string(),
+        content: z.string(),
+        creator: z.number(),
+        creatorName: z.string().optional(),
+        threadId: z.string(),
+        posted: z.string(),
+        commentUrl: z.string(),
+        attachments: z.array(AttachmentSchema).optional(),
+    })),
+    totalComments: z.number(),
+});
+/**
+ * Schema for load-conversation tool output
+ */
+export const LoadConversationOutputSchema = z.object({
+    type: z.literal('conversation_data'),
+    conversation: z.object({
+        id: z.string(),
+        workspaceId: z.number(),
+        userIds: z.array(z.number()),
+        archived: z.boolean(),
+        lastActive: z.string(),
+        title: z.string().optional(),
+        conversationUrl: z.string(),
+    }),
+    messages: z.array(z.object({
+        id: z.string(),
+        content: z.string(),
+        creatorId: z.number(),
+        creatorName: z.string().optional(),
+        conversationId: z.string(),
+        posted: z.string(),
+        messageUrl: z.string(),
+        attachments: z.array(AttachmentSchema).optional(),
+    })),
+    totalMessages: z.number(),
+});
+/**
+ * Schema for fetch-inbox tool output
+ */
+export const FetchInboxOutputSchema = z.object({
+    type: z.literal('inbox_data'),
+    workspaceId: z.number(),
+    threads: z.array(z.object({
+        id: z.string(),
+        title: z.string(),
+        channelId: z.string(),
+        channelName: z.string().optional(),
+        creator: z.number(),
+        isUnread: z.boolean(),
+        isArchived: z.boolean(),
+        isStarred: z.boolean(),
+        threadUrl: z.string(),
+    })),
+    conversations: z.array(z.object({
+        id: z.string(),
+        title: z.string(),
+        userIds: z.array(z.number()),
+        participantNames: z.array(z.string()),
+        isUnread: z.boolean(),
+        conversationUrl: z.string(),
+    })),
+    unreadCount: z.number(),
+    unreadThreads: z.array(z.any()),
+    unreadConversations: z.array(z.any()),
+    totalThreads: z.number(),
+    totalConversations: z.number(),
+});
+/**
+ * Shared result item for search-content and get-mentions output.
+ *
+ * The search API only emits 'thread' and 'conversation' results: a match inside a
+ * comment is a 'thread' result with `commentId` set. `id` is an opaque result key,
+ * not a Comms object id — use the typed id fields to reference objects.
+ */
+const searchResultItemBaseShape = {
+    id: z
+        .string()
+        .describe('Opaque search-result key (`thread_<threadId>` or `conversation_<conversationId>`). Not a Comms object id — use the typed id fields (threadId, commentId, conversationId, messageId) instead.'),
+    content: z.string(),
+    creatorId: z.number(),
+    creatorName: z.string().optional(),
+    created: z.string(),
+    workspaceId: z.number(),
+    url: z.string(),
+};
+export const SearchResultItemSchema = z.discriminatedUnion('type', [
+    z.object({
+        ...searchResultItemBaseShape,
+        type: z.literal('thread'),
+        threadId: z.string().describe('The matched thread id.'),
+        commentId: z
+            .string()
+            .optional()
+            .describe('The matched comment id, set when the match is a comment in the thread.'),
+        channelId: z.string().optional(),
+        channelName: z.string().optional(),
+    }),
+    z.object({
+        ...searchResultItemBaseShape,
+        type: z.literal('conversation'),
+        conversationId: z.string().describe('The matched conversation id.'),
+        messageId: z.string().describe('The matched message id within the conversation.'),
+    }),
+]);
+/**
+ * Schema for search-content tool output
+ */
+export const SearchContentOutputSchema = z.object({
+    type: z.literal('search_results'),
+    query: z.string(),
+    workspaceId: z.number(),
+    results: z.array(SearchResultItemSchema),
+    totalResults: z.number(),
+    hasMore: z.boolean(),
+    cursor: z.string().optional(),
+});
+/**
+ * Schema for get-mentions tool output
+ */
+export const GetMentionsOutputSchema = z.object({
+    type: z.literal('mentions_results'),
+    workspaceId: z.number(),
+    results: z.array(SearchResultItemSchema),
+    totalResults: z.number(),
+    hasMore: z.boolean(),
+    cursor: z.string().optional(),
+});
+/**
+ * Schema for get-workspaces tool output
+ */
+export const GetWorkspacesOutputSchema = z.object({
+    type: z.literal('get_workspaces'),
+    workspaces: z.array(z.object({
+        id: z.number(),
+        name: z.string(),
+        creator: z.number(),
+        creatorName: z.string().optional(),
+        created: z.string(),
+        url: z.url(),
+        defaultConversation: z.string().optional(),
+        defaultConversationTitle: z.string().optional(),
+        defaultConversationUrl: z.url().optional(),
+        plan: z.string().optional(),
+        avatarId: z.string().optional(),
+        avatarUrls: z
+            .object({
+            s35: z.string(),
+            s60: z.string(),
+            s195: z.string(),
+            s640: z.string(),
+        })
+            .optional(),
+    })),
+});
+/**
+ * Schema for get-users tool output
+ */
+export const GetUsersOutputSchema = z.object({
+    type: z.literal('get_users'),
+    workspaceId: z.number(),
+    users: z.array(z.object({
+        id: z.number(),
+        name: z.string(),
+        shortName: z.string(),
+        email: z.string().optional(),
+        // Absent on a restricted profile, which the API sends in place of the
+        // full one when the viewer may not see the user.
+        userType: z.string().optional(),
+        removed: z.boolean(),
+        timezone: z.string().optional(),
+        restricted: z.boolean().optional(),
+    })),
+    totalUsers: z.number(),
+    filteredUsers: z.number(),
+});
+/**
+ * A group member. `name`/`email` are omitted when the user ID cannot be resolved
+ * against the workspace directory (e.g. the member has since been removed).
+ */
+export const GroupMemberSchema = z.object({
+    id: z.number(),
+    name: z.string().optional(),
+    email: z.string().optional(),
+});
+/**
+ * Schema for get-groups tool output
+ */
+export const GetGroupsOutputSchema = z.object({
+    type: z.literal('get_groups'),
+    workspaceId: z.number(),
+    groups: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        workspaceId: z.number(),
+        memberCount: z.number(),
+        members: z.array(GroupMemberSchema).optional(),
+    })),
+    totalGroups: z.number(),
+    filteredGroups: z.number(),
+});
+/**
+ * Schema for user-info and update-user-info tool output. `name` mirrors `User.fullName`.
+ */
+export const UserInfoOutputSchema = z.object({
+    type: z.literal('user_info'),
+    userId: z.number(),
+    name: z.string(),
+    shortName: z.string(),
+    email: z.string(),
+    timezone: z.string(),
+    lang: z.string(),
+    status: z
+        .object({
+        message: z.string(),
+        emoji: z.string().optional(),
+        activeUntil: z
+            .string()
+            .optional()
+            .describe('ISO 8601 end. Omitted when it has no end.'),
+        pauseNotifications: z.boolean().describe('Comms notifications held back.'),
+        pauseActivity: z.boolean().describe('Karma and streaks paused.'),
+    })
+        .optional()
+        .describe('Shared with Todoist. Omitted when there is no active status.'),
+});
+/**
+ * Schema for build-link tool output
+ */
+export const BuildLinkOutputSchema = z.object({
+    type: z.literal('link_data'),
+    url: z.string(),
+    linkType: z.enum(['conversation', 'message', 'thread', 'comment']),
+    params: z.object({
+        workspaceId: z.number(),
+        conversationId: z.string().optional(),
+        messageId: z.string().optional(),
+        channelId: z.string().optional(),
+        threadId: z.string().optional(),
+        commentId: z.string().optional(),
+    }),
+});
+/**
+ * Schema for create-channel tool output
+ */
+export const ChannelOutputFieldsSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    public: z.boolean(),
+    archived: z.boolean(),
+    created: z.string(),
+    channelUrl: z.string(),
+});
+export const CreateChannelOutputSchema = ChannelOutputFieldsSchema.extend({
+    type: z.literal('create_channel_result'),
+    success: z.boolean(),
+    channelId: z.string(),
+    workspaceId: z.number(),
+    creator: z.number(),
+    userIds: z.array(z.number()).optional(),
+});
+/**
+ * Schema for update-channel tool output
+ */
+export const UpdateChannelOutputSchema = ChannelOutputFieldsSchema.extend({
+    type: z.literal('update_channel_result'),
+    success: z.boolean(),
+    channelId: z.string(),
+    workspaceId: z.number(),
+    creator: z.number(),
+    userIds: z.array(z.number()).optional(),
+});
+/**
+ * Schema for create-thread tool output
+ */
+export const CreateThreadOutputSchema = z.object({
+    type: z.literal('create_thread_result'),
+    success: z.boolean(),
+    threadId: z.string(),
+    title: z.string(),
+    channelId: z.string(),
+    workspaceId: z.number(),
+    content: z.string(),
+    creator: z.number(),
+    created: z.string(),
+    threadUrl: z.string(),
+    recipients: z.array(z.number()).optional(),
+    groups: z.array(z.string()).optional(),
+    notifyAudience: z.enum(NOTIFY_AUDIENCES).optional(),
+});
+/**
+ * Schema for create-conversation tool output
+ */
+export const CreateConversationOutputSchema = z.object({
+    type: z.literal('create_conversation_result'),
+    success: z.boolean(),
+    conversationId: z.string(),
+    messageId: z.string(),
+    workspaceId: z.number(),
+    content: z.string(),
+    recipients: z.array(z.number()),
+    participants: z.array(z.number()),
+    created: z.string(),
+    conversationUrl: z.string(),
+    messageUrl: z.string(),
+});
+/**
+ * Schema for update-thread tool output
+ */
+export const UpdateThreadOutputSchema = z.object({
+    type: z.literal('update_thread_result'),
+    success: z.boolean(),
+    threadId: z.string(),
+    title: z.string(),
+    channelId: z.string(),
+    workspaceId: z.number(),
+    content: z.string(),
+    threadUrl: z.string(),
+    lastEdited: z.string().optional(),
+});
+/**
+ * Schema for update-comment tool output
+ */
+export const UpdateCommentOutputSchema = z.object({
+    type: z.literal('update_comment_result'),
+    success: z.boolean(),
+    commentId: z.string(),
+    threadId: z.string(),
+    channelId: z.string(),
+    workspaceId: z.number(),
+    content: z.string(),
+    commentUrl: z.string(),
+    lastEdited: z.string().optional(),
+});
+/**
+ * Schema for update-message tool output
+ */
+export const UpdateMessageOutputSchema = z.object({
+    type: z.literal('update_message_result'),
+    success: z.boolean(),
+    messageId: z.string(),
+    conversationId: z.string(),
+    workspaceId: z.number(),
+    content: z.string(),
+    messageUrl: z.string(),
+    lastEdited: z.string().optional(),
+});
+/**
+ * Schema for update-object tool output.
+ *
+ * The MCP `outputSchema` field requires a flat `z.ZodRawShape`, so we expose a single
+ * object schema whose `type` discriminator selects which optional fields are populated:
+ *  - `update_thread_result`  → threadId, title, channelId, threadUrl
+ *  - `update_comment_result` → commentId, threadId, channelId, commentUrl
+ *  - `update_message_result` → messageId, conversationId, messageUrl
+ * Consumers should narrow on `type`. The per-variant schemas above remain authoritative
+ * for typed construction inside the tool.
+ */
+export const UpdateObjectOutputSchema = z.object({
+    type: z.enum(['update_thread_result', 'update_comment_result', 'update_message_result']),
+    success: z.boolean(),
+    content: z.string(),
+    workspaceId: z.number(),
+    lastEdited: z.string().optional(),
+    // thread fields
+    threadId: z.string().optional(),
+    title: z.string().optional(),
+    channelId: z.string().optional(),
+    threadUrl: z.string().optional(),
+    // comment fields
+    commentId: z.string().optional(),
+    commentUrl: z.string().optional(),
+    // message fields
+    messageId: z.string().optional(),
+    conversationId: z.string().optional(),
+    messageUrl: z.string().optional(),
+});
+/**
+ * Schema for delete-thread branch of delete-object output
+ */
+export const DeleteThreadOutputSchema = z.object({
+    type: z.literal('delete_thread_result'),
+    success: z.boolean(),
+    targetType: z.literal('thread'),
+    threadId: z.string(),
+});
+/**
+ * Schema for delete-comment branch of delete-object output
+ */
+export const DeleteCommentOutputSchema = z.object({
+    type: z.literal('delete_comment_result'),
+    success: z.boolean(),
+    targetType: z.literal('comment'),
+    commentId: z.string(),
+});
+/**
+ * Schema for delete-message branch of delete-object output
+ */
+export const DeleteMessageOutputSchema = z.object({
+    type: z.literal('delete_message_result'),
+    success: z.boolean(),
+    targetType: z.literal('message'),
+    messageId: z.string(),
+});
+/**
+ * Schema for delete-object tool output.
+ *
+ * The Comms SDK delete endpoints return no body, so the structured payload simply
+ * confirms which object was deleted. The `type` discriminator selects which
+ * id field is populated:
+ *  - `delete_thread_result`  → threadId
+ *  - `delete_comment_result` → commentId
+ *  - `delete_message_result` → messageId
+ */
+export const DeleteObjectOutputSchema = z.object({
+    type: z.enum(['delete_thread_result', 'delete_comment_result', 'delete_message_result']),
+    success: z.boolean(),
+    targetType: z.enum(['thread', 'comment', 'message']),
+    threadId: z.string().optional(),
+    commentId: z.string().optional(),
+    messageId: z.string().optional(),
+});
+/**
+ * Schema for reply tool output
+ */
+export const ReplyOutputSchema = z.object({
+    type: z.literal('reply_result'),
+    success: z.boolean(),
+    targetType: z.enum(['thread', 'conversation']),
+    targetId: z.string(),
+    replyId: z.string(),
+    content: z.string(),
+    created: z.string(),
+    replyUrl: z.string(),
+    recipients: z.array(z.number()).optional(),
+    notifyAudience: z.enum(NOTIFY_AUDIENCES).optional(),
+    groups: z.array(z.string()).optional(),
+});
+/**
+ * Schema for react tool output
+ */
+export const ReactOutputSchema = z.object({
+    type: z.literal('reaction_result'),
+    success: z.boolean(),
+    operation: z.enum(['add', 'remove']),
+    targetType: z.enum(['thread', 'comment', 'message']),
+    targetId: z.string(),
+    emoji: z.string(),
+    targetUrl: z.string(),
+});
+/**
+ * Schema for mark-done tool output
+ */
+// Per-item operations mark-done can run. Shared so the operation name can't
+// drift between the tool implementation and this schema.
+export const MARK_DONE_OPS = ['markRead', 'archive'];
+export const MarkDoneOpSchema = z.enum(MARK_DONE_OPS);
+const MarkDoneOpErrorSchema = z.object({
+    op: MarkDoneOpSchema,
+    error: z.string(),
+});
+export const MarkDoneOutputSchema = z.object({
+    type: z.literal('mark_done_result'),
+    itemType: z.enum(['thread', 'conversation']),
+    mode: z.enum(['individual', 'bulk']),
+    completed: z.array(z.string()),
+    failed: z.array(z.object({
+        item: z.string(),
+        // Display text summarising which operation(s) failed.
+        error: z.string(),
+        // Structured per-operation failures so callers don't have to parse
+        // `error`.
+        opErrors: z.array(MarkDoneOpErrorSchema),
+    })),
+    // Non-fatal per-item issues: a secondary operation failed (e.g. markRead)
+    // while the done-defining operation (archive) still succeeded, so the item
+    // is reported as completed rather than failed.
+    warnings: z.array(z.object({
+        item: z.string(),
+        op: MarkDoneOpSchema,
+        error: z.string(),
+    })),
+    totalRequested: z.number(),
+    successCount: z.number(),
+    failureCount: z.number(),
+    operations: z.object({
+        markRead: z.boolean(),
+        archive: z.boolean(),
+        clearUnread: z.boolean(),
+    }),
+    selectors: z
+        .object({
+        workspaceId: z.number().optional(),
+        channelId: z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Schema for mark-read tool output
+ */
+const MarkReadItemsSchema = z.object({
+    // IDs whose unread marker was moved to the latest comment/message.
+    marked: z.array(z.string()),
+    // Requested IDs that were not in the workspace's unread list, so no
+    // mark-read call was made for them.
+    alreadyRead: z.array(z.string()),
+});
+export const MarkReadOutputSchema = z.object({
+    type: z.literal('mark_read_result'),
+    workspaceId: z.number(),
+    mode: z.enum(['individual', 'all']),
+    threads: MarkReadItemsSchema,
+    conversations: MarkReadItemsSchema,
+    failed: z.array(z.object({
+        item: z.string(),
+        itemType: MarkReadItemTypeSchema,
+        error: z.string(),
+    })),
+    markedCount: z.number(),
+    failureCount: z.number(),
+});
+/**
+ * Schema for list-channels tool output
+ */
+export const ListChannelsOutputSchema = z.object({
+    type: z.literal('list_channels'),
+    workspaceId: z.number(),
+    channels: z.array(ChannelOutputFieldsSchema.extend({
+        id: z.string(),
+        creatorId: z.number(),
+        creatorName: z.string().optional(),
+        color: z.number().optional(),
+    })),
+    totalChannels: z.number(),
+});
+/**
+ * Schema for list-conversations tool output
+ */
+export const ListConversationsOutputSchema = z.object({
+    type: z.literal('list_conversations'),
+    workspaceId: z.number(),
+    conversations: z.array(z.object({
+        id: z.string(),
+        workspaceId: z.number(),
+        title: z.string().optional(),
+        // Full set of participant IDs. `participantNames` resolves only the first
+        // few, positionally aligned with the leading entries of this array.
+        userIds: z.array(z.number()),
+        participantNames: z.array(z.string()).optional(),
+        archived: z.boolean(),
+        lastActive: z.string(),
+        snippet: z.string().optional(),
+        conversationUrl: z.string(),
+    })),
+    totalConversations: z.number(),
+    hasMore: z.boolean().optional(),
+    cursor: z.string().optional(),
+});
+/**
+ * Union of all possible structured outputs for type safety
+ */
+export const StructuredOutputSchema = z.union([
+    LoadThreadOutputSchema,
+    LoadConversationOutputSchema,
+    FetchInboxOutputSchema,
+    SearchContentOutputSchema,
+    GetWorkspacesOutputSchema,
+    GetUsersOutputSchema,
+    GetGroupsOutputSchema,
+    UserInfoOutputSchema,
+    BuildLinkOutputSchema,
+    CreateChannelOutputSchema,
+    UpdateChannelOutputSchema,
+    CreateThreadOutputSchema,
+    CreateConversationOutputSchema,
+    UpdateThreadOutputSchema,
+    UpdateCommentOutputSchema,
+    UpdateMessageOutputSchema,
+    DeleteThreadOutputSchema,
+    DeleteCommentOutputSchema,
+    DeleteMessageOutputSchema,
+    ReplyOutputSchema,
+    ReactOutputSchema,
+    MarkDoneOutputSchema,
+    MarkReadOutputSchema,
+    ListChannelsOutputSchema,
+    ListConversationsOutputSchema,
+]);

package/dist/utils/read-position.d.ts

@@ -0,0 +1,21 @@
+import type { CommsApi } from '@doist/comms-sdk';
+/**
+ * Marks a thread as read through its latest comment.
+ *
+ * `threads.markRead` takes the objIndex the caller has read up to; the unread
+ * marker moves to the comment after it. Passing 0 only covers the thread post,
+ * so any thread with comments stays unread and keeps its badge. The read
+ * position is resolved from the thread record rather than guessed: overshooting
+ * (e.g. `commentCount`) also clears the badge, but pushes the marker past the
+ * next comment so it would arrive already read.
+ */
+export declare function markThreadFullyRead(client: CommsApi, id: string): Promise<void>;
+/**
+ * Marks a conversation as read through its latest message.
+ *
+ * The API rejects `conversations.markRead` without a position (`Either
+ * obj_index or message_id should be provided`), and `objIndex: 0` only covers
+ * the first message, so the conversation record is fetched for its
+ * `lastObjIndex`.
+ */
+export declare function markConversationFullyRead(client: CommsApi, id: string): Promise<void>;