Merge pull request #36 from RadCod3/feat/29-improve-transaction-search

Enhance transaction search functionality

Author: RadCod3

src/lampyrid/clients/firefly.py

@@ -88,10 +88,77 @@ async def search_accounts(self, req: SearchAccountRequest) -> AccountArray:
 		r.raise_for_status()
 		return AccountArray.model_validate(r.json())
 
+	@staticmethod
+	def _sanitize_value(value: str) -> str:
+		"""Escape and optionally quote a search value for Firefly III query syntax.
+
+		Escapes backslashes and double quotes, then wraps the value in double quotes
+		if it contains whitespace or quote characters.
+
+		Args:
+			value: The raw search value
+
+		Returns:
+			Escaped and optionally quoted value safe for Firefly III queries
+		"""
+		# Escape backslashes first, then escape double quotes
+		escaped = value.replace('\\', '\\\\').replace('"', '\\"')
+
+		# Quote if contains whitespace or quote characters
+		if ' ' in value or '"' in value or "'" in value:
+			return f'"{escaped}"'
+		return escaped
+
 	async def search_transactions(self, req: SearchTransactionsRequest) -> TransactionArray:
-		"""Search transactions by description or other text fields."""
+		"""Search transactions using structured filters or raw query string."""
+		# Build query string from structured fields
+		query_parts = []
+
+		# Add raw query if provided
+		if req.query:
+			query_parts.append(req.query)
+
+		# Transaction type and amount filters
+		if req.type:
+			query_parts.append(f'type:{req.type}')
+		if req.amount_equals is not None:
+			query_parts.append(f'amount:{req.amount_equals}')
+		if req.amount_more is not None:
+			query_parts.append(f'more:{req.amount_more}')
+		if req.amount_less is not None:
+			query_parts.append(f'less:{req.amount_less}')
+
+		# Date filters
+		if req.date_on:
+			query_parts.append(f'date_on:{req.date_on}')
+		if req.date_after:
+			query_parts.append(f'date_after:{req.date_after}')
+		if req.date_before:
+			query_parts.append(f'date_before:{req.date_before}')
+
+		# Content filters
+		if req.description_contains:
+			query_parts.append(
+				f'description_contains:{self._sanitize_value(req.description_contains)}'
+			)
+
+		# Metadata filters
+		if req.category:
+			query_parts.append(f'category_is:{self._sanitize_value(req.category)}')
+		if req.budget:
+			query_parts.append(f'budget_is:{self._sanitize_value(req.budget)}')
+
+		# Account filters
+		if req.account_contains:
+			query_parts.append(f'account_contains:{self._sanitize_value(req.account_contains)}')
+		if req.account_id is not None:
+			query_parts.append(f'account_id:{req.account_id}')
+
+		# Combine all query parts with spaces (AND logic)
+		final_query = ' '.join(query_parts)
+
 		params: Dict[str, Any] = {
-			'query': req.query,
+			'query': final_query,
 			'page': req.page,
 			'limit': req.limit,
 		}

src/lampyrid/models/lampyrid_models.py

@@ -1,8 +1,8 @@
 from datetime import date, datetime, timezone
 from enum import Enum
