actual-mcp-server 0.6.49 → 0.6.52

package/README.md

@@ -84,12 +84,12 @@ docker run -d \
   -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:/app/data \        # required, see note below
   -v actual-mcp-logs:/app/logs \
   ghcr.io/agigante80/actual-mcp-server:latest
 ```
 
-> **Why the `/data` volume is required:** Actual Budget does not expose a REST API. The official `@actual-app/api` library (used internally by this server) works by downloading a local copy of your budget data, running all queries on that local copy, then syncing changes back. The `/data` volume gives the container a persistent, writable place to store that local copy. Without it the container has nowhere to write and will fail on startup. See the [Actual API docs](https://actualbudget.org/docs/api/) for details.
+> **Why the `/app/data` volume is required:** Actual Budget does not expose a REST API. The official `@actual-app/api` library (used internally by this server) works by downloading a local copy of your budget data, running all queries on that local copy, then syncing changes back. The `/app/data` volume gives the container a persistent, writable place to store that local copy (it is the directory the image creates and owns as the runtime user). Without it the container has nowhere to write and will fail on startup. See the [Actual API docs](https://actualbudget.org/docs/api/) for details.
 >
 > **actual-mcp does not need to run on the same machine as Actual Budget.** You can have Actual Budget on one server and actual-mcp on another - as long as `ACTUAL_SERVER_URL` points to your Actual Budget instance, everything works.
 
@@ -147,7 +147,7 @@ npm run build
 npm run dev -- --http
 ```
 
-Server starts at `http://localhost:3000/http` (dev) or `http://localhost:3600/http` (Docker).
+Server starts at `http://localhost:3600/http` by default (the listen port is `MCP_BRIDGE_PORT`, default `3600`).
 
 ### Option D: stdio (Claude Desktop native, no Docker or HTTP server needed)
 
