Add account filter to MCP search, list, and aggregate tools (#110)

## Summary
- Adds optional `account` parameter to `search_messages`,
`list_messages`, and `aggregate` MCP tools
- Allows filtering results to a specific archived Gmail account when
multiple accounts are synced
- Account parameter accepts an email address (e.g., "alice@gmail.com")
- Users can discover available accounts via the `get_stats` tool

## Test plan
- [x] Added `TestAccountFilter` with 7 test cases covering valid/invalid
accounts for all three tools
- [x] All existing MCP tests pass
- [x] `go vet` passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Rob Elkin <rob@rational.partners>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

internal/mcp/handlers.go

@@ -25,6 +25,24 @@ type handlers struct {
 	attachmentsDir string
 }
 
+// getAccountID looks up a source ID by email address.
+// Returns nil if account is empty (no filter), or an error if not found.
+func (h *handlers) getAccountID(ctx context.Context, account string) (*int64, error) {
+	if account == "" {
+		return nil, nil
+	}
+	accounts, err := h.engine.ListAccounts(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list accounts: %w", err)
+	}
+	for _, acc := range accounts {
+		if acc.Identifier == account {
+			return &acc.ID, nil
+		}
+	}
+	return nil, fmt.Errorf("account not found: %s", account)
+}
+
 // getIDArg extracts a required positive integer ID from the arguments map.
 func getIDArg(args map[string]any, key string) (int64, error) {
 	v, ok := args[key].(float64)
@@ -94,10 +112,20 @@ func (h *handlers) searchMessages(ctx context.Context, req mcp.CallToolRequest)
 	limit := limitArg(args, "limit", 20)
 	offset := limitArg(args, "offset", 0)
 
+	// Look up account filter
+	account, _ := args["account"].(string)
+	sourceID, err := h.getAccountID(ctx, account)
+	if err != nil {
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
 	q := search.Parse(queryStr)
+	q.AccountID = sourceID
+
+	filter := query.MessageFilter{SourceID: sourceID}
 
 	// Try fast search first (metadata only), fall back to full FTS.
-	results, err := h.engine.SearchFast(ctx, q, query.MessageFilter{}, limit, offset)
+	results, err := h.engine.SearchFast(ctx, q, filter, limit, offset)
 	if err != nil {
 		return mcp.NewToolResultError(fmt.Sprintf("search failed: %v", err)), nil
 	}
@@ -276,7 +304,15 @@ func (h *handlers) exportAttachment(ctx context.Context, req mcp.CallToolRequest
 func (h *handlers) listMessages(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	args := req.GetArguments()
 
+	// Look up account filter
+	account, _ := args["account"].(string)
+	sourceID, err := h.getAccountID(ctx, account)
+	if err != nil {
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
 	filter := query.MessageFilter{
+		SourceID: sourceID,
 		Pagination: query.Pagination{
 			Limit:  limitArg(args, "limit", 20),
 			Offset: limitArg(args, "offset", 0),
@@ -295,7 +331,6 @@ func (h *handlers) listMessages(ctx context.Context, req mcp.CallToolRequest) (*
 	if v, ok := args["has_attachment"].(bool); ok && v {
 		filter.WithAttachmentsOnly = true
 	}
-	var err error
 	if filter.After, err = getDateArg(args, "after"); err != nil {
 		return mcp.NewToolResultError(err.Error()), nil
 	}
@@ -341,11 +376,18 @@ func (h *handlers) aggregate(ctx context.Context, req mcp.CallToolRequest) (*mcp
 		return mcp.NewToolResultError("group_by parameter is required"), nil
 	}
 
+	// Look up account filter
+	account, _ := args["account"].(string)
+	sourceID, err := h.getAccountID(ctx, account)
+	if err != nil {
+		return mcp.NewToolResultError(err.Error()), nil
+	}
+
 	opts := query.AggregateOptions{
-		Limit: limitArg(args, "limit", 50),
+		SourceID: sourceID,
+		Limit:    limitArg(args, "limit", 50),
 	}
 
-	var err error
 	if opts.After, err = getDateArg(args, "after"); err != nil {
 		return mcp.NewToolResultError(err.Error()), nil
 	}

internal/mcp/server.go

@@ -46,6 +46,12 @@ func withBefore() mcp.ToolOption {
 	)
 }
 
+func withAccount() mcp.ToolOption {
+	return mcp.WithString("account",
+		mcp.Description("Filter by account email address (use get_stats to list available accounts)"),
+	)
+}
+
 // Serve creates an MCP server with email archive tools and serves over stdio.
 // It blocks until stdin is closed or the context is cancelled.
 func Serve(ctx context.Context, engine query.Engine, attachmentsDir string) error {
@@ -77,6 +83,7 @@ func searchMessagesTool() mcp.Tool {
 			mcp.Required(),
 			mcp.Description("Gmail-style search query (e.g. 'from:alice subject:meeting after:2024-01-01')"),
 		),
+		withAccount(),
 		withLimit("20"),
 		withOffset(),
 	)
@@ -121,6 +128,7 @@ func listMessagesTool() mcp.Tool {
 	return mcp.NewTool(ToolListMessages,
 		mcp.WithDescription("List messages with optional filters. Returns message summaries sorted by date."),
 		mcp.WithReadOnlyHintAnnotation(true),
+		withAccount(),
 		mcp.WithString("from",
 			mcp.Description("Filter by sender email address"),
 		),
@@ -156,6 +164,7 @@ func aggregateTool() mcp.Tool {
 			mcp.Description("Dimension to group by"),
 			mcp.Enum("sender", "recipient", "domain", "label", "time"),
 		),
+		withAccount(),
 		withLimit("50"),
 		withAfter(),
 		withBefore(),

internal/mcp/server_test.go

@@ -769,3 +769,94 @@ func TestLimitArgClamping(t *testing.T) {
 		})
 	}
 }
+
+func TestAccountFilter(t *testing.T) {
+	eng := &querytest.MockEngine{
+		Accounts: []query.AccountInfo{
+			{ID: 1, Identifier: "alice@gmail.com"},
+			{ID: 2, Identifier: "bob@gmail.com"},
+		},
+		SearchFastResults: []query.MessageSummary{
+			testutil.NewMessageSummary(1).WithSubject("Test").WithFromEmail("alice@gmail.com").Build(),
+		},
+		ListResults: []query.MessageSummary{
+			testutil.NewMessageSummary(2).WithSubject("List Test").WithFromEmail("bob@gmail.com").Build(),
+		},
+		AggregateRows: []query.AggregateRow{
+			{Key: "alice@gmail.com", Count: 100},
+		},
+	}
+	h := newTestHandlers(eng)
+
+	t.Run("search with valid account", func(t *testing.T) {
+		msgs := runTool[[]query.MessageSummary](t, "search_messages", h.searchMessages, map[string]any{
+			"query":   "test",
+			"account": "alice@gmail.com",
+		})
+		if len(msgs) != 1 {
+			t.Fatalf("expected 1 message, got %d", len(msgs))
+		}
+	})
+
+	t.Run("search with invalid account", func(t *testing.T) {
+		r := runToolExpectError(t, "search_messages", h.searchMessages, map[string]any{
+			"query":   "test",
+			"account": "unknown@gmail.com",
+		})
+		txt := resultText(t, r)
+		if !strings.Contains(txt, "account not found") {
+			t.Fatalf("expected 'account not found' error, got: %s", txt)
+		}
+	})
+
+	t.Run("list with valid account", func(t *testing.T) {
+		msgs := runTool[[]query.MessageSummary](t, "list_messages", h.listMessages, map[string]any{
+			"account": "bob@gmail.com",
+		})
+		if len(msgs) != 1 {
+			t.Fatalf("expected 1 message, got %d", len(msgs))
+		}
+	})
+
+	t.Run("list with invalid account", func(t *testing.T) {
+		r := runToolExpectError(t, "list_messages", h.listMessages, map[string]any{
+			"account": "unknown@gmail.com",
+		})
+		txt := resultText(t, r)
+		if !strings.Contains(txt, "account not found") {
+			t.Fatalf("expected 'account not found' error, got: %s", txt)
+		}
+	})
+
+	t.Run("aggregate with valid account", func(t *testing.T) {
+		rows := runTool[[]query.AggregateRow](t, "aggregate", h.aggregate, map[string]any{
+			"group_by": "sender",
+			"account":  "alice@gmail.com",
+		})
+		if len(rows) != 1 {
+			t.Fatalf("expected 1 row, got %d", len(rows))
+		}
+	})
+
+	t.Run("aggregate with invalid account", func(t *testing.T) {
+		r := runToolExpectError(t, "aggregate", h.aggregate, map[string]any{
+			"group_by": "sender",
+			"account":  "unknown@gmail.com",
+		})
+		txt := resultText(t, r)
+		if !strings.Contains(txt, "account not found") {
+			t.Fatalf("expected 'account not found' error, got: %s", txt)
+		}
+	})
+
+	t.Run("empty account means no filter", func(t *testing.T) {
+		// Empty string should not filter - return all results
+		msgs := runTool[[]query.MessageSummary](t, "search_messages", h.searchMessages, map[string]any{
+			"query":   "test",
+			"account": "",
+		})
+		if len(msgs) != 1 {
+			t.Fatalf("expected 1 message, got %d", len(msgs))
+		}
+	})
+}