mcp-grocy 2.7.0 → 2.7.2

package/build/tools/shopping/definitions.js

@@ -0,0 +1,147 @@
+export const shoppingToolDefinitions = [
+    {
+        name: 'shopping_lists_get',
+        description: '[SHOPPING/BOOK] Get all shopping lists, including their ID, name, and notes.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'shopping_list_get',
+        description: '[SHOPPING/LIST] Get a shopping list, including its metadata (like notes) and its array of product items.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                shoppingListId: {
+                    type: 'number',
+                    description: 'ID of the shopping list to get (default: 1). Most users have only one shopping list with ID 1.',
+                    default: 1,
+                },
+            },
+            required: ['shoppingListId'],
+        },
+    },
+    {
+        name: 'shopping_list_update',
+        description: '[SHOPPING/BOOK] Update a shopping list. You can update its name or notes.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                shoppingListId: {
+                    type: 'number',
+                    description: 'ID of the shopping list to update. Most users have only one shopping list with ID 1.',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Optional. New name for the shopping list.',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Optional. Notes or description for the shopping list.',
+                },
+            },
+            required: ['shoppingListId'],
+        },
+    },
+    {
+        name: 'shopping_list_add_item',
+        description: '[SHOPPING/LIST] Add an item to a shopping list. Use inventory_products_get first to find the product ID you want to add. If multiple similar products exist or you are unsure, you can omit the product ID and just provide the item name in the note.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                productId: {
+                    type: 'number',
+                    description: 'Optional. ID of the product to add. If a great match is found, use it. Otherwise, omit this and just specify the requested item in the note.',
+                },
+                amount: {
+                    type: 'number',
+                    description: "Amount to add to shopping list in the product's stock unit (e.g., 2 pieces, 1.5 kg, 750 ml). Ensure you know the product's unit before specifying amount. Default: 0 (meaning: buy whatever you find reasonable).",
+                    default: 0,
+                },
+                shoppingListId: {
+                    type: 'number',
+                    description: 'ID of the shopping list to add to (default: 1). Most users have only one shopping list with ID 1.',
+                    default: 1,
+                },
+                note: {
+                    type: 'string',
+                    description: 'Note or name of the item. Required if productId is omitted.',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'shopping_list_remove_item',
+        description: '[SHOPPING/LIST] Remove an item from a shopping list. Use shopping_list_get first to find the shopping list item ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                shoppingListItemId: {
+                    type: 'number',
+                    description: 'ID of the shopping list item to remove. Use shopping_list_get tool to find the correct shopping list item ID by looking at the "id" field in the results.',
+                },
+            },
+            required: ['shoppingListItemId'],
+        },
+    },
+    {
+        name: 'shopping_list_update_item',
+        description: '[SHOPPING/LIST] Update an item in a shopping list (e.g., to edit the note or amount). Use shopping_list_get first to find the shopping list item ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                shoppingListItemId: {
+                    type: 'number',
+                    description: 'ID of the shopping list item to update. Use shopping_list_get tool to find the correct shopping list item ID by looking at the "id" field in the results.',
+                },
+                productId: {
+                    type: 'number',
+                    description: 'Optional. Product ID if you want to change it.',
+                },
+                amount: {
+                    type: 'number',
+                    description: 'Optional. Amount to update to.',
+                },
+                shoppingListId: {
+                    type: 'number',
+                    description: 'Optional. Shopping list ID if you want to move it.',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional. Note for the shopping list item. Use this to add or edit notes.',
+                },
+            },
+            required: ['shoppingListItemId'],
+        },
+    },
+    {
+        name: 'shopping_list_print_thermal',
+        description: '[SHOPPING/PRINTING] Print the shopping list with a thermal printer. This creates a physical shopping list for store visits.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                shoppingListId: {
+                    type: 'number',
+                    description: 'ID of the shopping list to print (default: 1). Most users have only one shopping list with ID 1.',
+                    default: 1,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'shopping_locations_get',
+        description: '[SHOPPING/LOCATIONS] Get **retail store / shop** locations where you buy groceries (Grocy shopping locations). NOT pantry or home storage—use system_locations_get for storage location IDs (locationId). Use shopping_locations_get for storeId when adding shopping-list items or store-specific workflows.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+];

package/build/tools/shopping/handlers.js

@@ -0,0 +1,198 @@
+import { BaseToolHandler } from '../base.js';
+export class ShoppingToolHandlers extends BaseToolHandler {
+    async getResolvedShoppingMetadata() {
+        const [productsResponse, quantityUnitsResponse] = await Promise.all([
+            this.apiCall('/objects/products'),
+            this.apiCall('/objects/quantity_units'),
+        ]);
+        const products = Array.isArray(productsResponse) ? productsResponse : [];
+        const quantityUnits = Array.isArray(quantityUnitsResponse) ? quantityUnitsResponse : [];
+        return {
+            productsById: new Map(products
+                .filter((product) => product && product.id !== undefined && product.id !== null)
+                .map((product) => [Number(product.id), product])),
+            quantityUnitsById: new Map(quantityUnits
+                .filter((unit) => unit && unit.id !== undefined && unit.id !== null)
+                .map((unit) => [Number(unit.id), unit])),
+        };
+    }
+    enrichShoppingListItem(item, productsById, quantityUnitsById) {
+        const productId = item?.product_id !== undefined && item?.product_id !== null ? Number(item.product_id) : null;
+        const product = productId !== null ? productsById.get(productId) : undefined;
+        const productQuIdStock = product?.qu_id_stock !== undefined && product?.qu_id_stock !== null
+            ? Number(product.qu_id_stock)
+            : null;
+        const productQuantityUnitStock = productQuIdStock !== null ? quantityUnitsById.get(productQuIdStock) : undefined;
+        const quId = item?.qu_id !== undefined && item?.qu_id !== null ? Number(item.qu_id) : productQuIdStock;
+        const quantityUnit = quId !== null ? quantityUnitsById.get(quId) : undefined;
+        const { product_id: _product_id, shopping_list_id: _shopping_list_id, qu_id: _qu_id, ...restItem } = item || {};
+        return {
+            ...restItem,
+            product: product
+                ? {
+                    id: product.id,
+                    name: product.name,
+                    description: product.description ?? null,
+                    quantityUnitStock: productQuantityUnitStock
+                        ? {
+                            id: productQuantityUnitStock.id,
+                            name: productQuantityUnitStock.name,
+                        }
+                        : null,
+                }
+                : null,
+            quantityUnit: quantityUnit
+                ? {
+                    id: quantityUnit.id,
+                    name: quantityUnit.name,
+                }
+                : null,
+        };
+    }
+    async enrichShoppingListResponse(data) {
+        if (Array.isArray(data)) {
+            if (data.length === 0) {
+                return data;
+            }
+            const { productsById, quantityUnitsById } = await this.getResolvedShoppingMetadata();
+            return data.map((item) => this.enrichShoppingListItem(item, productsById, quantityUnitsById));
+        }
+        if (data && typeof data === 'object') {
+            const hasShoppingFields = 'product_id' in data || 'qu_id' in data;
+            if (!hasShoppingFields) {
+                return data;
+            }
+            const { productsById, quantityUnitsById } = await this.getResolvedShoppingMetadata();
+            return this.enrichShoppingListItem(data, productsById, quantityUnitsById);
+        }
+        return data;
+    }
+    normalizeShoppingList(item) {
+        if (!item || typeof item !== 'object') {
+            return item;
+        }
+        const { description, ...rest } = item;
+        return {
+            ...rest,
+            notes: description ?? null,
+        };
+    }
+    normalizeShoppingListsResponse(data) {
+        if (Array.isArray(data)) {
+            return data.map((item) => this.normalizeShoppingList(item));
+        }
+        return this.normalizeShoppingList(data);
+    }
+    getShoppingLists = async () => {
+        return this.executeToolHandler(async () => {
+            const result = await this.apiCall('/objects/shopping_lists');
+            return this.createSuccess(this.normalizeShoppingListsResponse(result), 'Shopping lists retrieved successfully');
+        });
+    };
+    getShoppingList = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { shoppingListId } = args || {};
+            this.validateRequired({ shoppingListId }, ['shoppingListId']);
+            const queryParams = {
+                'query[]': `shopping_list_id=${shoppingListId}`,
+            };
+            const result = await this.apiCall('/objects/shopping_list', 'GET', undefined, {
+                queryParams,
+            });
+            const enriched = await this.enrichShoppingListResponse(result);
+            const meta = await this.apiCall(`/objects/shopping_lists/${shoppingListId}`);
+            const listMetadata = this.normalizeShoppingList(meta);
+            return this.createSuccess({
+                list: listMetadata,
+                items: enriched,
+            }, 'Shopping list retrieved successfully');
+        });
+    };
+    updateShoppingList = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { shoppingListId, name, notes } = args || {};
+            this.validateRequired({ shoppingListId }, ['shoppingListId']);
+            const existingList = await this.apiCall(`/objects/shopping_lists/${shoppingListId}`);
+            if (!existingList) {
+                throw new Error(`Shopping list ${shoppingListId} not found`);
+            }
+            const body = {
+                ...existingList,
+            };
+            if (name !== undefined)
+                body.name = name;
+            if (notes !== undefined) {
+                body.description = notes;
+            }
+            const result = await this.apiCall(`/objects/shopping_lists/${shoppingListId}`, 'PUT', body);
+            return this.createSuccess(this.normalizeShoppingListsResponse(result), 'Shopping list updated successfully');
+        });
+    };
+    addShoppingListItem = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { productId, amount = 1, shoppingListId = 1, note = '' } = args || {};
+            if (productId === undefined && !note) {
+                throw new Error('Either productId or note must be provided');
+            }
+            const body = {
+                amount,
+                shopping_list_id: shoppingListId,
+                note,
+            };
+            if (productId !== undefined) {
+                body.product_id = productId;
+            }
+            const result = await this.apiCall('/objects/shopping_list', 'POST', body);
+            const enriched = await this.enrichShoppingListResponse(result);
+            return this.createSuccess(enriched, 'Shopping list item added successfully');
+        });
+    };
+    removeShoppingListItem = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { shoppingListItemId } = args || {};
+            this.validateRequired({ shoppingListItemId }, ['shoppingListItemId']);
+            const result = await this.apiCall(`/objects/shopping_list/${shoppingListItemId}`, 'DELETE');
+            return this.createSuccess(result, 'Shopping list item removed successfully');
+        });
+    };
+    updateShoppingListItem = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { shoppingListItemId, productId, amount, shoppingListId, note } = args || {};
+            this.validateRequired({ shoppingListItemId }, ['shoppingListItemId']);
+            const existingItem = await this.apiCall(`/objects/shopping_list/${shoppingListItemId}`);
+            if (!existingItem) {
+                throw new Error(`Shopping list item ${shoppingListItemId} not found`);
+            }
+            const body = {
+                ...existingItem,
+            };
+            if (productId !== undefined)
+                body.product_id = productId;
+            if (amount !== undefined)
+                body.amount = amount;
+            if (shoppingListId !== undefined)
+                body.shopping_list_id = shoppingListId;
+            if (note !== undefined)
+                body.note = note;
+            const result = await this.apiCall(`/objects/shopping_list/${shoppingListItemId}`, 'PUT', body);
+            const enriched = await this.enrichShoppingListResponse(result);
+            return this.createSuccess(enriched, 'Shopping list item updated successfully');
+        });
+    };
+    printShoppingListThermal = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { shoppingListId } = args || {};
+            const endpoint = shoppingListId !== undefined
+                ? `/print/shoppinglist/thermal?list_id=${shoppingListId}`
+                : '/print/shoppinglist/thermal';
+            const result = await this.apiCall(endpoint);
+            return this.createSuccess(result, 'Shopping list sent to thermal printer successfully');
+        });
+    };
+    getShoppingLocations = async () => {
+        return this.executeToolHandler(async () => {
+            const result = await this.apiCall('/objects/shopping_locations');
+            return this.createSuccess(result, 'Shopping locations retrieved successfully');
+        });
+    };
+}

