fastmail-mcp-server 0.1.0

package/src/jmap/methods.ts

@@ -0,0 +1,500 @@
+import { getClient } from "./client.js";
+import type {
+	Email,
+	EmailAddress,
+	EmailCreate,
+	Identity,
+	Mailbox,
+} from "./types.js";
+
+// Standard properties to fetch for email listings
+const EMAIL_LIST_PROPERTIES = [
+	"id",
+	"threadId",
+	"mailboxIds",
+	"keywords",
+	"from",
+	"to",
+	"subject",
+	"receivedAt",
+	"preview",
+	"hasAttachment",
+	"size",
+];
+
+// Full properties for single email fetch
+const EMAIL_FULL_PROPERTIES = [
+	...EMAIL_LIST_PROPERTIES,
+	"cc",
+	"bcc",
+	"replyTo",
+	"sentAt",
+	"messageId",
+	"inReplyTo",
+	"references",
+	"bodyValues",
+	"textBody",
+	"htmlBody",
+	"attachments",
+];
+
+// ============ Mailbox Methods ============
+
+export async function listMailboxes(): Promise<Mailbox[]> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const result = await client.call<{ list: Mailbox[] }>("Mailbox/get", {
+		accountId,
+	});
+
+	return result.list;
+}
+
+export async function getMailboxByName(name: string): Promise<Mailbox | null> {
+	const mailboxes = await listMailboxes();
+	const lowerName = name.toLowerCase();
+
+	// Try exact match first, then role match, then case-insensitive
+	return (
+		mailboxes.find((m) => m.name === name) ||
+		mailboxes.find((m) => m.role === lowerName) ||
+		mailboxes.find((m) => m.name.toLowerCase() === lowerName) ||
+		null
+	);
+}
+
+export async function getMailboxById(id: string): Promise<Mailbox | null> {
+	const mailboxes = await listMailboxes();
+	return mailboxes.find((m) => m.id === id) || null;
+}
+
+// ============ Email Methods ============
+
+export async function listEmails(
+	mailboxName: string,
+	limit = 25,
+): Promise<Email[]> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const mailbox = await getMailboxByName(mailboxName);
+	if (!mailbox) {
+		throw new Error(`Mailbox not found: ${mailboxName}`);
+	}
+
+	// Query for email IDs
+	const queryResult = await client.call<{ ids: string[] }>("Email/query", {
+		accountId,
+		filter: { inMailbox: mailbox.id },
+		sort: [{ property: "receivedAt", isAscending: false }],
+		limit,
+	});
+
+	if (queryResult.ids.length === 0) {
+		return [];
+	}
+
+	// Fetch email details
+	const getResult = await client.call<{ list: Email[] }>("Email/get", {
+		accountId,
+		ids: queryResult.ids,
+		properties: EMAIL_LIST_PROPERTIES,
+	});
+
+	return getResult.list;
+}
+
+export async function getEmail(emailId: string): Promise<Email | null> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const result = await client.call<{ list: Email[] }>("Email/get", {
+		accountId,
+		ids: [emailId],
+		properties: EMAIL_FULL_PROPERTIES,
+		fetchTextBodyValues: true,
+		fetchHTMLBodyValues: true,
+		maxBodyValueBytes: 1024 * 1024, // 1MB
+	});
+
+	return result.list[0] || null;
+}
+
+export async function searchEmails(
+	query: string,
+	limit = 25,
+): Promise<Email[]> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	// Query for email IDs with text filter
+	const queryResult = await client.call<{ ids: string[] }>("Email/query", {
+		accountId,
+		filter: { text: query },
+		sort: [{ property: "receivedAt", isAscending: false }],
+		limit,
+	});
+
+	if (queryResult.ids.length === 0) {
+		return [];
+	}
+
+	// Fetch email details
+	const getResult = await client.call<{ list: Email[] }>("Email/get", {
+		accountId,
+		ids: queryResult.ids,
+		properties: EMAIL_LIST_PROPERTIES,
+	});
+
+	return getResult.list;
+}
+
+// ============ Email Modification Methods ============
+
+export async function moveEmail(
+	emailId: string,
+	targetMailboxName: string,
+): Promise<void> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const targetMailbox = await getMailboxByName(targetMailboxName);
+	if (!targetMailbox) {
+		throw new Error(`Target mailbox not found: ${targetMailboxName}`);
+	}
+
+	// Get current email to find its mailboxes
+	const email = await getEmail(emailId);
+	if (!email) {
+		throw new Error(`Email not found: ${emailId}`);
+	}
+
+	// Build new mailboxIds - remove all current, add target
+	const newMailboxIds: Record<string, boolean> = { [targetMailbox.id]: true };
+
+	await client.call("Email/set", {
+		accountId,
+		update: {
+			[emailId]: { mailboxIds: newMailboxIds },
+		},
+	});
+}
+
+export async function setEmailKeywords(
+	emailId: string,
+	keywords: Record<string, boolean>,
+): Promise<void> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	await client.call("Email/set", {
+		accountId,
+		update: {
+			[emailId]: { keywords },
+		},
+	});
+}
+
+export async function markAsRead(emailId: string, read = true): Promise<void> {
+	const email = await getEmail(emailId);
+	if (!email) {
+		throw new Error(`Email not found: ${emailId}`);
+	}
+
+	const keywords: Record<string, boolean> = { ...email.keywords };
+	if (read) {
+		keywords.$seen = true;
+	} else {
+		delete keywords.$seen;
+	}
+
+	await setEmailKeywords(emailId, keywords);
+}
+
+export async function markAsSpam(emailId: string): Promise<void> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const junkMailbox = await getMailboxByName("junk");
+	if (!junkMailbox) {
+		throw new Error("Junk mailbox not found");
+	}
+
+	// Move to Junk and set $junk keyword (trains spam filter)
+	const email = await getEmail(emailId);
+	if (!email) {
+		throw new Error(`Email not found: ${emailId}`);
+	}
+
+	const keywords: Record<string, boolean> = { ...email.keywords, $junk: true };
+	delete keywords.$notjunk;
+
+	await client.call("Email/set", {
+		accountId,
+		update: {
+			[emailId]: {
+				mailboxIds: { [junkMailbox.id]: true },
+				keywords,
+			},
+		},
+	});
+}
+
+// ============ Identity Methods ============
+
+export async function getIdentities(): Promise<Identity[]> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const result = await client.call<{ list: Identity[] }>("Identity/get", {
+		accountId,
+	});
+
+	return result.list;
+}
+
+export async function getDefaultIdentity(): Promise<Identity> {
+	const identities = await getIdentities();
+	const identity = identities[0];
+	if (!identity) {
+		throw new Error("No email identity found");
+	}
+	return identity;
+}
+
+// ============ Email Sending Methods ============
+
+export interface SendEmailParams {
+	to: EmailAddress[];
+	subject: string;
+	textBody: string;
+	htmlBody?: string;
+	cc?: EmailAddress[];
+	bcc?: EmailAddress[];
+	inReplyTo?: string;
+	references?: string[];
+}
+
+export async function sendEmail(params: SendEmailParams): Promise<string> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	const identity = await getDefaultIdentity();
+
+	// Get Drafts and Sent mailbox IDs
+	const mailboxes = await listMailboxes();
+	const draftsMailbox = mailboxes.find((m) => m.role === "drafts");
+	const sentMailbox = mailboxes.find((m) => m.role === "sent");
+
+	if (!draftsMailbox || !sentMailbox) {
+		throw new Error("Could not find Drafts or Sent mailbox");
+	}
+
+	// Create email body
+	const emailCreate: EmailCreate = {
+		mailboxIds: { [draftsMailbox.id]: true },
+		keywords: { $draft: true },
+		from: [{ name: identity.name, email: identity.email }],
+		to: params.to,
+		cc: params.cc,
+		bcc: params.bcc,
+		subject: params.subject,
+		bodyValues: {
+			body: {
+				value: params.textBody,
+				isEncodingProblem: false,
+				isTruncated: false,
+			},
+		},
+		textBody: [{ partId: "body", type: "text/plain" } as const].map((p) => ({
+			...p,
+			blobId: null,
+			size: 0,
+			name: null,
+			charset: null,
+			disposition: null,
+			cid: null,
+			language: null,
+			location: null,
+		})),
+	};
+
+	if (params.inReplyTo) {
+		emailCreate.inReplyTo = [params.inReplyTo];
+	}
+	if (params.references) {
+		emailCreate.references = params.references;
+	}
+
+	// Create email and submit in one request
+	const responses = await client.request([
+		[
+			"Email/set",
+			{
+				accountId,
+				create: { draft: emailCreate },
+			},
+			"0",
+		],
+		[
+			"EmailSubmission/set",
+			{
+				accountId,
+				create: {
+					submission: {
+						identityId: identity.id,
+						emailId: "#draft",
+						envelope: null,
+					},
+				},
+				onSuccessUpdateEmail: {
+					"#submission": {
+						mailboxIds: { [sentMailbox.id]: true },
+						"keywords/$draft": null,
+					},
+				},
+			},
+			"1",
+		],
+	]);
+
+	// Extract created email ID
+	const emailSetResponse = responses[0];
+	if (!emailSetResponse) {
+		throw new Error("No response from Email/set");
+	}
+
+	const created = (
+		emailSetResponse[1] as { created?: Record<string, { id: string }> }
+	).created;
+	const emailId = created?.draft?.id;
+
+	if (!emailId) {
+		throw new Error("Failed to create email");
+	}
+
+	return emailId;
+}
+
+// ============ Attachment Methods ============
+
+export interface AttachmentInfo {
+	blobId: string;
+	name: string | null;
+	type: string;
+	size: number;
+}
+
+export async function getAttachments(
+	emailId: string,
+): Promise<AttachmentInfo[]> {
+	const email = await getEmail(emailId);
+	if (!email) {
+		throw new Error(`Email not found: ${emailId}`);
+	}
+
+	if (!email.attachments || email.attachments.length === 0) {
+		return [];
+	}
+
+	return email.attachments
+		.filter((a) => a.blobId)
+		.map((a) => ({
+			blobId: a.blobId as string,
+			name: a.name,
+			type: a.type,
+			size: a.size,
+		}));
+}
+
+export async function downloadAttachment(
+	emailId: string,
+	blobId: string,
+): Promise<{
+	content: string;
+	type: string;
+	name: string | null;
+	isText: boolean;
+}> {
+	const client = getClient();
+	const accountId = await client.getAccountId();
+
+	// Get attachment info for the name
+	const attachments = await getAttachments(emailId);
+	const attachment = attachments.find((a) => a.blobId === blobId);
+	if (!attachment) {
+		throw new Error(`Attachment not found: ${blobId}`);
+	}
+
+	const { data, type } = await client.downloadBlob(blobId, accountId);
+
+	// Determine if it's text-based content
+	const isText =
+		type.startsWith("text/") ||
+		type.includes("json") ||
+		type.includes("xml") ||
+		type.includes("javascript") ||
+		type.includes("csv") ||
+		type === "application/pdf"; // We'll try to extract text from PDFs
+
+	if (isText && type !== "application/pdf") {
+		// Return as text
+		const decoder = new TextDecoder();
+		return {
+			content: decoder.decode(data),
+			type,
+			name: attachment.name,
+			isText: true,
+		};
+	}
+
+	// For binary files (including PDFs for now), return base64
+	const base64 = Buffer.from(data).toString("base64");
+	return {
+		content: base64,
+		type,
+		name: attachment.name,
+		isText: false,
+	};
+}
+
+// Helper to build a reply
+export async function buildReply(
+	originalEmailId: string,
+	replyBody: string,
+): Promise<SendEmailParams> {
+	const original = await getEmail(originalEmailId);
+	if (!original) {
+		throw new Error(`Original email not found: ${originalEmailId}`);
+	}
+
+	// Determine who to reply to
+	const replyTo = original.replyTo?.[0] || original.from?.[0];
+	if (!replyTo) {
+		throw new Error("Cannot determine reply address");
+	}
+
+	// Build subject (add Re: if not present)
+	let subject = original.subject || "";
+	if (!subject.toLowerCase().startsWith("re:")) {
+		subject = `Re: ${subject}`;
+	}
+
+	// Build references chain
+	const references: string[] = [];
+	if (original.references) {
+		references.push(...original.references);
+	}
+	if (original.messageId?.[0]) {
+		references.push(original.messageId[0]);
+	}
+
+	return {
+		to: [replyTo],
+		subject,
+		textBody: replyBody,
+		inReplyTo: original.messageId?.[0],
+		references: references.length > 0 ? references : undefined,
+	};
+}

