Function registerMessageTools

mcp/src/tools/messages.ts:20–473

(server: McpServer, client: McpClient)

}

export function registerMessageTools(server: McpServer, client: McpClient): void {
  server.registerTool(
    "send_message",
    {
      title: "Send email",
      annotations: { destructiveHint: false },
      description:
        "Use when starting a NEW email thread to a fresh recipient. To respond to a message you can see in `list_messages`, use `reply_to_message` instead — it preserves the In-Reply-To / References headers so the reply lands in the same thread, which this tool deliberately does not do. Attach files via `attachments`; pass base64 strings produced by other tools (e.g. `get_attachment`) verbatim — don't hand-encode raw text. **`pending_review` is not failure.** If the agent's review policy holds the send, the response is `{ status: \"pending_review\", message_id: ... }`; the message is held for human review — do not retry. Check on it with `list_messages` (held drafts show review_status=pending_review) / `get_message`.",
      inputSchema: strictInputSchema({
        to: z.array(z.string()).describe("Recipient email addresses (one or more)."),
        subject: z.string(),
        body: z.string().describe("Plain-text body. Use `html_body` for HTML."),
        html_body: z.string().optional(),
        cc: z.array(z.string()).optional(),
        bcc: z.array(z.string()).optional(),
        attachments: attachmentsArraySchema,
        conversation_id: z
          .string()
          .optional()
          .describe("Optional conversation grouping ID. Server generates one if omitted."),
        idempotency_key: z
          .string()
          .optional()
          .describe(
            "Stable key for retry-safe sends. Set to deduplicate when the caller has its own retry loop (e.g. a stable triggering event id). When omitted the SDK mints a fresh UUIDv4 per call — protects against network-layer retries only, not user-driven retries.",
          ),
        email: z
          .string()
          .optional()
          .describe(
            "Sending agent's inbox. Omit to use the credential's bound agent (agent-scoped credentials).",
          ),
      }),
    },
    async (args) =>
      runTool(() => {
        const opts: SendOpts =
          args.idempotency_key !== undefined
            ? { idempotencyKey: args.idempotency_key }
            : {};
        return client.send(
          {
            to: args.to,
            subject: args.subject,
            body: args.body,
            ...(args.html_body !== undefined ? { htmlBody: args.html_body } : {}),
            ...(args.cc !== undefined ? { cc: args.cc } : {}),
            ...(args.bcc !== undefined ? { bcc: args.bcc } : {}),
            ...(mapAttachments(args.attachments) !== undefined
              ? { attachments: mapAttachments(args.attachments) }
              : {}),
            ...(args.conversation_id !== undefined
              ? { conversationId: args.conversation_id }
              : {}),
          },
          opts,
          args.email,
        );