Add export_attachment MCP tool to save files to disk

Claude Desktop can only display image attachments inline. For PDFs and
other file types, add an export_attachment tool that writes the file to
the local filesystem (defaults to ~/Downloads) and returns the path.

Handles filename sanitization and collision avoidance (_1, _2, etc).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: wesm

internal/mcp/handlers.go

@@ -197,6 +197,99 @@ func (h *handlers) getAttachment(ctx context.Context, req mcp.CallToolRequest) (
 	}, nil
 }
 
+func (h *handlers) exportAttachment(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := req.GetArguments()
+
+	id, err := getIDArg(args, "attachment_id")
+	if err != nil {
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
+	att, err := h.engine.GetAttachment(ctx, id)
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("get attachment failed: %v", err)), nil
+	}
+	if att == nil {
+		return mcp.NewToolResultError("attachment not found"), nil
+	}
+
+	if h.attachmentsDir == "" {
+		return mcp.NewToolResultError("attachments directory not configured"), nil
+	}
+
+	data, err := h.readAttachmentFile(att.ContentHash)
+	if err != nil {
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
+	// Determine destination directory.
+	destDir, _ := args["destination"].(string)
+	if destDir == "" {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return mcp.NewToolResultError(fmt.Sprintf("cannot determine home directory: %v", err)), nil
+		}
+		destDir = filepath.Join(home, "Downloads")
+	}
+
+	info, err := os.Stat(destDir)
+	if err != nil || !info.IsDir() {
+		return mcp.NewToolResultError(fmt.Sprintf("destination directory does not exist: %s", destDir)), nil
+	}
+
+	// Sanitize and deduplicate filename.
+	filename := sanitizeFilename(filepath.Base(att.Filename))
+	if filename == "" || filename == "." {
+		filename = att.ContentHash
+	}
+	outPath := uniquePath(filepath.Join(destDir, filename))
+
+	if err := os.WriteFile(outPath, data, 0644); err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("write failed: %v", err)), nil
+	}
+
+	resp := struct {
+		Path     string `json:"path"`
+		Filename string `json:"filename"`
+		Size     int64  `json:"size"`
+	}{
+		Path:     outPath,
+		Filename: filepath.Base(outPath),
+		Size:     int64(len(data)),
+	}
+	return jsonResult(resp)
+}
+
+// sanitizeFilename replaces characters that are invalid in filenames.
+func sanitizeFilename(s string) string {
+	var result []rune
+	for _, r := range s {
+		switch r {
+		case '/', '\\', ':', '*', '?', '"', '<', '>', '|', '\n', '\r', '\t':
+			result = append(result, '_')
+		default:
+			result = append(result, r)
+		}
+	}
+	return string(result)
+}
+
+// uniquePath returns a path that doesn't collide with existing files by
+// appending _1, _2, etc. before the extension.
+func uniquePath(p string) string {
+	if _, err := os.Stat(p); os.IsNotExist(err) {
+		return p
+	}
+	ext := filepath.Ext(p)
+	base := p[:len(p)-len(ext)]
+	for i := 1; ; i++ {
+		candidate := fmt.Sprintf("%s_%d%s", base, i, ext)
+		if _, err := os.Stat(candidate); os.IsNotExist(err) {
+			return candidate
+		}
+	}
+}
+
 func (h *handlers) listMessages(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	args := req.GetArguments()
 

internal/mcp/server.go

@@ -11,12 +11,13 @@ import (
 
 // Tool name constants.
 const (
-	ToolSearchMessages = "search_messages"
-	ToolGetMessage     = "get_message"
-	ToolGetAttachment  = "get_attachment"
-	ToolListMessages   = "list_messages"
-	ToolGetStats       = "get_stats"
-	ToolAggregate      = "aggregate"
+	ToolSearchMessages   = "search_messages"
+	ToolGetMessage       = "get_message"
+	ToolGetAttachment    = "get_attachment"
+	ToolExportAttachment = "export_attachment"
+	ToolListMessages     = "list_messages"
+	ToolGetStats         = "get_stats"
+	ToolAggregate        = "aggregate"
 )
 
 // Common argument helpers for recurring tool option definitions.
@@ -59,6 +60,7 @@ func Serve(ctx context.Context, engine query.Engine, attachmentsDir string) erro
 	s.AddTool(searchMessagesTool(), h.searchMessages)
 	s.AddTool(getMessageTool(), h.getMessage)
 	s.AddTool(getAttachmentTool(), h.getAttachment)
+	s.AddTool(exportAttachmentTool(), h.exportAttachment)
 	s.AddTool(listMessagesTool(), h.listMessages)
 	s.AddTool(getStatsTool(), h.getStats)
 	s.AddTool(aggregateTool(), h.aggregate)
@@ -102,6 +104,19 @@ func getAttachmentTool() mcp.Tool {
 	)
 }
 
+func exportAttachmentTool() mcp.Tool {
+	return mcp.NewTool(ToolExportAttachment,
+		mcp.WithDescription("Save an attachment to the local filesystem. Use this for file types that cannot be displayed inline (e.g. PDFs, documents). Returns the saved file path."),
+		mcp.WithNumber("attachment_id",
+			mcp.Required(),
+			mcp.Description("Attachment ID (from get_message response)"),
+		),
+		mcp.WithString("destination",
+			mcp.Description("Directory to save the file to (default: ~/Downloads)"),
+		),
+	)
+}
+
 func listMessagesTool() mcp.Tool {
 	return mcp.NewTool(ToolListMessages,
 		mcp.WithDescription("List messages with optional filters. Returns message summaries sorted by date."),

internal/mcp/server_test.go

@@ -494,6 +494,110 @@ func TestGetAttachment(t *testing.T) {
 	})
 }
 
+type exportResponse struct {
+	Path     string `json:"path"`
+	Filename string `json:"filename"`
+	Size     int64  `json:"size"`
+}
+
+func TestExportAttachment(t *testing.T) {
+	srcDir := t.TempDir()
+	hash := "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
+	content := []byte("hello world PDF content")
+	createAttachmentFixture(t, srcDir, hash, content)
+
+	eng := &querytest.MockEngine{
+		Attachments: map[int64]*query.AttachmentInfo{
+			10: {ID: 10, Filename: "report.pdf", MimeType: "application/pdf", Size: int64(len(content)), ContentHash: hash},
+		},
+	}
+	h := &handlers{engine: eng, attachmentsDir: srcDir}
+
+	t.Run("export to custom destination", func(t *testing.T) {
+		destDir := t.TempDir()
+		resp := runTool[exportResponse](t, "export_attachment", h.exportAttachment, map[string]any{
+			"attachment_id": float64(10),
+			"destination":   destDir,
+		})
+		if resp.Filename != "report.pdf" {
+			t.Fatalf("unexpected filename: %s", resp.Filename)
+		}
+		if resp.Size != int64(len(content)) {
+			t.Fatalf("unexpected size: %d", resp.Size)
+		}
+		wantPath := filepath.Join(destDir, "report.pdf")
+		if resp.Path != wantPath {
+			t.Fatalf("unexpected path: %s (want %s)", resp.Path, wantPath)
+		}
+		got, err := os.ReadFile(wantPath)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if string(got) != string(content) {
+			t.Fatalf("content mismatch")
+		}
+	})
+
+	t.Run("filename collision appends suffix", func(t *testing.T) {
+		destDir := t.TempDir()
+		// Create existing file to force collision.
+		if err := os.WriteFile(filepath.Join(destDir, "report.pdf"), []byte("old"), 0644); err != nil {
+			t.Fatal(err)
+		}
+		resp := runTool[exportResponse](t, "export_attachment", h.exportAttachment, map[string]any{
+			"attachment_id": float64(10),
+			"destination":   destDir,
+		})
+		if resp.Filename != "report_1.pdf" {
+			t.Fatalf("expected report_1.pdf, got %s", resp.Filename)
+		}
+		// Original file should be untouched.
+		old, _ := os.ReadFile(filepath.Join(destDir, "report.pdf"))
+		if string(old) != "old" {
+			t.Fatal("original file was overwritten")
+		}
+	})
+
+	t.Run("default destination is ~/Downloads", func(t *testing.T) {
+		// This test only verifies the handler doesn't error when
+		// ~/Downloads exists (it does on macOS).
+		home, err := os.UserHomeDir()
+		if err != nil {
+			t.Skip("cannot determine home dir")
+		}
+		downloads := filepath.Join(home, "Downloads")
+		if _, err := os.Stat(downloads); os.IsNotExist(err) {
+			t.Skip("~/Downloads does not exist")
+		}
+
+		resp := runTool[exportResponse](t, "export_attachment", h.exportAttachment, map[string]any{
+			"attachment_id": float64(10),
+		})
+		if !strings.HasPrefix(resp.Path, downloads) {
+			t.Fatalf("expected path under ~/Downloads, got %s", resp.Path)
+		}
+		// Clean up the file we just wrote.
+		os.Remove(resp.Path)
+	})
+
+	t.Run("invalid destination", func(t *testing.T) {
+		runToolExpectError(t, "export_attachment", h.exportAttachment, map[string]any{
+			"attachment_id": float64(10),
+			"destination":   "/nonexistent/path/that/does/not/exist",
+		})
+	})
+
+	t.Run("missing attachment_id", func(t *testing.T) {
+		runToolExpectError(t, "export_attachment", h.exportAttachment, map[string]any{})
+	})
+
+	t.Run("attachment not found", func(t *testing.T) {
+		runToolExpectError(t, "export_attachment", h.exportAttachment, map[string]any{
+			"attachment_id": float64(999),
+		})
+	})
+}
+
 func TestLimitArgClamping(t *testing.T) {
 	tests := []struct {
 		name string