mcp-grocy 2.2.0 → 2.5.0

package/build/tools/shopping/definitions.js

@@ -2,11 +2,12 @@ export const shoppingToolDefinitions = [
     {
         name: 'shopping_list_get',
         description: '[SHOPPING/LIST] Get your current shopping list items.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     },
     {
         name: 'shopping_list_add_item',
@@ -16,25 +17,25 @@ export const shoppingToolDefinitions = [
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to add. Use inventory_products_get tool to find the correct product ID by searching for the product name in the results.'
+                    description: 'ID of the product to add. Use inventory_products_get tool to find the correct product ID by searching for the product name in the results.',
                 },
                 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: 1',
-                    default: 1
+                    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: 1",
+                    default: 1,
                 },
                 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
+                    default: 1,
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for the shopping list item'
-                }
+                    description: 'Optional note for the shopping list item',
+                },
             },
-            required: ['productId']
-        }
+            required: ['productId'],
+        },
     },
     {
         name: 'shopping_list_remove_item',
@@ -44,20 +45,21 @@ export const shoppingToolDefinitions = [
             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.'
-                }
+                    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']
-        }
+            required: ['shoppingListItemId'],
+        },
     },
     {
         name: 'shopping_locations_get',
-        description: '[SHOPPING/LOCATIONS] Get all shopping locations (stores) from your Grocy instance. Use this to find store IDs and names when working with tools that require storeId parameters.',
+        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: []
-        }
+            required: [],
+        },
     },
     {
         name: 'shopping_list_print_thermal',
@@ -65,7 +67,7 @@ export const shoppingToolDefinitions = [
         inputSchema: {
             type: 'object',
             properties: {},
-            required: []
-        }
-    }
+            required: [],
+        },
+    },
 ];

package/build/tools/shopping/handlers.js

@@ -14,7 +14,7 @@ export class ShoppingToolHandlers extends BaseToolHandler {
                 product_id: productId,
                 amount,
                 shopping_list_id: shoppingListId,
-                note
+                note,
             };
             const result = await this.apiCall('/objects/shopping_list', 'POST', body);
             return this.createSuccess(result, 'Shopping list item added successfully');

package/build/tools/shopping/index.js

@@ -8,7 +8,7 @@ export const shoppingModule = {
         shopping_list_add_item: handlers.addShoppingListItem,
         shopping_list_remove_item: handlers.removeShoppingListItem,
         shopping_locations_get: handlers.getShoppingLocations,
-        shopping_list_print_thermal: handlers.printShoppingListThermal
-    }
+        shopping_list_print_thermal: handlers.printShoppingListThermal,
+    },
 };
 export * from './definitions.js';

package/build/tools/system/definitions.js

@@ -3,30 +3,33 @@ export const systemToolDefinitions = [
     // ==================== CORE SYSTEM UTILITIES ====================
     {
         name: 'system_locations_get',
-        description: '[SYSTEM/LOCATIONS] Get all storage locations from your Grocy instance. Use this to find location IDs and names when working with other tools that require locationId parameters.',
+        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: []
-        }
+            required: [],
+        },
     },
     {
         name: 'system_units_get',
         description: '[SYSTEM/UNITS] Get all quantity units from your Grocy instance.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     },
     {
         name: 'system_users_get',
         description: '[SYSTEM/USERS] Get all users from your Grocy instance.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     },
     // ==================== DEVELOPER UTILITIES ====================
     {
@@ -37,21 +40,21 @@ export const systemToolDefinitions = [
             properties: {
                 endpoint: {
                     type: 'string',
-                    description: 'Grocy API endpoint to call (e.g., "objects/products"). Do not include /api/ prefix.'
+                    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'
+                    default: 'GET',
                 },
                 body: {
                     type: 'object',
-                    description: 'Optional request body for POST/PUT requests'
-                }
+                    description: 'Optional request body for POST/PUT requests',
+                },
             },
-            required: ['endpoint']
-        }
+            required: ['endpoint'],
+        },
     },
     {
         name: 'system_dev_test_request',
@@ -62,25 +65,25 @@ export const systemToolDefinitions = [
                 method: {
                     type: 'string',
                     enum: ['GET', 'POST', 'PUT', 'DELETE'],
-                    description: 'HTTP method to use'
+                    description: 'HTTP method to use',
                 },
                 endpoint: {
                     type: 'string',
-                    description: 'Endpoint path (e.g. "/users"). Do not include full URLs - only the path.'
+                    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'
+                    description: 'Optional request body for POST/PUT requests',
                 },
                 headers: {
                     type: 'object',
                     description: 'Optional request headers for one-time use.',
                     additionalProperties: {
-                        type: 'string'
-                    }
-                }
+                        type: 'string',
+                    },
+                },
             },
-            required: ['method', 'endpoint']
-        }
-    }
+            required: ['method', 'endpoint'],
+        },
+    },
 ];

