mcp-grocy 2.2.0 → 2.5.0

package/build/tools/inventory/definitions.js

@@ -3,6 +3,7 @@ export const inventoryToolDefinitions = [
     {
         name: 'inventory_products_get',
         description: '[INVENTORY/PRODUCTS] Get specific fields for all products from your Grocy instance. You must specify which fields to retrieve.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {
@@ -10,184 +11,219 @@ export const inventoryToolDefinitions = [
                     type: 'array',
                     items: {
                         type: 'string',
-                        enum: ['id', 'name', 'description', 'product_group_id', 'active', 'location_id', 'shopping_location_id', 'qu_id_purchase', 'qu_id_stock', 'qu_factor_purchase_to_stock', 'min_stock_amount', 'default_best_before_days', 'default_best_before_days_after_open', 'default_best_before_days_after_freezing', 'default_best_before_days_after_thawing', 'picture_file_name', 'allow_label_per_unit', 'energy_per_stock_unit', 'calories_per_stock_unit', 'default_stock_label_type', 'should_not_be_frozen', 'treat_opened_as_out_of_stock', 'no_own_stock', 'cumulate_min_stock_amount_of_sub_products', 'parent_product_id', 'calories_per_unit_factor', 'quick_consume_amount', 'hide_on_stock_overview']
+                        enum: [
+                            'id',
+                            'name',
+                            'description',
+                            'product_group_id',
+                            'active',
+                            'location_id',
+                            'shopping_location_id',
+                            'qu_id_purchase',
+                            'qu_id_stock',
+                            'qu_factor_purchase_to_stock',
+                            'min_stock_amount',
+                            'default_best_before_days',
+                            'default_best_before_days_after_open',
+                            'default_best_before_days_after_freezing',
+                            'default_best_before_days_after_thawing',
+                            'picture_file_name',
+                            'allow_label_per_unit',
+                            'energy_per_stock_unit',
+                            'calories_per_stock_unit',
+                            'default_stock_label_type',
+                            'should_not_be_frozen',
+                            'treat_opened_as_out_of_stock',
+                            'no_own_stock',
+                            'cumulate_min_stock_amount_of_sub_products',
+                            'parent_product_id',
+                            'calories_per_unit_factor',
+                            'quick_consume_amount',
+                            'hide_on_stock_overview',
+                        ],
                     },
-                    description: 'Array of field names to retrieve. For basic lookup use ["id", "name"]. For detailed info include ["id", "name", "description", "active"]. Available fields: id, name, description, product_group_id, active, location_id, shopping_location_id, qu_id_purchase, qu_id_stock, qu_factor_purchase_to_stock, min_stock_amount, default_best_before_days, default_best_before_days_after_open, default_best_before_days_after_freezing, default_best_before_days_after_thawing, picture_file_name, allow_label_per_unit, energy_per_stock_unit, calories_per_stock_unit, default_stock_label_type, should_not_be_frozen, treat_opened_as_out_of_stock, no_own_stock, cumulate_min_stock_amount_of_sub_products, parent_product_id, calories_per_unit_factor, quick_consume_amount, hide_on_stock_overview'
-                }
+                    description: 'Array of field names to retrieve. For basic lookup use ["id", "name"]. For detailed info include ["id", "name", "description", "active"]. Available fields: id, name, description, product_group_id, active, location_id, shopping_location_id, qu_id_purchase, qu_id_stock, qu_factor_purchase_to_stock, min_stock_amount, default_best_before_days, default_best_before_days_after_open, default_best_before_days_after_freezing, default_best_before_days_after_thawing, picture_file_name, allow_label_per_unit, energy_per_stock_unit, calories_per_stock_unit, default_stock_label_type, should_not_be_frozen, treat_opened_as_out_of_stock, no_own_stock, cumulate_min_stock_amount_of_sub_products, parent_product_id, calories_per_unit_factor, quick_consume_amount, hide_on_stock_overview',
+                },
             },
