mcp-grocy 1.9.0

package/build/tools/stock/definitions.js

@@ -0,0 +1,234 @@
+export const stockToolDefinitions = [
+    {
+        name: 'get_all_stock',
+        description: 'Get all stock entries from every location in your Grocy instance. This returns the complete stock database with detailed information including stock entry IDs.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: 'get_stock_volatile',
+        description: 'Get volatile stock information (due products, overdue products, expired products, missing products).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                includeDetails: {
+                    type: 'boolean',
+                    description: 'Whether to include additional details about each stock item'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_stock_by_location',
+        description: 'Get stock entries from a specific location in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                locationId: {
+                    type: 'number',
+                    description: 'ID of the location to get stock for.'
+                }
+            },
+            required: ['locationId']
+        }
+    },
+    {
+        name: 'inventory_product',
+        description: 'Track a product inventory (set current stock amount). Use get_products to find the product ID and get_locations to find location IDs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                productId: {
+                    type: 'number',
+                    description: 'ID of the product to inventory. Use get_products tool to find the correct product ID by name.'
+                },
+                newAmount: {
+                    type: 'number',
+                    description: 'The new total amount in stock in the product\'s stock unit (e.g., 5 pieces, 2.5 kg, 1000 ml). Ensure you know the product\'s stock unit before specifying amount.'
+                },
+                bestBeforeDate: {
+                    type: 'string',
+                    description: 'Best before date in YYYY-MM-DD format (default: today + 1 year)'
+                },
+                locationId: {
+                    type: 'number',
+                    description: 'ID of the storage location. Use get_locations tool to find available location IDs and names.'
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note'
+                }
+            },
+            required: ['productId', 'newAmount', 'locationId']
+        }
+    },
+    {
+        name: 'purchase_product',
+        description: 'Track a product purchase in your Grocy instance. Use get_products to find product IDs, get_shopping_locations for store IDs, and get_locations for storage location 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.'
+                },
+                amount: {
+                    type: 'number',
+                    description: 'Amount to purchase in the product\'s stock unit (e.g., 1 piece, 2.5 kg, 500 ml). Ensure you know the product\'s stock unit before specifying amount.'
+                },
+                bestBeforeDate: {
+                    type: 'string',
+                    description: 'Best before date in YYYY-MM-DD format (default: today + 1 year)'
+                },
+                price: {
+                    type: 'number',
+                    description: 'Price of the purchase (optional)'
+                },
+                storeId: {
+                    type: 'number',
+                    description: 'ID of the store where purchased (optional). Use get_shopping_locations tool to find available store IDs and names.'
+                },
+                locationId: {
+                    type: 'number',
+                    description: 'ID of the storage location. Use get_locations tool to find available location IDs and names.'
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note'
+                }
+            },
+            required: ['productId', 'amount', 'locationId']
+        }
+    },
+    {
+        name: 'consume_product',
+        description: 'Track consumption of a specific stock entry in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    description: 'ID of the specific stock entry to consume.'
+                },
+                productId: {
+                    type: 'number',
+                    // ProductId is required for verification - if user knows the stockId, they must know the productId.
+                    // This ensures the call is made to the correct stock entry and prevents accidental operations.
+                    description: 'ID of the product being consumed.'
+                },
+                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.'
+                },
+                spoiled: {
+                    type: 'boolean',
+                    description: 'Whether the product is spoiled (default: false)',
+                    default: false
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note'
+                }
+            },
+            required: ['stockId', 'productId', 'amount']
+        }
+    },
+    {
+        name: 'transfer_product',
+        description: 'Transfer a specific stock entry to another location in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    description: 'ID of the specific stock entry to transfer.'
+                },
+                productId: {
+                    type: 'number',
+                    // ProductId is required for verification - if user knows the stockId, they must know the productId.
+                    // This ensures the call is made to the correct stock entry and prevents accidental operations.
+                    description: 'ID of the product being transferred.'
+                },
+                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.'
+                },
+                locationIdTo: {
+                    type: 'number',
+                    description: 'ID of the destination location.'
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note for this transfer'
+                }
+            },
+            required: ['stockId', 'productId', 'amount', 'locationIdTo']
+        }
+    },
+    {
+        name: 'open_product',
+        description: 'Mark a specific stock entry as opened in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    description: 'ID of the specific stock entry to mark as opened.'
+                },
+                productId: {
+                    type: 'number',
+                    // ProductId is required for verification - if user knows the stockId, they must know the productId.
+                    // This ensures the call is made to the correct stock entry and prevents accidental operations.
+                    description: 'ID of the product being opened.'
+                },
+                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.'
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note'
+                }
+            },
+            required: ['stockId', 'productId', 'amount']
+        }
+    },
+    {
+        name: 'lookup_product',
+        description: 'Lookup product information with advanced fuzzy matching. Returns all relevant data including exact IDs, available locations, and stock entries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                productName: {
+                    type: 'string',
+                    description: 'Name of the product to lookup.'
+                }
+            },
+            required: ['productName']
+        }
+    },
+    {
+        name: 'print_stock_entry_label',
+        description: 'Print a label for a specific stock entry.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    description: 'ID of the stock entry to print label for.'
+                },
+                productId: {
+                    type: 'number',
+                    // ProductId is required for verification - if user knows the stockId, they must know the productId.
+                    // This ensures the call is made to the correct stock entry and prevents accidental operations.
+                    description: 'ID of the product for the label.'
+                }
+            },
+            required: ['stockId', 'productId']
+        }
+    }
+];

