actual-mcp-server 0.6.6 → 0.6.8

package/README.md

@@ -13,7 +13,7 @@
 
 **Talk to your budget. Run it anywhere. Trust it in production.**
 
-Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that connects any MCP-compatible AI assistant — [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), [Claude Desktop](https://claude.ai/download), and more — directly to your self-hosted [Actual Budget](https://actualbudget.org/) instance. Ask natural language questions, create transactions, analyse spending, and manage your entire budget without ever opening the Actual Budget UI.
+Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that connects any MCP-compatible AI assistant (such as [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), [Claude Desktop](https://claude.ai/download), and more) directly to your self-hosted [Actual Budget](https://actualbudget.org/) instance. Ask natural language questions, create transactions, analyse spending, and manage your entire budget without ever opening the Actual Budget UI.
 
 ```
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
@@ -33,11 +33,11 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **62 tools — the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
-- **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`) — no Docker or HTTP server needed for local use.
+- **62 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
+- **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`.
-- **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs — no shared tokens required.
+- **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
 > **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 63 tools tested end-to-end. Any MCP-compatible client should work.
@@ -69,22 +69,22 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 - Your **Budget Sync ID**: Actual → Settings → Show Advanced Settings → Sync ID
 - **Node.js 20+** (npm method) or **Docker**
 
-### Option A — Docker (recommended)
+### Option A: Docker (recommended)
 
 ```bash
 docker run -d \
   --name actual-mcp-server-backend \
   -p 3600:3600 \
   # Use the same URL you type in your browser to open Actual Budget:
-  #   http://localhost:5006          — if Actual Budget runs on the same machine
-  #   http://192.168.1.50:5006       — if it runs on another machine on your network
-  #   https://actual.yourdomain.com  — if you use a domain name
-  #   http://actual:5006             — if both containers share a Docker network (use container name)
+  #   http://localhost:5006          (if Actual Budget runs on the same machine)
+  #   http://192.168.1.50:5006       (if it runs on another machine on your network)
+  #   https://actual.yourdomain.com  (if you use a domain name)
+  #   http://actual:5006             (if both containers share a Docker network; use container name)
   -e ACTUAL_SERVER_URL=http://localhost:5006 \
   -e ACTUAL_PASSWORD=your_password \
   -e ACTUAL_BUDGET_SYNC_ID=your_sync_id \
   -e MCP_SSE_AUTHORIZATION=your_secret_token \
-  -v actual-mcp-data:/data \        # required — see note below
+  -v actual-mcp-data:/data \        # required, see note below
   -v actual-mcp-logs:/app/logs \
   ghcr.io/agigante80/actual-mcp-server:latest
 ```
@@ -114,7 +114,7 @@ curl -s -X POST http://localhost:3600/http \
 
 Also available on Docker Hub: `agigante80/actual-mcp-server:latest`
 
-### Option B — Docker Compose
+### Option B: Docker Compose
 
 ```bash
 git clone https://github.com/agigante80/actual-mcp-server.git
@@ -128,7 +128,7 @@ docker compose --profile dev up -d          # dev mode with hot-reload
 docker compose --profile fullstack up -d    # includes Actual Budget server on :5006
 ```
 
-### Option C — npm (HTTP server)
+### Option C: npm (HTTP server)
 
 ```bash
 # Quick start via npx (no clone needed):
@@ -149,9 +149,9 @@ npm run dev -- --http
 
 Server starts at `http://localhost:3000/http` (dev) or `http://localhost:3600/http` (Docker).
 
-### Option D — stdio (Claude Desktop native, no Docker or HTTP server needed)
+### Option D: stdio (Claude Desktop native, no Docker or HTTP server needed)
 
-The stdio transport runs the MCP server as a child process — Claude Desktop spawns it directly and communicates over stdin/stdout. No network port, no auth token, no Docker required. No cloning needed — `npx` downloads and caches the package automatically.
+The stdio transport runs the MCP server as a child process. Claude Desktop spawns it directly and communicates over stdin/stdout. No network port, no auth token, no Docker required. No cloning needed: `npx` downloads and caches the package automatically.
 
 Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) for config file location and all client options):
 
@@ -172,13 +172,13 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user — the transport itself is the security boundary. All 63 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 63 tools are available.
 >
-> **`MCP_BRIDGE_DATA_DIR` should be an absolute path** — without it, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
+> **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
 ### Connect an AI client
 
-**LibreChat / LobeChat** — add to `librechat.yaml` (or LobeChat MCP plugin settings):
+**LibreChat / LobeChat**: add to `librechat.yaml` (or LobeChat MCP plugin settings):
 
 ```yaml
 mcpServers:
@@ -212,7 +212,7 @@ See [docs/guides/AI_CLIENT_SETUP.md](docs/guides/AI_CLIENT_SETUP.md) for full Li
 }
 ```
 