-            required: ['fields']
-        }
+            required: ['fields'],
+        },
     },
     {
         name: 'inventory_products_get_groups',
-        description: '[INVENTORY/PRODUCTS] Get all product groups from your Grocy instance.',
+        description: '[INVENTORY/PRODUCTS] **Categories only:** list product groups (taxonomy), not individual products. For product rows with fields use inventory_products_get.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     },
     {
         name: 'inventory_products_get_price_history',
         description: '[INVENTORY/PRODUCTS] Get the price history of a product from your Grocy instance.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to get price history for. Use get_products tool to find the correct product ID by name.'
-                }
+                    description: 'ID of the product to get price history for. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
+                },
             },
-            required: ['productId']
-        }
+            required: ['productId'],
+        },
     },
     // Stock Management Tools
     {
         name: 'inventory_stock_get_all',
-        description: '[INVENTORY/STOCK] Get all stock entries from every location in your Grocy instance. This returns the complete stock database with detailed information including stock entry IDs.',
+        description: '[INVENTORY/STOCK] **Full stock dump**—every stock entry in the home with stockIds. Prefer inventory_stock_get_by_product when the user names one product; prefer inventory_stock_get_by_location when they name one storage place.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     },
     {
         name: 'inventory_stock_get_by_product',
-        description: '[INVENTORY/STOCK] Get stock entries for a specific product in your Grocy instance with filtered essential information.',
+        description: '[INVENTORY/STOCK] Stock rows for **one product** across locations (needs productId). Use when the user asks how much of a product is on hand or needs stockId for that product—not for everything in a cupboard (use inventory_stock_get_by_location).',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to get stock entries for. Use get_products tool to find the correct product ID by name.'
-                }
+                    description: 'ID of the product to get stock entries for. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
+                },
             },
-            required: ['productId']
-        }
+            required: ['productId'],
+        },
     },
     {
         name: 'inventory_stock_get_volatile',
         description: '[INVENTORY/STOCK] Get volatile stock information (due products, overdue products, expired products, missing products).',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {
                 includeDetails: {
                     type: 'boolean',
-                    description: 'Whether to include additional details about each stock item'
-                }
+                    description: 'Whether to include additional details about each stock item',
+                },
             },
-            required: []
-        }
+            required: [],
+        },
     },
     {
         name: 'inventory_stock_get_by_location',
-        description: '[INVENTORY/STOCK] Get stock entries from a specific location in your Grocy instance.',
+        description: '[INVENTORY/STOCK] Everything stocked in **one storage location** (needs locationId from system_locations_get). Use when the user asks what is in the freezer/pantry—not for one named product across sites (use inventory_stock_get_by_product).',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {
                 locationId: {
                     type: 'number',
-                    description: 'ID of the location to get stock for.'
-                }
+                    description: 'ID of the location to get stock for.',
+                },
             },
-            required: ['locationId']
-        }
+            required: ['locationId'],
+        },
     },
     // Stock Transaction Tools
     {
         name: 'inventory_transactions_purchase',
-        description: '[INVENTORY/TRANSACTIONS] Add a product to stock (purchase/add inventory). Use inventory_products_get to find the product ID and system_locations_get to find location IDs.',
+        description: '[INVENTORY/TRANSACTIONS] **Product-level purchase:** add quantity by productId (creates/merges stock). No stockId. Use inventory_products_get and system_locations_get for IDs.',
         inputSchema: {
             type: 'object',
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to purchase. Use get_products tool to find the correct product ID by name.'
+                    description: 'ID of the product to purchase. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to purchase 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.'
+                    description: "Amount to purchase 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.",
                 },
                 bestBeforeDate: {
                     type: 'string',
-                    description: 'Best before date in YYYY-MM-DD format. If not provided, will use product\'s default best before days.'
+                    description: "Best before date in YYYY-MM-DD format. If not provided, will use product's default best before days.",
                 },
                 price: {
                     type: 'number',
-                    description: 'Price per stock unit (optional)'
+                    description: 'Price per stock unit (optional)',
                 },
                 locationId: {
                     type: 'number',
-                    description: 'Location ID where the product should be stored. Use get_locations tool to find the correct location ID. If not provided, uses product\'s default location.'
+                    description: "Location ID where the product should be stored. Use system_locations_get to find the location ID. If not provided, uses product's default location.",
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for the stock entry'
-                }
+                    description: 'Optional note for the stock entry',
+                },
             },
