Add category update, details, and monthly cashflow tools#62
Merged
robcerda merged 6 commits intoMay 25, 2026
Merged
Conversation
Add three new tools for managing merchants and recurring transaction streams: - get_merchant: query merchant details including recurring stream configuration - update_merchant: modify merchant name and/or recurring stream settings (frequency, amount, base date, active status) - review_recurring_stream: accept, ignore, or reset recurring streams These use custom GraphQL queries (Common_GetEditMerchant, Common_UpdateMerchant, Web_ReviewStream) via gql_call, following the same pattern as the existing transaction rules tools. Includes 14 tests covering success paths, not-found handling, null recurring streams, partial updates, no-op validation, GraphQL error surfacing, and auth errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
get_spending_summary was returning zeros for all values because it called client.get_cashflow_summary() which returns empty/incompatible data. Replaced with a direct gql_call to Common_GetCashFlowEntityAggregates, which is what the Monarch web app uses for its spending breakdown. The response now includes: - by_category: spending per category with group info, sorted by magnitude - by_category_group: spending per category group - by_merchant: income/expense per merchant - overall totals: income, expenses, savings, savings_rate Also removed the unused `limit` parameter (the GraphQL endpoint returns all aggregates, not a paginated list) and added 9 tests covering the full response, date filtering, empty results, sorting, null categories, and error handling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three new tools for category management and budget trend analysis: - update_category: modify name, icon, group, budget variability, and rollover settings via the Web_UpdateCategory GraphQL mutation - get_category_details: query a single category's budget amounts for a specific month (planned, actual, remaining, rollover) - get_cashflow_by_month: spending by category broken down by month over a date range for trend analysis Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Validate budget_variability against known values (fixed, flexible, non_monthly) and rollover_frequency (monthly, variable) before calling the mutation. Returns clear error messages instead of cryptic GraphQL failures. - Add dry_run parameter that returns current state vs proposed changes without executing the mutation. Follows the pattern from bulk_categorize_transactions and upload_account_balance_history. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Replace dict comprehension None-filter with explicit is-not-None checks so that legitimate falsy values (exclude_from_budget=False, rollover_enabled=False, rollover_starting_balance=0) are correctly included in the mutation input rather than silently dropped. - Fix validation guards to use `is not None` instead of truthiness, so empty strings don't bypass validation. - Clean up sort-key pattern in get_cashflow_by_month. - Add test proving falsy values are sent to GraphQL correctly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three new tools for category management and budget trend analysis:
update_category: Modify a category's name, icon, group, budget variability (fixed/flexible/non_monthly), and rollover settings. Uses theWeb_UpdateCategoryGraphQL mutation (not available in the monarchmoney library).get_category_details: Query a single category's full configuration plus budget amounts for a specific month (planned, actual, remaining, rollover carryover).get_cashflow_by_month: Spending by category broken down by month over a date range. Use for trend analysis; complementsget_spending_summarywhich gives single-period totals.All three use custom GraphQL via
gql_call, following the same pattern as the merchant tools in PR #56.Motivation
The MCP server can create categories but cannot update them. Changing budget variability or enabling rollover currently requires using the Monarch web app directly. These GraphQL operations were identified by analyzing the Monarch web app's network traffic (HAR capture).
Changes
src/monarch_mcp_server/tools/categories.py— 3 new tools + GraphQL constants (+440 lines)src/monarch_mcp_server/server.py— re-export new functions in backward-compat shimtests/test_categories.py— 14 new tests across 3 test classes (+318 lines)Notes
update_categoryshould be added to the mutation guard list.delete_transaction_categoryis deferred — the library already has the method; a thin MCP wrapper is separate scope.Test plan
pytest tests/test_categories.py -v— 22 passedpytest(full suite) — 176 passed, no regressions