fastmail-mcp-server 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fastmail-mcp-server",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "MCP server for Fastmail - read, search, and send emails via Claude",
 	"type": "module",
 	"main": "src/index.ts",
@@ -37,6 +37,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.25.1",
+		"officeparser": "^6.0.4",
 		"zod": "^4.3.4"
 	},
 	"devDependencies": {

package/src/index.ts

@@ -1,6 +1,10 @@
 #!/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 { parseOffice } from "officeparser";
 import { z } from "zod";
 import {
 	buildReply,
@@ -20,7 +24,7 @@ import type { Email, EmailAddress, Mailbox } from "./jmap/types.js";
 
 const server = new McpServer({
 	name: "fastmail",
-	version: "0.1.0",
+	version: "0.2.0",
 });
 
 // ============ Formatters ============
@@ -95,7 +99,7 @@ ${body}`;
 
 server.tool(
 	"list_mailboxes",
-	"List all mailboxes (folders) in the account with their unread counts. Use this to discover available folders before listing emails.",
+	"List all mailboxes (folders) in the account with their unread counts. START HERE - use this to discover available folders before listing emails.",
 	{},
 	async () => {
 		const mailboxes = await listMailboxes();
@@ -278,14 +282,12 @@ server.tool(
 
 server.tool(
 	"mark_as_spam",
-	"Mark an email as spam. This moves it to the Junk folder AND trains the spam filter. USE WITH CAUTION - this affects future filtering. Requires explicit confirmation.",
+	"Mark an email as spam. This moves it to Junk AND trains the spam filter - affects future filtering! MUST use action='preview' first, then 'confirm' after user approval.",
 	{
 		email_id: z.string().describe("The email ID to mark as spam"),
 		action: z
 			.enum(["preview", "confirm"])
-			.describe(
-				"'preview' to see what will happen, 'confirm' to actually mark as spam",
-			),
+			.describe("'preview' first, then 'confirm' after user approval"),
 	},
 	async ({ email_id, action }) => {
 		const email = await getEmail(email_id);
@@ -332,23 +334,30 @@ To proceed, call this tool again with action: "confirm"`,
 
 server.tool(
 	"send_email",
-	"Compose and send a new email. ALWAYS use action='preview' first to review the draft before sending.",
+	"Compose and send a new email. CRITICAL: You MUST call with action='preview' first, show the user the draft, get explicit approval, then call again with action='confirm'. NEVER skip the preview step.",
 	{
 		action: z
 			.enum(["preview", "confirm"])
-			.describe("'preview' to see the draft, 'confirm' to send"),
+			.describe(
+				"'preview' to see the draft, 'confirm' to send - ALWAYS preview first",
+			),
 		to: z.string().describe("Recipient email address(es), comma-separated"),
 		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 +368,7 @@ server.tool(
 
 To: ${formatAddressList(toAddrs)}
 CC: ${ccAddrs ? formatAddressList(ccAddrs) : "(none)"}
+BCC: ${bccAddrs ? formatAddressList(bccAddrs) : "(none)"}
 Subject: ${subject}
 
 --- Body ---
@@ -376,6 +386,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,19 +405,40 @@ 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. CRITICAL: You MUST call with action='preview' first, show the user the draft, get explicit approval, then call again with action='confirm'. NEVER skip the preview step. For reply-all, include original CC recipients in the cc param.",
 	{
 		action: z
 			.enum(["preview", "confirm"])
-			.describe("'preview' to see the draft, 'confirm' to send"),
+			.describe(
+				"'preview' to see the draft, 'confirm' to send - ALWAYS preview first",
+			),
 		email_id: z.string().describe("The email ID to reply to"),
 		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 +447,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)"}
 
@@ -484,9 +518,90 @@ server.tool(
 	},
 );
 
+// File types that officeparser can extract text from
+const EXTRACTABLE_TYPES = [
+	"application/pdf",
+	"application/msword", // .doc
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document", // .docx
+	"application/vnd.ms-excel", // .xls
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", // .xlsx
+	"application/vnd.ms-powerpoint", // .ppt
+	"application/vnd.openxmlformats-officedocument.presentationml.presentation", // .pptx
+	"application/rtf",
+	"application/vnd.oasis.opendocument.text", // .odt
+	"application/vnd.oasis.opendocument.spreadsheet", // .ods
+	"application/vnd.oasis.opendocument.presentation", // .odp
+];
+
+// Also match by extension for when MIME types are wrong
+const EXTRACTABLE_EXTENSIONS = [
+	".pdf",
+	".doc",
+	".docx",
+	".xls",
+	".xlsx",
+	".ppt",
+	".pptx",
+	".rtf",
+	".odt",
+	".ods",
+	".odp",
+];
+
+function canExtractText(mimeType: string, filename: string | null): boolean {
+	// Check MIME type first
+	if (EXTRACTABLE_TYPES.includes(mimeType)) return true;
+
+	// Check extension - this catches octet-stream with proper filenames
+	if (filename) {
+		const ext = filename.toLowerCase().match(/\.[^.]+$/)?.[0];
+		console.error(`[canExtractText] filename=${filename}, ext=${ext}`);
+		if (ext && EXTRACTABLE_EXTENSIONS.includes(ext)) return true;
+	}
+
+	return false;
+}
+
+async function extractText(
+	data: Uint8Array,
+	filename: string | null,
+): Promise<string> {
+	const buffer = Buffer.from(data);
+	const ext = filename?.toLowerCase().match(/\.[^.]+$/)?.[0];
+
+	// For .doc files, use macOS textutil (officeparser doesn't handle old OLE format well)
+	if (ext === ".doc") {
+		console.error("[extractText] Using textutil for .doc file");
+		const tmpPath = `/tmp/fastmail-${Date.now()}.doc`;
+		await Bun.write(tmpPath, buffer);
+		try {
+			const proc = Bun.spawn([
+				"textutil",
+				"-convert",
+				"txt",
+				"-stdout",
+				tmpPath,
+			]);
+			const output = await new Response(proc.stdout).text();
+			return output;
+		} finally {
+			(await Bun.file(tmpPath).exists()) &&
+				(await Bun.$`rm ${tmpPath}`.quiet());
+		}
+	}
+
+	// For everything else, use officeparser
+	const result = await parseOffice(buffer, { outputFormat: "text" });
+	if (typeof result === "string") {
+		return result;
+	}
+	// AST result - extract text from it
+	return JSON.stringify(result, null, 2);
+}
+
 server.tool(
 	"get_attachment",
-	"Download and read an attachment's content. Works best with text-based files (txt, csv, json, xml, html, etc). Binary files are returned as base64.",
+	"Download an attachment. Text files and documents (PDF, DOC, DOCX, XLS, PPT, etc) have text extracted and returned. Images returned as viewable content.",
 	{
 		email_id: z.string().describe("The email ID the attachment belongs to"),
 		blob_id: z
@@ -496,6 +611,11 @@ server.tool(
 	async ({ email_id, blob_id }) => {
 		const result = await downloadAttachment(email_id, blob_id);
 
+		console.error(
+			`[get_attachment] Downloaded ${result.size} bytes, type: ${result.type}, name: ${result.name}`,
+		);
+
+		// Plain text - return directly
 		if (result.isText) {
 			return {
 				content: [
@@ -507,18 +627,158 @@ server.tool(
 			};
 		}
 
-		// Binary content - return as base64 with warning
+		// Documents - extract text
+		const shouldExtract = canExtractText(result.type, result.name);
+		console.error(
+			`[get_attachment] canExtractText(${result.type}, ${result.name}) = ${shouldExtract}`,
+		);
+
+		if (shouldExtract) {
+			try {
+				console.error(`[get_attachment] Extracting text from ${result.type}`);
+				const text = await extractText(result.data, result.name);
+				console.error(
+					`[get_attachment] Extracted ${text.length} chars of text`,
+				);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Attachment: ${result.name || "(unnamed)"}\nType: ${result.type}\nSize: ${Math.round(result.size / 1024)}KB\n\n--- Extracted Text ---\n${text}`,
+						},
+					],
+				};
+			} catch (err) {
+				console.error(`[get_attachment] Text extraction failed:`, err);
+				// Fall through to base64
+			}
+		}
+
+		const base64 = Buffer.from(result.data).toString("base64");
+
+		// Images - return as image content
+		if (result.type.startsWith("image/")) {
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `Attachment: ${result.name || "(unnamed)"} (${Math.round(result.size / 1024)}KB)`,
+					},
+					{
+						type: "image" as const,
+						data: base64,
+						mimeType: result.type,
+					},
+				],
+			};
+		}
+
+		// Other binary - return base64 as last resort
 		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: ${Math.round(result.size / 1024)}KB\nEncoding: base64\n\n${base64}`,
+				},
+			],
+		};
+	},
+);
+
+// ============ 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;
@@ -413,8 +434,10 @@ export async function downloadAttachment(
 	blobId: string,
 ): Promise<{
 	content: string;
+	data: Uint8Array;
 	type: string;
 	name: string | null;
+	size: number;
 	isText: boolean;
 }> {
 	const client = getClient();
@@ -428,6 +451,7 @@ export async function downloadAttachment(
 	}
 
 	const { data, type } = await client.downloadBlob(blobId, accountId);
+	const bytes = new Uint8Array(data);
 
 	// Determine if it's text-based content
 	const isText =
@@ -435,26 +459,28 @@ export async function downloadAttachment(
 		type.includes("json") ||
 		type.includes("xml") ||
 		type.includes("javascript") ||
-		type.includes("csv") ||
-		type === "application/pdf"; // We'll try to extract text from PDFs
+		type.includes("csv");
 
-	if (isText && type !== "application/pdf") {
+	if (isText) {
 		// Return as text
 		const decoder = new TextDecoder();
 		return {
 			content: decoder.decode(data),
+			data: bytes,
 			type,
 			name: attachment.name,
+			size: bytes.length,
 			isText: true,
 		};
 	}
 
-	// For binary files (including PDFs for now), return base64
-	const base64 = Buffer.from(data).toString("base64");
+	// For binary files, return raw data (caller decides what to do)
 	return {
-		content: base64,
+		content: "", // Not used for binary
+		data: bytes,
 		type,
 		name: attachment.name,
+		size: bytes.length,
 		isText: false,
 	};
 }

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;