-**Claude Desktop via stdio** (native, no HTTP server needed — see Option D above):
+**Claude Desktop via stdio** (native, no HTTP server needed; see Option D above):
 
 ```json
 {
@@ -266,7 +266,7 @@ npm run build
 
 ### npx / stdio (Options C & D)
 
-If you run `npx actual-mcp-server` without a globally installed version, npx fetches the latest from the registry automatically. But if you previously installed it globally (`npm install -g actual-mcp-server`), the global install takes precedence — you must upgrade it explicitly:
+If you run `npx actual-mcp-server` without a globally installed version, npx fetches the latest from the registry automatically. But if you previously installed it globally (`npm install -g actual-mcp-server`), the global install takes precedence, so you must upgrade it explicitly:
 
 ```bash
 # Upgrade the global install
@@ -315,7 +315,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 |------|-------------|
 | `actual_transactions_uncategorized` | Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass `includeTransactions:true` for paginated rows |
 
-**Exclusive ActualQL-powered (6)** — unique to this MCP server
+**Exclusive ActualQL-powered (6)**, unique to this MCP server
 
 | Tool | Description |
 |------|-------------|
@@ -332,7 +332,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 |------|-------------|
 | `actual_transfers_create` | Create a paired transfer between two accounts (debit + credit linked by `transfer_id`, identical to UI "Make Transfer") |
 
-> **How transfers work under the hood** — Actual Budget requires the `runTransfers: true` option when adding transactions so that both sides (the debit on the source account and the credit on the destination account) are created and linked via a shared `transfer_id`. Prior to v0.5.6, the adapter forwarded a hardcoded empty options object `{}` to `rawAddTransactions`, silently dropping any options including this flag. This meant that calling `actual_transfers_create` would appear to succeed but only one side of the transfer would be recorded. The fix ensures options are forwarded correctly; use `actual_transfers_create` (not `actual_transactions_create`) for all account-to-account moves.
+> **Note:** Use `actual_transfers_create` for any account-to-account movement, not `actual_transactions_create`. The dedicated tool creates both sides (debit and credit) atomically so the books stay balanced. Limitations: both accounts must exist and be open, and `from_account` must differ from `to_account`.
 
 ### Categories (4)
 
@@ -374,7 +374,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ### Batch Operations (1)
 
-`actual_budget_updates_batch` — batch multiple budget updates in one call
+`actual_budget_updates_batch`: batch multiple budget updates in one call
 
 ### Server Information & Lookup (3)
 
@@ -404,13 +404,13 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 |----------|---------|----------|-------------|
 | **Actual Budget Connection** ||||
 | `ACTUAL_SERVER_URL` | `http://localhost:5006` | Yes | URL of your Actual Budget server. Use the same URL you type in your browser: `http://localhost:5006` (local), `http://192.168.1.x:5006` (network), `https://actual.yourdomain.com` (domain), or `http://actual:5006` (container name if on the same Docker network) |
-| `ACTUAL_PASSWORD` | — | Yes | Password for Actual Budget server |
-| `ACTUAL_BUDGET_SYNC_ID` | — | Yes | Budget Sync ID from Actual (Settings → Sync ID) |
-| `ACTUAL_BUDGET_PASSWORD` | — | No | Optional encryption password for encrypted budgets |
+| `ACTUAL_PASSWORD` | _(none)_ | Yes | Password for Actual Budget server |
+| `ACTUAL_BUDGET_SYNC_ID` | _(none)_ | Yes | Budget Sync ID from Actual (Settings then Sync ID) |
+| `ACTUAL_BUDGET_PASSWORD` | _(none)_ | No | Optional encryption password for encrypted budgets |
 | **MCP Server Settings** ||||
 | `MCP_BRIDGE_PORT` | `3000` (dev) / `3600` (Docker) | No | Port for MCP server to listen on |
 | `MCP_BRIDGE_BIND_HOST` | `0.0.0.0` | No | Host address to bind server to (`0.0.0.0` = all interfaces) |
-| `MCP_BRIDGE_DATA_DIR` | `./actual-data` | No | Directory to store Actual Budget local data (SQLite). **Required to be a persistent path.** The `@actual-app/api` library downloads a local copy of your budget here to run queries — use a volume mount in Docker to persist it across restarts |
+| `MCP_BRIDGE_DATA_DIR` | `./actual-data` | No | Directory to store Actual Budget local data (SQLite). **Required to be a persistent path.** The `@actual-app/api` library downloads a local copy of your budget here to run queries; use a volume mount in Docker to persist it across restarts |
 | `MCP_BRIDGE_PUBLIC_HOST` | auto-detected | No | Public hostname/IP for server (shown in logs) |
 | `MCP_BRIDGE_PUBLIC_SCHEME` | auto-detected | No | Public scheme (`http` or `https`) |
 | `MCP_BRIDGE_USE_TLS` | `false` | No | Set to `true` to advertise `https://` in the server URL (for reverse-proxy setups where TLS is terminated upstream) |
@@ -424,14 +424,14 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `SESSION_IDLE_TIMEOUT_MINUTES` | `5` (pool) / `2` (HTTP) | No | Minutes before idle session cleanup |
 | **Security & Authentication** ||||
 | `AUTH_PROVIDER` | `none` | No | Auth mode: `none` (static Bearer) or `oidc` (JWKS-validated JWT) |