-from typing import List, Optional
+from typing import List, Optional, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from .firefly_models import (
 	AccountRead,
@@ -282,19 +282,120 @@ class GetTransactionsRequest(BaseModel):
 
 
 class SearchTransactionsRequest(BaseModel):
-	query: str = Field(
-		...,
-		description='Text to search for in transaction descriptions, account names, and other transaction fields',
+	query: str | None = Field(
+		None,
+		description='Free-text search or raw Firefly III query string. Can be combined with structured filters below.',
 	)
-	page: Optional[int] = Field(
+
+	# Transaction type and amount filters
+	type: Literal['withdrawal', 'deposit', 'transfer'] | None = Field(
+		None,
+		description='Transaction type to filter by',
+		examples=['withdrawal', 'deposit', 'transfer'],
+	)
+	amount_equals: float | None = Field(
+		None,
+		description='Exact amount to match',
+		examples=[123.45],
+	)
+	amount_more: float | None = Field(
+		None,
+		description='Minimum amount (inclusive)',
+		examples=[100.00],
+	)
+	amount_less: float | None = Field(
+		None,
+		description='Maximum amount (inclusive)',
+		examples=[50.00],
+	)
+
+	# Date filters
+	date_on: date | None = Field(
+		None,
+		description='Exact date match in YYYY-MM-DD format',
+		examples=['2024-01-15'],
+	)
+	date_after: date | None = Field(
+		None,
+		description='From date (inclusive) in YYYY-MM-DD format',
+		examples=['2024-01-01'],
+	)
+	date_before: date | None = Field(
+		None,
+		description='Until date (inclusive) in YYYY-MM-DD format',
+		examples=['2024-12-31'],
+	)
+
+	# Content filters
+	description_contains: str | None = Field(
+		None,
+		description='Text to search for in transaction descriptions',
+		examples=['groceries', 'coffee'],
+	)
+
+	# Metadata filters
+	category: str | None = Field(
+		None,
+		description='Category name to filter by (exact match)',
+		examples=['Food', 'Transportation'],
+	)
+	budget: str | None = Field(
+		None,
+		description='Budget name to filter by (exact match)',
+		examples=['Groceries', 'Dining Out'],
+	)
+
+	# Account filters
+	account_contains: str | None = Field(
+		None,
+		description='Text to search for in any account name (source or destination)',
+		examples=['checking', 'savings'],
+	)
+	account_id: str | None = Field(
+		None,
+		description='Account ID to filter by (matches source or destination account)',
+		examples=['123'],
+	)
+
+	# Pagination
+	page: int | None = Field(
 		1,
 		description='Page number to retrieve (1-based). Use for browsing large result sets.',
 		ge=1,
 	)
-	limit: Optional[int] = Field(
+	limit: int | None = Field(
 		50, description='Maximum number of transactions to return per page (1-500)', ge=1, le=500
 	)
 
+	@model_validator(mode='after')
+	def validate_search_criteria(self):
+		"""Ensure at least one search criterion is provided."""
+		search_fields = [
+			self.query,
+			self.type,
+			self.amount_equals,
+			self.amount_more,
+			self.amount_less,
+			self.date_on,
+			self.date_after,
+			self.date_before,
+			self.description_contains,
+			self.category,
+			self.budget,
+			self.account_contains,
+			self.account_id,
+		]
+		# Consider a field provided if: (a) it's not None and not a string, or
+		# (b) it's a string and not empty/whitespace-only
+		has_criteria = any(
+			(field is not None and not isinstance(field, str))
+			or (isinstance(field, str) and field.strip() != '')
+			for field in search_fields
+		)
+		if not has_criteria:
+			raise ValueError('At least one search criterion must be provided')
+		return self
+
 
 class DeleteTransactionRequest(BaseModel):
 	id: str = Field(..., description='Unique identifier of the transaction to permanently remove')

src/lampyrid/tools/transactions.py

@@ -81,7 +81,7 @@ async def get_transactions(req: GetTransactionsRequest) -> TransactionListRespon
 
 	@transactions_mcp.tool(tags={'transactions', 'query'})
 	async def search_transactions(req: SearchTransactionsRequest) -> TransactionListResponse:
-		"""Find transactions by searching text content. Perfect for locating specific purchases, payments, or merchants by description."""
+		"""Search transactions with powerful filtering options. Supports free-text search, type filtering (withdrawal/deposit/transfer), amount ranges, date ranges, categories, budgets, and account matching. All filters combine with AND logic for precise results."""
 		transaction_array = await client.search_transactions(req)
 
 		return TransactionListResponse.from_transaction_array(