actual-mcp-server 0.6.33 → 0.6.35

package/README.md

@@ -33,14 +33,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:
 
-- **63 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
+- **69 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.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`.
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 63 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 69 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -346,6 +346,26 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 `actual_payees_get` · `actual_payees_create` · `actual_payees_update` · `actual_payees_delete` · `actual_payees_merge` · `actual_payee_rules_get`
 
+### Tags (4)
+
+`actual_tags_list` · `actual_tags_create` · `actual_tags_update` · `actual_tags_delete`
+
+| Tool | Description |
+|------|-------------|
+| `actual_tags_list` | List all tags (id, tag word, optional color and description) |
+| `actual_tags_create` | Create or upsert a tag by name; returns the tag UUID |
+| `actual_tags_update` | Update tag name, color, or description by UUID |
+| `actual_tags_delete` | Soft-delete a tag by UUID |
+
+### Notes (2)
+
+`actual_notes_get` · `actual_notes_update`
+
+| Tool | Description |
+|------|-------------|
+| `actual_notes_get` | Get the note for any entity (account/category/category-group/payee UUID, or budget-YYYY-MM) |
+| `actual_notes_update` | Set or clear the note for any entity; validates entity exists or matches budget-YYYY-MM pattern |
+
 ### Budgets (10)
 
 | Tool | Description |
@@ -730,4 +750,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.33 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.35 | **Tool Count:** 69 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,12 +1,12 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.33",
+    "version": "0.6.35",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
     },
-    "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+    "description": "MCP server with 69 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
     "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
     "repository": {
         "type": "git",
@@ -30,7 +30,7 @@
         "verify-tools": "npm run build && node scripts/verify-tools.js",
         "check:coverage": "node scripts/list-actual-api-methods.mjs",
         "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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",
+        "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",
         "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

@@ -66,6 +66,12 @@ const IMPLEMENTED_TOOLS = [
     'actual_session_list',
     'actual_get_id_by_name',
     'actual_server_get_version',
+    'actual_tags_list',
+    'actual_tags_create',
+    'actual_tags_update',
+    'actual_tags_delete',
+    'actual_notes_get',
+    'actual_notes_update',
 ];
 // 🔑 Mapping of Actual API function names → your MCP tool names
 // This allows us to compare what exists in the API vs. what it has been wrapped.

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

@@ -6,12 +6,13 @@ import api from '@actual-app/api';
 // cannot expose its named exports via static import syntax. At runtime the default import
 // IS module.exports, so all methods are accessible as properties.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule,
+const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
  } = api;
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
 import retry, { isRetryableError } from './retry.js';
+import { notFoundMsg } from './errors.js';
 import logger from '../logger.js';
 import config from '../config.js';
 import { parseBudgetRegistry } from './budget-registry.js';
@@ -1749,6 +1750,60 @@ export async function getServerVersion() {
         return await withConcurrency(() => retry(() => rawGetServerVersion(), { retries: 2, backoffMs: 200 }));
     });
 }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function getTags() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.tags.get').catch(() => { });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await withConcurrency(() => retry(() => rawGetTags(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function createTag(tag) {
+    observability.incrementToolCall('actual.tags.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const raw = await withConcurrency(() => retry(() => rawCreateTag(tag), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
+        return normalizeToId(raw);
+    });
+}
+export async function updateTag(id, fields) {
+    observability.incrementToolCall('actual.tags.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const tags = await withConcurrency(() => retry(() => rawGetTags(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const exists = tags.some((t) => t.id === id);
+        if (!exists) {
+            throw new Error(notFoundMsg('Tag', id, 'actual_tags_list'));
+        }
+        await withConcurrency(() => retry(() => rawUpdateTag(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+    });
+}
+export async function deleteTag(id) {
+    observability.incrementToolCall('actual.tags.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const tags = await withConcurrency(() => retry(() => rawGetTags(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const exists = tags.some((t) => t.id === id);
+        if (!exists) {
+            throw new Error(notFoundMsg('Tag', id, 'actual_tags_list'));
+        }
+        await withConcurrency(() => retry(() => rawDeleteTag(id), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function getNote(id) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.notes.get').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetNote(id), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function updateNote(id, note) {
+    observability.incrementToolCall('actual.notes.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawUpdateNote(id, note), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+    });
+}
 export default {
     getAccounts,
     getAccountsWithBalances,
@@ -1760,6 +1815,12 @@ export default {
     createCategory,
     getPayees,
     createPayee,
+    getTags,
+    createTag,
+    updateTag,
+    deleteTag,
+    getNote,
+    updateNote,
     getBudgetMonths,
     getBudgetMonth,
     setBudgetAmount,

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

@@ -58,6 +58,14 @@ export const ruleIdSchema = z
     .string()
     .regex(UUID_PATTERN, 'Invalid rule ID format (expected UUID)')
     .describe('Rule UUID');
+/**
+ * Tag UUID validation
+ * Used for: tag management operations (update, delete)
+ */
+export const tagIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid tag ID format (expected UUID)')
+    .describe('Tag UUID');
 // ============================================================================
 // DATE SCHEMAS
 // ============================================================================
@@ -169,6 +177,7 @@ export const CommonSchemas = {
     categoryGroupId: categoryGroupIdSchema,
     payeeId: payeeIdSchema,
     ruleId: ruleIdSchema,
+    tagId: tagIdSchema,
     // Dates
     date: dateSchema,
     monthYear: monthYearSchema,

package/dist/src/tools/index.js

@@ -62,3 +62,9 @@ export { default as transactions_update_batch } from './transactions_update_batc
 export { default as transfers_create } from './transfers_create.js';
 export { default as session_close } from './session_close.js';
 export { default as session_list } from './session_list.js';
+export { default as tags_list } from './tags_list.js';
+export { default as tags_create } from './tags_create.js';
+export { default as tags_update } from './tags_update.js';
+export { default as tags_delete } from './tags_delete.js';
+export { default as notes_get } from './notes_get.js';
+export { default as notes_update } from './notes_update.js';

package/dist/src/tools/notes_get.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+export default createTool({
+    name: 'actual_notes_get',
+    description: 'Get the note attached to an entity in Actual Budget. ' +
+        'The id can be any entity UUID (account, category, category-group, payee) ' +
+        'or the synthetic budget-month id in the form "budget-YYYY-MM" ' +
+        '(e.g. "budget-2026-01" for January 2026). ' +
+        'Returns the note text when one exists. ' +
+        'Returns a clear "no note" result (not null) when no note has been set for the given id.',
+    schema: z.object({
+        id: z.string().min(1).describe('Entity id: a UUID for an account/category/category-group/payee, ' +
+            'or "budget-YYYY-MM" for a budget month note'),
+    }),
+    handler: async ({ id }) => {
+        const note = await adapter.getNote(id);
+        if (note === null) {
+            return { found: false, id, note: null, message: `No note set for ${id}` };
+        }
+        return { found: true, id: note.id, note: note.note };
+    },
+    examples: [
+        {
+            description: 'Get note for an account',
+            input: { id: '00000000-0000-0000-0000-000000000001' },
+        },
+        {
+            description: 'Get note for a budget month',
+            input: { id: 'budget-2026-01' },
+        },
+    ],
+});

package/dist/src/tools/notes_update.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+const BUDGET_MONTH_RE = /^budget-\d{4}-\d{2}$/;
+export default createTool({
+    name: 'actual_notes_update',
+    description: 'Set or clear the note attached to an entity in Actual Budget. ' +
+        'This is an upsert: creates the note if none exists, updates it if one does. ' +
+        'Pass an empty string for note to clear it. ' +
+        'The id must resolve to a known entity (account, category, category-group, payee) ' +
+        'or match the pattern "budget-YYYY-MM" for a budget month note. ' +
+        'Unknown ids are rejected to prevent orphan notes. ' +
+        'Budget month notes support template directives such as "#template 250" and "#goal 1000".',
+    schema: z.object({
+        id: z.string().min(1).describe('Entity id: a UUID for an account/category/category-group/payee, ' +
+            'or "budget-YYYY-MM" for a budget month note'),
+        note: z.string().describe('Note text to set. Pass an empty string to clear the note.'),
+    }),
+    handler: async ({ id, note }) => {
+        // Fast path: budget-YYYY-MM synthetic ids need no entity lookup.
+        if (!BUDGET_MONTH_RE.test(id)) {
+            // Validate that the id resolves to a known entity.
+            // Fetch in parallel to minimise latency.
+            const [accounts, categories, categoryGroups, payees] = await Promise.all([
+                adapter.getAccounts(),
+                adapter.getCategories(),
+                adapter.getCategoryGroups(),
+                adapter.getPayees(),
+            ]);
+            const known = (Array.isArray(accounts) && accounts.some((e) => e.id === id)) ||
+                (Array.isArray(categories) && categories.some((e) => e.id === id)) ||
+                (Array.isArray(categoryGroups) && categoryGroups.some((e) => e.id === id)) ||
+                (Array.isArray(payees) && payees.some((e) => e.id === id));
+            if (!known) {
+                return {
+                    error: `Entity "${id}" not found. ` +
+                        'The id must be a UUID from actual_accounts_list, actual_categories_get, ' +
+                        'actual_category_groups_get, or actual_payees_get, ' +
+                        'or a budget month id like "budget-2026-01".',
+                };
+            }
+        }
+        await adapter.updateNote(id, note);
+        return {
+            success: true,
+            id,
+            note,
+            cleared: note === '',
+        };
+    },
+    examples: [
+        {
+            description: 'Set a budget template note for January 2026',
+            input: { id: 'budget-2026-01', note: '#template 250' },
+        },
+        {
+            description: 'Clear a note',
+            input: { id: 'budget-2026-01', note: '' },
+        },
+        {
+            description: 'Set a note on an account',
+            input: { id: '00000000-0000-0000-0000-000000000001', note: 'Reconcile monthly' },
+        },
+    ],
+});

package/dist/src/tools/tags_create.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+export default createTool({
+    name: 'actual_tags_create',
+    description: 'Create a new tag in Actual Budget. The "tag" field is the raw word WITHOUT a leading "#" character ' +
+        '(e.g. use "groceries", not "#groceries"). ' +
+        'IMPORTANT: this operation is an upsert on the tag word. If a tag with the same name already exists ' +
+        '(including previously deleted ones), the existing tag is updated and its id is returned. ' +
+        'Creating the same tag name twice always returns the same id. ' +
+        'Color convention is CSS hex (e.g. "#33aa33") but no format is enforced by the API.',
+    schema: z.object({
+        tag: z.string().min(1, 'tag must not be empty').describe('Tag word without "#" prefix (e.g. "groceries")'),
+        color: z.string().optional().describe('Optional color string (convention: CSS hex like "#33aa33")'),
+        description: z.string().optional().describe('Optional description of the tag'),
+    }),
+    handler: async (input) => {
+        return await adapter.createTag(input);
+    },
+    examples: [
+        {
+            description: 'Create a groceries tag with a green color',
+            input: { tag: 'groceries', color: '#33aa33', description: 'Food purchases' },
+        },
+        {
+            description: 'Create a minimal tag (no color or description)',
+            input: { tag: 'travel' },
+        },
+    ],
+});

package/dist/src/tools/tags_delete.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+export default createTool({
+    name: 'actual_tags_delete',
+    description: 'Delete a tag from Actual Budget by its UUID. ' +
+        'The tag is soft-deleted (tombstoned) and will no longer appear in actual_tags_list. ' +
+        'If the id does not exist, a not-found error is returned. ' +
+        'Use actual_tags_list to find valid tag UUIDs.',
+    schema: z.object({
+        id: CommonSchemas.tagId,
+    }),
+    handler: async ({ id }) => {
+        await adapter.deleteTag(id);
+        return { success: true };
+    },
+    examples: [
+        {
+            description: 'Delete a tag by its UUID',
+            input: { id: '00000000-0000-0000-0000-000000000001' },
+        },
+    ],
+});

package/dist/src/tools/tags_list.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+export default createTool({
+    name: 'actual_tags_list',
+    description: 'List all tags defined in Actual Budget. Tags are stored without a leading "#" character ' +
+        '(e.g. "groceries", not "#groceries"). Returns id, tag (the word), and optional color and description fields.',
+    schema: z.object({}),
+    handler: async () => {
+        return await adapter.getTags();
+    },
+    examples: [
+        { description: 'List all tags', input: {} },
+    ],
+});

package/dist/src/tools/tags_update.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+export default createTool({
+    name: 'actual_tags_update',
+    description: 'Update an existing tag in Actual Budget. At least one of tag/color/description must be provided. ' +
+        'The id must be a valid UUID from actual_tags_list. ' +
+        'If the id does not exist, a not-found error is returned (the API would silently no-op; this tool adds a pre-flight guard). ' +
+        'The "tag" field is the raw word WITHOUT a leading "#" character.',
+    schema: z.object({
+        id: CommonSchemas.tagId,
+        tag: z.string().min(1, 'tag must not be empty').optional().describe('New tag word without "#" prefix'),
+        color: z.string().optional().describe('New color string (convention: CSS hex like "#112233")'),
+        description: z.string().optional().describe('New description'),
+    }).refine((data) => data.tag !== undefined || data.color !== undefined || data.description !== undefined, { message: 'At least one of tag, color, or description must be provided' }),
+    handler: async ({ id, tag, color, description }) => {
+        const fields = {};
+        if (tag !== undefined)
+            fields.tag = tag;
+        if (color !== undefined)
+            fields.color = color;
+        if (description !== undefined)
+            fields.description = description;
+        await adapter.updateTag(id, fields);
+        return { success: true };
+    },
+    examples: [
+        {
+            description: 'Rename a tag and change its color',
+            input: { id: '00000000-0000-0000-0000-000000000001', tag: 'food', color: '#112233' },
+        },
+        {
+            description: 'Update only the description',
+            input: { id: '00000000-0000-0000-0000-000000000001', description: 'Updated description' },
+        },
+    ],
+});

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.33",
+  "version": "0.6.35",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 63 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 69 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
   "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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",
+    "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",
     "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",