-| `MCP_SSE_AUTHORIZATION` | — | No | Static Bearer token (`AUTH_PROVIDER=none`; highly recommended in production) |
-| `OIDC_ISSUER` | — | If OIDC | OIDC issuer URL (e.g., `https://sso.example.com`) |
-| `OIDC_RESOURCE` | — | No | Expected `aud` claim in JWT (your client ID) |
-| `OIDC_SCOPES` | — | No | Comma-separated required scopes; leave empty for Casdoor |
-| `AUTH_BUDGET_ACL` | — | No | Per-user budget ACL — see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
+| `MCP_SSE_AUTHORIZATION` | _(none)_ | No | Static Bearer token (`AUTH_PROVIDER=none`; highly recommended in production) |
+| `OIDC_ISSUER` | _(none)_ | If OIDC | OIDC issuer URL (e.g., `https://sso.example.com`) |
+| `OIDC_RESOURCE` | _(none)_ | No | Expected `aud` claim in JWT (your client ID) |
+| `OIDC_SCOPES` | _(none)_ | No | Comma-separated required scopes; leave empty for Casdoor |
+| `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
 | `MCP_ENABLE_HTTPS` | `false` | No | Enable native TLS. Requires `MCP_HTTPS_CERT` and `MCP_HTTPS_KEY` |
-| `MCP_HTTPS_CERT` | — | No | Path to PEM certificate file (required when `MCP_ENABLE_HTTPS=true`) |
-| `MCP_HTTPS_KEY` | — | No | Path to PEM private key file (required when `MCP_ENABLE_HTTPS=true`) |
+| `MCP_HTTPS_CERT` | _(none)_ | No | Path to PEM certificate file (required when `MCP_ENABLE_HTTPS=true`) |
+| `MCP_HTTPS_KEY` | _(none)_ | No | Path to PEM private key file (required when `MCP_ENABLE_HTTPS=true`) |
 | **Logging Configuration** ||||
 | `MCP_BRIDGE_STORE_LOGS` | `false` | No | Enable file logging (vs console only) |
 | `MCP_BRIDGE_LOG_DIR` | `./logs` | No | Directory for log files (if `STORE_LOGS=true`) |
@@ -461,11 +461,11 @@ Configure multiple Actual Budget files so the AI can switch between them at runt
 | Variable | Required | Fallback |
 |----------|----------|---------|
 | `BUDGET_DEFAULT_NAME` | No | `"Default"` |
-| `BUDGET_N_NAME` | Yes (enables group) | — |
-| `BUDGET_N_SYNC_ID` | Yes | — |
+| `BUDGET_N_NAME` | Yes (enables group) | _(none)_ |
+| `BUDGET_N_SYNC_ID` | Yes | _(none)_ |
 | `BUDGET_N_SERVER_URL` | No | `ACTUAL_SERVER_URL` |
 | `BUDGET_N_PASSWORD` | No | `ACTUAL_PASSWORD` |
-| `BUDGET_N_ENCRYPTION_PASSWORD` | No | — |
+| `BUDGET_N_ENCRYPTION_PASSWORD` | No | _(none)_ |
 
 ```bash
 # Default budget
@@ -474,11 +474,11 @@ ACTUAL_PASSWORD=my-password
 ACTUAL_BUDGET_SYNC_ID=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
 BUDGET_DEFAULT_NAME=Personal
 
-# Budget 1 — same server, same password
+# Budget 1 (same server, same password)
 BUDGET_1_NAME=Family
 BUDGET_1_SYNC_ID=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
 
-# Budget 2 — different server
+# Budget 2 (different server)
 BUDGET_2_NAME=Business
 BUDGET_2_SERVER_URL=https://actual-office.example.com
 BUDGET_2_PASSWORD=office-password
@@ -496,7 +496,7 @@ The server supports two transport modes:
 | HTTP | `--http` | LibreChat, LobeChat, Docker, multi-user deployments | Bearer token or OIDC |
 | stdio | `--stdio` | Claude Desktop, Cursor, local single-user use | None (OS process isolation) |
 
-The two modes are mutually exclusive — pass exactly one flag when starting the server.
+The two modes are mutually exclusive. Pass exactly one flag when starting the server.
 
 ### stdio transport
 
@@ -504,8 +504,8 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 
 **Key properties of stdio mode:**
 
-- No network port — the transport is a pipe, not a socket
-- No auth token — process ownership is the security boundary
+- No network port. The transport is a pipe, not a socket.
+- No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
 - All 63 tools are available, identical to HTTP mode
@@ -576,7 +576,7 @@ OIDC_RESOURCE=your-client-id    # must match 'aud' JWT claim
 OIDC_SCOPES=                    # leave empty for Casdoor
 ```
 
-See [AI Client Setup — OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) for `AUTH_BUDGET_ACL` format and Casdoor notes.
+See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) for `AUTH_BUDGET_ACL` format and Casdoor notes.
 
 ---
 
@@ -602,7 +602,7 @@ See [`tests/manual/README.md`](tests/manual/README.md) and [`tests/e2e/README.md
 
 | Document | Contents |
 |---|---|
