From dac16891a4f2a080b3ce78f45c46240ebd08763f Mon Sep 17 00:00:00 2001 From: Jamie Dubs <1903+jamiew@users.noreply.github.com> Date: Thu, 28 May 2026 21:49:21 -0400 Subject: [PATCH] Pin monarch lib to a commit SHA and document the fork landscape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - bump monarchmoneycommunity pin from moving `rev=main` to the fork's `dev` HEAD SHA (befdadc) — gains the `reviewed` param on update_transaction and makes builds reproducible - add an "Upstream Library & Fork Landscape" section to CLAUDE.md covering the parent/community/enhanced forks, our pin, unused capabilities, and a how-to-keep-current checklist - fix the stale dependency line that still referenced `monarchmoney ≥0.1.15` --- CLAUDE.md | 29 ++++++++++++++++++++++++++++- pyproject.toml | 4 +++- uv.lock | 4 ++-- 3 files changed, 33 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6d0cec8..c77d2f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -214,7 +214,7 @@ refactor: split server.py into modular components (auth, tools, models) ### Dependencies (Latest Versions - Updated July 2025) - **mcp[cli]**: Latest MCP protocol with FastMCP support (≥1.12.2) -- **monarchmoney**: Python client for Monarch Money API (≥0.1.15) +- **monarchmoneycommunity**: Python client for Monarch Money API — a maintained community fork, pinned to a commit SHA in `[tool.uv.sources]`. See "Upstream Library & Fork Landscape" below. - **pydantic**: Runtime type validation and data models (≥2.11.7) - **python-dateutil**: Enhanced date parsing support (≥2.9.0.post0) - **structlog**: Structured logging for debugging (≥25.4.0) @@ -402,6 +402,33 @@ Server runs as MCP server configured in `.mcp.json` with: **Current Status** (Updated October 2025): Production-ready with 70 passing tests, 22 intelligent tools, comprehensive analytics, robust error handling, and enhanced reliability. Recent features: `update_transactions_bulk()` for parallel batch updates, `search_transactions` tool for efficient context-aware search, detailed tool call debugging with result size tracking. Recent critical fixes completed: authentication retry bug (stale client after re-auth), date serialization, broken pipe handling, dependency updates, and enhanced date parsing. Server is stable and ready for real-world usage with excellent user experience for date filtering, bulk operations, and error recovery. +## Upstream Library & Fork Landscape + +**Last checked: 2026-05-28.** Update the date and findings below whenever you re-analyze (see "How to keep this current"). + +This MCP server is a thin wrapper over a Python Monarch Money client. That client is a *fork of a fork*, so it's worth understanding the lineage: + +| Repo | Role | Stars | Health (as of last check) | +|---|---|---|---| +| [`hammem/monarchmoney`](https://github.com/hammem/monarchmoney) | original parent | ~490 | **Effectively abandoned.** Critical fixes sit unmerged in 5+ open PRs (e.g. #184 API domain change, #191 gql 4.0 break). Do **not** depend on this directly. | +| [`bradleyseanf/monarchmoneycommunity`](https://github.com/bradleyseanf/monarchmoneycommunity) | **what we use** | ~84 | Active. `dev` branch was ~97 commits ahead of parent / 0 behind. Already carries the domain fix (`api.monarch.com`), gql 4.0 fix, auth persistence, and budget query fix. Published to PyPI as `monarchmoneycommunity`. | +| [`keithah/monarchmoney-enhanced`](https://github.com/keithah/monarchmoney-enhanced) | sibling fork, **not used yet** | ~24 | Active, MIT, on PyPI as `monarchmoney-enhanced`. ~6,100 LOC vs our ~3,500 — much larger surface. | + +**Our pin:** `pyproject.toml` → `[tool.uv.sources]` pins `monarchmoneycommunity` to a **specific commit SHA** (the fork's `dev` HEAD), not a moving branch, for reproducible builds. When bumping, update the SHA *and* the comment date there. + +**Unused capabilities in the fork we already depend on** (zero new dependencies — just need new `@mcp.tool()` wrappers in `server.py`): transaction tags (`get/set/create_transaction_tag`), splits (`get/update_transaction_splits`), `find_duplicate_transactions`, `get_transaction_details`, `get_cashflow_summary`, `get_subscription_details`, `get_credit_history`, `delete_transaction`, `create_transaction_category`, `update_account`, `request_accounts_refresh_and_wait`. + +**`keithah/monarchmoney-enhanced` (worth exploring in a followup, needs testing):** adds whole capability areas neither our fork nor the parent has, several of which map onto TODOs above — a transaction **rules engine** (categorization/amount/ignore rules + apply-to-existing), a built-in **caching layer** (`preload_cache`, `clear_cache`, cache metrics), **proactive session management** (`validate_session`, `ensure_valid_session`, `is_session_stale`), **goals**, **bills** (`get_bills`), **merchants**, and **insights** (`get_insights`, `get_net_worth_history`, `get_investment_performance`, `get_credit_score`). Caveat: it is **not** a strict superset — our current fork has a few methods it lacks (`upload_attachment`, `reset_budget`, flex-budget methods, `get_credit_history`). So adopting it is a real decision (switch dependency vs. cherry-pick specific GraphQL queries), not a drop-in — needs hands-on testing against a live account first. + +### How to keep this current + +Re-run this analysis periodically (e.g. quarterly, or when something breaks): +1. **Check our fork moved:** `gh api repos/bradleyseanf/monarchmoneycommunity/compare/main...dev` and compare `dev` HEAD SHA against our pinned SHA in `uv.lock`. Bump if meaningfully ahead. +2. **Check parent for new critical fixes:** `gh api 'repos/hammem/monarchmoney/issues?state=open&sort=reactions'` and the open PRs — verify our fork carries any new breaking-bug fixes. +3. **Check sibling forks:** `gh api 'repos/hammem/monarchmoney/forks?sort=stargazers'`. Diff method surfaces by downloading each fork's `monarchmoney/monarchmoney.py` and `comm`-ing the `def ` lists. +4. **Find unused wins:** diff the installed lib's public methods against the method names `server.py` passes to `api_call_with_retry(...)` — anything in the lib but not wrapped is a cheap new tool. +5. Update the **Last checked** date and the table above with what changed. + ## Documentation References **Keep These Updated Regularly:** diff --git a/pyproject.toml b/pyproject.toml index 45a2465..bf9f303 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -150,4 +150,6 @@ exclude_lines = [ ] [tool.uv.sources] -monarchmoneycommunity = { git = "https://github.com/bradleyseanf/monarchmoneycommunity", rev = "main" } +# Pinned to a specific commit (not a moving branch) for reproducible builds. +# This is the fork's `dev` HEAD as of 2026-05-28 — see "Upstream library" in CLAUDE.md. +monarchmoneycommunity = { git = "https://github.com/bradleyseanf/monarchmoneycommunity", rev = "befdadc7163f90053be5820346f3095b78c7a857" } diff --git a/uv.lock b/uv.lock index 4e4d38b..c50d321 100644 --- a/uv.lock +++ b/uv.lock @@ -967,7 +967,7 @@ dev = [ [package.metadata] requires-dist = [ { name = "mcp", extras = ["cli"], specifier = ">=1.26.0,<2" }, - { name = "monarchmoneycommunity", git = "https://github.com/bradleyseanf/monarchmoneycommunity?rev=main" }, + { name = "monarchmoneycommunity", git = "https://github.com/bradleyseanf/monarchmoneycommunity?rev=befdadc7163f90053be5820346f3095b78c7a857" }, { name = "pydantic", specifier = ">=2.12.5" }, { name = "python-dateutil", specifier = ">=2.9.0.post0" }, { name = "structlog", specifier = ">=25.5.0" }, @@ -986,7 +986,7 @@ dev = [ [[package]] name = "monarchmoneycommunity" version = "1.3.2" -source = { git = "https://github.com/bradleyseanf/monarchmoneycommunity?rev=main#4a26e220e03388c06603fffa3f22bed5714fe463" } +source = { git = "https://github.com/bradleyseanf/monarchmoneycommunity?rev=befdadc7163f90053be5820346f3095b78c7a857#befdadc7163f90053be5820346f3095b78c7a857" } dependencies = [ { name = "aiohttp" }, { name = "gql" },