fastmail-mcp-server 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fastmail-mcp-server",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "MCP server for Fastmail - read, search, and send emails via Claude",
 	"type": "module",
 	"main": "src/index.ts",

package/src/index.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+	McpServer,
+	ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import {
@@ -20,7 +23,7 @@ import type { Email, EmailAddress, Mailbox } from "./jmap/types.js";
 
 const server = new McpServer({
 	name: "fastmail",
-	version: "0.1.0",
+	version: "0.1.1",
 });
 
 // ============ Formatters ============
@@ -341,14 +344,19 @@ server.tool(
 		subject: z.string().describe("Email subject line"),
 		body: z.string().describe("Email body text"),
 		cc: z.string().optional().describe("CC recipients, comma-separated"),
+		bcc: z
+			.string()
+			.optional()
+			.describe("BCC recipients (hidden), comma-separated"),
 	},
-	async ({ action, to, subject, body, cc }) => {
+	async ({ action, to, subject, body, cc, bcc }) => {
 		// Parse addresses
 		const parseAddresses = (s: string): EmailAddress[] =>
 			s.split(",").map((e) => ({ name: null, email: e.trim() }));
 
 		const toAddrs = parseAddresses(to);
 		const ccAddrs = cc ? parseAddresses(cc) : undefined;
+		const bccAddrs = bcc ? parseAddresses(bcc) : undefined;
 
 		if (action === "preview") {
 			return {
@@ -359,6 +367,7 @@ server.tool(
 
 To: ${formatAddressList(toAddrs)}
 CC: ${ccAddrs ? formatAddressList(ccAddrs) : "(none)"}
+BCC: ${bccAddrs ? formatAddressList(bccAddrs) : "(none)"}
 Subject: ${subject}
 
 --- Body ---
@@ -376,6 +385,7 @@ To send this email, call this tool again with action: "confirm" and the same par
 			subject,
 			textBody: body,
 			cc: ccAddrs,
+			bcc: bccAddrs,
 		});
 
 		return {
@@ -394,7 +404,7 @@ Email ID: ${emailId}`,
 
 server.tool(
 	"reply_to_email",
-	"Reply to an existing email thread. ALWAYS use action='preview' first to review the draft before sending.",
+	"Reply to an existing email thread. ALWAYS use action='preview' first to review the draft before sending. For reply-all, include original CC recipients in the cc param.",
 	{
 		action: z
 			.enum(["preview", "confirm"])
@@ -403,10 +413,29 @@ server.tool(
 		body: z
 			.string()
 			.describe("Reply body text (your response, without quoting original)"),
+		cc: z
+			.string()
+			.optional()
+			.describe("CC recipients for reply-all, comma-separated"),
+		bcc: z
+			.string()
+			.optional()
+			.describe("BCC recipients (hidden), comma-separated"),
 	},
-	async ({ action, email_id, body }) => {
+	async ({ action, email_id, body, cc, bcc }) => {
+		const parseAddresses = (s: string): EmailAddress[] =>
+			s.split(",").map((e) => ({ name: null, email: e.trim() }));
+
 		const replyParams = await buildReply(email_id, body);
 
+		// Add cc/bcc if provided
+		if (cc) {
+			replyParams.cc = parseAddresses(cc);
+		}
+		if (bcc) {
+			replyParams.bcc = parseAddresses(bcc);
+		}
+
 		if (action === "preview") {
 			return {
 				content: [
@@ -415,6 +444,8 @@ server.tool(
 						text: `📧 REPLY PREVIEW - Review before sending:
 
 To: ${formatAddressList(replyParams.to)}
+CC: ${replyParams.cc ? formatAddressList(replyParams.cc) : "(none)"}
+BCC: ${replyParams.bcc ? formatAddressList(replyParams.bcc) : "(none)"}
 Subject: ${replyParams.subject}
 In-Reply-To: ${replyParams.inReplyTo || "(none)"}
 
@@ -507,18 +538,112 @@ server.tool(
 			};
 		}
 
-		// Binary content - return as base64 with warning
+		// Binary content - return full base64
 		return {
 			content: [
 				{
 					type: "text" as const,
-					text: `Attachment: ${result.name || "(unnamed)"}\nType: ${result.type}\n\nThis is a binary file. Base64 content (first 1000 chars):\n${result.content.slice(0, 1000)}${result.content.length > 1000 ? "..." : ""}`,
+					text: `Attachment: ${result.name || "(unnamed)"}\nType: ${result.type}\nSize: ${result.content.length} bytes (base64)\n\n--- Base64 Content ---\n${result.content}`,
 				},
 			],
 		};
 	},
 );
 
+// ============ Resources ============
+
+// Expose attachments as resources with blob content
+server.resource(
+	"attachment",
+	new ResourceTemplate("fastmail://attachment/{emailId}/{blobId}", {
+		list: undefined,
+	}),
+	{
+		description: "Email attachment content",
+		mimeType: "application/octet-stream",
+	},
+	async (uri, variables) => {
+		const { emailId, blobId } = variables as {
+			emailId: string;
+			blobId: string;
+		};
+		const result = await downloadAttachment(emailId, blobId);
+
+		if (result.isText) {
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						mimeType: result.type,
+						text: result.content,
+					},
+				],
+			};
+		}
+
+		// Binary - return as blob (base64)
+		return {
+			contents: [
+				{
+					uri: uri.toString(),
+					mimeType: result.type,
+					blob: result.content, // already base64
+				},
+			],
+		};
+	},
+);
+
+// ============ Prompts ============
+
+server.prompt(
+	"fastmail-usage",
+	"Instructions for using the Fastmail MCP server effectively",
+	() => ({
+		messages: [
+			{
+				role: "user",
+				content: {
+					type: "text",
+					text: `# Fastmail MCP Server Usage Guide
+
+## Reading Emails
+1. Use \`list_mailboxes\` to see available folders
+2. Use \`list_emails\` with a mailbox name to see emails (e.g., "inbox", "Archive", "Sent")
+3. Use \`get_email\` with an email ID to read full content
+4. Use \`search_emails\` to find emails across all folders
+
+## Attachments
+1. Use \`list_attachments\` to see attachments on an email
+2. Use \`get_attachment\` with email_id and blob_id to read attachment content
+3. For binary files (PDFs, images), access via resource URI: fastmail://attachment/{emailId}/{blobId}
+
+## Sending Emails (ALWAYS preview first!)
+1. Use \`send_email\` with action="preview" to draft
+2. Review the preview with the user
+3. Only use action="confirm" after explicit user approval
+4. Supports to, cc, bcc fields
+
+## Replying
+1. Use \`reply_to_email\` with action="preview" to draft a reply
+2. The reply automatically threads correctly
+3. Add cc/bcc for reply-all scenarios
+
+## Managing Emails
+- \`move_email\` - Move to folder (Archive, Trash, etc.)
+- \`mark_as_read\` - Toggle read/unread
+- \`mark_as_spam\` - Requires preview→confirm (trains spam filter!)
+
+## Safety Rules
+- NEVER send without showing preview first
+- NEVER confirm send without explicit user approval
+- Be careful with mark_as_spam - it affects future filtering`,
+				},
+			},
+		],
+	}),
+);
+
 // ============ Start Server ============
 
 const transport = new StdioServerTransport();