package/build/tools/system/handlers.js

@@ -4,6 +4,64 @@ 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 () => {
@@ -34,7 +92,7 @@ export class SystemToolHandlers extends BaseToolHandler {
         try {
             const response = await apiClient.request(`/${cleanEndpoint}`, {
                 method,
-                body
+                body,
             });
             return this.createSuccess(response.data);
         }
@@ -49,34 +107,38 @@ export class SystemToolHandlers extends BaseToolHandler {
             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: { ...config.getCustomHeaders(), ...headers }
+                headers: requestHeaders,
             });
             const endTime = Date.now();
+            const responseWithLimit = this.applyResponseSizeLimit(response.data);
             const responseObj = {
                 request: {
                     url: `${config.grocy.base_url}${normalizedEndpoint}`,
                     method,
-                    headers: { ...config.getCustomHeaders(), ...headers },
+                    headers: safeRequestHeaders,
                     body,
-                    authMethod: config.grocy.api_key ? 'apikey' : 'none'
+                    authMethod: config.grocy.api_key ? 'apikey' : 'none',
                 },
                 response: {
                     statusCode: response.status,
                     timing: `${endTime - startTime}ms`,
                     headers: response.headers,
-                    body: response.data
+                    body: responseWithLimit.body,
                 },
                 validation: {
                     isError: response.status >= 400,
-                    messages: response.status >= 400 ?
-                        [`Request failed with status ${response.status}`] :
-                        ['Request completed successfully']
-                }
+                    messages: response.status >= 400
+                        ? [`Request failed with status ${response.status}`]
+                        : ['Request completed successfully'],
+                    ...(responseWithLimit.truncated ? { truncated: responseWithLimit.truncated } : {}),
+                },
             };
             return this.createSuccess(responseObj);
         }
@@ -85,9 +147,9 @@ export class SystemToolHandlers extends BaseToolHandler {
                 request: {
                     url: `${config.grocy.base_url}${normalizedEndpoint}`,
                     method,
-                    headers: { ...config.getCustomHeaders(), ...headers },
-                    body
-                }
+                    headers: safeRequestHeaders,
+                    body,
+                },
             });
         }
     };

package/build/tools/system/index.js

@@ -10,7 +10,7 @@ export const systemModule = {
         system_users_get: handlers.getUsers,
         // Developer Utilities
         system_dev_call_api: handlers.callGrocyApi,
-        system_dev_test_request: handlers.testRequest
-    }
+        system_dev_test_request: handlers.testRequest,
+    },
 };
 export * from './definitions.js';

package/build/tools/validation-helpers.js