-            required: ['productId', 'amount']
-        }
+            required: ['productId', 'amount'],
+        },
     },
     {
         name: 'inventory_transactions_consume',
-        description: '[INVENTORY/TRANSACTIONS] Remove a product from stock (consume/use inventory). For more granular control over specific stock entries, prefer inventory_stock_entry_consume. Use inventory_products_get to find the product ID.',
+        description: '[INVENTORY/TRANSACTIONS] **Product-level consume:** reduce stock by productId+amount (Grocy picks lots). If the user refers to a specific package/stock row, use inventory_stock_entry_consume (stockId). Use inventory_products_get for productId.',
         inputSchema: {
             type: 'object',
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to consume. Use get_products tool to find the correct product ID by name.'
+                    description: 'ID of the product to consume. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to consume 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.'
+                    description: "Amount to consume 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.",
                 },
                 spoiled: {
                     type: 'boolean',
                     description: 'Whether the product was spoiled/wasted (default: false)',
-                    default: false
+                    default: false,
                 },
                 locationId: {
                     type: 'number',
-                    description: 'Location ID to consume from (optional). Use get_locations tool to find the correct location ID.'
+                    description: 'Location ID to consume from (optional). Use system_locations_get to find the location ID.',
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for the consumption'
-                }
+                    description: 'Optional note for the consumption',
+                },
             },
-            required: ['productId', 'amount']
-        }
+            required: ['productId', 'amount'],
+        },
     },
     {
         name: 'inventory_transactions_transfer',
-        description: '[INVENTORY/TRANSACTIONS] Transfer a product between locations. For more granular control over specific stock entries, prefer inventory_stock_entry_transfer. Use inventory_products_get to find the product ID and system_locations_get to find location IDs.',
+        description: '[INVENTORY/TRANSACTIONS] **Product-level transfer:** move amount of a product between locations without choosing a stock row. For one specific lot, use inventory_stock_entry_transfer (stockId). Use inventory_products_get and system_locations_get.',
         inputSchema: {
             type: 'object',
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to transfer. Use get_products tool to find the correct product ID by name.'
+                    description: 'ID of the product to transfer. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to transfer 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.'
+                    description: "Amount to transfer 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.",
                 },
                 fromLocationId: {
                     type: 'number',
-                    description: 'Source location ID. Use get_locations tool to find the correct location ID.'
+                    description: 'Source location ID. Use system_locations_get to find the location ID.',
                 },
                 toLocationId: {
                     type: 'number',
-                    description: 'Destination location ID. Use get_locations tool to find the correct location ID.'
+                    description: 'Destination location ID. Use system_locations_get to find the location ID.',
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for the transfer'
-                }
+                    description: 'Optional note for the transfer',
+                },
             },
-            required: ['productId', 'amount', 'fromLocationId', 'toLocationId']
-        }
+            required: ['productId', 'amount', 'fromLocationId', 'toLocationId'],
+        },
     },
     {
         name: 'inventory_transactions_adjust',
@@ -197,64 +233,65 @@ export const inventoryToolDefinitions = [
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to inventory. Use get_products tool to find the correct product ID by name.'
+                    description: 'ID of the product to inventory. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
                 },
                 newAmount: {
                     type: 'number',
-                    description: 'The new/correct total amount of stock for this product in the product\'s stock unit.'
+                    description: "The new/correct total amount of stock for this product in the product's stock unit.",
                 },
                 bestBeforeDate: {
                     type: 'string',
-                    description: 'Best before date in YYYY-MM-DD format for the inventory correction.'
+                    description: 'Best before date in YYYY-MM-DD format for the inventory correction.',
                 },
                 locationId: {
                     type: 'number',
-                    description: 'Location ID for the inventory (optional). Use get_locations tool to find the correct location ID.'
+                    description: 'Location ID for the inventory (optional). Use system_locations_get to find the location ID.',
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for the inventory correction'
-                }
+                    description: 'Optional note for the inventory correction',
+                },
             },
