actual-mcp-server 0.22.14 → 0.22.18

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (82 tools)      │               │   Server     │
+│  (remote)   │               │  (83 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (82 tools)      │               │   Server     │
+│  (local)    │               │  (83 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ 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:
 
-- **82 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.
+- **83 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`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. Automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 82 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 83 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -182,7 +182,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 82 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 83 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -308,7 +308,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**82 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**83 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (12)
 
@@ -425,13 +425,14 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_budgets_export` | Export the active budget as a `.zip` into `ACTUAL_EXPORT_DIR`; returns path, byte size and sha256, never the file contents |
 | `actual_budgets_import` | Restore a budget from an Actual `.zip` or a YNAB4/YNAB5 export. **Destructive:** the budget id comes from the archive, so re-importing an export *replaces* that budget's data rather than making a copy. Also loads the imported budget, changing the session's active budget |
 
-### Rules (5)
+### Rules (6)
 
 `actual_rules_get` · `actual_rules_create` · `actual_rules_update` · `actual_rules_delete`
 
 | Tool | Description |
 |------|-------------|
 | `actual_rules_create_or_update` | Idempotent upsert: create a rule, or update the existing one that matches the same conditions, in a single call. Use this instead of get-then-create when re-running a categorisation setup, so repeated runs do not pile up duplicate rules |
+| `actual_rules_create_batch` | Create 1 to 50 rules in one call, each exactly the input of `actual_rules_create`. Best-effort, not atomic (see Batch Operations): a rule that fails its own checks, names a category, payee or account that does not exist, or is rejected by Actual is reported with its index while the rest continue |
 
 ### Schedules (4)
 
@@ -451,7 +452,12 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ### Batch Operations (1)
 
-`actual_budget_updates_batch`: batch multiple budget updates in one call
+Four tools take many items in one call, for clients that allow only a few tool calls per turn. They share ONE contract: each item is applied independently and **not atomically**. There is no rollback, so items applied before a failure stay applied; a bad item is reported by its index and the rest continue; an infrastructure failure (lost connection, timeout) fails the whole call, and then you must read the data back before retrying anything. A bulk path never retries a create on its own.
+
+- `actual_transactions_update_batch` (counted under Transactions): update up to 50 transactions, `{id, fields}` each. Result: `{ succeeded: [{id}], failed: [{id, error}], total, successCount, failureCount }`.
+- `actual_transactions_import` (counted under Transactions): bulk create with import semantics (deduplication and reconciliation against existing transactions, rules optionally applied). Use it to add many transactions at once.
+- `actual_budget_updates_batch`: set budget amounts and/or carryover flags for 1 to 100 month/category pairs, and the way to rebalance categories: read the month with `actual_budgets_getMonth`, then send one batch of absolute amounts. Each operation needs at least one of `amount` (integer cents) or `carryover`. Result: `{ succeeded: [{index, month, categoryId}], failed: [{index, month, categoryId, error}], total, successCount, failureCount }`. An unknown category, an out-of-range month or a carryover on an income category fails only that item. After a timeout, read the months back with `actual_budgets_getMonth` before retrying.
+- `actual_rules_create_batch` (counted under Rules): create 1 to 50 rules, each exactly the input of `actual_rules_create`. Result: `{ succeeded: [{index, id}], failed: [{index, error}], total, successCount, failureCount }`. Items marked "not attempted" were never sent. Re-read with `actual_rules_get` before retrying any item.
 
 ### Server Information & Lookup (5)
 
@@ -498,6 +504,10 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `MCP_HTTP_PATH` | `/http` | No | HTTP endpoint routing path |
 | `MCP_BRIDGE_HTTP_PATH` | same as `MCP_HTTP_PATH` | No | Advertised HTTP path shown to clients (set when a reverse proxy rewrites the path) |
 | `MCP_HTTP_BODY_LIMIT` | `512kb` | No | Maximum accepted JSON-RPC request body size (e.g. `512kb`, `1mb`, `1048576`). Validated at startup: an invalid, zero or overflowing size refuses to start naming the variable (#466) |
+| **Tool Surface** ||||
+| `MCP_TOOLSETS` | `all` | No | Comma-separated toolset groups (`context`, `transactions`, `analysis`, `budget`, `rules`, `schedules`, `structure`, `query`, `admin`) and presets (`chat`) to publish; `all` publishes every tool. Unknown names refuse to start. See [Reducing the tool surface](#reducing-the-tool-surface) |
+| `MCP_TOOLS` | _(empty)_ | No | Extra tools to add on top of `MCP_TOOLSETS`, by full registered name (e.g. `actual_accounts_list`). Unknown names refuse to start |
+| `MCP_READ_ONLY` | `false` | No | `true` hides and refuses the 47 write-capable tools. Only `true` or `false` (case-insensitive) are accepted; any other value refuses to start |
 | **Session Management** ||||
 | `USE_CONNECTION_POOL` | `true` | No | Enable session-based connection pooling |
 | `MAX_CONCURRENT_SESSIONS` | `15` | No | Maximum concurrent MCP sessions allowed |
@@ -544,6 +554,42 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `VERSION` | auto-detected | No | Server version (auto-set by build/Docker) |
 | `TZ` | `UTC` | No | Timezone for timestamps (e.g., `America/New_York`) |
 
+### Reducing the tool surface
+
+All 83 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer, so the surface can be narrowed at startup. A tool that is not published is also refused if a client calls it by name, and the refusal names the setting responsible.
+
+| Toolset | Tools | Contents |
+|---------|-------|----------|
+| `context` | 14 | Orientation, lookups and server information |
+| `transactions` | 13 | Transaction reads, create, update, delete, import and transfers |
+| `analysis` | 7 | Summaries, aggregates and balances |
+| `budget` | 10 | Budget months, amounts, carryover, holds, transfers, batch updates and notes |
+| `rules` | 7 | Rules and payee rules, including `actual_rules_create_batch` |
+| `schedules` | 4 | Scheduled transactions |
+| `structure` | 21 | Accounts, account groups, categories, category groups, payees and tags |
+| `query` | 1 | `actual_query_run` (SELECT only) |
+| `admin` | 6 | Budget switching, import, export, bank sync and session management |
+
+Each tool is in exactly one group. The `chat` preset cuts across them and publishes 12 tools: `actual_get_context`, `actual_query_run`, `actual_transactions_create`, `actual_transactions_update`, `actual_transactions_delete`, `actual_transactions_update_batch`, `actual_rules_create`, `actual_rules_create_batch`, `actual_budget_updates_batch`, `actual_budgets_transfer`, `actual_budgets_setAmount` and `actual_budgets_getMonth`. Measured on the `tools/list` payload, all 83 tools are 108,164 bytes and the `chat` preset is 25,949 bytes (about 6.5k tokens saved, a 76% cut).
+
+`MCP_READ_ONLY=true` additionally hides and refuses every write-capable tool (47 of the 83, including `actual_bank_sync`, `actual_budgets_export`, `actual_budgets_switch` and `actual_session_close`), leaving 36. `actual_session_list` stays available under read-only. See [Security and Privacy](docs/SECURITY_AND_PRIVACY.md#tool-surface-mcp_toolsets-and-mcp_read_only).
+
+Example: a chat assistant.
+
+```bash
+MCP_TOOLSETS=chat
+MCP_TOOLS=actual_accounts_list,actual_payees_get
+```
+
+Example: a read-only household assistant.
+
+```bash
+MCP_TOOLSETS=context,analysis,query
+MCP_READ_ONLY=true
+```
+
+A configuration that resolves to zero tools refuses to start.
+
 ---
 
 ## Multi-Budget Switching
@@ -602,7 +648,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 82 tools are available, identical to HTTP mode
+- All 83 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -705,7 +751,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 82-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 83-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -789,7 +835,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.14 | **Tool Count:** 82 (verified LibreChat-compatible)
+**Version:** 0.22.18 | **Tool Count:** 83 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualConnection.js

@@ -165,6 +165,10 @@ export async function shutdownActualForSession(sessionId) {
         logger.error(`Error shutting down Actual for session ${sessionId}:`, err);
     }
 }
+function poolSummary() {
+    const { sessions: _sessions, ...summary } = connectionPool.getStats();
+    return summary;
+}
 export function getConnectionState() {
     // When using connection pooling, consider server initialized if pool is ready
     // (even with 0 active connections, pool being initialized means server is ready to accept sessions)
@@ -173,7 +177,9 @@ export function getConnectionState() {
     return {
         initialized: effectivelyInitialized,
         initializationError,
-        connectionPool: useConnectionPool ? connectionPool.getStats() : null,
+        // Aggregate figures only. This feeds the unauthenticated /health route, so the
+        // per-session list (full session ids) is left out on purpose.
+        connectionPool: useConnectionPool ? poolSummary() : null,
         idleTimeoutMinutes: useConnectionPool ? connectionPool.getIdleTimeoutMinutes() : null,
     };
 }

package/dist/src/actualToolsManager.js

@@ -1,6 +1,10 @@
 // src/actualToolsManager.ts
 import logger from './logger.js';
 import { formatZodError } from './lib/zod-error-format.js';
+import config from './config.js';
+import { createModuleLogger } from './lib/loggerFactory.js';
+import { resolvePublishedToolNames, unavailableError } from './lib/toolsets.js';
+const toolsetLog = createModuleLogger('TOOLSETS');
 // ✅ List of tools already implemented in this class.
 // Adding the tool name here is considered fully implemented.
 const IMPLEMENTED_TOOLS = [
@@ -46,6 +50,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_payee_rules_get',
     'actual_query_run',
     'actual_rules_create',
+    'actual_rules_create_batch',
     'actual_rules_create_or_update',
     'actual_rules_delete',
     'actual_rules_get',
@@ -135,8 +140,20 @@ const API_TOOL_MAP = {
 };
 class ActualToolsManager {
     tools = new Map();
+    // Resolved ONCE in initialize() (#483) and never recomputed. Null before that, and every
+    // accessor below throws rather than fall back to "all tools", so a caller that runs
+    // before initialize() fails closed instead of publishing a surface the operator hid.
+    policy = null;
     constructor() { }
-    async initialize() {
+    /**
+     * @param settings Overrides the validated config. Production passes nothing; the unit
+     *   tests pass explicit settings so they never depend on process.env.
+     */
+    async initialize(settings = {
+        toolsets: config.MCP_TOOLSETS,
+        tools: config.MCP_TOOLS,
+        readOnly: config.MCP_READ_ONLY,
+    }) {
         // Dynamically import all tool modules from src/tools/index.ts
         const toolModules = (await import('./tools/index.js'));
         let count = 0;
@@ -148,6 +165,33 @@ class ActualToolsManager {
             }
         }
         logger.info(`🔗 Loaded ${count} tool modules from src/tools`);
+        // Throws on an unknown name or an empty result: startup fails loudly (#483).
+        this.policy = resolvePublishedToolNames(this.getToolNames(), settings);
+        toolsetLog.info(`Publishing ${this.policy.published.length} of ${this.policy.registered} registered tools`, {
+            published: this.policy.published.length,
+            registered: this.policy.registered,
+            toolsets: this.policy.settings.toolsets,
+            extraTools: this.policy.settings.tools,
+            readOnly: this.policy.settings.readOnly,
+        });
+    }
+    requirePolicy() {
+        if (!this.policy) {
+            throw new Error('Tool publication policy is not resolved: actualToolsManager.initialize() has not run');
+        }
+        return this.policy;
+    }
+    /** The tools this process publishes (tools/list) and dispatches, in registry order. */
+    getPublishedToolNames() {
+        return [...this.requirePolicy().published];
+    }
+    isPublished(name) {
+        return !this.requirePolicy().hidden.has(name) && this.tools.has(name);
+    }
+    /** The resolved MCP_TOOLSETS / MCP_TOOLS / MCP_READ_ONLY, for server_info. */
+    getToolPolicy() {
+        const { toolsets, tools, readOnly } = this.requirePolicy().settings;
+        return { toolsets: [...toolsets], tools: [...tools], readOnly };
     }
     getToolNames() {
         return Array.from(this.tools.keys());
@@ -156,9 +200,17 @@ class ActualToolsManager {
         return this.tools.get(name);
     }
     async callTool(name, args) {
+        const policy = this.requirePolicy();
+        // Registration is checked BEFORE publication: an unregistered name stays "not found".
         const tool = this.getTool(name);
         if (!tool)
             throw new Error(`Tool not found: ${name}`);
+        // Hide AND refuse (#483): omitting a tool from tools/list is not access control.
+        const unavailable = unavailableError(policy, name);
+        if (unavailable) {
+            toolsetLog.warn('Refused a call to an unpublished tool', { tool: name, setting: unavailable.setting });
+            throw unavailable;
+        }
         try {
             const result = await tool.call(args);
             // Force-serialize/deserialize to ensure result is JSON-safe (no circular refs,

package/dist/src/config.js

@@ -119,6 +119,35 @@ export const configSchema = z.object({
     MCP_HTTP_BODY_LIMIT: z.string().default('512kb').refine((v) => parseStrictByteSize(v) !== null, 'MCP_HTTP_BODY_LIMIT must be a positive byte size such as 512kb, 1mb or 1048576 (units b, kb, mb, gb, tb, pb; ' +
         'no spaces around it, no separators; at least 1 byte and at most 9007199254740991 bytes) (#466)'),
     MAX_CONCURRENT_SESSIONS: z.string().default('15').transform(val => parseInt(val, 10)),
+    // --- Published tool surface (#483) ---
+    // Which tools this process publishes AND dispatches. Names are validated, and an unknown
+    // one aborts startup, by resolvePublishedToolNames (src/lib/toolsets.ts) in
+    // actualToolsManager.initialize(), because the registry is only known there.
+    //   MCP_TOOLSETS  comma list of toolsets and presets ('all' by default = every tool).
+    //   MCP_TOOLS     extra individual tool names published on top of MCP_TOOLSETS.
+    MCP_TOOLSETS: z.string().default('all'),
+    MCP_TOOLS: z.string().default(''),
+    // MCP_READ_ONLY drops every write-capable tool, and operators read it as a safety
+    // promise, so it is parsed STRICTLY and in this one place: trimmed and case-insensitive
+    // 'true' or 'false'; unset or empty is false; anything else ('1', 'yes', 'on', a typo)
+    // refuses startup naming the value. The usual `=== 'true'` idiom is wrong here: it
+    // fails SAFE for a flag that enables risk, but would fail OPEN for this one, silently
+    // publishing every writer when an operator wrote MCP_READ_ONLY=1.
+    MCP_READ_ONLY: z
+        .string()
+        .optional()
+        .transform((raw, ctx) => {
+        const v = (raw ?? '').trim().toLowerCase();
+        if (v === '' || v === 'false')
+            return false;
+        if (v === 'true')
+            return true;
+        ctx.addIssue({
+            code: 'custom',
+            message: `MCP_READ_ONLY must be "true" or "false" (case-insensitive; unset or empty means false), got ${JSON.stringify(raw)}.`,
+        });
+        return z.NEVER;
+    }),
     // --- OIDC / mcp-auth (CF-5) ---
     // Set AUTH_PROVIDER=oidc to enable JWT validation via mcp-auth.
     // When 'none' (default), the legacy MCP_SSE_AUTHORIZATION static Bearer token is used.

package/dist/src/index.js

@@ -238,8 +238,9 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         }
         // Initialize tools before usage
         await actualToolsManager.initialize();
-        // Now get implemented tools after initialization
-        const implementedTools = actualToolsManager.getToolNames();
+        // The PUBLISHED tools (#483). This is the one name list every tools/list path receives
+        // (HTTP SDK handler, the no-session LobeChat path, the expired-session shim, stdio).
+        const implementedTools = actualToolsManager.getPublishedToolNames();
         // Extract schemas map with tool name → JSON schema
         const toolSchemas = {};
         for (const toolName of implementedTools) {

package/dist/src/lib/ActualMCPConnection.js

@@ -45,7 +45,7 @@ export class ActualMCPConnection extends EventEmitter {
         // If actualToolsManager is not ready, return demo tools
         let tools;
         try {
-            const toolNames = actualToolsManager.getToolNames();
+            const toolNames = actualToolsManager.getPublishedToolNames();
             tools = toolNames.map((name) => {
                 const tool = actualToolsManager.getTool(name);
                 if (!tool) {