package/build/tools/stock/handlers.js

@@ -0,0 +1,391 @@
+import { BaseToolHandler } from '../base.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import apiClient from '../../api/client.js';
+import Fuse from 'fuse.js';
+export class StockToolHandlers extends BaseToolHandler {
+    async splitStockEntry(originalEntry, stockAmounts, getUnitForm) {
+        const splitEntries = [];
+        if (stockAmounts.length === 1) {
+            const note = `${originalEntry.note} - ${originalEntry.id} - 1`;
+            await apiClient.put(`/stock/entry/${originalEntry.id}`, {
+                amount: stockAmounts[0],
+                open: false,
+                note: note,
+                best_before_date: originalEntry.best_before_date,
+                purchased_date: originalEntry.purchased_date,
+                location_id: originalEntry.location_id
+            });
+            splitEntries.push({
+                stockId: originalEntry.id,
+                amount: stockAmounts[0],
+                type: 'updated',
+                unit: getUnitForm(stockAmounts[0])
+            });
+        }
+        else {
+            for (let i = 0; i < stockAmounts.length; i++) {
+                const amount = stockAmounts[i];
+                const note = `${originalEntry.note} - ${originalEntry.id} - ${i + 1}`;
+                if (i === 0) {
+                    await apiClient.put(`/stock/entry/${originalEntry.id}`, {
+                        amount: amount,
+                        open: false,
+                        note: note,
+                        best_before_date: originalEntry.best_before_date,
+                        purchased_date: originalEntry.purchased_date,
+                        location_id: originalEntry.location_id
+                    });
+                    splitEntries.push({
+                        stockId: originalEntry.id,
+                        amount,
+                        type: 'updated',
+                        unit: getUnitForm(amount)
+                    });
+                }
+                else {
+                    const createResponse = await apiClient.post(`/stock/products/${originalEntry.product_id}/add`, {
+                        amount,
+                        best_before_date: originalEntry.best_before_date,
+                        purchased_date: originalEntry.purchased_date,
+                        transaction_type: 'purchase',
+                        location_id: originalEntry.location_id,
+                        note: note
+                    });
+                    const stockId = createResponse.data[0].stock_id || createResponse.data[0].id;
+                    const stockResponse = await apiClient.get('/objects/stock');
+                    const stockEntries = Array.isArray(stockResponse.data) ? stockResponse.data : [];
+                    const actualStockEntry = stockEntries.find((entry) => entry.product_id === originalEntry.product_id &&
+                        entry.stock_id === stockId);
+                    if (!actualStockEntry) {
+                        throw new Error(`Could not find created stock entry with product_id ${originalEntry.product_id} and stock_id ${stockId}`);
+                    }
+                    splitEntries.push({
+                        stockId: actualStockEntry.id,
+                        amount,
+                        type: 'created',
+                        unit: getUnitForm(amount)
+                    });
+                }
+            }
+        }
+        return splitEntries;
+    }
+    getAllStock = async (args) => {
+        return this.handleApiCall('/stock', 'Get current stock');
+    };
+    getStockVolatile = async (args) => {
+        const queryParams = args?.includeDetails ? { include_details: 'true' } : {};
+        return this.handleApiCall('/stock/volatile', 'Get volatile stock information', { queryParams });
+    };
+    getStockByLocation = async (args) => {
+        const { locationId } = args || {};
+        if (!locationId) {
+            throw new McpError(ErrorCode.InvalidParams, 'locationId is required');
+        }
+        return this.handleApiCall(`stock`, 'Get stock by location', {
+            queryParams: { location_id: locationId.toString() }
+        });
+    };
+    inventoryProduct = async (args) => {
+        const { productId, newAmount, bestBeforeDate, locationId, note } = args || {};
+        if (!productId || newAmount === undefined) {
+            throw new McpError(ErrorCode.InvalidParams, 'productId and newAmount are required');
+        }
+        const defaultBBD = new Date();
+        defaultBBD.setFullYear(defaultBBD.getFullYear() + 1);
+        const formattedBBD = bestBeforeDate || defaultBBD.toISOString().split('T')[0];
+        const body = {
+            new_amount: newAmount,
+            best_before_date: formattedBBD,
+            transaction_type: 'inventory-correction'
+        };
+        if (locationId)
+            body.location_id = locationId;
+        if (note)
+            body.note = note;
+        return this.handleApiCall(`/stock/products/${productId}/inventory`, 'Inventory product', {
+            method: 'POST',
+            body
+        });
+    };
+    purchaseProduct = async (args) => {
+        const { productId, amount = 1, bestBeforeDate, price, storeId, locationId, note } = args || {};
+        if (!productId) {
+            throw new McpError(ErrorCode.InvalidParams, 'productId is required');
+        }
+        const defaultBBD = new Date();
+        defaultBBD.setFullYear(defaultBBD.getFullYear() + 1);
+        const formattedBBD = bestBeforeDate || defaultBBD.toISOString().split('T')[0];
+        const body = {
+            amount,
+            transaction_type: 'purchase',
+            best_before_date: formattedBBD
+        };
+        if (price !== undefined)
+            body.price = price;
+        if (storeId)
+            body.shopping_location_id = storeId;
+        if (locationId)
+            body.location_id = locationId;
+        if (note)
+            body.note = note;
+        return this.handleApiCall(`/stock/products/${productId}/add`, 'Purchase product', {
+            method: 'POST',
+            body
+        });
+    };
+    consumeProduct = async (args) => {
+        const { stockId, productId, amount, spoiled = false, note } = args || {};
+        if (!stockId) {
+            throw new McpError(ErrorCode.InvalidParams, 'stockId is required. Use get_stock_by_product or get_stock_by_location to find specific stockId values.');
+        }
+        if (!productId) {
+            throw new McpError(ErrorCode.InvalidParams, 'productId is required.');
+        }
+        if (amount === undefined) {
+            throw new McpError(ErrorCode.InvalidParams, 'amount is required');
+        }
+        try {
+            const stockEntryResponse = await apiClient.get(`/stock/entry/${stockId}`);
+            if (!stockEntryResponse.data || !stockEntryResponse.data.product_id) {
+                throw new Error(`Could not resolve product ID from stock entry ${stockId}`);
+            }
+            if (stockEntryResponse.data.product_id !== productId) {
+                throw new Error(`Product ID mismatch: stock entry ${stockId} belongs to product ${stockEntryResponse.data.product_id}, but ${productId} was provided`);
+            }
+            const body = {
+                amount,
+                spoiled,
+                stock_entry_id: stockEntryResponse.data.stock_id,
+                location_id: stockEntryResponse.data.location_id
+            };
+            if (note)
+                body.note = note;
+            return this.handleApiCall(`/stock/products/${stockEntryResponse.data.product_id}/consume`, 'Consume product', {
+                method: 'POST',
+                body
+            });
+        }
+        catch (error) {
+            return this.createErrorResult(`Failed to consume product: ${error.message}`);
+        }
+    };
+    transferProduct = async (args) => {
+        const { stockId, productId, amount, locationIdTo, note } = args || {};
+        if (!stockId) {
+            throw new McpError(ErrorCode.InvalidParams, 'stockId is required. Use get_stock_by_product or get_stock_by_location to find specific stockId values.');
+        }
+        if (!productId) {
+            throw new McpError(ErrorCode.InvalidParams, 'productId is required.');
+        }
+        if (amount === undefined) {
+            throw new McpError(ErrorCode.InvalidParams, 'amount is required');
+        }
+        try {
+            const stockEntryResponse = await apiClient.get(`/stock/entry/${stockId}`);
+            if (!stockEntryResponse.data || !stockEntryResponse.data.product_id) {
+                throw new Error(`Could not resolve product ID from stock entry ${stockId}`);
+            }
+            if (stockEntryResponse.data.product_id !== productId) {
+                throw new Error(`Product ID mismatch: stock entry ${stockId} belongs to product ${stockEntryResponse.data.product_id}, but ${productId} was provided`);
+            }
+            const body = {
+                amount,
+                location_id_from: stockEntryResponse.data.location_id,
+                location_id_to: locationIdTo,
+                transaction_type: 'transfer',
+                stock_entry_id: stockEntryResponse.data.stock_id
+            };
+            if (note)
+                body.note = note;
+            return this.handleApiCall(`/stock/products/${stockEntryResponse.data.product_id}/transfer`, 'Transfer product', {
+                method: 'POST',
+                body
+            });
+        }
+        catch (error) {
+            return this.createErrorResult(`Failed to transfer product: ${error.message}`);
+        }
+    };
+    openProduct = async (args) => {
+        const { stockId, productId, amount, note } = args;
+        if (!stockId) {
+            throw new McpError(ErrorCode.InvalidParams, 'stockId is required. Use get_stock_by_product tool to find specific stockId values.');
+        }
+        if (!productId) {
+            throw new McpError(ErrorCode.InvalidParams, 'productId is required.');
+        }
+        if (amount === undefined) {
+            throw new McpError(ErrorCode.InvalidParams, 'amount is required');
+        }
+        try {
+            const stockEntryResponse = await apiClient.get(`/stock/entry/${stockId}`);
+            if (!stockEntryResponse.data || !stockEntryResponse.data.product_id) {
+                throw new Error(`Could not resolve product ID from stock entry ${stockId}`);
+            }
+            if (stockEntryResponse.data.product_id !== productId) {
+                throw new Error(`Product ID mismatch: stock entry ${stockId} belongs to product ${stockEntryResponse.data.product_id}, but ${productId} was provided`);
+            }
+            const body = {
+                amount,
+                stock_entry_id: stockEntryResponse.data.stock_id,
+                location_id: stockEntryResponse.data.location_id
+            };
+            if (note)
+                body.note = note;
+            return this.handleApiCall(`/stock/products/${stockEntryResponse.data.product_id}/open`, 'Open product', {
+                method: 'POST',
+                body
+            });
+        }
+        catch (error) {
+            console.error('Error opening product:', error);
+            return this.createErrorResult(`Failed to open product: ${error.message}`, {
+                help: "Use get_stock_by_product tool to find valid stockId values for a specific product.",
+                example: "Try using get_stock_by_product with a product ID to find valid stock entries"
+            });
+        }
+    };
+    lookupProduct = async (args) => {
+        const { productName } = args || {};
+        if (!productName) {
+            throw new McpError(ErrorCode.InvalidParams, 'productName is required');
+        }
+        try {
+            const [productsResponse, locationsResponse, quantityUnitsResponse] = await Promise.all([
+                apiClient.get('/objects/products'),
+                apiClient.get('/objects/locations'),
+                apiClient.get('/objects/quantity_units')
+            ]);
+            const products = Array.isArray(productsResponse.data) ? productsResponse.data : [];
+            const locations = Array.isArray(locationsResponse.data) ? locationsResponse.data : [];
+            const quantityUnits = Array.isArray(quantityUnitsResponse.data) ? quantityUnitsResponse.data : [];
+            const fuseOptions = {
+                keys: [
+                    { name: 'name', weight: 1.0 },
+                    { name: 'description', weight: 0.3 }
+                ],
+                threshold: 0.6,
+                distance: 100,
+                minMatchCharLength: 1,
+                ignoreLocation: true,
+                includeScore: true,
+                includeMatches: true,
+                useExtendedSearch: false,
+                isCaseSensitive: false,
+                shouldSort: true,
+                findAllMatches: false
+            };
+            const fuse = new Fuse(products, fuseOptions);
+            const fuseResults = fuse.search(productName);
+            let productMatches = fuseResults.map((result) => ({
+                ...result.item,
+                matchScore: Math.round((1 - result.score) * 100),
+                fuseScore: result.score,
+                matches: result.matches
+            }));
+            if (productMatches.length === 0) {
+                const permissiveFuse = new Fuse(products, {
+                    ...fuseOptions,
+                    threshold: 0.8,
+                    distance: 200
+                });
+                const permissiveResults = permissiveFuse.search(productName);
+                productMatches = permissiveResults.map((result) => ({
+                    ...result.item,
+                    matchScore: Math.round((1 - result.score) * 100),
+                    fuseScore: result.score,
+                    matches: result.matches,
+                    isPermissiveMatch: true
+                }));
+            }
+            productMatches = productMatches.slice(0, 5);
+            if (productMatches.length === 0) {
+                return this.createErrorResult(`No products found matching "${productName}"`, {
+                    suggestion: 'Try a different product name or check the spelling',
+                    availableProducts: products.slice(0, 10).map((p) => p.name)
+                });
+            }
+            const enrichedMatches = await Promise.all(productMatches.map(async (product) => {
+                let productEntries = [];
+                try {
+                    const entriesResponse = await apiClient.get(`/stock/products/${product.id}/entries`);
+                    productEntries = Array.isArray(entriesResponse.data) ? entriesResponse.data : [];
+                }
+                catch {
+                    productEntries = [];
+                }
+                const stockEntries = productEntries.map((stockItem) => {
+                    return {
+                        amount: stockItem.amount,
+                        bestBeforeDate: stockItem.best_before_date,
+                        stockId: stockItem.id,
+                        locationId: parseInt(stockItem.location_id)
+                    };
+                });
+                stockEntries.sort((a, b) => {
+                    if (!a.bestBeforeDate && !b.bestBeforeDate)
+                        return 0;
+                    if (!a.bestBeforeDate)
+                        return 1;
+                    if (!b.bestBeforeDate)
+                        return -1;
+                    return new Date(a.bestBeforeDate).getTime() - new Date(b.bestBeforeDate).getTime();
+                });
+                const unit = quantityUnits.find((u) => u.id == product.qu_id_stock);
+                const unitInfo = unit
+                    ? { id: unit.id, name: unit.name }
+                    : { id: null, name: 'pieces' };
+                const hasMultipleLocations = stockEntries.length > 1 &&
+                    new Set(stockEntries.map((entry) => entry.locationId)).size > 1;
+                const locationInstructions = hasMultipleLocations
+                    ? 'IMPORTANT: This product has stock in multiple locations. Make sure the user requested a specific location or confirm the locationId before performing any operations.'
+                    : undefined;
+                return {
+                    productId: product.id,
+                    productName: product.name,
+                    stockEntries: stockEntries,
+                    totalStockAmount: productEntries.reduce((sum, s) => sum + parseFloat(s.amount || 0), 0),
+                    unit: unitInfo,
+                    locationInstructions
+                };
+            }));
+            return this.createSuccessResult({
+                message: `Found ${enrichedMatches.length} product matches for "${productName}" (ordered from most likely to least likely match)`,
+                productMatches: enrichedMatches,
+                allAvailableLocations: locations.map((l) => ({ id: l.id, name: l.name })),
+                instructions: 'Review the matches above. Use the exact productId and locationId from this data for any product operations (consume_product, purchase_product, inventory_product, transfer_product, etc.).'
+            });
+        }
+        catch (error) {
+            return this.createErrorResult(`Failed to lookup product: ${error.message}`);
+        }
+    };
+    printStockEntryLabel = async (args) => {
+        const { stockId, productId } = args || {};
+        if (!stockId) {
+            throw new McpError(ErrorCode.InvalidParams, 'stockId is required. Use get_stock_by_product tool to find specific stockId values.');
+        }
+        if (!productId) {
+            throw new McpError(ErrorCode.InvalidParams, 'productId is required.');
+        }
+        try {
+            const stockEntryResponse = await apiClient.get(`/stock/entry/${stockId}`);
+            if (!stockEntryResponse.data || !stockEntryResponse.data.product_id) {
+                throw new Error(`Could not resolve product ID from stock entry ${stockId}`);
+            }
+            if (stockEntryResponse.data.product_id !== productId) {
+                throw new Error(`Product ID mismatch: stock entry ${stockId} belongs to product ${stockEntryResponse.data.product_id}, but ${productId} was provided`);
+            }
+            return this.handleApiCall(`/stock/entry/${stockId}/printlabel`, 'Print stock entry label');
+        }
+        catch (error) {
+            console.error('Error printing stock entry label:', error);
+            return this.createErrorResult(`Failed to print stock entry label: ${error.message}`, {
+                help: "Use get_stock_by_product tool to find valid stockId values for a specific product.",
+                example: "Try using get_stock_by_product with a product ID to find valid stock entries"
+            });
+        }
+    };
+}
+export const stockHandlers = new StockToolHandlers();

package/build/tools/stock/index.js

@@ -0,0 +1,19 @@
+import { stockToolDefinitions } from './definitions.js';
+import { stockHandlers } from './handlers.js';
+export const stockModule = {
+    definitions: stockToolDefinitions,
+    handlers: {
+        get_all_stock: stockHandlers.getAllStock,
+        get_stock_volatile: stockHandlers.getStockVolatile,
+        get_stock_by_location: stockHandlers.getStockByLocation,
+        inventory_product: stockHandlers.inventoryProduct,
+        purchase_product: stockHandlers.purchaseProduct,
+        consume_product: stockHandlers.consumeProduct,
+        transfer_product: stockHandlers.transferProduct,
+        open_product: stockHandlers.openProduct,
+        lookup_product: stockHandlers.lookupProduct,
+        print_stock_entry_label: stockHandlers.printStockEntryLabel
+    }
+};
+export * from './definitions.js';
+export * from './handlers.js';