package/src/jmap/types.ts

@@ -0,0 +1,198 @@
+// JMAP Core Types
+// Based on RFC 8620 (JMAP Core) and RFC 8621 (JMAP Mail)
+
+export interface JMAPSession {
+	capabilities: Record<string, unknown>;
+	accounts: Record<string, JMAPAccount>;
+	primaryAccounts: Record<string, string>;
+	username: string;
+	apiUrl: string;
+	downloadUrl: string;
+	uploadUrl: string;
+	eventSourceUrl: string;
+	state: string;
+}
+
+export interface JMAPAccount {
+	name: string;
+	isPersonal: boolean;
+	isReadOnly: boolean;
+	accountCapabilities: Record<string, unknown>;
+}
+
+export interface JMAPRequest {
+	using: string[];
+	methodCalls: JMAPMethodCall[];
+}
+
+export type JMAPMethodCall = [string, Record<string, unknown>, string];
+
+export interface JMAPResponse {
+	methodResponses: JMAPMethodResponse[];
+	sessionState: string;
+}
+
+export type JMAPMethodResponse = [string, Record<string, unknown>, string];
+
+// Mailbox Types
+export interface Mailbox {
+	id: string;
+	name: string;
+	parentId: string | null;
+	role: MailboxRole | null;
+	sortOrder: number;
+	totalEmails: number;
+	unreadEmails: number;
+	totalThreads: number;
+	unreadThreads: number;
+	myRights: MailboxRights;
+	isSubscribed: boolean;
+}
+
+export type MailboxRole =
+	| "all"
+	| "archive"
+	| "drafts"
+	| "flagged"
+	| "important"
+	| "inbox"
+	| "junk"
+	| "sent"
+	| "subscribed"
+	| "trash";
+
+export interface MailboxRights {
+	mayReadItems: boolean;
+	mayAddItems: boolean;
+	mayRemoveItems: boolean;
+	maySetSeen: boolean;
+	maySetKeywords: boolean;
+	mayCreateChild: boolean;
+	mayRename: boolean;
+	mayDelete: boolean;
+	maySubmit: boolean;
+}
+
+// Email Types
+export interface Email {
+	id: string;
+	blobId: string;
+	threadId: string;
+	mailboxIds: Record<string, boolean>;
+	keywords: Record<string, boolean>;
+	size: number;
+	receivedAt: string;
+	messageId: string[] | null;
+	inReplyTo: string[] | null;
+	references: string[] | null;
+	sender: EmailAddress[] | null;
+	from: EmailAddress[] | null;
+	to: EmailAddress[] | null;
+	cc: EmailAddress[] | null;
+	bcc: EmailAddress[] | null;
+	replyTo: EmailAddress[] | null;
+	subject: string | null;
+	sentAt: string | null;
+	hasAttachment: boolean;
+	preview: string;
+	bodyStructure?: EmailBodyPart;
+	bodyValues?: Record<string, EmailBodyValue>;
+	textBody?: EmailBodyPart[];
+	htmlBody?: EmailBodyPart[];
+	attachments?: EmailBodyPart[];
+	headers?: EmailHeader[];
+}
+
+export interface EmailAddress {
+	name: string | null;
+	email: string;
+}
+
+export interface EmailBodyPart {
+	partId: string | null;
+	blobId: string | null;
+	size: number;
+	headers?: EmailHeader[];
+	name: string | null;
+	type: string;
+	charset: string | null;
+	disposition: string | null;
+	cid: string | null;
+	language: string[] | null;
+	location: string | null;
+	subParts?: EmailBodyPart[];
+}
+
+export interface EmailBodyValue {
+	value: string;
+	isEncodingProblem: boolean;
+	isTruncated: boolean;
+}
+
+export interface EmailHeader {
+	name: string;
+	value: string;
+}
+
+// Identity Types (for sending)
+export interface Identity {
+	id: string;
+	name: string;
+	email: string;
+	replyTo: EmailAddress[] | null;
+	bcc: EmailAddress[] | null;
+	textSignature: string;
+	htmlSignature: string;
+	mayDelete: boolean;
+}
+
+// EmailSubmission Types
+export interface EmailSubmission {
+	id: string;
+	identityId: string;
+	emailId: string;
+	threadId: string;
+	envelope: Envelope | null;
+	sendAt: string;
+	undoStatus: "pending" | "final" | "canceled";
+	deliveryStatus: Record<string, DeliveryStatus> | null;
+	dsnBlobIds: string[];
+	mdnBlobIds: string[];
+}
+
+export interface Envelope {
+	mailFrom: EnvelopeAddress;
+	rcptTo: EnvelopeAddress[];
+}
+
+export interface EnvelopeAddress {
+	email: string;
+	parameters: Record<string, string | null> | null;
+}
+
+export interface DeliveryStatus {
+	smtpReply: string;
+	delivered: "queued" | "yes" | "no" | "unknown";
+	displayed: "unknown" | "yes";
+}
+
+// Helper type for creating emails
+export interface EmailCreate {
+	mailboxIds: Record<string, boolean>;
+	keywords?: Record<string, boolean>;
+	from?: EmailAddress[];
+	to?: EmailAddress[];
+	cc?: EmailAddress[];
+	bcc?: EmailAddress[];
+	replyTo?: EmailAddress[];
+	subject?: string;
+	sentAt?: string;
+	bodyStructure?: EmailBodyPart;
+	bodyValues?: Record<string, EmailBodyValue>;
+	textBody?: EmailBodyPart[];
+	htmlBody?: EmailBodyPart[];
+	inReplyTo?: string[];
+	references?: string[];
+	messageId?: string[];
+	headers?: EmailHeader[];
+}