@@ -1,35 +1,38 @@
 /**
  * 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 Error(`${fieldName} must be a boolean`);
+            throw new ValidationError(`${fieldName} must be a boolean`, 'sub-config validation');
         }
     }
     static validateString(value, fieldName) {
         if (value !== undefined && typeof value !== 'string') {
-            throw new Error(`${fieldName} must be a 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 Error(`${fieldName} must be a number`);
+                throw new ValidationError(`${fieldName} must be a number`, 'sub-config validation');
             }
             if (options?.min !== undefined && value < options.min) {
-                throw new Error(`${fieldName} must be at least ${options.min}`);
+                throw new ValidationError(`${fieldName} must be at least ${options.min}`, 'sub-config validation');
             }
             if (options?.max !== undefined && value > options.max) {
-                throw new Error(`${fieldName} must be at most ${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 Error(`Unknown sub-configuration option '${key}' for ${toolName} tool. Valid options are: ${validOptions}`);
+                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');
             }
         }
     }

package/build/types/index.js

@@ -19,11 +19,13 @@ export const ConfigSchema = z.object({
             enable_ssl_verify: z.boolean().default(true),
             response_size_limit: z.number().positive().default(10000),
         }),
-        tools: z.record(z.string(), z.object({
+        tools: z.record(z.string(), z
+            .object({
             enabled: z.boolean().default(false),
             ack_token: z.string().optional(),
-        }).catchall(z.unknown())),
-    })
+        })
+            .catchall(z.unknown())),
+    }),
 });
 // Validation schemas for runtime type checking
 export const ToolResultSchema = z.object({
@@ -31,20 +33,20 @@ export const ToolResultSchema = z.object({
     data: z.any().optional(),
     error: z.string().optional(),
     message: z.string().optional(),
-    details: z.any().optional()
+    details: z.any().optional(),
 });
 export const ToolDefinitionSchema = z.object({
     name: z.string(),
     description: z.string(),
     inputSchema: z.object({
         type: z.literal('object'),
-        properties: z.record(z.any()),
-        required: z.array(z.string()).optional()
-    })
+        properties: z.record(z.string(), z.any()),
+        required: z.array(z.string()).optional(),
+    }),
 });
 export const ToolModuleSchema = z.object({
     definitions: z.array(ToolDefinitionSchema),
-    handlers: z.record(z.function())
+    handlers: z.record(z.string(), z.custom((v) => typeof v === 'function')),
 });
 // Type guards
 export function isToolResult(obj) {
@@ -54,9 +56,9 @@ export function isToolDefinition(obj) {
     return ToolDefinitionSchema.safeParse(obj).success;
 }
 export function isToolModule(obj) {
-    return obj &&
+    return (obj &&
         typeof obj === 'object' &&
         Array.isArray(obj.definitions) &&
         typeof obj.handlers === 'object' &&
-        obj.definitions.every((def) => isToolDefinition(def));
+        obj.definitions.every((def) => isToolDefinition(def)));
 }

package/build/utils/errors.js

@@ -27,15 +27,18 @@ export class AppError extends Error {
     }
     getErrorCode() {
         switch (this.category) {
-            case 'VALIDATION': return ErrorCode.InvalidParams;
-            case 'AUTH': return ErrorCode.InvalidRequest;
+            case 'VALIDATION':
+                return ErrorCode.InvalidParams;
+            case 'AUTH':
+                return ErrorCode.InvalidRequest;
             case 'API':
                 if (this.statusCode === 404)
                     return ErrorCode.InvalidRequest;
                 if (this.statusCode === 401 || this.statusCode === 403)
                     return ErrorCode.InvalidRequest;
                 return ErrorCode.InternalError;
-            default: return ErrorCode.InternalError;
+            default:
+                return ErrorCode.InternalError;
         }
     }
 }
@@ -52,7 +55,9 @@ export class ApiError extends AppError {
             return new ApiError(error.response.data?.message || `HTTP ${error.response.status}`, error.response.status, operation, { url: error.config?.url, method: error.config?.method });
         }
         if (error.request) {
-            return new ApiError('Network error - unable to reach server', undefined, operation, { url: error.config?.url });
+            return new ApiError('Network error - unable to reach server', undefined, operation, {
+                url: error.config?.url,
+            });
         }
         return new ApiError(error.message || 'Request error', undefined, operation);
     }
@@ -102,7 +107,7 @@ export class ErrorHandler {
                 category: error.category,
                 statusCode: error.statusCode,
                 operation: error.operation,
-                details: error.details
+                details: error.details,
             });
         }
         else {

package/build/utils/logger.js

@@ -19,7 +19,7 @@ export class Logger {
         // Allow filtering by categories
         const categories = process.env.LOG_CATEGORIES;
         if (categories) {
-            this.enabledCategories = new Set(categories.split(',').map(c => c.trim().toUpperCase()));
+            this.enabledCategories = new Set(categories.split(',').map((c) => c.trim().toUpperCase()));
         }
     }
     static getInstance() {
@@ -31,12 +31,18 @@ export class Logger {
     parseLogLevel(level) {
         const upperLevel = level.toUpperCase();
         switch (upperLevel) {
-            case 'ERROR': return LogLevel.ERROR;
-            case 'WARN': return LogLevel.WARN;
-            case 'INFO': return LogLevel.INFO;
-            case 'DEBUG': return LogLevel.DEBUG;
-            case 'TRACE': return LogLevel.TRACE;
-            default: return LogLevel.INFO;
+            case 'ERROR':
+                return LogLevel.ERROR;
+            case 'WARN':
+                return LogLevel.WARN;
+            case 'INFO':
+                return LogLevel.INFO;
+            case 'DEBUG':
+                return LogLevel.DEBUG;
+            case 'TRACE':
+                return LogLevel.TRACE;
+            default:
+                return LogLevel.INFO;
         }
     }
     shouldLog(level, category) {
@@ -66,16 +72,11 @@ export class Logger {
             message,
             category: category || undefined,
             data,
-            timestamp: new Date()
+            timestamp: new Date(),
         };
         const formattedMessage = this.formatMessage(entry);
         // Use stderr for all logs to avoid interfering with MCP stdio protocol
-        if (level <= LogLevel.ERROR) {
-            console.error(formattedMessage);
-        }
-        else {
-            console.error(formattedMessage);
-        }
+        console.error(formattedMessage);
     }
     error(message, category, data) {
         this.log(LogLevel.ERROR, message, category, data);
@@ -113,7 +114,7 @@ export class Logger {
         this.logLevel = level;
     }
     setEnabledCategories(categories) {
-        this.enabledCategories = categories ? new Set(categories.map(c => c.toUpperCase())) : null;
+        this.enabledCategories = categories ? new Set(categories.map((c) => c.toUpperCase())) : null;
     }
 }
 // Export singleton instance

package/build/version.js

@@ -1,4 +1,4 @@
 // Auto-generated file - DO NOT MODIFY
-export const VERSION = '2.2.0';
+export const VERSION = '2.5.0';
 export const PACKAGE_NAME = 'mcp-grocy';
-export const SERVER_NAME = 'grocy-api';
+export const SERVER_NAME = 'mcp-grocy';