-| [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) | **Start here** — connect Claude Desktop, Cursor, VS Code (Copilot), Gemini CLI, or Claude Code |
+| [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) | **Start here** to connect Claude Desktop, Cursor, VS Code (Copilot), Gemini CLI, or Claude Code |
 | [docs/guides/AI_CLIENT_SETUP.md](docs/guides/AI_CLIENT_SETUP.md) | LibreChat & LobeChat setup, Docker networking, HTTPS/TLS proxy, OIDC |
 | [docs/guides/DEPLOYMENT.md](docs/guides/DEPLOYMENT.md) | Docker, Docker Compose profiles, production config, Kubernetes |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Component layers, data flow, transport protocols |
@@ -628,36 +628,36 @@ Several MCP servers exist for personal finance management. Here's how this proje
 | **Budget App** | Actual Budget (self-hosted) | Actual Budget (self-hosted) | Actual Budget (self-hosted) | YNAB (cloud, subscription) |
 | **Language** | TypeScript / Node.js | TypeScript / Node.js | TypeScript / Node.js | Python |
 | **Tool Count** | **63** | ~22 | 18 | 9 |
-| **— Setup & Distribution —** |||||
+| **Setup & Distribution** |||||
 | **Transport** | HTTP + stdio | STDIO + SSE option | STDIO | STDIO |
 | **Docker support** | ✅ Full (image + Compose) | ✅ Image only | ❌ | ❌ |
 | **Published package (npx/pip)** | ✅ `npx actual-mcp-server` | ✅ `npx actual-mcp` | ✅ `npx actual-budget-mcp` | ✅ `pip install ynab-mcp` |
-| **— Security & Access —** |||||
+| **Security & Access** |||||
 | **Authentication** | ✅ Bearer token + OIDC (JWKS) | ⚠️ Optional Bearer token | ❌ None (local only) | ✅ OS keyring / env var |
 | **Read-only mode** | ❌ All tools always available | ✅ Write requires `--enable-write` flag | ❌ | ✅ Most tools are read-only |
 | **Multi-budget switching** | ✅ Runtime switch via tool | ❌ | ❌ | ✅ (YNAB natively multi-budget) |
-| **— Production & Reliability —** |||||
+| **Production & Reliability** |||||
 | **Connection pooling** | ✅ Up to 15 concurrent sessions | ❌ | ❌ | ❌ |
 | **Retry / backoff** | ✅ 3 attempts, exponential backoff | ❌ | ❌ | ❌ |
 | **Automated test suite** | ✅ Unit + E2E + integration | ❌ | ❌ | ❌ |
-| **— Transactions —** |||||
+| **Transactions** |||||
 | **Create / update / delete** | ✅ | ✅ | ✅ | ✅ |
 | **Import & reconcile** | ✅ `actual_transactions_import` | ❌ | ❌ | ❌ |
 | **Scheduled / recurring** | ❌ (planned) | ❌ | ❌ | ❌ |
-| **— Analysis & Reporting —** |||||
+| **Analysis & Reporting** |||||
 | **ActualQL custom queries** | ✅ 6 exclusive tools + `actual_query_run` | ❌ | ❌ | N/A |
 | **Summary by category / payee** | ✅ | ✅ spending-by-category | ✅ | ❌ |
 | **Spending projections / forecast** | ❌ | ❌ | ✅ end-of-month forecast | ❌ |
 | **Budget vs actual comparison** | ✅ via `actual_budgets_getMonth` | ❌ | ✅ dedicated tool | ✅ month summary |
 | **Bank sync** | ✅ GoCardless / SimpleFIN | ❌ | ✅ | ❌ (YNAB handles sync natively) |
-| **— Budget Management —** |||||
+| **Budget Management** |||||
 | **Set / transfer / carryover / hold** | ✅ Full (10 tools) | ❌ | ✅ Partial | ✅ Partial |
 | **Batch budget updates** | ✅ `actual_budget_updates_batch` | ❌ | ❌ | ❌ |
-| **— Accounts, Payees & Rules —** |||||
+| **Accounts, Payees & Rules** |||||
 | **Account lifecycle (close/reopen)** | ✅ | ❌ | ❌ | N/A |
 | **Payee merging** | ✅ `actual_payees_merge` | ❌ | ❌ | N/A |
 | **Payee rules management** | ✅ Full CRUD | ✅ Full CRUD | ❌ | N/A |
-| **— UX & Usability —** |||||
+| **UX & Usability** |||||
 | **Natural language date parsing** | ❌ YYYY-MM-DD required | ❌ | ✅ "last month", "yesterday" | ❌ |
 | **Bilingual support** | ❌ | ❌ | ✅ English + Spanish | ❌ |
 | **Auto name → UUID resolution** | ⚠️ Explicit tool (`actual_get_id_by_name`) | ❌ | ✅ Automatic in all tools | ❌ |
