mcp-grocy 1.11.0 → 2.0.0

package/README.md

@@ -63,7 +63,7 @@ Transform your LLM into an intelligent household management assistant with focus
    
    # Configure
    cp .env.example .env
-   # Edit .env with your GROCY_BASE_URL and GROCY_APIKEY_VALUE
+   # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
    
    # Run
    docker compose up -d
@@ -74,7 +74,7 @@ Test with mock data (no real Grocy instance needed):
 ```bash
 # In .env file, any values work for mock mode
 GROCY_BASE_URL=http://mock
-GROCY_APIKEY_VALUE=mock
+GROCY_API_KEY=mock
 
 npm install && npm run dev
 ```
@@ -93,7 +93,7 @@ npm run build
 ### Docker
 
 ```bash
-docker run -e GROCY_APIKEY_VALUE=your_api_key -e GROCY_BASE_URL=http://your-grocy-instance ghcr.io/miguelangel-nubla/mcp-grocy:latest
+docker run -e GROCY_API_KEY=your_api_key -e GROCY_BASE_URL=http://your-grocy-instance ghcr.io/miguelangel-nubla/mcp-grocy:latest
 ```
 
 ### Docker Compose (Recommended)
@@ -126,19 +126,19 @@ docker compose up -d
 2. **Configure the server:**
    ```bash
    cp .env.example .env
-   # Edit .env with your GROCY_BASE_URL and GROCY_APIKEY_VALUE
+   # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
    ```
 
 3. **Essential variables:**
    - `GROCY_BASE_URL` - Your Grocy instance URL
-   - `GROCY_APIKEY_VALUE` - Your Grocy API key
+   - `GROCY_API_KEY` - Your Grocy API key
 
 ### Configuration Options
 
 | Method | Use Case | Command |
 |--------|----------|---------|
 | **`.env` file** | Recommended for most users | `cp .env.example .env` |
-| **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_APIKEY_VALUE=... mcp-grocy` |
+| **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy` |
 | **Tool configuration** | Customize functionality | Edit `tools` section in `mcp-grocy.yaml` |
 
 📖 **For complete configuration reference:** See [Configuration Guide](src/resources/config.md)
@@ -185,7 +185,7 @@ npm start
 - For HTTPS URLs, ensure SSL certificate is valid or disable verification with `GROCY_ENABLE_SSL_VERIFY=false`
 
 **"Invalid API key" or "Authentication failed"**
-- Verify your `GROCY_APIKEY_VALUE` is correct
+- Verify your `GROCY_API_KEY` is correct
 - Check that the API key exists in your Grocy instance (User Settings → API Keys)
 - Ensure the API key has proper permissions
 

package/build/api/client.js

