@open-workspace/email 0.0.0-stage → 0.1.1

package/worker/mcp/mail-action-tools.ts

@@ -0,0 +1,210 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { AccountApiClient, apiPath } from "@open-workspace/core/worker/mcp/account-client.ts";
+import { runTool } from "@open-workspace/core/worker/mcp/results.ts";
+import {
+  conversationIdsSchema,
+  entityIdSchema,
+  mailboxIdSchema,
+  mailboxStateSchema,
+} from "@open-workspace/core/worker/mcp/schemas.ts";
+
+const write = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export function registerMailActionTools(server: McpServer, api: AccountApiClient) {
+  server.registerTool(
+    "set_message_read",
+    {
+      title: "Mark message read or unread",
+      description: "Set the current account's personal read state for one message.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        messageId: entityIdSchema,
+        isRead: z.boolean(),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, messageId, isRead }) => runTool(() => api.json(apiPath(
+      `/mail/messages/${encodeURIComponent(messageId)}/read`,
+      { mailboxId },
+    ), { method: "PATCH", json: { isRead } })),
+  );
+
+  server.registerTool(
+    "set_conversations_read",
+    {
+      title: "Mark conversations read or unread",
+      description: "Set the current account's personal read state for all messages in up to 500 conversations.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        conversationIds: conversationIdsSchema,
+        isRead: z.boolean(),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, conversationIds, isRead }) => runTool(() => api.json(apiPath(
+      "/mail/conversations/bulk",
+      { mailboxId },
+    ), {
+      method: "PATCH",
+      json: { type: "read", conversationIds, isRead },
+    })),
+  );
+
+  server.registerTool(
+    "move_conversations",
+    {
+      title: "Move conversations",
+      description: "Move up to 500 conversations between Inbox, Archive, Trash, or a custom folder, or out of Spam. To put mail in Spam use report_conversations (or report_message), which also records the report for the spam classifier.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        conversationIds: conversationIdsSchema,
+        sourceFolderId: entityIdSchema,
+        // Spam goes through reporting so the classifier learns from it.
+        mailboxState: mailboxStateSchema.exclude(["spam"]).optional(),
+        folderId: entityIdSchema.nullable().optional(),
+      }).refine(
+        (value) => value.mailboxState !== undefined || value.folderId !== undefined,
+        "Provide mailboxState, folderId, or both",
+      ),
+      annotations: write,
+    },
+    ({ mailboxId, conversationIds, sourceFolderId, mailboxState, folderId }) =>
+      runTool(() => api.json(apiPath("/mail/conversations/bulk", { mailboxId }), {
+        method: "PATCH",
+        json: {
+          type: "update",
+          conversationIds,
+          sourceFolderId,
+          update: { mailboxState, folderId },
+        },
+      })),
+  );
+
+  server.registerTool(
+    "delete_conversations_permanently",
+    {
+      title: "Permanently delete conversations",
+      description: "Permanently delete up to 500 conversations. Every conversation must already be in Trash.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        conversationIds: conversationIdsSchema,
+      }),
+      annotations: {
+        ...write,
+        destructiveHint: true,
+      },
+    },
+    ({ mailboxId, conversationIds }) => runTool(() => api.json(apiPath(
+      "/mail/conversations/bulk",
+      { mailboxId },
+    ), {
+      method: "PATCH",
+      json: { type: "delete_permanently", conversationIds },
+    })),
+  );
+
+  server.registerTool(
+    "create_folder",
+    {
+      title: "Create custom folder",
+      description: "Create a custom folder shared by everyone with access to the mailbox.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        name: z.string().trim().min(1).max(80),
+      }),
+      annotations: { ...write, idempotentHint: false },
+    },
+    ({ mailboxId, name }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/folders`,
+      { method: "POST", json: { name } },
+    )),
+  );
+
+  server.registerTool(
+    "rename_folder",
+    {
+      title: "Rename custom folder",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        folderId: entityIdSchema,
+        name: z.string().trim().min(1).max(80),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, folderId, name }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/folders/${encodeURIComponent(folderId)}`,
+      { method: "PATCH", json: { name } },
+    )),
+  );
+
+  server.registerTool(
+    "delete_folder",
+    {
+      title: "Delete custom folder",
+      description: "Delete a custom folder. Conversations remain in Inbox.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        folderId: entityIdSchema,
+      }),
+      annotations: { ...write, destructiveHint: true },
+    },
+    ({ mailboxId, folderId }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/folders/${encodeURIComponent(folderId)}`,
+      { method: "DELETE" },
+    )),
+  );
+
+  server.registerTool(
+    "reorder_folders",
+    {
+      title: "Reorder custom folders",
+      description: "Set the complete order of custom folders in a mailbox.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        folderIds: z.array(entityIdSchema).max(100),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, folderIds }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/folders/order`,
+      { method: "PUT", json: { folderIds } },
+    )),
+  );
+
+  server.registerTool(
+    "get_mailbox_ai_settings",
+    {
+      title: "Get mailbox AI rules",
+      description: "Read mailbox-level classification instructions and confidence threshold.",
+      inputSchema: z.object({ mailboxId: mailboxIdSchema }),
+      annotations: { ...write, readOnlyHint: true },
+    },
+    ({ mailboxId }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/ai`,
+    )),
+  );
+
+  server.registerTool(
+    "update_mailbox_ai_settings",
+    {
+      title: "Update mailbox AI rules",
+      description: "Update mailbox-level classification instructions and confidence threshold.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        instructions: z.string().trim().max(4_000),
+        confidenceThreshold: z.number().int().min(50).max(100),
+      }),
+      annotations: write,
+    },
+    ({ mailboxId, instructions, confidenceThreshold }) => runTool(() => api.json(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/ai`,
+      { method: "PUT", json: { instructions, confidenceThreshold } },
+    )),
+  );
+}