@@ -667,10 +667,10 @@ Several MCP servers exist for personal finance management. Here's how this proje
 
 ### When to choose which project
 
-- **This project** — best for production deployments, multi-user environments (OIDC), LibreChat/LobeChat, Docker-native setup, or for Claude Desktop users who want a native stdio connection without any HTTP server overhead.
-- **s-stefanov/actual-mcp** — the original implementation; good for Claude Desktop with STDIO transport, AI-generated prompt templates, and built-in read-only mode.
-- **henfrydls/actual-budget-mcp** — best for Spanish-speaking users, Cursor/VS Code integration, or when you want natural-language dates, automatic name resolution, and spending forecasts without any server setup.
-- **WGDevelopment/ynab-mcp-server** — only option if you're a YNAB user; privacy-first design with OS keyring token storage and local-LLM focus.
+- **This project**: best for production deployments, multi-user environments (OIDC), LibreChat/LobeChat, Docker-native setup, or for Claude Desktop users who want a native stdio connection without any HTTP server overhead.
+- **s-stefanov/actual-mcp**: the original implementation; good for Claude Desktop with STDIO transport, AI-generated prompt templates, and built-in read-only mode.
+- **henfrydls/actual-budget-mcp**: best for Spanish-speaking users, Cursor/VS Code integration, or when you want natural-language dates, automatic name resolution, and spending forecasts without any server setup.
+- **WGDevelopment/ynab-mcp-server**: only option if you're a YNAB user; privacy-first design with OS keyring token storage and local-LLM focus.
 
 ---
 