package/src/jmap/client.ts

@@ -77,12 +77,19 @@ export class JMAPClient {
 		for (const [methodName, data] of result.methodResponses) {
 			if (methodName === "error") {
 				const errorData = data as { type: string; description?: string };
+				console.error("[JMAP Error]", JSON.stringify(errorData, null, 2));
 				throw new Error(
 					`JMAP error: ${errorData.type}${errorData.description ? ` - ${errorData.description}` : ""}`,
 				);
 			}
 		}
 
+		// Log responses for debugging
+		console.error(
+			"[JMAP Response]",
+			JSON.stringify(result.methodResponses, null, 2),
+		);
+
 		return result.methodResponses;
 	}
 

package/src/jmap/methods.ts

@@ -301,23 +301,11 @@ export async function sendEmail(params: SendEmailParams): Promise<string> {
 		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,
-		})),
+			body: { value: params.textBody },
+		} as unknown as EmailCreate["bodyValues"],
+		textBody: [
+			{ partId: "body", type: "text/plain" },
+		] as EmailCreate["textBody"],
 	};
 
 	if (params.inReplyTo) {
@@ -359,19 +347,52 @@ export async function sendEmail(params: SendEmailParams): Promise<string> {
 		],
 	]);
 
-	// Extract created email ID
+	// Extract created email ID and check for errors
 	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;
+	const emailSetResult = emailSetResponse[1] as {
+		created?: Record<string, { id: string }>;
+		notCreated?: Record<string, { type: string; description?: string }>;
+	};
+
+	// Check for creation errors
+	if (emailSetResult.notCreated?.draft) {
+		const err = emailSetResult.notCreated.draft;
+		console.error("[Email/set notCreated]", JSON.stringify(err, null, 2));
+		throw new Error(
+			`Failed to create email: ${err.type}${err.description ? ` - ${err.description}` : ""}`,
+		);
+	}
 
+	const emailId = emailSetResult.created?.draft?.id;
 	if (!emailId) {
-		throw new Error("Failed to create email");
+		console.error(
+			"[Email/set response]",
+			JSON.stringify(emailSetResult, null, 2),
+		);
+		throw new Error("Failed to create email - no ID returned");
+	}
+
+	// Check submission response
+	const submissionResponse = responses[1];
+	if (submissionResponse) {
+		const submissionResult = submissionResponse[1] as {
+			created?: Record<string, unknown>;
+			notCreated?: Record<string, { type: string; description?: string }>;
+		};
+		if (submissionResult.notCreated?.submission) {
+			const err = submissionResult.notCreated.submission;
+			console.error(
+				"[EmailSubmission/set notCreated]",
+				JSON.stringify(err, null, 2),
+			);
+			throw new Error(
+				`Failed to submit email: ${err.type}${err.description ? ` - ${err.description}` : ""}`,
+			);
+		}
 	}
 
 	return emailId;

package/src/jmap/types.ts

@@ -123,6 +123,12 @@ export interface EmailBodyPart {
 	subParts?: EmailBodyPart[];
 }
 
+// Minimal body part for creating emails - only partId and type required
+export interface EmailBodyPartCreate {
+	partId: string;
+	type: string;
+}
+
 export interface EmailBodyValue {
 	value: string;
 	isEncodingProblem: boolean;