@@ -14,19 +14,17 @@ export class GrocyApiClient {
         this.setupInterceptors();
     }
     createAxiosInstance() {
-        const { yaml } = config.getConfig();
-        const apiKey = config.getApiKey();
         const instance = axios.create({
-            baseURL: config.getGrocyBaseUrl(),
+            baseURL: config.grocy.base_url,
             validateStatus: () => true, // Handle all status codes manually
             timeout: 30000,
-            httpsAgent: yaml.grocy.enable_ssl_verify ? undefined : new https.Agent({
+            httpsAgent: config.grocy.enable_ssl_verify ? undefined : new https.Agent({
                 rejectUnauthorized: false
             })
         });
         // Set default authentication
-        if (apiKey) {
-            instance.defaults.headers.common[this.API_KEY_HEADER] = apiKey;
+        if (config.grocy.api_key) {
+            instance.defaults.headers.common[this.API_KEY_HEADER] = config.grocy.api_key;
         }
         return instance;
     }

package/build/config/index.js

@@ -11,7 +11,18 @@ import { logger } from '../utils/logger.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Environment schema
 const EnvironmentSchema = z.object({
-    GROCY_APIKEY_VALUE: z.string().optional(),
+    // Grocy Configuration
+    GROCY_BASE_URL: z.string().url().optional(),
+    GROCY_API_KEY: z.string().optional(),
+    GROCY_ENABLE_SSL_VERIFY: z.enum(['true', 'false']).optional(),
+    // Server Configuration  
+    REST_RESPONSE_SIZE_LIMIT: z.string().regex(/^\d+$/).optional(),
+    ENABLE_HTTP_SERVER: z.enum(['true', 'false']).optional(),
+    HTTP_SERVER_PORT: z.string().regex(/^\d+$/).optional(),
+    // Logging Configuration
+    LOG_LEVEL: z.enum(['DEBUG', 'INFO', 'WARN', 'ERROR']).optional(),
+    LOG_CATEGORIES: z.string().optional(),
+    // Build Configuration
     RELEASE_VERSION: z.string().optional(),
     NODE_ENV: z.enum(['development', 'production', 'test']).optional(),
 });
@@ -23,6 +34,7 @@ const YamlConfigSchema = z.object({
     }).default({}),
     grocy: z.object({
         base_url: z.string().url().default('http://localhost:9283'),
+        api_key: z.string().optional(),
         enable_ssl_verify: z.boolean().default(true),
         response_size_limit: z.number().positive().default(10000),
     }).default({}),
@@ -34,8 +46,24 @@ const YamlConfigSchema = z.object({
 export class ConfigManager {
     static instance;
     config;
+    // Unified config properties - final resolved values
+    grocy;
+    server;
+    tools;
     constructor(configPath) {
         this.config = this.loadConfig(configPath);
+        // Expose final resolved values
+        this.grocy = {
+            base_url: this.config.yaml.grocy.base_url,
+            ...(this.config.yaml.grocy.api_key !== undefined && { api_key: this.config.yaml.grocy.api_key }),
+            enable_ssl_verify: this.config.yaml.grocy.enable_ssl_verify,
+            response_size_limit: this.config.yaml.grocy.response_size_limit
+        };
+        this.server = {
+            enable_http_server: this.config.yaml.server.enable_http_server,
+            http_server_port: this.config.yaml.server.http_server_port
+        };
+        this.tools = this.config.yaml.tools;
     }
     static getInstance() {
         if (!ConfigManager.instance) {
@@ -43,14 +71,13 @@ export class ConfigManager {
         }
         return ConfigManager.instance;
     }
-    static createForTesting(configPath) {
-        return new ConfigManager(configPath);
-    }
     loadConfig(configPath) {
         // Load environment variables
         const env = this.loadEnvironment();
         // Load YAML configuration
         const yaml = this.loadYamlConfig(configPath);
+        // Apply environment variable overrides
+        this.applyEnvironmentOverrides(yaml, env);
         return { env, yaml };
     }
     loadEnvironment() {
@@ -112,26 +139,41 @@ export class ConfigManager {
     getConfig() {
         return this.config;
     }
-    getGrocyBaseUrl() {
-        return this.config.yaml.grocy.base_url;
-    }
     getApiUrl() {
-        const baseUrl = this.getGrocyBaseUrl();
-        return baseUrl.endsWith('/') ? `${baseUrl}api` : `${baseUrl}/api`;
-    }
-    hasApiKey() {
-        return !!this.config.env.GROCY_APIKEY_VALUE;
-    }
-    getApiKey() {
-        return this.config.env.GROCY_APIKEY_VALUE;
+        return this.grocy.base_url.endsWith('/') ? `${this.grocy.base_url}api` : `${this.grocy.base_url}/api`;
     }
     getCustomHeaders() {
         const headers = {};
-        if (this.config.env.GROCY_APIKEY_VALUE) {
-            headers['GROCY-API-KEY'] = this.config.env.GROCY_APIKEY_VALUE;
+        if (this.grocy.api_key) {
+            headers['GROCY-API-KEY'] = this.grocy.api_key;
         }
         return headers;
     }
+    /**
+     * Apply environment variable overrides to YAML configuration
+     */
+    applyEnvironmentOverrides(yaml, env) {
+        // Grocy configuration overrides
+        if (env.GROCY_BASE_URL) {
+            yaml.grocy.base_url = env.GROCY_BASE_URL;
+        }
+        if (env.GROCY_API_KEY) {
+            yaml.grocy.api_key = env.GROCY_API_KEY;
+        }
+        if (env.GROCY_ENABLE_SSL_VERIFY !== undefined) {
+            yaml.grocy.enable_ssl_verify = env.GROCY_ENABLE_SSL_VERIFY === 'true';
+        }
+        if (env.REST_RESPONSE_SIZE_LIMIT !== undefined) {
+            yaml.grocy.response_size_limit = parseInt(env.REST_RESPONSE_SIZE_LIMIT, 10);
+        }
+        // Server configuration overrides
+        if (env.ENABLE_HTTP_SERVER !== undefined) {
+            yaml.server.enable_http_server = env.ENABLE_HTTP_SERVER === 'true';
+        }
+        if (env.HTTP_SERVER_PORT !== undefined) {
+            yaml.server.http_server_port = parseInt(env.HTTP_SERVER_PORT, 10);
+        }
+    }
     parseToolConfiguration() {
         const enabledTools = new Set();
         const toolSubConfigs = new Map();

package/build/main.js

@@ -14,16 +14,14 @@ import { ErrorHandler } from './utils/errors.js';
 logger.info(`Starting ${SERVER_NAME} v${VERSION}`, 'SERVER');
 async function main() {
     return ErrorHandler.handleAsync(async () => {
-        // Validate configuration
-        const cfg = config.getConfig();
         // Check API key
-        if (!config.hasApiKey()) {
+        if (!config.grocy.api_key) {
             logger.warn('No API key configured. Some operations may fail.', 'CONFIG');
         }
         // Log configuration summary
-        logger.config(`Grocy URL: ${config.getGrocyBaseUrl()}`);
-        logger.config(`SSL Verify: ${cfg.yaml.grocy.enable_ssl_verify}`);
-        logger.config(`HTTP Server: ${cfg.yaml.server.enable_http_server}`);
+        logger.config(`Grocy URL: ${config.grocy.base_url}`);
+        logger.config(`SSL Verify: ${config.grocy.enable_ssl_verify}`);
+        logger.config(`HTTP Server: ${config.server.enable_http_server}`);
         // Create and start server
         const server = await GrocyMcpServer.create();
         await server.start();

package/build/resources/README.md

@@ -63,7 +63,7 @@ Transform your LLM into an intelligent household management assistant with focus
    
    # Configure
    cp .env.example .env
-   # Edit .env with your GROCY_BASE_URL and GROCY_APIKEY_VALUE
+   # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
    
    # Run
    docker compose up -d
@@ -74,7 +74,7 @@ Test with mock data (no real Grocy instance needed):
 ```bash
 # In .env file, any values work for mock mode
 GROCY_BASE_URL=http://mock
-GROCY_APIKEY_VALUE=mock
+GROCY_API_KEY=mock
 
 npm install && npm run dev
 ```
@@ -93,7 +93,7 @@ npm run build
 ### Docker
 
 ```bash
-docker run -e GROCY_APIKEY_VALUE=your_api_key -e GROCY_BASE_URL=http://your-grocy-instance ghcr.io/miguelangel-nubla/mcp-grocy:latest
+docker run -e GROCY_API_KEY=your_api_key -e GROCY_BASE_URL=http://your-grocy-instance ghcr.io/miguelangel-nubla/mcp-grocy:latest
 ```
 
 ### Docker Compose (Recommended)
@@ -126,19 +126,19 @@ docker compose up -d
 2. **Configure the server:**
    ```bash
    cp .env.example .env
-   # Edit .env with your GROCY_BASE_URL and GROCY_APIKEY_VALUE
+   # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
    ```
 
 3. **Essential variables:**
    - `GROCY_BASE_URL` - Your Grocy instance URL
-   - `GROCY_APIKEY_VALUE` - Your Grocy API key
+   - `GROCY_API_KEY` - Your Grocy API key
 
 ### Configuration Options
 
 | Method | Use Case | Command |
 |--------|----------|---------|
 | **`.env` file** | Recommended for most users | `cp .env.example .env` |
-| **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_APIKEY_VALUE=... mcp-grocy` |
+| **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy` |
 | **Tool configuration** | Customize functionality | Edit `tools` section in `mcp-grocy.yaml` |
 
 📖 **For complete configuration reference:** See [Configuration Guide](src/resources/config.md)
@@ -185,7 +185,7 @@ npm start
 - For HTTPS URLs, ensure SSL certificate is valid or disable verification with `GROCY_ENABLE_SSL_VERIFY=false`
 
 **"Invalid API key" or "Authentication failed"**
-- Verify your `GROCY_APIKEY_VALUE` is correct
+- Verify your `GROCY_API_KEY` is correct
 - Check that the API key exists in your Grocy instance (User Settings → API Keys)
 - Ensure the API key has proper permissions
 

package/build/resources/config.md

@@ -9,7 +9,7 @@ Advanced configuration reference for the MCP Grocy server. For basic setup, see
 | Variable | Description | Default | Required |
 |----------|-------------|---------|----------|
 | `GROCY_BASE_URL` | Your Grocy instance URL | `http://localhost:9283` | ✅ |
-| `GROCY_APIKEY_VALUE` | Your Grocy API key | - | ✅ |
+| `GROCY_API_KEY` | Your Grocy API key | - | ✅ |
 
 ### Optional Variables
 
@@ -77,7 +77,7 @@ Configuration examples for common use cases are provided in `mcp-grocy.yaml.exam
 ```bash
 # .env for development
 GROCY_BASE_URL=http://localhost:9283
-GROCY_APIKEY_VALUE=dev_api_key_here
+GROCY_API_KEY=dev_api_key_here
 GROCY_ENABLE_SSL_VERIFY=false
 REST_RESPONSE_SIZE_LIMIT=50000
 
@@ -90,7 +90,7 @@ HTTP_SERVER_PORT=8080
 ```bash
 # .env for production
 GROCY_BASE_URL=https://grocy.yourdomain.com
-GROCY_APIKEY_VALUE=secure_production_key
+GROCY_API_KEY=secure_production_key
 GROCY_ENABLE_SSL_VERIFY=true
 REST_RESPONSE_SIZE_LIMIT=20000
 ```

package/build/resources/examples.md

@@ -10,7 +10,7 @@ Before testing the API, you can create your own private Grocy demo instance:
 4. Use the provided API key and URL in your `.env` file:
    ```
    GROCY_BASE_URL=https://your-name-xxxxx.demo.grocy.info
-   GROCY_APIKEY_VALUE=your-private-api-key
+   GROCY_API_KEY=your-private-api-key
    ```
 
 ⚠️ IMPORTANT: Only provide the endpoint path - do not include full URLs. Your path will be automatically resolved to the full URL.

package/build/resources/installation.md

@@ -17,7 +17,7 @@ Edit `claude_desktop_config.json`(for Claude Desktop) or `.cursor/mcp.json`(for
       ], 
       "env": {
         "GROCY_BASE_URL": "",
-        "GROCY_APIKEY_VALUE": "",
+        "GROCY_API_KEY": "",
         "GROCY_ENABLE_SSL_VERIFY": "False",
         "REST_RESPONSE_SIZE_LIMIT": "10000"
       }
@@ -41,7 +41,7 @@ Or you can use Docker:
         ],
       "env": {
         "GROCY_BASE_URL": "",
-        "GROCY_APIKEY_VALUE": "",
+        "GROCY_API_KEY": "",
         "GROCY_ENABLE_SSL_VERIFY": "False",
         "REST_RESPONSE_SIZE_LIMIT": "10000"
       }

package/build/resources/response-format.md

@@ -67,7 +67,7 @@ Configure your environment with the private demo details:
 
 ```
 GROCY_BASE_URL=https://your-name-xxxxx.demo.grocy.info
-GROCY_APIKEY_VALUE=your-private-api-key
+GROCY_API_KEY=your-private-api-key
 ```
 
 These values can be set in your `.env` file for local development or in your project configuration for production use.
@@ -79,7 +79,7 @@ These values can be set in your `.env` file for local development or in your pro
 - `method`: HTTP method used (e.g., GET, POST, PUT, DELETE).
 - `headers`: Request headers sent to the Grocy API. Sensitive headers like `GROCY-API-KEY` will have their values redacted.
 - `body`: Request body sent (if applicable, e.g., for POST/PUT requests).
-- `authMethod`: Authentication method used. For Grocy, this will typically be `apikey` if `GROCY_APIKEY_VALUE` is configured, or `none`.
+- `authMethod`: Authentication method used. For Grocy, this will typically be `apikey` if `GROCY_API_KEY` is configured, or `none`.
 
 ### Response Details (`response`)
 - `statusCode`: HTTP status code returned by the Grocy API (e.g., 200, 400, 401).

package/build/server/mcp-server.js

@@ -113,7 +113,7 @@ export class GrocyMcpServer {
             }
             catch (error) {
                 ErrorHandler.logError(error, `tool: ${toolName}`);
-                throw ErrorHandler.toMcpError(error, `Tool execution failed: ${toolName}`);
+                throw ErrorHandler.toMcpError(error, `${toolName} failed`);
             }
         });
         // Resources
@@ -140,12 +140,11 @@ export class GrocyMcpServer {
         await this.server.connect(transport);
         logger.info('MCP server running on stdio', 'SERVER');
         // Start HTTP/SSE if enabled
-        const { yaml } = config.getConfig();
-        if (yaml.server.enable_http_server) {
+        if (config.server.enable_http_server) {
             try {
-                logger.config(`Starting HTTP server on port ${yaml.server.http_server_port}`);
+                logger.config(`Starting HTTP server on port ${config.server.http_server_port}`);
                 const serverFactory = () => this.server;
-                await startHttpServer(serverFactory, yaml.server.http_server_port);
+                await startHttpServer(serverFactory, config.server.http_server_port);
             }
             catch (error) {
                 logger.error('Failed to start HTTP server', 'SERVER', { error });

package/build/tools/base.js

@@ -68,17 +68,17 @@ export class BaseToolHandler {
     /**
      * Handle tool execution with standardized error handling
      */
-    async executeToolHandler(handler, operation) {
+    async executeToolHandler(handler) {
         try {
             return await handler();
         }
         catch (error) {
-            ErrorHandler.logError(error, operation);
+            ErrorHandler.logError(error, 'tool execution');
             if (error instanceof ValidationError) {
                 return this.createError(error.message);
             }
             const message = error instanceof Error ? error.message : 'Internal error';
-            return this.createError(`${operation} failed: ${message}`);
+            return this.createError(`Tool execution failed: ${message}`);
         }
     }
     /**

package/build/tools/household/definitions.js

@@ -95,6 +95,35 @@ export const householdToolDefinitions = [
             required: ['batteryId']
         }
     },
+    {
+        name: 'household_batteries_print_label',
+        description: '[HOUSEHOLD/BATTERIES] Print a Grocycode label for a battery. Use household_batteries_get to find valid batteryId values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                batteryId: {
+                    type: 'number',
+                    description: 'ID of the battery to print label for. Use household_batteries_get tool to find the correct battery ID.'
+                }
+            },
+            required: ['batteryId']
+        }
+    },
+    // ==================== CHORE LABEL PRINTING ====================
+    {
+        name: 'household_chores_print_label',
+        description: '[HOUSEHOLD/CHORES] Print a Grocycode label for a chore. Use household_chores_get to find valid choreId values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                choreId: {
+                    type: 'number',
+                    description: 'ID of the chore to print label for. Use household_chores_get tool to find the correct chore ID.'
+                }
+            },
+            required: ['choreId']
+        }
+    },
     // ==================== EQUIPMENT MANAGEMENT ====================
     {
         name: 'household_equipment_get',

package/build/tools/household/handlers.js

@@ -5,7 +5,7 @@ export class HouseholdToolHandlers extends BaseToolHandler {
         return this.executeToolHandler(async () => {
             const data = await this.apiCall('/objects/chores');
             return this.createSuccess(data);
-        }, 'get chores');
+        });
     };
     trackChoreExecution = async (args) => {
         return this.executeToolHandler(async () => {
@@ -19,14 +19,14 @@ export class HouseholdToolHandlers extends BaseToolHandler {
             };
             const result = await this.apiCall(`/chores/${choreId}/execute`, 'POST', body);
             return this.createSuccess(result, 'Chore execution tracked successfully');
-        }, 'track chore execution');
+        });
     };
     // ==================== TASK MANAGEMENT ====================
     getTasks = async () => {
         return this.executeToolHandler(async () => {
             const data = await this.apiCall('/objects/tasks');
             return this.createSuccess(data);
-        }, 'get tasks');
+        });
     };
     completeTask = async (args) => {
         return this.executeToolHandler(async () => {
@@ -34,14 +34,14 @@ export class HouseholdToolHandlers extends BaseToolHandler {
             this.validateRequired({ taskId }, ['taskId']);
             const result = await this.apiCall(`/tasks/${taskId}/complete`, 'POST', note ? { note } : {});
             return this.createSuccess(result, 'Task completed successfully');
-        }, 'complete task');
+        });
     };
     // ==================== BATTERY MANAGEMENT ====================
     getBatteries = async () => {
         return this.executeToolHandler(async () => {
             const data = await this.apiCall('/objects/batteries');
             return this.createSuccess(data);
-        }, 'get batteries');
+        });
     };
     chargeBattery = async (args) => {
         return this.executeToolHandler(async () => {
@@ -54,14 +54,31 @@ export class HouseholdToolHandlers extends BaseToolHandler {
             };
             const result = await this.apiCall(`/batteries/${batteryId}/charge`, 'POST', body);
             return this.createSuccess(result, 'Battery charged successfully');
-        }, 'charge battery');
+        });
     };
     // ==================== EQUIPMENT MANAGEMENT ====================
     getEquipment = async () => {
         return this.executeToolHandler(async () => {
             const data = await this.apiCall('/objects/equipment');
             return this.createSuccess(data);
-        }, 'get equipment');
+        });
+    };
+    // ==================== LABEL PRINTING ====================
+    printBatteryLabel = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { batteryId } = args || {};
+            this.validateRequired({ batteryId }, ['batteryId']);
+            const result = await this.apiCall(`/batteries/${batteryId}/printlabel`);
+            return this.createSuccess(result, 'Battery label printed successfully');
+        });
+    };
+    printChoreLabel = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { choreId } = args || {};
+            this.validateRequired({ choreId }, ['choreId']);
+            const result = await this.apiCall(`/chores/${choreId}/printlabel`);
+            return this.createSuccess(result, 'Chore label printed successfully');
+        });
     };
     // ==================== ACTION UTILITIES ====================
     undoAction = async (args) => {
@@ -87,6 +104,6 @@ export class HouseholdToolHandlers extends BaseToolHandler {
             }
             const result = await this.apiCall(endpoint, 'POST');
             return this.createSuccess(result, `${entityType} action undone successfully`);
-        }, 'undo action');
+        });
     };
 }

package/build/tools/household/index.js

@@ -13,6 +13,9 @@ export const householdModule = {
         // Battery Management
         household_batteries_get: handlers.getBatteries,
         household_batteries_charge: handlers.chargeBattery,
+        household_batteries_print_label: handlers.printBatteryLabel,
+        // Chore Label Printing
+        household_chores_print_label: handlers.printChoreLabel,
         // Equipment Management
         household_equipment_get: handlers.getEquipment,
         // Action Utilities

package/build/tools/index.js

@@ -1,5 +1,2 @@
 // Re-export simplified module loader functionality
 export { createToolRegistry } from './module-loader.js';
-// Export types and modules for testing
-export * from './types.js';
-export * from './base.js';

package/build/tools/inventory/definitions.js

@@ -257,7 +257,21 @@ export const inventoryToolDefinitions = [
         }
     },
     {
-        name: 'inventory_stock_print_label',
+        name: 'inventory_products_print_label',
+        description: '[INVENTORY/PRODUCTS] Print a Grocycode label for a product. Use inventory_products_get to find valid productId values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                productId: {
+                    type: 'number',
+                    description: 'ID of the product to print label for. Use inventory_products_get tool to find the correct product ID.'
+                }
+            },
+            required: ['productId']
+        }
+    },
+    {
+        name: 'inventory_stock_entry_print_label',
         description: '[INVENTORY/STOCK] Print a label for a specific stock entry. Use inventory_stock_get_by_product to find valid stockId values.',
         inputSchema: {
             type: 'object',
@@ -273,5 +287,93 @@ export const inventoryToolDefinitions = [
             },
             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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    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.'
+                },
+                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: '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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    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.'
+                },
+                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: '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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                stockId: {
+                    type: 'number',
+                    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.'
+                },
+                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']
+        }
     }
 ];