package/worker/mcp/mail-compose-tools.ts

@@ -0,0 +1,196 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import {
+  MAX_COMPOSER_ATTACHMENT_BYTES,
+  MAX_MAIL_RECIPIENTS,
+} from "../../shared/mail";
+import { emailSchema } from "@open-workspace/core/worker/auth/schemas.ts";
+import { dedupeRecipientFields, recipientCount } from "../mail/recipients";
+import { AccountApiClient, apiPath } from "@open-workspace/core/worker/mcp/account-client.ts";
+import { runTool } from "@open-workspace/core/worker/mcp/results.ts";
+import {
+  entityIdSchema,
+  mailboxIdSchema,
+  messageContentFields,
+  recipientFields,
+  replyModeSchema,
+  requestId,
+} from "@open-workspace/core/worker/mcp/schemas.ts";
+
+const sendAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true,
+} as const;
+
+const composeInputSchema = z.object({
+  mailboxId: mailboxIdSchema,
+  ...recipientFields,
+  replyTo: emailSchema.optional(),
+  subject: z.string().trim().max(998).default(""),
+  ...messageContentFields,
+}).refine(
+  (value) => recipientCount(dedupeRecipientFields(value)) > 0,
+  "Add at least one recipient",
+).refine(
+  (value) => recipientCount(dedupeRecipientFields(value)) <= MAX_MAIL_RECIPIENTS,
+  `An email can have at most ${MAX_MAIL_RECIPIENTS} recipients`,
+);
+
+const forwardInputSchema = z.object({
+  mailboxId: mailboxIdSchema,
+  sourceMessageId: entityIdSchema,
+  ...recipientFields,
+  replyTo: emailSchema.optional(),
+  ...messageContentFields,
+}).refine(
+  (value) => recipientCount(dedupeRecipientFields(value)) > 0,
+  "Add at least one recipient",
+).refine(
+  (value) => recipientCount(dedupeRecipientFields(value)) <= MAX_MAIL_RECIPIENTS,
+  `An email can have at most ${MAX_MAIL_RECIPIENTS} recipients`,
+);
+
+export function registerMailComposeTools(server: McpServer, api: AccountApiClient) {
+  server.registerTool(
+    "create_attachment_upload",
+    {
+      title: "Create attachment upload",
+      description: "Create a 15-minute presigned R2 PUT URL. Upload exactly the declared number of bytes to upload.uploadUrl using upload.headers, then call complete_attachment_upload with upload.id.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        filename: z.string().trim().min(1).max(255),
+        contentType: z.string().trim().min(1).max(255).default("application/octet-stream"),
+        size: z.number().int().positive().max(MAX_COMPOSER_ATTACHMENT_BYTES),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    ({ mailboxId, filename, contentType, size }) => runTool(() =>
+      api.json(apiPath("/mail/uploads", { mailboxId, directOnly: true }), {
+        method: "POST",
+        json: { filename, contentType, size },
+      })
+    ),
+  );
+
+  server.registerTool(
+    "complete_attachment_upload",
+    {
+      title: "Complete attachment upload",
+      description: "Verify and seal a file uploaded with create_attachment_upload. Use the returned upload id in send_email, reply_to_email, or forward_email attachments.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        uploadId: entityIdSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    ({ mailboxId, uploadId }) => runTool(() => api.json(apiPath(
+      `/mail/uploads/${encodeURIComponent(uploadId)}/complete`,
+      { mailboxId },
+    ), { method: "POST" })),
+  );
+
+  server.registerTool(
+    "discard_attachment_upload",
+    {
+      title: "Discard attachment upload",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        uploadId: entityIdSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    ({ mailboxId, uploadId }) => runTool(() => api.json(apiPath(
+      `/mail/uploads/${encodeURIComponent(uploadId)}`,
+      { mailboxId },
+    ), { method: "DELETE" })),
+  );
+
+  server.registerTool(
+    "send_email",
+    {
+      title: "Send email",
+      description: "Compose and send a new email from a mailbox where the current account has send access.",
+      inputSchema: composeInputSchema,
+      annotations: sendAnnotations,
+    },
+    (input) => runTool(() => api.json("/mail/messages", {
+      method: "POST",
+      json: { ...input, requestId: requestId(input.requestId) },
+    })),
+  );
+
+  server.registerTool(
+    "reply_to_email",
+    {
+      title: "Reply to email",
+      description: "Reply, reply all, continue a draft-like outgoing thread, or reply to a mailing list.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        sourceMessageId: entityIdSchema,
+        mode: replyModeSchema.default("reply"),
+        cc: z.array(emailSchema).max(MAX_MAIL_RECIPIENTS).optional(),
+        bcc: z.array(emailSchema).max(MAX_MAIL_RECIPIENTS).default([]),
+        ...messageContentFields,
+      }),
+      annotations: sendAnnotations,
+    },
+    ({ sourceMessageId, ...input }) => runTool(() => api.json(
+      `/mail/messages/${encodeURIComponent(sourceMessageId)}/replies`,
+      {
+        method: "POST",
+        json: { ...input, requestId: requestId(input.requestId) },
+      },
+    )),
+  );
+
+  server.registerTool(
+    "forward_email",
+    {
+      title: "Forward email",
+      description: "Forward a message, including its original attachments, to new recipients.",
+      inputSchema: forwardInputSchema,
+      annotations: sendAnnotations,
+    },
+    ({ sourceMessageId, ...input }) => runTool(() => api.json(
+      `/mail/messages/${encodeURIComponent(sourceMessageId)}/forward`,
+      {
+        method: "POST",
+        json: { ...input, requestId: requestId(input.requestId) },
+      },
+    )),
+  );
+
+  server.registerTool(
+    "send_email_again",
+    {
+      title: "Retry failed email",
+      description: "Retry an outgoing message whose delivery is failed or unconfirmed.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        messageId: entityIdSchema,
+      }),
+      annotations: sendAnnotations,
+    },
+    ({ mailboxId, messageId }) => runTool(() => api.json(apiPath(
+      `/mail/messages/${encodeURIComponent(messageId)}/send-again`,
+      { mailboxId },
+    ), { method: "POST" })),
+  );
+}

