actual-mcp-server 0.7.2 → 0.7.4

package/README.md

@@ -1,4 +1,8 @@
-# Actual MCP Server
+<p align="center">
+  <img src="unraid/actual-mcp-icon.png" alt="Actual MCP Server icon" width="128" height="128">
+</p>
+
+<h1 align="center">Actual MCP Server</h1>
 
 [![npm version](https://img.shields.io/npm/v/actual-mcp-server)](https://www.npmjs.com/package/actual-mcp-server)
 [![npm downloads](https://img.shields.io/npm/dm/actual-mcp-server)](https://www.npmjs.com/package/actual-mcp-server)
@@ -51,10 +55,9 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 - [Available Tools](#available-tools)
 - [Configuration](#configuration)
 - [Multi-Budget Switching](#multi-budget-switching)
-- [Transport & Authentication](#transport--authentication)
+- [Transport & Authentication](#transport-authentication)
 - [Testing](#testing)
 - [Documentation](#documentation)
-- [Comparison with Similar Projects](#comparison-with-similar-projects)
 - [Contributing](#contributing)
 - [License](#license)
 - [Disclaimer](#disclaimer)
@@ -634,74 +637,14 @@ See [`tests/manual/README.md`](tests/manual/README.md) and [`tests/e2e/README.md
 | [docs/SECURITY_AND_PRIVACY.md](docs/SECURITY_AND_PRIVACY.md) | Auth models, threat model, hardening |
 | [docs/TESTING_AND_RELIABILITY.md](docs/TESTING_AND_RELIABILITY.md) | Test strategy, coverage, reliability patterns |
 | [docs/NEW_TOOL_CHECKLIST.md](docs/NEW_TOOL_CHECKLIST.md) | Step-by-step guide for adding a new MCP tool |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, code standards, PR process |
+| [CONTRIBUTING.md](.github/CONTRIBUTING.md) | Development setup, code standards, PR process |
 | [.env.example](.env.example) | Fully annotated environment variable reference |
 
 ---
 
-## Comparison with Similar Projects
-
-Several MCP servers exist for personal finance management. Here's how this project compares with the closest alternatives.
-
-> **Snapshot date**: 2026-03-20. Versions and features reflect each project's latest release at that date.
-
-### Feature Comparison
-
-| Feature | **agigante80/actual-mcp-server** | [s-stefanov/actual-mcp](https://github.com/s-stefanov/actual-mcp) | [henfrydls/actual-budget-mcp](https://github.com/henfrydls/actual-budget-mcp) | [WGDevelopment/ynab-mcp-server](https://github.com/WGDevelopment/ynab-mcp-server) |
-|---|---|---|---|---|
-| **Version** | v0.4.26 | v1.11.1 | v0.2.0 | v0.1.0 |
-| **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** | **71** | ~22 | 18 | 9 |
-| **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** |||||
-| **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** |||||
-| **Connection pooling** | ✅ Up to 15 concurrent sessions | ❌ | ❌ | ❌ |
-| **Retry / backoff** | ✅ 3 attempts, exponential backoff | ❌ | ❌ | ❌ |
-| **Automated test suite** | ✅ Unit + E2E + integration | ❌ | ❌ | ❌ |
-| **Transactions** |||||
-| **Create / update / delete** | ✅ | ✅ | ✅ | ✅ |
-| **Import & reconcile** | ✅ `actual_transactions_import` | ❌ | ❌ | ❌ |
-| **Scheduled / recurring** | ❌ (planned) | ❌ | ❌ | ❌ |
-| **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** |||||
-| **Set / transfer / carryover / hold** | ✅ Full (10 tools) | ❌ | ✅ Partial | ✅ Partial |
-| **Batch budget updates** | ✅ `actual_budget_updates_batch` | ❌ | ❌ | ❌ |
-| **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** |||||
-| **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 | ❌ |
-| **AI prompt templates** | ❌ | ✅ financial-insights, budget-review | ❌ | ❌ |
-| **Tested AI clients** | LibreChat, LobeChat | Claude Desktop, Codex | Claude Desktop, Cursor, VS Code | Claude Code |
-| **License** | MIT | MIT | MIT | MIT |
-
-### 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.
-
----
-
 ## Contributing
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code standards, and the PR process.
+Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for development setup, code standards, and the PR process.
 
 Quick flow:
 1. Fork → `git checkout -b feature/my-feature`
@@ -714,9 +657,9 @@ Quick flow:
 ## Architecture
 
 - **Runtime**: Node.js 22 (Alpine Linux in Docker)
-- **Language**: TypeScript 5.9 (ESM, NodeNext module resolution)
-- **MCP SDK**: `@modelcontextprotocol/sdk` ^1.25.2
-- **Actual API**: `@actual-app/api` ^26.3.0
+- **Language**: TypeScript (ESM, NodeNext module resolution)
+- **MCP SDK**: `@modelcontextprotocol/sdk`
+- **Actual API**: `@actual-app/api`
 - **Validation**: Zod (runtime types + JSON Schema for tool inputs)
 - **Transports**: Express + StreamableHTTP (`--http`) · `StdioServerTransport` (`--stdio`)
 - **Logging**: Winston with daily rotation (all output routed to stderr in stdio mode)
@@ -755,4 +698,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.7.2 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.7.4 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.7.2",
+    "version": "0.7.4",
     "engines": {
         "node": ">=22.0.0",
         "npm": ">=10.0.0"
@@ -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/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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 && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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 && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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",

package/dist/src/actualToolsManager.js

@@ -1,5 +1,5 @@
+// src/actualToolsManager.ts
 import logger from './logger.js';
-import { z } from 'zod';
 import { formatZodError } from './lib/zod-error-format.js';
 // ✅ List of tools already implemented in this class.
 // Adding the tool name here is considered fully implemented.
@@ -119,21 +119,6 @@ const API_TOOL_MAP = {
     getIDByName: 'actual_get_id_by_name',
     getServerVersion: 'actual_server_get_version',
 };
-// Define Account schema for validation (simplified example)
-const AccountSchema = z.object({
-    id: z.string().optional(),
-    name: z.string(),
-    type: z.string(), // Consider enum if you have fixed valid types
-    offbudget: z.boolean().optional().default(false),
-    closed: z.boolean().optional().default(false),
-});
-// Input schema for get_accounts - no args
-const GetAccountsInputSchema = z.object({});
-// Input schema for get_account_balance
-const GetAccountBalanceInputSchema = z.object({
-    id: z.string().optional().describe('Account ID to get balance for (optional; defaults to first account)'),
-    cutoff: z.string().optional().describe('Optional ISO date string cutoff'),
-});
 class ActualToolsManager {
     tools = new Map();
     constructor() { }
@@ -141,7 +126,7 @@ class ActualToolsManager {
         // Dynamically import all tool modules from src/tools/index.ts
         const toolModules = (await import('./tools/index.js'));
         let count = 0;
-        for (const [key, tool] of Object.entries(toolModules)) {
+        for (const [_key, tool] of Object.entries(toolModules)) {
             const t = tool;
             if (t && t.name) {
                 this.tools.set(t.name, tool);

package/dist/src/index.js

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
 // Add global error handlers
-let isHandlingQueryError = false;
 process.on('unhandledRejection', (reason, promise) => {
     console.error('=== UNHANDLED REJECTION ===');
     console.error('Promise:', promise);
@@ -125,16 +124,14 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         import('./actualConnection.js'),
         import('./lib/ActualMCPConnection.js'),
     ]);
-    const [{ startHttpServer }, { startStdioServer }, loggerModule, osModule, utilsModule, actualToolsManagerModule,] = await Promise.all([
+    const [{ startHttpServer }, { startStdioServer }, loggerModule, utilsModule, actualToolsManagerModule,] = await Promise.all([
         import('./server/httpServer.js'),
         import('./server/stdioServer.js'),
         import('./logger.js'),
-        import('os'),
         import('./utils.js'),
         import('./actualToolsManager.js'),
     ]);
     const logger = loggerModule.default;
-    const os = osModule;
     const { getLocalIp } = utilsModule;
     const actualToolsManager = actualToolsManagerModule.default;
     // Load version from environment (Docker build-time) or package.json (local dev)
@@ -248,8 +245,9 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         // If requested, run the MCP client-side tests now that all variables are ready
         if (useTestMcpClient) {
             logger.info('⚙️  --test-mcp-client specified, starting HTTP server and running client-side MCP tests...');
-            // start server in http mode (bind to configured PORT)
-            await startHttpServer(mcp, PORT, HTTP_PATH, capabilities, implementedTools, SERVER_DESCRIPTION, SERVER_INSTRUCTIONS, toolSchemas, version, process.env.MCP_BRIDGE_BIND_HOST || 'localhost', advertisedUrl);
+            // start server in http mode. Bind all interfaces by default (#239): advertisedUrl
+            // uses the LAN IP (getLocalIp), so the self-test client must be able to reach it.
+            await startHttpServer(mcp, PORT, HTTP_PATH, capabilities, implementedTools, SERVER_DESCRIPTION, SERVER_INSTRUCTIONS, toolSchemas, version, process.env.MCP_BRIDGE_BIND_HOST || '0.0.0.0', advertisedUrl);
             // dynamic import to avoid circular at top
             const { testMcpClient } = await import('./tests/testMcpClient.js');
             try {

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

@@ -689,30 +689,6 @@ export function getConcurrencyState() {
         writeConnectionReuses: writeConnectionReuseCount,
     };
 }
-/**
- * Sync local changes to the Actual Budget server.
- *
- * This function should be called after write operations (create, update, delete)
- * to ensure changes are properly synced to the remote server. Without syncing,
- * changes may only exist locally and could be lost.
- *
- * Note: Adds a small delay to ensure local changes are committed before syncing.
- */
-async function syncToServer() {
-    try {
-        // Small delay to ensure local changes are committed to the database
-        // before attempting to sync to the server
-        await new Promise(resolve => setTimeout(resolve, 100));
-        // TypeScript doesn't recognize sync in the type definitions, but it exists at runtime
-        console.log('[SYNC] Calling api.sync()...');
-        await api.sync();
-        console.log('[SYNC] api.sync() completed successfully');
-    }
-    catch (err) {
-        // Log but don't throw - sync failures shouldn't break the operation
-        console.error('[SYNC] Sync to server failed:', err);
-    }
-}
 /**
  * Wrap a raw function with the standard adapter retry + concurrency behavior.
  * Useful for tests that want to exercise retry behavior without calling the real raw methods.

package/dist/src/server/httpServer.js

@@ -37,7 +37,8 @@ serverDescription, // was passed by index.ts
 serverInstructions, // was passed by index.ts
 toolSchemas, // was passed by index.ts
 version, // server version from package.json
-bindHost = 'localhost', advertisedUrl) {
+bindHost = 'localhost', // #239: interface to bind; forwarded to listen()
+advertisedUrl) {
     const app = express();
     // Explicit body-size cap (#168). An oversized payload is rejected with HTTP 413
     // rather than buffered unbounded. Tunable via MCP_HTTP_BODY_LIMIT (default 512kb).
@@ -580,11 +581,14 @@ bindHost = 'localhost', advertisedUrl) {
                 `MCP_HTTPS_CERT=${config.MCP_HTTPS_CERT}, MCP_HTTPS_KEY=${config.MCP_HTTPS_KEY}. Cause: ${cause}`);
         }
     }
-    const listener = (tlsOptions ? https.createServer(tlsOptions, app) : app).listen(port, () => {
+    const listener = (tlsOptions ? https.createServer(tlsOptions, app) : app).listen(port, bindHost, () => {
         const advertised = advertisedUrl || `${scheme}://${serverIp}:${port}${httpPath}`;
+        // #239: when bound to a specific (non all-interfaces) host the server is NOT on
+        // loopback, so point the health hint at the actual bind host instead of localhost.
+        const healthHost = (!bindHost || bindHost === '0.0.0.0' || bindHost === '::') ? 'localhost' : bindHost;
         console.info(`MCP Streamable HTTP Server listening on ${port}`);
         console.info(`📨 MCP endpoint: ${advertised}`);
-        console.info(`❤️ Health check: ${scheme}://localhost:${port}/health`);
+        console.info(`❤️ Health check: ${scheme}://${healthHost}:${port}/health`);
         if (config.AUTH_PROVIDER === 'oidc') {
             logger.info(`🔒 OIDC authentication enabled (JWT Bearer token required — issuer: ${config.OIDC_ISSUER})`);
         }

package/dist/src/tests/testMcpClient.js

@@ -1,4 +1,4 @@
-export async function testMcpClient(advertisedUrl, port, httpPath) {
+export async function testMcpClient(advertisedUrl, _port, httpPath) {
     // Try builtin fetch or fallback to node-fetch if necessary
     const globalFetch = globalThis.fetch;
     const fetchAny = globalFetch ?? (await import('node-fetch')).default;
@@ -82,14 +82,10 @@ export async function testMcpClient(advertisedUrl, port, httpPath) {
         throw new Error('initialize result.capabilities missing or not object');
     }
     // Accept either a tools array or derive tools from capabilities.tools object
-    let initTools = [];
-    if (Array.isArray(initResult['tools'])) {
-        initTools = initResult['tools'];
-    }
-    else if (initResult['capabilities'] && typeof initResult['capabilities']['tools'] === 'object') {
-        initTools = Object.keys(initResult['capabilities']['tools']);
-    }
-    else {
+    const hasTools = Array.isArray(initResult['tools'])
+        || (initResult['capabilities'] != null
+            && typeof initResult['capabilities']['tools'] === 'object');
+    if (!hasTools) {
         throw new Error('initialize result.tools missing or not array and capabilities.tools not present');
     }
     // serverInstructions may be a string, an object { instructions }, or absent.
@@ -106,7 +102,6 @@ export async function testMcpClient(advertisedUrl, port, httpPath) {
     else {
         console.warn('Warning: serverInstructions present but in unexpected shape — continuing tests');
     }
-    // replace usages below with initTools where needed
     console.info('Initialize OK: capabilities/tools/serverInstructions present');
     // call tools/list (JSON-RPC) to verify RPC path works
     const listPayload = { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} };

package/dist/src/tools/accounts_list.js

@@ -1,11 +1,12 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({});
+// RESPONSE_TYPE: Account[]
 const tool = {
     name: 'actual_accounts_list',
     description: "List all accounts in Actual Budget including checking, savings, credit cards, and investment accounts. Returns account ID, name, balance (in cents), on-budget/off-budget status, and open/closed state.",
     inputSchema: InputSchema,
-    call: async (args, _meta) => {
+    call: async (_args, _meta) => {
         // Single API session: getAccounts + all balances in one withActualApi cycle.
         // Calling getAccountBalance() per-account would open N separate sessions and
         // overwhelm the Actual server with concurrent init/shutdown cycles.

package/dist/src/tools/budgets_getMonth.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({ month: z.string().optional() });
+// RESPONSE_TYPE: BudgetMonth
 const tool = {
     name: 'actual_budgets_getMonth',
     description: "Get budget data for a specific month in YYYY-MM format (e.g., '2025-12'). Returns all categories with their budgeted amounts, actual spending, and available balances for the month.",

package/dist/src/tools/budgets_getMonths.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({});
+// RESPONSE_TYPE: array
 const tool = {
     name: 'actual_budgets_getMonths',
     description: "Get a list of all available budget months with summary data. Returns an array of months showing total budgeted, spent, and income for each month. Useful for viewing budget history and trends over time.",

package/dist/src/tools/categories_create.js

@@ -6,6 +6,7 @@ const InputSchema = z.object({
     group_id: CommonSchemas.categoryGroupId,
     is_income: z.boolean().nullable().optional(),
 }).passthrough(); // Allow other fields to pass through
+// RESPONSE_TYPE: string
 const tool = {
     name: 'actual_categories_create',
     description: "Create a category. REQUIRED: group_id (category group UUID). Use actual_category_groups_get to find available groups. Optional: is_income (boolean, defaults to false for expense categories).",

package/dist/src/tools/categories_get.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({});
+// RESPONSE_TYPE: Category[]
 const tool = {
     name: 'actual_categories_get',
     description: 'List all budget categories organized by category groups. Categories are spending/income buckets (e.g., Groceries, Rent, Salary) used for budgeting and transaction categorization. Returns both grouped view and flat list with category IDs, names, and group assignments.',

package/dist/src/tools/category_groups_get.js

@@ -5,7 +5,7 @@ const tool = {
     name: 'actual_category_groups_get',
     description: `List all category groups in Actual Budget. Category groups organize related categories together (e.g., "Monthly Bills" group contains "Rent", "Utilities", "Internet" categories). Each group has an ID, name, and optional properties.`,
     inputSchema: InputSchema,
-    call: async (args, _meta) => {
+    call: async (_args, _meta) => {
         const groups = await adapter.getCategoryGroups();
         return { groups };
     },

package/dist/src/tools/payees_get.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({});
+// RESPONSE_TYPE: Payee[]
 const tool = {
     name: 'actual_payees_get',
     description: "List all payees in Actual Budget. Payees represent merchants, service providers, individuals, or other entities you transact with. Returns payee ID, name, and optional transfer account information for internal transfers.",

package/dist/src/tools/rules_get.js

@@ -5,7 +5,7 @@ const tool = {
     name: 'actual_rules_get',
     description: `List all budget rules in Actual Budget. Rules automate transaction categorization and other budget operations based on conditions. Each rule has conditions (e.g., payee matches "Amazon") and actions (e.g., set category to "Shopping").`,
     inputSchema: InputSchema,
-    call: async (args, _meta) => {
+    call: async (_args, _meta) => {
         const rules = await adapter.getRules();
         return { rules };
     },

package/dist/src/tools/session_close.js

@@ -9,7 +9,7 @@ const tool = {
     name: 'actual_session_close',
     description: 'Close an idle MCP session to free up connection slots. Useful when you get "Max concurrent sessions reached" errors. Only closes sessions other than the current one.',
     inputSchema: InputSchema,
-    call: async (args, meta) => {
+    call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
         const stats = connectionPool.getStats();
         if (stats.totalSessions === 0) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -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/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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 && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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 && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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",