package/build/tools/shopping/index.js

@@ -0,0 +1,17 @@
+import { shoppingToolDefinitions } from './definitions.js';
+import { ShoppingToolHandlers } from './handlers.js';
+const handlers = new ShoppingToolHandlers();
+export const shoppingModule = {
+    definitions: shoppingToolDefinitions,
+    handlers: {
+        shopping_lists_get: handlers.getShoppingLists,
+        shopping_list_get: handlers.getShoppingList,
+        shopping_list_update: handlers.updateShoppingList,
+        shopping_list_add_item: handlers.addShoppingListItem,
+        shopping_list_remove_item: handlers.removeShoppingListItem,
+        shopping_list_update_item: handlers.updateShoppingListItem,
+        shopping_list_print_thermal: handlers.printShoppingListThermal,
+        shopping_locations_get: handlers.getShoppingLocations,
+    },
+};
+export * from './definitions.js';

package/build/tools/system/definitions.js

@@ -0,0 +1,89 @@
+import { config } from '../../config/index.js';
+export const systemToolDefinitions = [
+    // ==================== CORE SYSTEM UTILITIES ====================
+    {
+        name: 'system_locations_get',
+        description: '[SYSTEM/LOCATIONS] Get **home storage / stock** locations (freezer, pantry, fridge—where inventory lives). NOT retail stores—use shopping_locations_get for shop/store IDs (storeId). Use this for locationId on stock, transfers, and purchases.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'system_units_get',
+        description: '[SYSTEM/UNITS] Get all quantity units from your Grocy instance.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'system_users_get',
+        description: '[SYSTEM/USERS] Get all users from your Grocy instance.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    // ==================== DEVELOPER UTILITIES ====================
+    {
+        name: 'system_dev_call_api',
+        description: '[SYSTEM/DEV] Call a specific Grocy API endpoint with custom parameters.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                endpoint: {
+                    type: 'string',
+                    description: 'Grocy API endpoint to call (e.g., "objects/products"). Do not include /api/ prefix.',
+                },
+                method: {
+                    type: 'string',
+                    enum: ['GET', 'POST', 'PUT', 'DELETE'],
+                    description: 'HTTP method to use',
+                    default: 'GET',
+                },
+                body: {
+                    type: 'object',
+                    description: 'Optional request body for POST/PUT requests',
+                },
+            },
+            required: ['endpoint'],
+        },
+    },
+    {
+        name: 'system_dev_test_request',
+        description: `[SYSTEM/DEV] Test a REST API endpoint and get detailed response information. Base URL: ${config.grocy.base_url} | SSL Verification enabled | Authentication: ${config.grocy.api_key ? 'API Key using header: GROCY-API-KEY' : 'No authentication configured'}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                method: {
+                    type: 'string',
+                    enum: ['GET', 'POST', 'PUT', 'DELETE'],
+                    description: 'HTTP method to use',
+                },
+                endpoint: {
+                    type: 'string',
+                    description: 'Endpoint path (e.g. "/users"). Do not include full URLs - only the path.',
+                },
+                body: {
+                    type: 'object',
+                    description: 'Optional request body for POST/PUT requests',
+                },
+                headers: {
+                    type: 'object',
+                    description: 'Optional request headers for one-time use.',
+                    additionalProperties: {
+                        type: 'string',
+                    },
+                },
+            },
+            required: ['method', 'endpoint'],
+        },
+    },
+];

package/build/tools/system/handlers.js

@@ -0,0 +1,156 @@
+import { BaseToolHandler } from '../base.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import apiClient from '../../api/client.js';
+import { config } from '../../config/index.js';
+import { logger } from '../../utils/logger.js';
+export class SystemToolHandlers extends BaseToolHandler {
+    redactHeaders(headers) {
+        const redacted = { ...headers };
+        const sensitiveHeaders = new Set([
+            'grocy-api-key',
+            'authorization',
+            'x-api-key',
+            'proxy-authorization',
+        ]);
+        for (const key of Object.keys(redacted)) {
+            if (sensitiveHeaders.has(key.toLowerCase())) {
+                redacted[key] = '[REDACTED]';
+            }
+        }
+        return redacted;
+    }
+    /**
+     * Truncate a string to at most `maxBytes` UTF-8 bytes without splitting a codepoint.
+     */
+    truncateStringToUtf8Bytes(str, maxBytes) {
+        const buf = Buffer.from(str, 'utf8');
+        if (buf.length <= maxBytes) {
+            return { text: str, byteLength: buf.length };
+        }
+        let end = maxBytes;
+        while (end > 0) {
+            while (end > 0 && (buf[end - 1] & 0xc0) === 0x80) {
+                end--;
+            }
+            if (end === 0) {
+                break;
+            }
+            const text = buf.subarray(0, end).toString('utf8');
+            if (Buffer.byteLength(text, 'utf8') === end) {
+                return { text, byteLength: end };
+            }
+            end--;
+        }
+        return { text: '', byteLength: 0 };
+    }
+    applyResponseSizeLimit(body) {
+        const sizeLimit = config.grocy.response_size_limit;
+        const jsonBody = JSON.stringify(body);
+        const originalSize = Buffer.byteLength(jsonBody, 'utf8');
+        if (originalSize <= sizeLimit) {
+            return { body };
+        }
+        const { text: truncatedJsonBody, byteLength: prefixBytes } = this.truncateStringToUtf8Bytes(jsonBody, sizeLimit);
+        const returnedSize = Buffer.byteLength(truncatedJsonBody, 'utf8');
+        return {
+            body: `${truncatedJsonBody}...[TRUNCATED]`,
+            truncated: {
+                originalSize,
+                returnedSize,
+                truncationPoint: prefixBytes,
+                sizeLimit,
+            },
+        };
+    }
+    // ==================== CORE SYSTEM UTILITIES ====================
+    getLocations = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/objects/locations');
+            return this.createSuccess(data);
+        });
+    };
+    getQuantityUnits = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/objects/quantity_units');
+            return this.createSuccess(data);
+        });
+    };
+    getUsers = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/users');
+            return this.createSuccess(data);
+        });
+    };
+    // ==================== DEVELOPER UTILITIES ====================
+    callGrocyApi = async (args) => {
+        const { endpoint, method = 'GET', body = null } = args;
+        if (!endpoint) {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: endpoint');
+        }
+        // Remove leading /api/ if present
+        const cleanEndpoint = endpoint.replace(/^\/?(?:api\/)?/, '');
+        try {
+            const response = await apiClient.request(`/${cleanEndpoint}`, {
+                method,
+                body,
+            });
+            return this.createSuccess(response.data);
+        }
+        catch (error) {
+            logger.error(`Error calling Grocy API endpoint ${endpoint}`, 'api', { error });
+            return this.createError(`Failed to call Grocy API endpoint ${endpoint}: ${error.message}`);
+        }
+    };
+    testRequest = async (args) => {
+        const { method, endpoint, body, headers = {} } = args;
+        if (!method || !endpoint) {
+            throw new McpError(ErrorCode.InvalidParams, 'method and endpoint are required');
+        }
+        const normalizedEndpoint = `/${endpoint.replace(/^\/+|\/+$/g, '')}`;
+        const requestHeaders = { ...config.getCustomHeaders(), ...headers };
+        const safeRequestHeaders = this.redactHeaders(requestHeaders);
+        try {
+            const startTime = Date.now();
+            const response = await apiClient.request(normalizedEndpoint, {
+                method,
+                body,
+                headers: requestHeaders,
+            });
+            const endTime = Date.now();
+            const responseWithLimit = this.applyResponseSizeLimit(response.data);
+            const responseObj = {
+                request: {
+                    url: `${config.grocy.base_url}${normalizedEndpoint}`,
+                    method,
+                    headers: safeRequestHeaders,
+                    body,
+                    authMethod: config.grocy.api_key ? 'apikey' : 'none',
+                },
+                response: {
+                    statusCode: response.status,
+                    timing: `${endTime - startTime}ms`,
+                    headers: response.headers,
+                    body: responseWithLimit.body,
+                },
+                validation: {
+                    isError: response.status >= 400,
+                    messages: response.status >= 400
+                        ? [`Request failed with status ${response.status}`]
+                        : ['Request completed successfully'],
+                    ...(responseWithLimit.truncated ? { truncated: responseWithLimit.truncated } : {}),
+                },
+            };
+            return this.createSuccess(responseObj);
+        }
+        catch (error) {
+            return this.createError(`Test request failed: ${error.message}`, {
+                request: {
+                    url: `${config.grocy.base_url}${normalizedEndpoint}`,
+                    method,
+                    headers: safeRequestHeaders,
+                    body,
+                },
+            });
+        }
+    };
+}

package/build/tools/system/index.js

@@ -0,0 +1,16 @@
+import { systemToolDefinitions } from './definitions.js';
+import { SystemToolHandlers } from './handlers.js';
+const handlers = new SystemToolHandlers();
+export const systemModule = {
+    definitions: systemToolDefinitions,
+    handlers: {
+        // Core System Utilities
+        system_locations_get: handlers.getLocations,
+        system_units_get: handlers.getQuantityUnits,
+        system_users_get: handlers.getUsers,
+        // Developer Utilities
+        system_dev_call_api: handlers.callGrocyApi,
+        system_dev_test_request: handlers.testRequest,
+    },
+};
+export * from './definitions.js';

package/build/tools/types.js

@@ -0,0 +1 @@
+export {};

package/build/tools/validation-helpers.js

@@ -0,0 +1,39 @@
+/**
+ * Common validation utility functions
+ */
+import { ValidationError } from '../utils/errors.js';
+export class ValidationHelpers {
+    static validateBoolean(value, fieldName) {
+        if (value !== undefined && typeof value !== 'boolean') {
+            throw new ValidationError(`${fieldName} must be a boolean`, 'sub-config validation');
+        }
+    }
+    static validateString(value, fieldName) {
+        if (value !== undefined && typeof value !== 'string') {
+            throw new ValidationError(`${fieldName} must be a string`, 'sub-config validation');
+        }
+    }
+    static validateNumber(value, fieldName, options) {
+        if (value !== undefined) {
+            if (typeof value !== 'number') {
+                throw new ValidationError(`${fieldName} must be a number`, 'sub-config validation');
+            }
+            if (options?.min !== undefined && value < options.min) {
+                throw new ValidationError(`${fieldName} must be at least ${options.min}`, 'sub-config validation');
+            }
+            if (options?.max !== undefined && value > options.max) {
+                throw new ValidationError(`${fieldName} must be at most ${options.max}`, 'sub-config validation');
+            }
+        }
+    }
+    static validateKnownOptions(subConfigs, knownOptions, toolName) {
+        for (const [key] of subConfigs) {
+            if (!knownOptions.has(key)) {
+                const validOptions = Array.from(knownOptions)
+                    .filter((k) => k !== 'ack_token')
+                    .join(', ');
+                throw new ValidationError(`Unknown sub-configuration option '${key}' for ${toolName} tool. Valid options are: ${validOptions}`, 'sub-config validation');
+            }
+        }
+    }
+}