actual-mcp-server 0.22.13 → 0.22.17

package/dist/src/lib/errors.js

@@ -95,6 +95,26 @@ export function isPreflightRefusal(error) {
         error !== null &&
         error[REFUSAL_BRAND] === true);
 }
+/**
+ * A registered tool exists but this process does not publish it (#483), so the call is
+ * refused before dispatch. Deliberately NOT a PreflightRefusal: a refusal is "the request
+ * named something that cannot be acted on, fix the request" and is treated as benign by
+ * rejection-allowlist.ts, whereas this is an operator policy decision the caller cannot
+ * fix. Decide on the type and `setting`, never on the message text.
+ */
+export class ToolUnavailableError extends Error {
+    tool;
+    setting;
+    constructor(tool, setting) {
+        super(setting === 'MCP_READ_ONLY'
+            ? `Tool "${tool}" is not available: it can change state and this server runs with MCP_READ_ONLY=true.`
+            : `Tool "${tool}" is not available: it is not published by this server's MCP_TOOLSETS configuration.`);
+        this.name = 'ToolUnavailableError';
+        this.tool = tool;
+        this.setting = setting;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /**
  * Build a "not found" message with a next-step hint.
  *

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

@@ -3,7 +3,7 @@
  *
  * Common validation schemas used across MCP tools for Actual Budget.
  * These schemas provide consistent validation, better error messages,
- * and reduce duplication across the 82 tool definitions.
+ * and reduce duplication across the 83 tool definitions.
  */
 import { z } from 'zod';
 import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';

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

@@ -6,19 +6,19 @@ import { z } from 'zod';
 // 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'),
+        .describe('How often it repeats'),
     start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
-        .describe('Start date in YYYY-MM-DD format'),
+        .describe('Start date, YYYY-MM-DD'),
     endMode: z.enum(['never', 'after_n_occurrences', 'on_date'])
-        .describe('When the schedule stops: never, after N occurrences, or on a specific date'),
+        .describe('When it stops'),
     interval: z.number().int().positive().optional()
-        .describe('Every N periods. Default: 1 (every period)'),
+        .describe('Every N periods. Default 1'),
     skipWeekend: z.boolean().optional()
-        .describe('If true, occurrence is moved when it falls on a weekend'),
+        .describe('Move an occurrence that falls on a weekend'),
     weekendSolveMode: z.enum(['before', 'after']).optional()
-        .describe('Move to Friday before or Monday after the weekend. Requires skipWeekend: true'),
+        .describe('Friday before or Monday after. Requires skipWeekend'),
     endOccurrences: z.number().int().positive().optional()
-        .describe('Number of occurrences before stopping. Required when endMode is after_n_occurrences'),
+        .describe('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'),
+        .describe('YYYY-MM-DD. Required when endMode is on_date'),
 });

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

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+// #485: the rule input shape and its imperative checks, shared by actual_rules_create and
+// actual_rules_create_batch so both accept and reject exactly the same rules with the same
+// messages. actual_rules_create_or_update keeps its own copies on purpose (out of scope).
+// #486: describe strings shared by the rule tools. Only the TEXT is shared, never the object
+// schemas: actual_rules_update keeps its own ActionSchema (op required, no default) and
+// actual_rules_create_or_update keeps its own stage (no default, #342), so neither can reuse
+// ActionSchema or RuleItemSchema without changing what it accepts.
+export const ACTION_DESCRIBE = {
+    op: 'One of "set", "set-split-amount", "link-schedule", "prepend-notes", "append-notes"',
+    field: 'Field to modify, required for "set": category, payee, notes, cleared, account',
+    value: 'Value to assign: a UUID for category, payee and account, text for notes, a number for amounts',
+    type: 'Value type hint: "id", "string", "number" or "boolean"',
+    options: 'Additional options for the action',
+};
+export const STAGE_DESCRIBE = 'null is the normal stage (the UI default), "pre" runs before it, "post" after';
+// Operators per field type, for the rule tool descriptions that document conditions.
+export const CONDITION_OPERATORS_HELP = 'Condition operators by field: imported_payee, notes, description (text): contains, matches, doesNotContain, is, isNot. ' +
+    'payee, account, category (ids): is, isNot, oneOf, notOneOf. amount: is, gte, lte, gt, lt, isapprox. date: is, gte, lte, gt, lt.';
+// Define the schema for rule conditions and actions
+export const ConditionSchema = z.object({
+    field: z.string().describe('Field to match, e.g. "payee", "notes", "amount", "category"'),
+    op: z.string().describe('Operator, e.g. "is", "contains", "gte"'),
+    value: z.union([z.string(), z.number()]).describe('Value to match against'),
+    type: z.string().optional().describe('Type hint, e.g. "string", "number", "id"'),
+});
+export const ActionSchema = z.object({
+    op: z.string().default('set').describe(`${ACTION_DESCRIBE.op}. Default "set"`),
+    field: z.string().optional().describe(ACTION_DESCRIBE.field),
+    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()]).describe(ACTION_DESCRIBE.value),
+    type: z.string().optional().describe(ACTION_DESCRIBE.type),
+    options: z.object({}).passthrough().optional().describe(ACTION_DESCRIBE.options),
+});
+// Operator validation map
+const FIELD_OPERATORS = {
+    'imported_payee': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'payee': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'account': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'category': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'notes': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'description': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'amount': { type: 'number', operators: ['is', 'gte', 'lte', 'gt', 'lt', 'isapprox'] },
+    'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
+};
+export const RuleItemSchema = z.object({
+    // #342: three stages, and the default one is `null`, not a string.
+    //
+    // Verified against Actual's validator (transaction-rules.ts) and a live server: it
+    // accepts exactly 'pre', 'post' and null. The published API reference says
+    // pre/default/post, which is wrong (reported upstream as actualbudget/actual#8682).
+    // #485: @actual-app/api 26.10.0 changed `fromExternalRule` to convert the string
+    // "default" to null, so Actual itself no longer rejects it. That has no behaviour impact
+    // here: this enum rejects "default" first, and the tool keeps sending null for the normal
+    // stage.
+    //
+    // The default here MUST be null and must be SENT. Two traps:
+    //   - Defaulting to 'pre' (what this did until #342) silently puts every
+    //     MCP-created rule ahead of every rule the user made in the UI, because
+    //     Actual runs stages in the order pre, default, post. No error, no warning.
+    //   - Simply making it .optional() and omitting the key does NOT work: on a
+    //     create the validator always runs and rejects `undefined` with
+    //     `Invalid rule stage: undefined`.
+    stage: z
+        .enum(['pre', 'post'])
+        .nullable()
+        .optional()
+        .default(null)
+        .describe(`${STAGE_DESCRIBE}. Default null; leave unset unless the rule must out-rank or defer to the user's rules`),
+    conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine conditions'),
+    conditions: z.array(ConditionSchema).describe('Conditions that must be met'),
+    actions: z.array(ActionSchema).describe('Actions to perform when they are met'),
+});
+/**
+ * The checks that Zod cannot express, run on a PARSED rule. Throws a plain Error with the
+ * message actual_rules_create has always produced. Pure: no I/O.
+ */
+export function validateRuleInput(input) {
+    // Validate that actions with op="set" have a field
+    for (const action of input.actions) {
+        if (action.op === 'set' && !action.field) {
+            throw new Error('Action with op="set" requires a "field" property (e.g., "category", "payee", "notes", "cleared")');
+        }
+        // Validate action field values for ID-type fields
+        if (action.op === 'set' && action.field) {
+            // Check if using category field with text value instead of ID
+            if (action.field === 'category' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Action field "category" expects a category ID (UUID), but got text value "${action.value}". ` +
+                    `Use the category UUID from your budget data. You can list categories to find the correct UUID.`);
+            }
+            // Check if using payee field with text value instead of ID
+            if (action.field === 'payee' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Action field "payee" expects a payee ID (UUID), but got text value "${action.value}". ` +
+                    `Use the payee UUID from your budget data. You can list payees to find the correct UUID.`);
+            }
+            // Check if using account field with text value instead of ID
+            if (action.field === 'account' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Action field "account" expects an account ID (UUID), but got text value "${action.value}". ` +
+                    `Use the account UUID from your budget data. You can list accounts to find the correct UUID.`);
+            }
+        }
+        // Validate append-notes and prepend-notes have string values
+        if ((action.op === 'append-notes' || action.op === 'prepend-notes') && typeof action.value !== 'string') {
+            throw new Error(`Action "${action.op}" requires a string value, but got ${typeof action.value}. ` +
+                `Example: {op: "${action.op}", value: "text to ${action.op === 'append-notes' ? 'append' : 'prepend'}"}`);
+        }
+    }
+    // Validate field usage to guide users toward correct field selection
+    for (const condition of input.conditions) {
+        const fieldInfo = FIELD_OPERATORS[condition.field];
+        // Validate operator is compatible with field type
+        if (fieldInfo && !fieldInfo.operators.includes(condition.op)) {
+            throw new Error(`Invalid operator "${condition.op}" for field "${condition.field}". ` +
+                `Field "${condition.field}" is a ${fieldInfo.type} field and only supports: ${fieldInfo.operators.join(', ')}. ` +
+                `Please use one of these operators instead.`);
+        }
+        // Check if using payee field with text value instead of ID
+        if (condition.field === 'payee' && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
+            throw new Error(`Field "payee" expects a payee ID (UUID), but got text value "${condition.value}". ` +
+                `To match payee names with text, use "imported_payee" field instead. ` +
+                `Example: {field: "imported_payee", op: "contains", value: "${condition.value}"}`);
+        }
+        // Similar validation for account and category
+        if (['account', 'category'].includes(condition.field) && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
+            throw new Error(`Field "${condition.field}" expects an ID (UUID), but got text value "${condition.value}". ` +
+                `Use the ${condition.field} UUID from your budget data. List ${condition.field === 'account' ? 'accounts' : 'categories'} to find the correct UUID.`);
+        }
+        // Validate oneOf/notOneOf operators expect array values
+        if (['oneOf', 'notOneOf'].includes(condition.op) && !Array.isArray(condition.value)) {
+            throw new Error(`Operator "${condition.op}" expects an array of values, but got ${typeof condition.value}. ` +
+                `Example: {field: "${condition.field}", op: "${condition.op}", value: ["uuid-1", "uuid-2"]}`);
+        }
+    }
+}

package/dist/src/lib/tool-annotations.js

@@ -1,5 +1,5 @@
 /**
- * MCP tool annotations for the 74-tool surface (#379).
+ * MCP tool annotations for the whole tool surface (#379).
  *
  * The Model Context Protocol lets a server describe each tool's NATURE to clients, so a
  * model or a UI can know which tools mutate a budget BEFORE calling one. This file is the
@@ -17,14 +17,15 @@
  * So a tool that declares nothing is already treated as write-capable, destructive and
  * open-world. The value here is therefore NOT warning about the dangerous tools; it is
  * telling clients which tools are SAFE, and correcting `openWorldHint`, whose default is
- * wrong for 73 of our 74 tools: this server's domain is one Actual Budget instance, a
+ * wrong for every tool but one: this server's domain is one Actual Budget instance, a
  * CLOSED world. Only `actual_bank_sync` reaches outside it, to GoCardless or SimpleFIN.
  *
  * THESE ARE HINTS, NEVER A GUARD. The spec is explicit: "all properties in ToolAnnotations
  * are hints. They are not guaranteed to provide a faithful description of tool behavior",
  * and "Clients should never make tool use decisions based on ToolAnnotations received from
  * untrusted servers." Nothing in `src/` may branch on an annotation. Authorisation stays in
- * `budget-acl.ts`, and refusal stays in the adapter guards.
+ * `budget-acl.ts`, and refusal stays in the adapter guards. That includes MCP_READ_ONLY (#483),
+ * which decides from the hard-coded WRITE_CAPABLE set in `toolsets.ts`, never from this table.
  *
  * WHY A CENTRAL TABLE rather than a field on each tool. `types/tool.d.ts` is in CLAUDE.md's
  * do-not-modify tier, and most tools use the legacy `ToolDefinition` shape, so a per-tool
@@ -173,6 +174,7 @@ const ADDITIVE = new Set([
     'actual_payees_create',
     'actual_payees_update',
     'actual_rules_create',
+    'actual_rules_create_batch',
     'actual_rules_create_or_update',
     'actual_rules_update',
     'actual_schedules_create',

package/dist/src/lib/toolsets.js

@@ -0,0 +1,302 @@
+/**
+ * Server-side toolsets, presets and read-only mode (#483).
+ *
+ * An operator chooses which tools this PROCESS publishes, so a chat client with a small
+ * context window or a strict turn limit sees a focused set instead of the whole registry.
+ * The idea and the first implementation are @andycarlberg's (PR #520); the design is
+ * modelled on GitHub's MCP server (GITHUB_TOOLSETS, GITHUB_TOOLS, GITHUB_READ_ONLY).
+ *
+ *   MCP_TOOLSETS   comma list of toolsets and presets. Default `all` (today's behaviour).
+ *   MCP_TOOLS      extra individual tools published on top of MCP_TOOLSETS.
+ *   MCP_READ_ONLY  drops every write-capable tool, overriding the two above.
+ *
+ * Design rules, each the answer to a way this can go wrong:
+ *   - ONE source. resolvePublishedToolNames is pure and runs once, in
+ *     actualToolsManager.initialize(), from the validated config. It returns an immutable
+ *     policy (the published set plus a per-tool hide reason). Nothing reads process.env
+ *     at dispatch time.
+ *   - Hide AND refuse. Omitting a tool from tools/list is not access control, so callTool
+ *     refuses an unpublished tool with ToolUnavailableError.
+ *   - Fail loud. An unknown toolset, preset or tool name throws, and so does a
+ *     configuration that resolves to zero tools. Never silently publish none or all.
+ *   - READ-ONLY NEVER READS ANNOTATIONS. Annotations are hints (AGENTS.md). Write
+ *     capability is the hard-coded WRITE_CAPABLE set below, guarded by
+ *     tests/unit/toolsets.test.js against the adapter call graph. It is not derived at
+ *     runtime because the Docker image ships dist/ only, with no src/ to scan.
+ *   - Static per process. No tools/list_changed: a changing list invalidates the
+ *     provider's prompt cache and client support for the notification is patchy.
+ */
+import { ToolUnavailableError } from './errors.js';
+/** Every registered tool belongs to exactly ONE of these (guarded by the unit test). */
+export const TOOLSETS = {
+    context: [
+        'actual_get_context',
+        'actual_accounts_list',
+        'actual_categories_get',
+        'actual_category_groups_get',
+        'actual_payees_get',
+        'actual_get_id_by_name',
+        'actual_entities_search',
+        'actual_server_info',
+        'actual_server_get_version',
+        'actual_tags_list',
+        'actual_account_groups_list',
+        'actual_budgets_list_available',
+        'actual_budgets_get_all',
+        'actual_preferences_get',
+    ],
+    transactions: [
+        'actual_transactions_get',
+        'actual_transactions_filter',
+        'actual_transactions_search_by_amount',
+        'actual_transactions_search_by_category',
+        'actual_transactions_search_by_month',
+        'actual_transactions_search_by_payee',
+        'actual_transactions_uncategorized',
+        'actual_transactions_create',
+        'actual_transactions_update',
+        'actual_transactions_update_batch',
+        'actual_transactions_delete',
+        'actual_transactions_import',
+        'actual_transfers_create',
+    ],
+    analysis: [
+        'actual_account_flow_summary',
+        'actual_recurring_expenses_summary',
+        'actual_transactions_summary_by_category',
+        'actual_transactions_summary_by_payee',
+        'actual_transactions_aggregate',
+        'actual_accounts_get_balance',
+        'actual_payees_common_list',
+    ],
+    budget: [
+        'actual_budgets_getMonth',
+        'actual_budgets_getMonths',
+        'actual_budgets_setAmount',
+        'actual_budgets_setCarryover',
+        'actual_budgets_holdForNextMonth',
+        'actual_budgets_resetHold',
+        'actual_budgets_transfer',
+        'actual_budget_updates_batch',
+        'actual_notes_get',
+        'actual_notes_update',
+    ],
+    rules: [
+        'actual_rules_get',
+        'actual_payee_rules_get',
+        'actual_rules_create',
+        'actual_rules_create_batch',
+        'actual_rules_update',
+        'actual_rules_create_or_update',
+        'actual_rules_delete',
+    ],
+    schedules: [
+        'actual_schedules_get',
+        'actual_schedules_create',
+        'actual_schedules_update',
+        'actual_schedules_delete',
+    ],
+    structure: [
+        'actual_accounts_create',
+        'actual_accounts_update',
+        'actual_accounts_delete',
+        'actual_account_groups_create',
+        'actual_account_groups_update',
+        'actual_account_groups_delete',
+        'actual_categories_create',
+        'actual_categories_update',
+        'actual_categories_delete',
+        'actual_category_groups_create',
+        'actual_category_groups_update',
+        'actual_category_groups_delete',
+        'actual_payees_create',
+        'actual_payees_update',
+        'actual_payees_delete',
+        'actual_tags_create',
+        'actual_tags_update',
+        'actual_tags_delete',
+        'actual_accounts_close',
+        'actual_accounts_reopen',
+        'actual_payees_merge',
+    ],
+    query: ['actual_query_run'],
+    admin: [
+        'actual_budgets_switch',
+        'actual_budgets_import',
+        'actual_budgets_export',
+        'actual_bank_sync',
+        'actual_session_list',
+        'actual_session_close',
+    ],
+};
+export const TOOLSET_NAMES = Object.keys(TOOLSETS);
+/**
+ * A PRESET is a named tool list that cuts across the groups, accepted anywhere a toolset
+ * name is. Presets are exempt from the one-group-per-tool rule.
+ *
+ * `chat` is seeded from a real day-to-day chat-assistant flow (#477): bootstrap, one read
+ * path, the batch writes, and the few single writes a chat assistant needs. It is 12 tools
+ * where the full surface is 83, roughly a 76% cut in tools/list bytes.
+ *
+ * actual_budgets_getMonth is in it on purpose (decision recorded on #483): budget_updates_batch
+ * and budgets_setAmount tell the model to read a month back with it, and query_run has no
+ * budget-month table to stand in. actual_budgets_getMonths is NOT in it: the out-of-range
+ * refusal from setAmount and the batch already states the budget's first and last month.
+ * tests/unit/toolsets.test.js scans every member's description and input schema for
+ * references to tools the preset hides, and each such reference must name a published
+ * substitute there, so a preset cannot quietly point the model at a tool it cannot call.
+ */
+export const PRESETS = {
+    chat: [
+        'actual_get_context',
+        'actual_query_run',
+        'actual_transactions_update_batch',
+        'actual_budget_updates_batch',
+        'actual_rules_create_batch',
+        'actual_transactions_create',
+        'actual_transactions_update',
+        'actual_transactions_delete',
+        'actual_rules_create',
+        'actual_budgets_transfer',
+        'actual_budgets_setAmount',
+        'actual_budgets_getMonth',
+    ],
+};
+export const PRESET_NAMES = Object.keys(PRESETS);
+/**
+ * Every tool that can change a budget or server state, for MCP_READ_ONLY.
+ *
+ * Derived by hand from the adapter call graph: the 43 tools whose adapter path reaches
+ * queueWriteOperation, plus the four that mutate WITHOUT the write queue (bank_sync imports
+ * transactions through the read path, budgets_export writes a zip to ACTUAL_EXPORT_DIR,
+ * budgets_switch changes the active budget, session_close closes a pooled connection).
+ * Never derive this from tool annotations.
+ *
+ * tests/unit/toolsets.test.js re-derives it from src/ and fails, naming the tool, when a
+ * new writer is missing here. Add a new write tool to this set in the same commit.
+ */
+export const WRITE_CAPABLE = new Set([
+    'actual_account_groups_create',
+    'actual_account_groups_delete',
+    'actual_account_groups_update',
+    'actual_accounts_close',
+    'actual_accounts_create',
+    'actual_accounts_delete',
+    'actual_accounts_reopen',
+    'actual_accounts_update',
+    'actual_bank_sync',
+    'actual_budget_updates_batch',
+    'actual_budgets_export',
+    'actual_budgets_holdForNextMonth',
+    'actual_budgets_import',
+    'actual_budgets_resetHold',
+    'actual_budgets_setAmount',
+    'actual_budgets_setCarryover',
+    'actual_budgets_switch',
+    'actual_budgets_transfer',
+    'actual_categories_create',
+    'actual_categories_delete',
+    'actual_categories_update',
+    'actual_category_groups_create',
+    'actual_category_groups_delete',
+    'actual_category_groups_update',
+    'actual_notes_update',
+    'actual_payees_create',
+    'actual_payees_delete',
+    'actual_payees_merge',
+    'actual_payees_update',
+    'actual_rules_create',
+    'actual_rules_create_batch',
+    'actual_rules_create_or_update',
+    'actual_rules_delete',
+    'actual_rules_update',
+    'actual_schedules_create',
+    'actual_schedules_delete',
+    'actual_schedules_update',
+    'actual_session_close',
+    'actual_tags_create',
+    'actual_tags_delete',
+    'actual_tags_update',
+    'actual_transactions_create',
+    'actual_transactions_delete',
+    'actual_transactions_import',
+    'actual_transactions_update',
+    'actual_transactions_update_batch',
+    'actual_transfers_create',
+]);
+const splitList = (raw) => raw.split(',').map((t) => t.trim()).filter(Boolean);
+/**
+ * Resolve the publication policy. Pure: same inputs, same policy, no environment reads.
+ * Throws (a startup failure) on an unknown toolset, preset or tool name, on a group or
+ * preset naming an unregistered tool, and on a configuration that publishes nothing.
+ */
+export function resolvePublishedToolNames(registeredNames, settings) {
+    const registered = new Set(registeredNames);
+    // A table naming a tool the registry lacks would advertise something that cannot run.
+    for (const [kind, table] of [['Toolset', TOOLSETS], ['Preset', PRESETS]]) {
+        for (const [name, members] of Object.entries(table)) {
+            const missing = members.filter((m) => !registered.has(m));
+            if (missing.length > 0) {
+                throw new Error(`${kind} "${name}" names tools that are not registered: ${missing.join(', ')}`);
+            }
+        }
+    }
+    const validToolsets = ['all', ...TOOLSET_NAMES, ...PRESET_NAMES];
+    const toolsetTokens = splitList(settings.toolsets);
+    if (settings.toolsets.trim() !== '' && toolsetTokens.length === 0) {
+        throw new Error(`MCP_TOOLSETS="${settings.toolsets}" names no toolset. Valid names: ${validToolsets.join(', ')}`);
+    }
+    const requested = toolsetTokens.length > 0 ? toolsetTokens : ['all'];
+    const unknownToolsets = requested.filter((t) => !validToolsets.includes(t));
+    if (unknownToolsets.length > 0) {
+        throw new Error(`Unknown name in MCP_TOOLSETS: ${unknownToolsets.map((t) => `"${t}"`).join(', ')}. ` +
+            `Valid names: ${validToolsets.join(', ')}`);
+    }
+    const extras = splitList(settings.tools);
+    const unknownTools = extras.filter((t) => !registered.has(t));
+    if (unknownTools.length > 0) {
+        throw new Error(`Unknown tool in MCP_TOOLS: ${unknownTools.map((t) => `"${t}"`).join(', ')}. ` +
+            `Use the full registered name, for example actual_accounts_list. Registered tools: ${[...registered].sort().join(', ')}`);
+    }
+    const selected = new Set();
+    if (requested.includes('all')) {
+        registeredNames.forEach((n) => selected.add(n));
+    }
+    else {
+        for (const token of requested) {
+            const members = token in TOOLSETS ? TOOLSETS[token] : PRESETS[token];
+            members.forEach((n) => selected.add(n));
+        }
+    }
+    extras.forEach((n) => selected.add(n));
+    const published = [];
+    const hidden = new Map();
+    for (const name of registeredNames) {
+        if (!selected.has(name))
+            hidden.set(name, 'MCP_TOOLSETS');
+        else if (settings.readOnly && WRITE_CAPABLE.has(name))
+            hidden.set(name, 'MCP_READ_ONLY');
+        else
+            published.push(name);
+    }
+    if (published.length === 0) {
+        throw new Error(`No tools would be published: MCP_TOOLSETS="${settings.toolsets}", MCP_TOOLS="${settings.tools}" and ` +
+            `MCP_READ_ONLY=${settings.readOnly} resolve to 0 tools. For example, a toolset made only of writers ` +
+            `(structure) publishes nothing under MCP_READ_ONLY=true.`);
+    }
+    return Object.freeze({
+        published: Object.freeze(published),
+        hidden,
+        registered: registeredNames.length,
+        settings: Object.freeze({
+            toolsets: Object.freeze(requested),
+            tools: Object.freeze(extras),
+            readOnly: settings.readOnly,
+        }),
+    });
+}
+/** The typed refusal for a registered but unpublished tool, built from the stored reason. */
+export function unavailableError(policy, tool) {
+    const setting = policy.hidden.get(tool);
+    return setting ? new ToolUnavailableError(tool, setting) : undefined;
+}

package/dist/src/server/httpServer.js

@@ -385,11 +385,8 @@ advertisedUrl) {
                     content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
                 };
             }
-            // fallback: attempt actualToolsManager
-            if (actualToolsManager && typeof actualToolsManager.invoke === 'function') {
-                const r = await actualToolsManager.invoke(name, args ?? {});
-                return { content: [{ type: 'text', text: JSON.stringify(r) }] };
-            }
+            // There is deliberately no second dispatch path here (#483): actualToolsManager has
+            // no `invoke`, and every call must go through callTool, which refuses unpublished tools.
             throw new Error(`Tool executor not available for ${name}`);
         });
         return { server };