-            required: ['productId', 'newAmount']
-        }
+            required: ['productId', 'newAmount'],
+        },
     },
     {
         name: 'inventory_transactions_open',
-        description: '[INVENTORY/TRANSACTIONS] Mark a product as opened/started. For more granular control over specific stock entries, prefer inventory_stock_entry_open. Use inventory_products_get to find the product ID.',
+        description: '[INVENTORY/TRANSACTIONS] **Product-level open:** mark opened/started without a stock row. For one specific package use inventory_stock_entry_open (stockId). Use inventory_products_get for productId.',
         inputSchema: {
             type: 'object',
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to open. Use get_products tool to find the correct product ID by name.'
+                    description: 'ID of the product to open. Use inventory_products_lookup to find the product ID by name (or inventory_products_get with fields if listing products).',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to mark as opened in the product\'s stock unit (e.g., 1 piece, 0.5 kg). Default: 1',
-                    default: 1
+                    description: "Amount to mark as opened in the product's stock unit (e.g., 1 piece, 0.5 kg). Default: 1",
+                    default: 1,
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for opening the product'
-                }
+                    description: 'Optional note for opening the product',
+                },
             },
-            required: ['productId']
-        }
+            required: ['productId'],
+        },
     },
     {
         name: 'inventory_products_lookup',
         description: '[INVENTORY/PRODUCTS] Search for products by name using fuzzy matching. Returns up to 5 best matches with stock information and location details.',
+        annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
             properties: {
                 productName: {
                     type: 'string',
-                    description: 'Product name to search for. Uses fuzzy matching to find similar products.'
-                }
+                    description: 'Product name to search for. Uses fuzzy matching to find similar products.',
+                },
             },