@@ -702,16 +702,16 @@ Every Actual API call goes through the `withActualApi()` wrapper in `src/lib/act
 
 ## License
 
-MIT — see [LICENSE](LICENSE) for details.
+MIT. See [LICENSE](LICENSE) for details.
 
 ---
 
 ## Acknowledgments
 
-- **[Actual Budget](https://actualbudget.org/)** — open-source budgeting software
-- **[Model Context Protocol](https://modelcontextprotocol.io/)** — standardised AI-app integration
-- **[LibreChat](https://github.com/danny-avila/LibreChat)** — open-source ChatGPT alternative
-- **[s-stefanov/actual-mcp](https://github.com/s-stefanov/actual-mcp)** — original adapter pattern
+- **[Actual Budget](https://actualbudget.org/)**: open-source budgeting software
+- **[Model Context Protocol](https://modelcontextprotocol.io/)**: standardised AI-app integration
+- **[LibreChat](https://github.com/danny-avila/LibreChat)**: open-source ChatGPT alternative
+- **[s-stefanov/actual-mcp](https://github.com/s-stefanov/actual-mcp)**: original adapter pattern
 
 ---
 
@@ -725,9 +725,9 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ## Support
 
-- **[GitHub Issues](https://github.com/agigante80/actual-mcp-server/issues)** — bug reports and feature requests
-- **[GitHub Discussions](https://github.com/agigante80/actual-mcp-server/discussions)** — questions and ideas
+- **[GitHub Issues](https://github.com/agigante80/actual-mcp-server/issues)**: bug reports and feature requests
+- **[GitHub Discussions](https://github.com/agigante80/actual-mcp-server/discussions)**: questions and ideas
 
 ---
 
-**Version:** 0.6.6 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.8 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,12 +1,12 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.6",
+    "version": "0.6.8",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
     },
-    "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget — HTTP and stdio transports, LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+    "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
     "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
     "repository": {
         "type": "git",
@@ -30,7 +30,7 @@
         "verify-tools": "npm run build && node scripts/verify-tools.js",
         "check:coverage": "node scripts/list-actual-api-methods.mjs",
         "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js",
+        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js",
         "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
         "test:e2e": "npx playwright test",
         "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",
@@ -57,7 +57,7 @@
         "release:patch": "npm run version:bump -- patch"
     },
     "dependencies": {
-        "@actual-app/api": "^26.5.0",
+        "@actual-app/api": "^26.5.2",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "debug": "^4.4.3",
         "dotenv": "^17.4.2",

package/dist/src/lib/actual-adapter.js

@@ -558,6 +558,27 @@ function queueWriteOperation(operation) {
         }, WRITE_SESSION_DELAY_MS);
     });
 }
+/**
+ * Run a read+write atomic sequence inside a SINGLE write-queue session.
+ *
+ * Use this when a tool needs to read state, decide what to write based on
+ * that state, and write all within one lock acquisition. Compare with the
+ * default pattern of one `withActualApi` (read) followed by one
+ * `queueWriteOperation` (write), which holds the api lock TWICE.
+ *
+ * Inside the callback, use the raw `@actual-app/api` functions imported at
+ * the top of `actual-adapter.ts` (e.g. `rawGetRules`, `rawDeleteRule`). Do
+ * NOT call public adapter methods (e.g. `adapter.getRules`) inside the
+ * callback, since each public adapter method opens its own lock cycle and
+ * defeats the purpose of this helper.
+ *
+ * Inherits the correctness guarantees of `queueWriteOperation`: serialised
+ * via `withApiLock`, single `api.sync()` after the callback resolves,
+ * pool-aware shutdown semantics. Issue #142.
+ */
+export async function withWriteSession(fn) {
+    return queueWriteOperation(fn);
+}
 function processQueue() {
     if (running >= MAX_CONCURRENCY)
         return;
@@ -876,6 +897,43 @@ export async function setBudgetAmount(month, categoryId, amount) {
         return result;
     });
 }
+export async function transferBudgetAmount(month, fromCategoryId, toCategoryId, amount) {
+    observability.incrementToolCall('actual.budgets.transfer').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Inside processWriteQueue we already hold _apiSessionLock and the api is
+        // initialised. Call raw functions only: adapter wrappers would re-enter
+        // queueWriteOperation / withActualApi and defeat the single-cycle goal.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const budgetMonth = await rawGetBudgetMonth(month);
+        if (!budgetMonth?.categoryGroups) {
+            throw new Error(`Budget not found for month ${month}`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const cats = budgetMonth.categoryGroups.flatMap((g) => g.categories || []);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const from = cats.find((c) => c.id === fromCategoryId);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const to = cats.find((c) => c.id === toCategoryId);
+        if (!from)
+            throw new Error(`Source category ${fromCategoryId} not found in budget`);
+        if (!to)
+            throw new Error(`Target category ${toCategoryId} not found in budget`);
+        const prevFrom = from.budgeted || 0;
+        const prevTo = to.budgeted || 0;
+        if (prevFrom < amount) {
+            throw new Error(`Insufficient budget in source category. Available: ${prevFrom}, Requested: ${amount}`);
+        }
+        await rawBatchBudgetUpdates(async () => {
+            await rawSetBudgetAmount(month, fromCategoryId, prevFrom - amount);
+            await rawSetBudgetAmount(month, toCategoryId, prevTo + amount);
+        });
+        return {
+            transferred: amount,
+            fromCategory: { id: fromCategoryId, previousAmount: prevFrom, newAmount: prevFrom - amount },
+            toCategory: { id: toCategoryId, previousAmount: prevTo, newAmount: prevTo + amount },
+        };
+    });
+}
 export async function createAccount(account, initialBalance) {
     observability.incrementToolCall('actual.accounts.create').catch(() => { });
     return queueWriteOperation(async () => {
@@ -1635,6 +1693,7 @@ export default {
     mergePayees,
     getPayeeRules,
     batchBudgetUpdates,
+    transferBudgetAmount,
     holdBudgetForNextMonth,
     resetBudgetHold,
     runQuery,
@@ -1649,5 +1708,6 @@ export default {
     updateSchedule,
     deleteSchedule,
     updateTransactionBatch,
+    withWriteSession,
     notifications,
 };

package/dist/src/tools/budgets_transfer.js

@@ -1,10 +1,19 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({
-    month: z.string().describe('Month in YYYY-MM format'),
-    fromCategoryId: z.string().describe('Source category ID to transfer from'),
-    toCategoryId: z.string().describe('Target category ID to transfer to'),
-    amount: z.number().describe('Amount to transfer in cents (positive integer)'),
+    month: z.string()
+        .regex(/^\d{4}-\d{2}$/, 'month must be YYYY-MM')
+        .describe('Month in YYYY-MM format'),
+    fromCategoryId: z.string()
+        .min(1, 'fromCategoryId is required')
+        .describe('Source category ID to transfer from'),
+    toCategoryId: z.string()
+        .min(1, 'toCategoryId is required')
+        .describe('Target category ID to transfer to'),
+    amount: z.number()
+        .int('amount must be an integer (cents)')
+        .positive('amount must be positive (cents)')
+        .describe('Amount to transfer in cents (positive integer)'),
 });
 const tool = {
     name: 'actual_budgets_transfer',
@@ -12,51 +21,16 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        if (input.amount <= 0) {
-            throw new Error('Transfer amount must be positive');
-        }
         if (input.fromCategoryId === input.toCategoryId) {
             throw new Error('Source and target categories must be different');
         }
-        // Get current budget for both categories
-        const budgetMonth = await adapter.getBudgetMonth(input.month);
-        if (!budgetMonth || !budgetMonth.categoryGroups) {
-            throw new Error(`Budget not found for month ${input.month}`);
-        }
-        // Flatten categories from all groups
-        const allCategories = budgetMonth.categoryGroups.flatMap((group) => group.categories || []);
-        const fromBudget = allCategories.find((c) => c.id === input.fromCategoryId);
-        const toBudget = allCategories.find((c) => c.id === input.toCategoryId);
-        if (!fromBudget) {
-            throw new Error(`Source category ${input.fromCategoryId} not found in budget`);
-        }
-        if (!toBudget) {
-            throw new Error(`Target category ${input.toCategoryId} not found in budget`);
-        }
-        const currentFromAmount = fromBudget.budgeted || 0;
-        const currentToAmount = toBudget.budgeted || 0;
-        // Check if source has enough budget
-        if (currentFromAmount < input.amount) {
-            throw new Error(`Insufficient budget in source category. Available: ${currentFromAmount}, Requested: ${input.amount}`);
-        }
-        // Perform the transfer - use adapter.setBudgetAmount directly (already queued)
-        // Note: Don't use batchBudgetUpdates as it creates a nested queue deadlock
-        await adapter.setBudgetAmount(input.month, input.fromCategoryId, currentFromAmount - input.amount);
-        await adapter.setBudgetAmount(input.month, input.toCategoryId, currentToAmount + input.amount);
+        const out = await adapter.transferBudgetAmount(input.month, input.fromCategoryId, input.toCategoryId, input.amount);
         return {
             result: {
                 success: true,
-                transferred: input.amount,
-                fromCategory: {
-                    id: input.fromCategoryId,
-                    previousAmount: currentFromAmount,
-                    newAmount: currentFromAmount - input.amount,
-                },
-                toCategory: {
-                    id: input.toCategoryId,
-                    previousAmount: currentToAmount,
-                    newAmount: currentToAmount + input.amount,
-                },
+                transferred: out.transferred,
+                fromCategory: out.fromCategory,
+                toCategory: out.toCategory,
             },
         };
     },

package/dist/src/tools/category_groups_delete.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { notFoundMsg } from '../lib/errors.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getCategoryGroups: rawGetCategoryGroups, deleteCategoryGroup: rawDeleteCategoryGroup } = api;
 const InputSchema = z.object({
     id: z.string().describe('Category group ID to delete'),
 });
@@ -10,17 +13,21 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Pre-flight: verify category group exists (BUG-10)
-        const groups = await adapter.getCategoryGroups();
-        const groupExists = groups.some((g) => g.id === input.id);
-        if (!groupExists) {
-            return {
-                error: notFoundMsg('Category group', input.id, 'actual_category_groups_get'),
-                success: false,
-            };
-        }
-        await adapter.deleteCategoryGroup(input.id);
-        return { success: true };
+        // Read+write inside one withWriteSession cycle (#142).
+        return await adapter.withWriteSession(async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const groups = await rawGetCategoryGroups();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const groupExists = groups.some((g) => g.id === input.id);
+            if (!groupExists) {
+                return {
+                    error: notFoundMsg('Category group', input.id, 'actual_category_groups_get'),
+                    success: false,
+                };
+            }
+            await rawDeleteCategoryGroup(input.id);
+            return { success: true };
+        });
     },
 };
 export default tool;

package/dist/src/tools/payees_delete.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { deletePayee: rawDeletePayee } = api;
 const InputSchema = z.object({
     id: z.string().describe('Payee ID to delete'),
 });
@@ -9,8 +12,12 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.deletePayee(input.id);
-        return { success: true };
+        // Single-write tool, but uses withWriteSession for consistency with the other
+        // delete tools and to share the same lock-cycle invariant (#142).
+        return await adapter.withWriteSession(async () => {
+            await rawDeletePayee(input.id);
+            return { success: true };
+        });
     },
 };
 export default tool;

package/dist/src/tools/rules_create_or_update.js

@@ -18,7 +18,10 @@
  * - Reuses exact same ConditionSchema / ActionSchema / FIELD_OPERATORS as rules_create.ts
  */
 import { z } from 'zod';
-import adapter from '../lib/actual-adapter.js';
+import adapter, { normalizeToId } from '../lib/actual-adapter.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule } = api;
 // Mirrors the same schemas used in rules_create.ts
 const ConditionSchema = z.object({
     field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category", "imported_payee")'),
@@ -148,36 +151,45 @@ Returns: { id, created: boolean } — created=true if new rule was created, fals
                     throw new Error(`Action "${action.op}" requires a string value.`);
                 }
             }
-            // ── Fetch existing rules and look for a match ──
-            const existingRules = await adapter.getRules();
-            let matchedRule = null;
-            for (const rule of existingRules) {
-                const r = rule;
-                if (!r.id || typeof r.id !== 'string')
-                    continue;
-                const existingConditions = Array.isArray(r.conditions) ? r.conditions : [];
-                const existingConditionsOp = r.conditionsOp || 'and';
-                if (conditionsMatch(existingConditions, existingConditionsOp, input.conditions, input.conditionsOp)) {
-                    matchedRule = r;
-                    break;
+            // Fetch existing rules and either update (matched) or create (no match) inside
+            // ONE withWriteSession cycle so the read and the write share a single lock
+            // acquisition (#142).
+            return await adapter.withWriteSession(async () => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const existingRules = await rawGetRules();
+                let matchedRule = null;
+                for (const rule of existingRules) {
+                    const r = rule;
+                    if (!r.id || typeof r.id !== 'string')
+                        continue;
+                    const existingConditions = Array.isArray(r.conditions) ? r.conditions : [];
+                    const existingConditionsOp = r.conditionsOp || 'and';
+                    if (conditionsMatch(existingConditions, existingConditionsOp, input.conditions, input.conditionsOp)) {
+                        matchedRule = r;
+                        break;
+                    }
                 }
-            }
-            const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for API call
-            if (matchedRule) {
-                // ── UPDATE existing rule ──
-                await adapter.updateRule(matchedRule.id, {
-                    stage: ruleData.stage,
-                    conditionsOp: ruleData.conditionsOp,
-                    conditions: ruleData.conditions,
-                    actions: ruleData.actions,
-                });
-                return { id: matchedRule.id, created: false };
-            }
-            else {
-                // ── CREATE new rule ──
-                const ruleId = await adapter.createRule(ruleData);
-                return { id: ruleId, created: true };
-            }
+                const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for API call
+                if (matchedRule) {
+                    // UPDATE existing rule. The Actual Budget API expects the FULL merged rule
+                    // object passed as a single argument (matches adapter.updateRule's behaviour).
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const merged = {
+                        id: matchedRule.id,
+                        stage: ruleData.stage ?? matchedRule.stage,
+                        conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
+                        conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
+                        actions: ruleData.actions ?? matchedRule.actions ?? [],
+                    };
+                    await rawUpdateRule(merged);
+                    return { id: matchedRule.id, created: false };
+                }
+                else {
+                    // CREATE new rule
+                    const rawId = await rawCreateRule(ruleData);
+                    return { id: normalizeToId(rawId), created: true };
+                }
+            });
         }
         catch (error) {
             if (error instanceof z.ZodError) {

package/dist/src/tools/rules_delete.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { notFoundMsg } from '../lib/errors.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getRules: rawGetRules, deleteRule: rawDeleteRule } = api;
 const InputSchema = z.object({
     id: z.string().describe('Rule ID to delete'),
 });
@@ -10,17 +13,21 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Pre-flight: verify rule exists (BUG-9)
-        const allRules = await adapter.getRules();
-        const ruleExists = allRules.some((r) => r.id === input.id);
-        if (!ruleExists) {
-            return {
-                error: notFoundMsg('Rule', input.id, 'actual_rules_get'),
-                success: false,
-            };
-        }
-        await adapter.deleteRule(input.id);
-        return { success: true };
+        // Read+write inside one withWriteSession cycle (#142).
+        return await adapter.withWriteSession(async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const allRules = await rawGetRules();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ruleExists = allRules.some((r) => r.id === input.id);
+            if (!ruleExists) {
+                return {
+                    error: notFoundMsg('Rule', input.id, 'actual_rules_get'),
+                    success: false,
+                };
+            }
+            await rawDeleteRule(input.id);
+            return { success: true };
+        });
     },
 };
 export default tool;

package/dist/src/tools/schedules_delete.js

@@ -2,6 +2,9 @@ import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { UUID_PATTERN } from '../lib/constants.js';
 import { notFoundMsg, constraintErrorMsg } from '../lib/errors.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getSchedules: rawGetSchedules, deleteSchedule: rawDeleteSchedule } = api;
 const InputSchema = z.object({
     id: z.string().regex(UUID_PATTERN, 'Invalid UUID format')
         .describe('UUID of the schedule to delete (from actual_schedules_get)'),
@@ -12,30 +15,34 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Pre-flight: verify schedule exists (BUG-11)
-        const schedules = await adapter.getSchedules();
-        const scheduleExists = schedules.some((s) => s.id === input.id);
-        if (!scheduleExists) {
-            return {
-                error: notFoundMsg('Schedule', input.id, 'actual_schedules_get'),
-                success: false,
-            };
-        }
-        try {
-            await adapter.deleteSchedule(input.id);
-            return { success: true };
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            // Translate raw SQLite constraint errors into user-readable messages
-            if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
+        // Read+write inside one withWriteSession cycle (#142). The constraint-error
+        // translation stays right around the delete call so error messages do not regress.
+        return await adapter.withWriteSession(async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const schedules = await rawGetSchedules();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const scheduleExists = schedules.some((s) => s.id === input.id);
+            if (!scheduleExists) {
                 return {
-                    error: constraintErrorMsg('Schedule', input.id, 'actual_schedules_get'),
+                    error: notFoundMsg('Schedule', input.id, 'actual_schedules_get'),
                     success: false,
                 };
             }
-            throw err;
-        }
+            try {
+                await rawDeleteSchedule(input.id);
+                return { success: true };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
+                    return {
+                        error: constraintErrorMsg('Schedule', input.id, 'actual_schedules_get'),
+                        success: false,
+                    };
+                }
+                throw err;
+            }
+        });
     },
 };
 export default tool;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget — HTTP and stdio transports, LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
   "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",
@@ -57,7 +57,7 @@
     "release:patch": "npm run version:bump -- patch"
   },
   "dependencies": {
-    "@actual-app/api": "^26.5.0",
+    "@actual-app/api": "^26.5.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "debug": "^4.4.3",
     "dotenv": "^17.4.2",