actual-mcp-server 0.6.56 → 0.7.3

package/README.md

@@ -3,9 +3,9 @@
 [![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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
-[![MCP Protocol](https://img.shields.io/badge/MCP-1.18-orange)](https://modelcontextprotocol.io/)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+[![MCP Protocol](https://img.shields.io/badge/MCP-1.29-orange)](https://modelcontextprotocol.io/)
 [![Docker Pulls](https://img.shields.io/docker/pulls/agigante80/actual-mcp-server)](https://hub.docker.com/r/agigante80/actual-mcp-server)
 [![Docker Image Size](https://img.shields.io/docker/image-size/agigante80/actual-mcp-server/latest)](https://hub.docker.com/r/agigante80/actual-mcp-server)
 [![GitHub Actions CI](https://github.com/agigante80/actual-mcp-server/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/agigante80/actual-mcp-server/actions)
@@ -33,7 +33,7 @@ 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:
 
-- **71 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers 87% of the Actual Budget API.
+- **71 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **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`.
@@ -67,7 +67,7 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 
 - [Actual Budget](https://actualbudget.org/) server running (local or remote)
 - Your **Budget Sync ID**: Actual → Settings → Show Advanced Settings → Sync ID
-- **Node.js 20+** (npm method) or **Docker**
+- **Node.js 22+** (npm method) or **Docker**
 
 ### Option A: Docker (recommended)
 
@@ -282,7 +282,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**71 tools** across 12 categories. All tools use the `actual_<category>_<action>` naming convention.
+**71 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (7)
 
@@ -755,4 +755,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.56 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.7.3 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,9 +1,9 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.56",
+    "version": "0.7.3",
     "engines": {
-        "node": ">=20.0.0",
+        "node": ">=22.0.0",
         "npm": ">=10.0.0"
     },
     "description": "MCP server with 71 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
@@ -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/node_polyfill_order.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/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",
@@ -57,7 +57,7 @@
         "release:patch": "npm run version:bump -- patch",
         "tool-count": "node scripts/tool-count.mjs",
         "config-drift": "npm run build && node scripts/config-drift.mjs",
-        "knip": "knip --no-exit-code"
+        "knip": "knip"
     },
     "dependencies": {
         "@actual-app/api": "^26.6.0",

package/dist/src/actualConnection.js

@@ -1,5 +1,3 @@
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import './lib/node-polyfills.js';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';

package/dist/src/actualToolsManager.js

@@ -1,8 +1,5 @@
 // src/actualToolsManager.ts
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import './lib/node-polyfills.js';
 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.
@@ -122,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() { }
@@ -144,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/auth/setup.js

@@ -52,7 +52,3 @@ export function createMcpAuth() {
     });
     return _instance;
 }
-/** Reset the singleton (test helper). */
-export function _resetMcpAuthForTests() {
-    _instance = null;
-}

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)

package/dist/src/lib/ActualConnectionPool.js

@@ -10,8 +10,6 @@
  * For true concurrent multi-session support, the Actual Budget API would
  * need to support multiple instances or we'd need request queuing.
  */
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import './node-polyfills.js';
 import api from '@actual-app/api';
 import logger from '../logger.js';
 import config from '../config.js';

package/dist/src/lib/ActualMCPConnection.js

@@ -1,6 +1,4 @@
 // lib/ActualMCPConnection.ts
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import './node-polyfills.js';
 import { EventEmitter } from 'events';
 import * as actual from '@actual-app/api';
 import actualToolsManager from '../actualToolsManager.js';

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

@@ -1,6 +1,3 @@
-// Must be the very first import — sets globalThis.navigator before @actual-app/api is evaluated.
-// Required by @actual-app/api v26.3.0+ which uses navigator.platform at module load time.
-import './node-polyfills.js';
 import api from '@actual-app/api';
 // @actual-app/api is a CJS package (no "type" field). In NodeNext/ESM context TypeScript
 // cannot expose its named exports via static import syntax. At runtime the default import
@@ -11,7 +8,7 @@ const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, import
  } = api;
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
-import retry, { isRetryableError } from './retry.js';
+import { retry, isRetryableError } from './retry.js';
 import { notFoundMsg } from './errors.js';
 import logger from '../logger.js';
 import config from '../config.js';
@@ -692,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/lib/actual-schema.js

@@ -211,12 +211,3 @@ export function isValidField(tableName, fieldName) {
 export function isValidJoinPath(path) {
     return path in JOIN_PATHS;
 }
-/**
- * Get field type information
- */
-export function getFieldType(tableName, fieldName) {
-    const table = ACTUAL_SCHEMA[tableName];
-    if (!table || !(fieldName in table))
-        return null;
-    return table[fieldName].type;
-}

package/dist/src/lib/config-registry.js

@@ -40,7 +40,7 @@ export const RAW_ENV_ALLOWLIST = [
     { name: 'MCP_BRIDGE_DEBUG_TRANSPORT', reason: 'transport debug flag, read pre-config', readSite: 'index.ts, utils.ts' },
     // Framework / internal: not user-facing config knobs.
     { name: 'NODE_ENV', reason: 'framework var; selects prod log format and prod behaviours', readSite: 'httpServer.ts, logger.ts (resolveLogConfig)' },
-    { name: 'DEBUG', reason: 'framework debug toggle', readSite: 'utils.ts, index.ts, httpServer_testing.ts' },
+    { name: 'DEBUG', reason: 'framework debug toggle', readSite: 'utils.ts, index.ts' },
     { name: 'LOG_LEVEL', reason: 'debug-detection toggle (distinct from MCP_BRIDGE_LOG_LEVEL, the winston level)', readSite: 'utils.ts' },
     { name: 'DOTENV_CONFIG_QUIET', reason: 'dotenv internal flag, not an operator knob', readSite: 'index.ts', documented: false },
     { name: 'VERSION', reason: 'build-time version arg, injected by the Docker build, not an operator knob', readSite: 'index.ts, server_info.ts', documented: false },

package/dist/src/lib/constants.js

@@ -30,14 +30,6 @@ export const DEFAULT_CONCURRENCY_LIMIT = 5;
 // ============================================================================
 // TIMEOUTS
 // ============================================================================
-/**
- * Default timeout for API operations in milliseconds
- */
-export const DEFAULT_OPERATION_TIMEOUT_MS = 30000;
-/**
- * Timeout for server shutdown grace period
- */
-export const SHUTDOWN_GRACE_PERIOD_MS = 5000;
 /**
  * How long (ms) to wait after calling rawRunBankSync for the SDK's background
  * promise to surface a BankSyncError as an unhandledRejection.
@@ -57,10 +49,6 @@ export const WRITE_SESSION_DELAY_MS = 100;
 // ============================================================================
 // MCP SERVER
 // ============================================================================
-/**
- * Default HTTP server bind host
- */
-export const DEFAULT_BIND_HOST = 'localhost';
 /**
  * Default HTTP port for MCP server. Canonical default is 3600 (#230): it matches
  * the listen-port fallback in src/index.ts, the Dockerfile EXPOSE/HEALTHCHECK, the
@@ -70,18 +58,6 @@ export const DEFAULT_BIND_HOST = 'localhost';
  * not by a runtime import, so Knip cannot see the usage. Alive: removing it breaks the guard.
  */
 export const DEFAULT_HTTP_PORT = 3600;
-/**
- * Default HTTP path for MCP server endpoint
- */
-export const DEFAULT_HTTP_PATH = '/';
-/**
- * Server information
- * Note: version is read from package.json at startup and passed as a parameter.
- */
-export const SERVER_INFO = {
-    name: 'actual-budget-mcp',
-    description: 'MCP server for Actual Budget - 71 tools for finance management',
-};
 // ============================================================================
 // VALIDATION & LIMITS
 // ============================================================================
@@ -105,22 +81,3 @@ export const MONTH_PATTERN = /^\d{4}-\d{2}$/;
  * UUID pattern for ID validation
  */
 export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-// ============================================================================
-// LOGGING
-// ============================================================================
-/**
- * Log level for production environments
- */
-export const PRODUCTION_LOG_LEVEL = 'info';
-/**
- * Log level for development environments
- */
-export const DEVELOPMENT_LOG_LEVEL = 'debug';
-/**
- * Maximum number of log files to retain
- */
-export const MAX_LOG_FILES = 14;
-/**
- * Maximum size of a single log file before rotation
- */
-export const MAX_LOG_FILE_SIZE = '20m';

package/dist/src/lib/retry.js

@@ -63,4 +63,3 @@ export async function retry(fn, opts) {
         }
     }
 }
-export default retry;

package/dist/src/lib/toolFactory.js

@@ -79,31 +79,3 @@ export function createTool(config) {
         },
     };
 }
-/**
- * Batch create multiple tools with shared configuration
- * Useful for creating related tools (CRUD operations) with common patterns
- *
- * @param baseConfig - Shared configuration for all tools
- * @param tools - Array of tool-specific overrides
- * @returns Array of tool definitions
- *
- * @example
- * ```typescript
- * export const accountTools = createTools(
- *   { namePrefix: 'actual_accounts_' },
- *   [
- *     { name: 'create', schema: createSchema, handler: createHandler },
- *     { name: 'update', schema: updateSchema, handler: updateHandler },
- *     { name: 'delete', schema: deleteSchema, handler: deleteHandler },
- *   ]
- * );
- * ```
- */
-export function createTools(baseConfig, tools) {
-    const { namePrefix = '', ...sharedConfig } = baseConfig;
-    return tools.map((toolConfig) => createTool({
-        ...sharedConfig,
-        ...toolConfig,
-        name: namePrefix + toolConfig.name,
-    }));
-}

package/dist/src/resources/accountsSummary.js

@@ -1,6 +1,4 @@
 // Example resource: summary of all accounts
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import '../lib/node-polyfills.js';
 import api from '@actual-app/api';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const { getAccounts } = api;

package/dist/src/server/httpServer.js

@@ -37,7 +37,7 @@ 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', 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).
@@ -170,7 +170,7 @@ bindHost = 'localhost', advertisedUrl) {
         }
         return true;
     };
-    // Create a fresh Server instance similar to httpServer_testing
+    // Create a fresh Server instance per session
     function createServerInstance() {
         // ensure capabilities.tools is an object mapping tool name -> {}
         const capabilitiesObj = capabilities && Object.keys(capabilities).length

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/tests_adapter_runner.js

@@ -41,7 +41,7 @@ runAdapterTests().catch((e) => {
 });
 // Concurrency and retry tests
 import { callWithRetry, getConcurrencyState, setMaxConcurrency } from './lib/actual-adapter.js';
-import retry from './lib/retry.js';
+import { retry } from './lib/retry.js';
 async function runConcurrencyAndRetryTests() {
     console.log('Running concurrency and retry tests...');
     // Concurrency test: set max concurrency to 1 and start 3 tasks that resolve after a delay.

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/budget_updates_batch.js

@@ -1,5 +1,3 @@
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import '../lib/node-polyfills.js';
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import api from '@actual-app/api';

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_delete.js

@@ -1,5 +1,3 @@
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import '../lib/node-polyfills.js';
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { notFoundMsg } from '../lib/errors.js';

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_create_or_update.js

@@ -17,8 +17,6 @@
  * - No wrapToolCall — uses direct call() pattern
  * - Reuses exact same ConditionSchema / ActionSchema / FIELD_OPERATORS as rules_create.ts
  */
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import '../lib/node-polyfills.js';
 import { z } from 'zod';
 import adapter, { normalizeToId } from '../lib/actual-adapter.js';
 import api from '@actual-app/api';

package/dist/src/tools/rules_delete.js

@@ -1,5 +1,3 @@
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import '../lib/node-polyfills.js';
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { notFoundMsg } from '../lib/errors.js';

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/schedules_delete.js

@@ -1,5 +1,3 @@
-// #232: load the navigator polyfill before @actual-app/api so the Node 20 global is defined first.
-import '../lib/node-polyfills.js';
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { UUID_PATTERN } from '../lib/constants.js';

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/dist/src/utils.js

@@ -10,54 +10,3 @@ export function getLocalIp() {
     }
     return '127.0.0.1';
 }
-// new: transport logging helpers (enabled when --debug or DEBUG/MCP_BRIDGE_DEBUG_TRANSPORT set)
-export function shouldDebugTransport() {
-    const argvDebug = process.argv.slice(2).includes('--debug');
-    const envDebug = Boolean(process.env.DEBUG) || process.env.MCP_BRIDGE_DEBUG_TRANSPORT === 'true' || process.env.LOG_LEVEL === 'debug';
-    return argvDebug || envDebug;
-}
-/**
- * Log transport-level request/response objects when debug is enabled.
- * - prefix: short label like "HTTP REQ" / "HTTP RES"
- * - obj: any serializable data (headers, body, meta)
- *
- * This uses console.debug (falls through to console if no structured logger available).
- */
-export function logTransport(prefix, obj) {
-    if (!shouldDebugTransport())
-        return;
-    const ts = new Date().toISOString();
-    let payload;
-    try {
-        payload = JSON.stringify(obj, replacer, 2);
-    }
-    catch {
-        try {
-            payload = String(obj);
-        }
-        catch {
-            payload = '[unserializable payload]';
-        }
-    }
-    // prefer console.debug so existing debug tooling (DEBUG env) can capture it
-    // format similar to other logs: "<iso> debug: [TRANSPORT] prefix: <json>"
-    // eslint-disable-next-line no-console
-    console.debug(`${ts} debug: [TRANSPORT] ${prefix}: ${payload}`);
-}
-// Helper replacer to avoid throwing on circular refs and to truncate very large buffers
-function replacer(_key, value) {
-    // Limit Buffer/Uint8Array printing
-    if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && value instanceof Buffer)) {
-        const buf = value;
-        const len = buf.length ?? 0;
-        const preview = Array.prototype.slice.call(buf, 0, 64);
-        return { _type: 'Buffer', length: len, preview };
-    }
-    if (value instanceof Uint8Array) {
-        const buf = value;
-        const len = buf.length;
-        const preview = Array.prototype.slice.call(buf, 0, 64);
-        return { _type: 'Uint8Array', length: len, preview };
-    }
-    return value;
-}