@@ -429,7 +429,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `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_PORT` | `3600` | 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_PUBLIC_HOST` | auto-detected | No | Public hostname/IP for server (shown in logs) |
@@ -751,4 +751,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.49 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.6.52 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.49",
+    "version": "0.6.52",
     "engines": {
         "node": ">=20.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_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/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.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",

package/dist/src/config.js

@@ -10,7 +10,7 @@ export const configSchema = z.object({
     // Off by default so a plaintext upstream + encryption password is refused.
     ALLOW_INSECURE_UPSTREAM: z.string().optional().transform(val => val === 'true'),
     MCP_BRIDGE_DATA_DIR: z.string().default('./actual-data'),
-    MCP_BRIDGE_PORT: z.string().default('3000'),
+    MCP_BRIDGE_PORT: z.string().default('3600'),
     MCP_TRANSPORT_MODE: z.enum(['--http']).default('--http'),
     MCP_SSE_AUTHORIZATION: z.string().optional(),
     MCP_ENABLE_HTTPS: z.string().optional().transform(val => val === 'true'),

package/dist/src/lib/constants.js

@@ -62,9 +62,11 @@ export const WRITE_SESSION_DELAY_MS = 100;
  */
 export const DEFAULT_BIND_HOST = 'localhost';
 /**
- * Default HTTP port for MCP server
+ * 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
+ * published image, .env.example, and every deployment guide.
  */
-export const DEFAULT_HTTP_PORT = 3000;
+export const DEFAULT_HTTP_PORT = 3600;
 /**
  * Default HTTP path for MCP server endpoint
  */

package/dist/src/lib/loggerFactory.js

@@ -17,8 +17,8 @@ import logger from '../logger.js';
  * import { createModuleLogger } from '../lib/loggerFactory.js';
  *
  * const log = createModuleLogger('HTTP');
- * log.info('Server started', { port: 3000 });
- * // Output: [HTTP] Server started { port: 3000 }
+ * log.info('Server started', { port: 3600 });
+ * // Output: [HTTP] Server started { port: 3600 }
  *
  * log.error('Connection failed', new Error('Timeout'), { retries: 3 });
  * // Output: [HTTP] Connection failed { error: 'Timeout', stack: '...', retries: 3 }

package/dist/src/lib/schemas/recur.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+// Shared recurrence-config schema for Actual schedules. Used by both actual_schedules_create
+// and actual_schedules_update so the two tools agree on the same shape and publish a typed
+// `date` branch in tools/list (#225). This mirrors the config Actual's `@actual-app/api`
+// accepts for a recurring schedule; it is a closed object so a malformed config gets an
+// actionable validation error rather than being forwarded unshaped.
+export const RecurConfigSchema = z.object({
+    frequency: z.enum(['daily', 'weekly', 'monthly', 'yearly'])
+        .describe('How often the schedule repeats'),
+    start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+        .describe('Start date in YYYY-MM-DD format'),
+    endMode: z.enum(['never', 'after_n_occurrences', 'on_date'])
+        .describe('When the schedule stops: never, after N occurrences, or on a specific date'),
+    interval: z.number().int().positive().optional()
+        .describe('Every N periods. Default: 1 (every period)'),
+    skipWeekend: z.boolean().optional()
+        .describe('If true, occurrence is moved when it falls on a weekend'),
+    weekendSolveMode: z.enum(['before', 'after']).optional()
+        .describe('Move to Friday before or Monday after the weekend. Requires skipWeekend: true'),
+    endOccurrences: z.number().int().positive().optional()
+        .describe('Number of occurrences before stopping. Required when endMode is after_n_occurrences'),
+    endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
+        .describe('Date (YYYY-MM-DD) after which the schedule stops. Required when endMode is on_date'),
+});

package/dist/src/tools/schedules_create.js

@@ -1,24 +1,7 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { UUID_PATTERN } from '../lib/constants.js';
-const RecurConfigSchema = z.object({
-    frequency: z.enum(['daily', 'weekly', 'monthly', 'yearly'])
-        .describe('How often the schedule repeats'),
-    start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
-        .describe('Start date in YYYY-MM-DD format'),
-    endMode: z.enum(['never', 'after_n_occurrences', 'on_date'])
-        .describe('When the schedule stops: never, after N occurrences, or on a specific date'),
-    interval: z.number().int().positive().optional()
-        .describe('Every N periods. Default: 1 (every period)'),
-    skipWeekend: z.boolean().optional()
-        .describe('If true, occurrence is moved when it falls on a weekend'),
-    weekendSolveMode: z.enum(['before', 'after']).optional()
-        .describe('Move to Friday before or Monday after the weekend. Requires skipWeekend: true'),
-    endOccurrences: z.number().int().positive().optional()
-        .describe('Number of occurrences before stopping. Required when endMode is after_n_occurrences'),
-    endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
-        .describe('Date (YYYY-MM-DD) after which the schedule stops. Required when endMode is on_date'),
-});
+import { RecurConfigSchema } from '../lib/schemas/recur.js';
 const InputSchema = z.object({
     name: z.string().optional()
         .describe('Unique display name for the schedule'),

package/dist/src/tools/schedules_update.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { UUID_PATTERN } from '../lib/constants.js';
+import { RecurConfigSchema } from '../lib/schemas/recur.js';
 const InputSchema = z.object({
     id: z.string().regex(UUID_PATTERN, 'Invalid UUID format')
         .describe('UUID of the schedule to update (from actual_schedules_get)'),
@@ -15,10 +16,12 @@ const InputSchema = z.object({
     amountOp: z.enum(['is', 'isapprox', 'isbetween']).optional()
         .describe('How to match the amount'),
     date: z.union([
-        z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-        z.object({}).passthrough(),
+        z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+            .describe('YYYY-MM-DD: one-off schedule on this specific date'),
+        RecurConfigSchema
+            .describe('RecurConfig object (frequency, start, endMode, ...): recurring schedule'),
     ]).optional()
-        .describe('New date string (YYYY-MM-DD) or RecurConfig object'),
+        .describe('New date string (YYYY-MM-DD) or RecurConfig object. Set resetNextDate: true when changing this.'),
     posts_transaction: z.boolean().optional()
         .describe('Whether Actual auto-posts a transaction on each occurrence'),
     completed: z.boolean().optional()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.49",
+  "version": "0.6.52",
   "engines": {
     "node": ">=20.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_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/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.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",