-            required: ['productName']
-        }
+            required: ['productName'],
+        },
     },
     {
         name: 'inventory_products_print_label',
@@ -264,11 +301,11 @@ export const inventoryToolDefinitions = [
             properties: {
                 productId: {
                     type: 'number',
-                    description: 'ID of the product to print label for. Use inventory_products_get tool to find the correct product ID.'
-                }
+                    description: 'ID of the product to print label for. Use inventory_products_get tool to find the correct product ID.',
+                },
             },
-            required: ['productId']
-        }
+            required: ['productId'],
+        },
     },
     {
         name: 'inventory_stock_entry_print_label',
@@ -278,102 +315,102 @@ export const inventoryToolDefinitions = [
             properties: {
                 stockId: {
                     type: 'number',
-                    description: 'ID of the stock entry to print label for. Use get_stock_by_product tool to find specific stockId values.'
+                    description: 'ID of the stock entry to print label for. Use inventory_stock_get_by_product to find stockId values.',
                 },
                 productId: {
                     type: 'number',
-                    description: 'ID of the product that the stock entry belongs to. This is required for validation.'
-                }
+                    description: 'ID of the product that the stock entry belongs to. This is required for validation.',
+                },
             },
-            required: ['stockId', 'productId']
-        }
+            required: ['stockId', 'productId'],
+        },
     },
     // ==================== GRANULAR STOCK ENTRY OPERATIONS ====================
     {
         name: 'inventory_stock_entry_consume',
-        description: '[INVENTORY/STOCK] Consume from a specific stock entry. Use inventory_stock_get_by_product to find specific stockId values.',
+        description: '[INVENTORY/STOCK] **Specific stock row (stockId):** consume from one lot. If the user only names a product/amount without a particular package, use inventory_transactions_consume instead. Find stockId via inventory_stock_get_by_product.',
         inputSchema: {
             type: 'object',
             properties: {
                 stockId: {
                     type: 'number',
-                    description: 'ID of the specific stock entry to consume from.'
+                    description: 'ID of the specific stock entry to consume from.',
                 },
                 productId: {
                     type: 'number',
-                    description: 'ID of the product being consumed. This is required for verification - if you know the stockId, you must know the productId.'
+                    description: 'ID of the product being consumed. This is required for verification - if you know the stockId, you must know the productId.',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to consume in the product\'s stock unit (e.g., 1 piece, 0.5 kg, 250 ml). Ensure you know the product\'s stock unit before specifying amount.'
+                    description: "Amount to consume in the product's stock unit (e.g., 1 piece, 0.5 kg, 250 ml). Ensure you know the product's stock unit before specifying amount.",
                 },
                 spoiled: {
                     type: 'boolean',
                     description: 'Whether the product is spoiled (default: false)',
-                    default: false
+                    default: false,
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note'
-                }
+                    description: 'Optional note',
+                },
             },
-            required: ['stockId', 'productId', 'amount']
-        }
+            required: ['stockId', 'productId', 'amount'],
+        },
     },
     {
         name: 'inventory_stock_entry_transfer',
-        description: '[INVENTORY/STOCK] Transfer a specific stock entry to another location. Use inventory_stock_get_by_product to find specific stockId values.',
+        description: '[INVENTORY/STOCK] **Specific stock row (stockId):** move one lot to another location. For moving an amount of a product without picking a row, use inventory_transactions_transfer. Find stockId via inventory_stock_get_by_product.',
         inputSchema: {
             type: 'object',
             properties: {
                 stockId: {
                     type: 'number',
-                    description: 'ID of the specific stock entry to transfer.'
+                    description: 'ID of the specific stock entry to transfer.',
                 },
                 productId: {
                     type: 'number',
-                    description: 'ID of the product being transferred. This is required for verification - if you know the stockId, you must know the productId.'
+                    description: 'ID of the product being transferred. This is required for verification - if you know the stockId, you must know the productId.',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to transfer in the product\'s stock unit (e.g., 1 piece, 0.5 kg, 250 ml). Ensure you know the product\'s stock unit before specifying amount.'
+                    description: "Amount to transfer in the product's stock unit (e.g., 1 piece, 0.5 kg, 250 ml). Ensure you know the product's stock unit before specifying amount.",
                 },
                 locationIdTo: {
                     type: 'number',
-                    description: 'ID of the destination location.'
+                    description: 'ID of the destination location.',
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note for this transfer'
-                }
+                    description: 'Optional note for this transfer',
+                },
             },
-            required: ['stockId', 'productId', 'amount', 'locationIdTo']
-        }
+            required: ['stockId', 'productId', 'amount', 'locationIdTo'],
+        },
     },
     {
         name: 'inventory_stock_entry_open',
-        description: '[INVENTORY/STOCK] Mark a specific stock entry as opened. Use inventory_stock_get_by_product to find specific stockId values.',
+        description: '[INVENTORY/STOCK] **Specific stock row (stockId):** mark one opened package. For product-level open without a row, use inventory_transactions_open. Find stockId via inventory_stock_get_by_product.',
         inputSchema: {
             type: 'object',
             properties: {
                 stockId: {
                     type: 'number',
-                    description: 'ID of the specific stock entry to mark as opened.'
+                    description: 'ID of the specific stock entry to mark as opened.',
                 },
                 productId: {
                     type: 'number',
-                    description: 'ID of the product being opened. This is required for verification - if you know the stockId, you must know the productId.'
+                    description: 'ID of the product being opened. This is required for verification - if you know the stockId, you must know the productId.',
                 },
                 amount: {
                     type: 'number',
-                    description: 'Amount to mark as opened in the product\'s stock unit (e.g., 1 piece, 0.5 kg, 200 ml). Ensure you know the product\'s stock unit before specifying amount.'
+                    description: "Amount to mark as opened in the product's stock unit (e.g., 1 piece, 0.5 kg, 200 ml). Ensure you know the product's stock unit before specifying amount.",
                 },
                 note: {
                     type: 'string',
-                    description: 'Optional note'
-                }
+                    description: 'Optional note',
+                },
             },
-            required: ['stockId', 'productId', 'amount']
-        }
-    }
+            required: ['stockId', 'productId', 'amount'],
+        },
+    },
 ];