package/worker/mcp/mail-query-tools.ts

@@ -0,0 +1,196 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { AccountApiClient, apiPath } from "@open-workspace/core/worker/mcp/account-client.ts";
+import {
+  runBinaryResourceTool,
+  runResourceLinkTool,
+  runTool,
+} from "@open-workspace/core/worker/mcp/results.ts";
+import { entityIdSchema, mailboxIdSchema, mailboxInputSchema } from "@open-workspace/core/worker/mcp/schemas.ts";
+
+const MAX_RESOURCE_CHUNK_BYTES = 4_000_000;
+
+const binaryResourceInputSchema = z.object({
+  mailboxId: mailboxIdSchema,
+  messageId: entityIdSchema,
+  offsetBytes: z.number().int().min(0).default(0),
+  maxBytes: z.number().int().min(1).max(MAX_RESOURCE_CHUNK_BYTES)
+    .default(MAX_RESOURCE_CHUNK_BYTES),
+});
+
+const attachmentLinkResponseSchema = z.object({
+  ok: z.literal(true),
+  attachment: z.object({
+    id: z.string(),
+    filename: z.string(),
+    contentType: z.string(),
+    size: z.number().int().nonnegative(),
+    url: z.url(),
+    expiresAt: z.number().int().positive(),
+  }),
+});
+
+const readOnly = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export function registerMailQueryTools(server: McpServer, api: AccountApiClient) {
+  server.registerTool(
+    "list_mailboxes",
+    {
+      title: "List mailboxes",
+      description: "List mailboxes available to the current account, including send access and unread counts.",
+      annotations: readOnly,
+    },
+    () => runTool(() => api.json("/mail/mailboxes")),
+  );
+
+  server.registerTool(
+    "list_folders",
+    {
+      title: "List mailbox folders",
+      description: "List system and custom folders with total and unread counts.",
+      inputSchema: mailboxInputSchema,
+      annotations: readOnly,
+    },
+    ({ mailboxId }) => runTool(() =>
+      api.json(`/mail/mailboxes/${encodeURIComponent(mailboxId)}/folders`)
+    ),
+  );
+
+  server.registerTool(
+    "list_conversations",
+    {
+      title: "List or search conversations",
+      description: "List a cursor-paginated mailbox folder. Supports search and unread-only filtering.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        folder: z.string().trim().min(1).max(80).default("inbox"),
+        limit: z.number().int().min(1).max(50).default(25),
+        cursor: z.string().trim().min(1).max(512).optional(),
+        search: z.string().trim().max(200).optional(),
+        unreadOnly: z.boolean().default(false),
+      }),
+      annotations: readOnly,
+    },
+    (input) => runTool(() => api.json(apiPath("/mail/conversations", {
+      mailboxId: input.mailboxId,
+      folder: input.folder,
+      limit: input.limit,
+      cursor: input.cursor,
+      search: input.search,
+      unreadOnly: input.unreadOnly ? "true" : undefined,
+    }))),
+  );
+
+  server.registerTool(
+    "get_conversation",
+    {
+      title: "Get conversation",
+      description: "Read a cursor-paginated conversation page, including bodies, attachment metadata, delivery state, and read receipts. The first page contains the newest messages; continue with nextCursor to load older messages.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        conversationId: entityIdSchema,
+        limit: z.number().int().min(1).max(25).default(25),
+        cursor: z.string().trim().min(1).max(512).optional(),
+      }),
+      annotations: readOnly,
+    },
+    ({ mailboxId, conversationId, limit, cursor }) => runTool(() => api.json(apiPath(
+      `/mail/conversations/${encodeURIComponent(conversationId)}`,
+      { mailboxId, limit, cursor },
+    ))),
+  );
+
+  server.registerTool(
+    "suggest_recipients",
+    {
+      title: "Suggest recipients",
+      description: "Find recent recipients known to a mailbox.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        query: z.string().trim().max(200).default(""),
+        limit: z.number().int().min(1).max(12).default(8),
+      }),
+      annotations: readOnly,
+    },
+    ({ mailboxId, query, limit }) => runTool(() => api.json(apiPath(
+      `/mail/mailboxes/${encodeURIComponent(mailboxId)}/recipient-suggestions`,
+      { q: query, limit },
+    ))),
+  );
+
+  server.registerTool(
+    "get_message_authentication",
+    {
+      title: "Get message authentication",
+      description: "Get SPF, DKIM, DMARC, and ARC results, the sending IP, the experimental Cloudflare spam score, and the sender verdict for an incoming message, as recorded by Cloudflare Email Routing in its headers.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        messageId: entityIdSchema,
+      }),
+      annotations: readOnly,
+    },
+    ({ mailboxId, messageId }) => runTool(() => api.json(apiPath(
+      `/mail/messages/${encodeURIComponent(messageId)}/authentication`,
+      { mailboxId },
+    ))),
+  );
+
+  server.registerTool(
+    "get_original_message",
+    {
+      title: "Read original message",
+      description: "Read the raw RFC 822 message as an embedded .eml resource. Large messages are returned in chunks; continue with nextOffsetBytes until it is null.",
+      inputSchema: binaryResourceInputSchema,
+      annotations: readOnly,
+    },
+    ({ mailboxId, messageId, offsetBytes, maxBytes }) =>
+      runBinaryResourceTool({
+        action: () => api.binary(apiPath(
+          `/mail/messages/${encodeURIComponent(messageId)}/original`,
+          { mailboxId },
+        ), { offsetBytes, maxBytes }),
+        uri: `openworkspace://mail/${encodeURIComponent(mailboxId)}/messages/${encodeURIComponent(messageId)}/original.eml#bytes=${offsetBytes}`,
+        mimeType: "message/rfc822",
+        fallbackFilename: `${messageId}.eml`,
+      }),
+  );
+
+  server.registerTool(
+    "get_attachment_download_url",
+    {
+      title: "Get attachment download URL",
+      description: "Return a private R2 download link that expires after 15 minutes. Treat the URL as a temporary bearer credential.",
+      inputSchema: z.object({
+        mailboxId: mailboxIdSchema,
+        messageId: entityIdSchema,
+        attachmentId: entityIdSchema,
+      }),
+      annotations: readOnly,
+    },
+    ({ mailboxId, messageId, attachmentId }) => runResourceLinkTool(async () => {
+      const response = attachmentLinkResponseSchema.parse(await api.json(
+        apiPath(
+          `/mail/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}/download-url`,
+          { mailboxId },
+        ),
+      ));
+      return {
+        structuredContent: response,
+        resource: {
+          type: "resource_link",
+          uri: response.attachment.url,
+          name: response.attachment.filename,
+          title: response.attachment.filename,
+          description: "Temporary private attachment download",
+          mimeType: response.attachment.contentType,
+          size: response.attachment.size,
+        },
+      };
+    }),
+  );
+}