mcp-grocy 2.7.1 → 2.7.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.7.2](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.1...v2.7.2) (2026-09-10)
+
+
+### Bug Fixes
+
+* add prepack script, update release configs, and fix docker workflows ([c464c05](https://github.com/miguelangel-nubla/mcp-grocy/commit/c464c054ab4f3f420647196ded7454c60f3702fc))
+
 ## [2.7.1](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.0...v2.7.1) (2026-09-10)
 
 ### Bug Fixes

package/README.md

@@ -6,6 +6,20 @@
 [![Configuration Status](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/validate-config.yml/badge.svg)](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/validate-config.yml)
 [![CI/CD Pipeline](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/pipeline.yml/badge.svg)](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/pipeline.yml)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![Recommended Backend: grocy-next](https://img.shields.io/badge/Recommended%20Backend-grocy--next-brightgreen?logo=docker)](https://github.com/miguelangel-nubla/grocy-next)
+
+> ### 🌟 Recommended Companion: [grocy-next](https://github.com/miguelangel-nubla/grocy-next)
+>
+> While **mcp-grocy** works great with standard upstream [Grocy](https://grocy.info/) (v4.x+), it is primarily developed and daily-driven with **[grocy-next](https://github.com/miguelangel-nubla/grocy-next)**.
+>
+> **grocy-next** is an enhanced, 100% compatible drop-in Docker distribution of Grocy featuring:
+>
+> - 📦 **Container Inventory Management:** Barcode-driven container packing, location hierarchies, and rapid transfers.
+> - ⚖️ **Hardware & Home Assistant Integration:** Native helper integration for smart scales and wireless barcode scanners.
+> - 🖥️ **Live Screens & Pending Scans:** Dedicated live inventory dashboards and async scan queues.
+> - 🥗 **Enhanced Meal Planning:** Calorie breakdown per serving and streamlined meal plan workflows.
+>
+> 👉 If you want the most seamless experience with this MCP, deploy **[miguelangel-nubla/grocy-next](https://github.com/miguelangel-nubla/grocy-next)**!
 
 > **🍴 Opinionated Fork Notice**
 >
@@ -26,10 +40,6 @@
 >
 > If you need complete API access, use the [original fork](https://github.com/saya6k/mcp-grocy-api). This version trades flexibility for focused, dependable grocery management workflows.
 
-> **⚡ Supported Grocy Backends**
->
-> This MCP server is compatible with standard [Grocy](https://grocy.info/) (v4.x+) as well as [grocy-next](https://github.com/miguelangel-nubla/grocy-next) (an enhanced fork with container inventory management and live workflows). The primary environment used by the author is `grocy-next`.
-
 ## 🎯 What This MCP Does
 
 Transform your LLM into an intelligent household management assistant with focused tools for:
@@ -64,7 +74,7 @@ Transform your LLM into an intelligent household management assistant with focus
 
 ## ⚡ Quick Start
 
-1. **Get your Grocy API key** from your Grocy instance (User Settings → API Keys)
+1. **Get your Grocy API key** from your Grocy or [grocy-next](https://github.com/miguelangel-nubla/grocy-next) instance (User Settings → API Keys)
 2. **Set up with Docker Compose:**
 
    ```bash

package/build/api/client.js

@@ -0,0 +1,119 @@
+/**
+ * Simplified API client for Grocy
+ */
+import axios from 'axios';
+import https from 'https';
+import { config } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+import { ApiError, ErrorHandler } from '../utils/errors.js';
+export class GrocyApiClient {
+    axiosInstance;
+    constructor() {
+        this.axiosInstance = this.createAxiosInstance();
+        this.setupInterceptors();
+    }
+    createAxiosInstance() {
+        const instance = axios.create({
+            baseURL: config.grocy.base_url,
+            validateStatus: () => true, // Handle all status codes manually
+            timeout: 30000,
+            maxContentLength: config.grocy.max_response_bytes,
+            httpsAgent: config.grocy.enable_ssl_verify
+                ? undefined
+                : new https.Agent({
+                    rejectUnauthorized: false,
+                }),
+        });
+        return instance;
+    }
+    setupInterceptors() {
+        // Request logging
+        this.axiosInstance.interceptors.request.use((config) => {
+            logger.api(`${config.method?.toUpperCase()} ${config.url}`);
+            return config;
+        }, (error) => {
+            logger.error('Request error', 'API', { error: error.message });
+            return Promise.reject(error);
+        });
+        // Response logging
+        this.axiosInstance.interceptors.response.use((response) => {
+            if (response.status >= 400) {
+                logger.warn(`HTTP ${response.status}`, 'API', {
+                    url: response.config?.url,
+                    status: response.status,
+                });
+            }
+            return response;
+        }, (error) => {
+            logger.error('Response error', 'API', { error: error.message });
+            return Promise.reject(error);
+        });
+    }
+    normalizeEndpoint(endpoint) {
+        if (endpoint.startsWith('/api/'))
+            return endpoint;
+        if (endpoint.startsWith('api/'))
+            return `/${endpoint}`;
+        if (endpoint.startsWith('/'))
+            return `/api${endpoint}`;
+        return `/api/${endpoint}`;
+    }
+    buildQueryString(params) {
+        return Object.entries(params)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join('&');
+    }
+    async request(endpoint, options = {}) {
+        const { method = 'GET', body = null, headers = {}, queryParams = {}, timeout } = options;
+        return ErrorHandler.handleAsync(async () => {
+            let url = this.normalizeEndpoint(endpoint);
+            if (Object.keys(queryParams).length > 0) {
+                url += `?${this.buildQueryString(queryParams)}`;
+            }
+            const requestConfig = {
+                method,
+                url,
+                headers: {
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                    ...config.getCustomHeaders(),
+                    ...headers,
+                },
+                ...(timeout && { timeout }),
+            };
+            if (['POST', 'PUT', 'PATCH'].includes(method) && body !== null) {
+                requestConfig.data = body;
+            }
+            const response = await this.axiosInstance.request(requestConfig);
+            if (response.status >= 400) {
+                throw new ApiError(response.data?.message || `HTTP ${response.status} error`, response.status, `${method} ${url}`, { responseData: response.data });
+            }
+            return {
+                data: response.data,
+                status: response.status,
+                headers: response.headers,
+            };
+        }, `API ${method} ${endpoint}`);
+    }
+    // Convenience methods
+    async get(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: 'GET' });
+    }
+    async post(endpoint, body, options = {}) {
+        return this.request(endpoint, { ...options, method: 'POST', body });
+    }
+    async put(endpoint, body, options = {}) {
+        return this.request(endpoint, { ...options, method: 'PUT', body });
+    }
+    async delete(endpoint, options = {}) {
+        return this.request(endpoint, { ...options, method: 'DELETE' });
+    }
+    async patch(endpoint, body, options = {}) {
+        return this.request(endpoint, { ...options, method: 'PATCH', body });
+    }
+}
+// Export singleton instance
+export const apiClient = new GrocyApiClient();
+export default apiClient;
+// Re-export ApiError for convenience
+export { ApiError };

package/build/config/index.js

@@ -0,0 +1,283 @@
+/**
+ * Unified configuration system
+ * Combines environment variables and YAML configuration
+ */
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import YAML from 'yaml';
+import { logger } from '../utils/logger.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Default cap for Grocy HTTP response bodies (axios maxContentLength), in bytes */
+export const DEFAULT_MAX_RESPONSE_BYTES = 52_428_800; // 50 MiB
+// Environment schema
+const EnvironmentSchema = z.object({
+    // Grocy Configuration
+    GROCY_BASE_URL: z.string().url().optional(),
+    GROCY_API_KEY: z.string().optional(),
+    GROCY_ENABLE_SSL_VERIFY: z.enum(['true', 'false']).optional(),
+    GROCY_MAX_RESPONSE_BYTES: z.string().regex(/^\d+$/).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(),
+    HTTP_CORS_ORIGIN: z.string().optional(),
+    MCP_HTTP_ACCESS_TOKEN: z.string().optional(),
+    MCP_SESSION_IDLE_TIMEOUT_MS: z.string().regex(/^\d+$/).optional(),
+    MCP_SESSION_SWEEP_INTERVAL_MS: z.string().regex(/^\d+$/).optional(),
+    SERIALIZE_STRUCTURED_TO_CONTENT: z.enum(['true', 'false']).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(),
+});
+// YAML configuration schema
+const YamlConfigSchema = z
+    .object({
+    server: z
+        .object({
+        enable_http_server: z.boolean().default(false),
+        http_server_port: z.number().min(1).max(65535).default(8080),
+        /** CORS `Access-Control-Allow-Origin` for HTTP MCP endpoints (`*` or a single origin URL) */
+        http_cors_origin: z.string().min(1).default('*'),
+        /** When set, MCP HTTP/SSE routes require `Authorization: Bearer <token>`, `X-MCP-Access-Token`, or `access_token` query (GET only). */
+        http_access_token: z.string().optional(),
+        /** Reap an idle streamable-HTTP MCP session after this many ms with no requests. Bounds memory when clients reconnect without sending `DELETE /mcp`. */
+        session_idle_timeout_ms: z.number().int().positive().default(300_000),
+        /** How often, in ms, to sweep for idle MCP sessions to reap. */
+        session_sweep_interval_ms: z.number().int().positive().default(60_000),
+        /** When true, tools also serialize structured JSON payload into the content text block for backwards-compatible MCP clients. Default: false. */
+        serialize_structured_to_content: z.boolean().default(false),
+    })
+        .strict()
+        .default({
+        enable_http_server: false,
+        http_server_port: 8080,
+        http_cors_origin: '*',
+        session_idle_timeout_ms: 300_000,
+        session_sweep_interval_ms: 60_000,
+        serialize_structured_to_content: false,
+    }),
+    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),
+        /** Max Grocy API response body size in bytes (all tools); larger responses fail fast */
+        max_response_bytes: z.number().positive().default(DEFAULT_MAX_RESPONSE_BYTES),
+    })
+        .strict()
+        .default({
+        base_url: 'http://localhost:9283',
+        enable_ssl_verify: true,
+        response_size_limit: 10000,
+        max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
+    }),
+    tools: z
+        .record(z.string(), z
+        .object({
+        enabled: z.boolean().default(false),
+        ack_token: z.string().optional(),
+    })
+        .catchall(z.unknown()))
+        .default({}),
+})
+    .strict();
+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,
+            max_response_bytes: this.config.yaml.grocy.max_response_bytes,
+        };
+        this.server = {
+            enable_http_server: this.config.yaml.server.enable_http_server,
+            http_server_port: this.config.yaml.server.http_server_port,
+            http_cors_origin: this.config.yaml.server.http_cors_origin,
+            session_idle_timeout_ms: this.config.yaml.server.session_idle_timeout_ms,
+            session_sweep_interval_ms: this.config.yaml.server.session_sweep_interval_ms,
+            serialize_structured_to_content: this.config.yaml.server.serialize_structured_to_content,
+            ...(this.config.yaml.server.http_access_token !== undefined &&
+                this.config.yaml.server.http_access_token !== '' && {
+                http_access_token: this.config.yaml.server.http_access_token,
+            }),
+        };
+        this.tools = this.config.yaml.tools;
+    }
+    static getInstance() {
+        if (!ConfigManager.instance) {
+            ConfigManager.instance = new ConfigManager();
+        }
+        return ConfigManager.instance;
+    }
+    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() {
+        try {
+            return EnvironmentSchema.parse(process.env);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                logger.error('Invalid environment variables', 'CONFIG');
+                for (const issue of error.issues) {
+                    const path = issue.path?.length ? issue.path.join('.') : '(root)';
+                    logger.error(`${path}: ${issue.message}`, 'CONFIG');
+                }
+                process.exit(1);
+            }
+            throw error;
+        }
+    }
+    loadYamlConfig(configPath) {
+        const yamlPath = this.findConfigFile(configPath);
+        try {
+            let configData = {};
+            if (existsSync(yamlPath)) {
+                const yamlContent = readFileSync(yamlPath, 'utf8');
+                configData = YAML.parse(yamlContent) || {};
+                logger.config(`Loaded YAML config from: ${yamlPath}`);
+            }
+            else {
+                logger.config('No YAML config found, using defaults');
+            }
+            return YamlConfigSchema.parse(configData);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                logger.error('Invalid YAML configuration', 'CONFIG');
+                for (const issue of error.issues) {
+                    const path = issue.path?.length ? issue.path.join('.') : '(root)';
+                    logger.error(`${path}: ${issue.message}`, 'CONFIG');
+                }
+                process.exit(1);
+            }
+            throw error;
+        }
+    }
+    findConfigFile(configPath) {
+        if (configPath)
+            return configPath;
+        // Look for config files in the following order:
+        // 1. Current working directory (for development)
+        // 2. Project root (relative to the compiled main.js)
+        const projectRoot = resolve(__dirname, '../..');
+        const possiblePaths = [
+            resolve(process.cwd(), 'mcp-grocy.yaml'),
+            resolve(process.cwd(), 'mcp-grocy.yml'),
+            resolve(projectRoot, 'mcp-grocy.yaml'),
+            resolve(projectRoot, 'mcp-grocy.yml'),
+        ];
+        return possiblePaths.find((path) => existsSync(path)) ?? possiblePaths[0];
+    }
+    // Public getters
+    getConfig() {
+        return this.config;
+    }
+    getApiUrl() {
+        return this.grocy.base_url.endsWith('/')
+            ? `${this.grocy.base_url}api`
+            : `${this.grocy.base_url}/api`;
+    }
+    getCustomHeaders() {
+        const headers = {};
+        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);
+        }
+        if (env.GROCY_MAX_RESPONSE_BYTES !== undefined) {
+            yaml.grocy.max_response_bytes = parseInt(env.GROCY_MAX_RESPONSE_BYTES, 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);
+        }
+        if (env.HTTP_CORS_ORIGIN !== undefined && env.HTTP_CORS_ORIGIN.length > 0) {
+            yaml.server.http_cors_origin = env.HTTP_CORS_ORIGIN;
+        }
+        if (env.MCP_HTTP_ACCESS_TOKEN !== undefined) {
+            yaml.server.http_access_token =
+                env.MCP_HTTP_ACCESS_TOKEN.length > 0 ? env.MCP_HTTP_ACCESS_TOKEN : undefined;
+        }
+        if (env.MCP_SESSION_IDLE_TIMEOUT_MS !== undefined) {
+            yaml.server.session_idle_timeout_ms = parseInt(env.MCP_SESSION_IDLE_TIMEOUT_MS, 10);
+        }
+        if (env.MCP_SESSION_SWEEP_INTERVAL_MS !== undefined) {
+            yaml.server.session_sweep_interval_ms = parseInt(env.MCP_SESSION_SWEEP_INTERVAL_MS, 10);
+        }
+        if (env.SERIALIZE_STRUCTURED_TO_CONTENT !== undefined) {
+            yaml.server.serialize_structured_to_content = env.SERIALIZE_STRUCTURED_TO_CONTENT === 'true';
+        }
+    }
+    parseToolConfiguration() {
+        const enabledTools = new Set();
+        const toolSubConfigs = new Map();
+        const toolAckTokens = new Map();
+        for (const [toolName, toolConfig] of Object.entries(this.config.yaml.tools)) {
+            if (toolConfig.enabled) {
+                enabledTools.add(toolName);
+                // Store ack_token separately if configured
+                if (toolConfig.ack_token && typeof toolConfig.ack_token === 'string') {
+                    toolAckTokens.set(toolName, toolConfig.ack_token);
+                }
+                // Extract sub-configs (everything except standard fields)
+                const subConfigs = new Map();
+                for (const [key, value] of Object.entries(toolConfig)) {
+                    if (!['enabled', 'ack_token'].includes(key)) {
+                        subConfigs.set(key, value);
+                    }
+                }
+                if (subConfigs.size > 0) {
+                    toolSubConfigs.set(toolName, subConfigs);
+                }
+            }
+        }
+        return { enabledTools, toolSubConfigs, toolAckTokens };
+    }
+}
+// Export singleton instance
+export const config = ConfigManager.getInstance();
+export default config;

package/build/main.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Simplified main entry point
+ * Demonstrates the refactored architecture
+ */
+// Load environment variables
+import 'dotenv/config';
+import { GrocyMcpServer } from './server/mcp-server.js';
+import { config } from './config/index.js';
+import { VERSION, PACKAGE_NAME as SERVER_NAME } from './version.js';
+import { logger } from './utils/logger.js';
+import { ErrorHandler } from './utils/errors.js';
+// Startup banner
+logger.info(`Starting ${SERVER_NAME} v${VERSION}`, 'SERVER');
+async function main() {
+    return ErrorHandler.handleAsync(async () => {
+        // Check API key
+        if (!config.grocy.api_key) {
+            logger.warn('No API key configured. Some operations may fail.', 'CONFIG');
+        }
+        // Log configuration summary
+        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();
+        logger.info('Server started successfully', 'SERVER');
+    }, 'server startup');
+}
+// Error handling
+process.on('uncaughtException', (error) => {
+    logger.error('Uncaught exception', 'PROCESS', { error });
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason, promise) => {
+    logger.error('Unhandled rejection', 'PROCESS', { reason, promise });
+    process.exit(1);
+});
+// Start the application
+main().catch((error) => {
+    logger.error('Failed to start server', 'SERVER', { error });
+    process.exit(1);
+});

package/build/resources/CHANGELOG.md

@@ -1,10 +1,16 @@
-## [2.7.1](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.0...v2.7.1) (2026-09-10)
+## [2.7.2](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.1...v2.7.2) (2026-09-10)
+
+
+### Bug Fixes
+
+* add prepack script, update release configs, and fix docker workflows ([c464c05](https://github.com/miguelangel-nubla/mcp-grocy/commit/c464c054ab4f3f420647196ded7454c60f3702fc))
 
+## [2.7.1](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.0...v2.7.1) (2026-09-10)
 
 ### Bug Fixes
 
-* refuse non-recipe meal plan entries in recipes_cooking_complete before writing ([172d1f0](https://github.com/miguelangel-nubla/mcp-grocy/commit/172d1f0089b1e401736b258cec652a30d90e0215)), closes [#2](https://github.com/miguelangel-nubla/mcp-grocy/issues/2)
-* send correct meal plan payload in recipes_mealplan_add_recipe ([2b180b0](https://github.com/miguelangel-nubla/mcp-grocy/commit/2b180b02b58ab03db69efab727ee53ab88caa0d0)), closes [#2](https://github.com/miguelangel-nubla/mcp-grocy/issues/2)
+- refuse non-recipe meal plan entries in recipes_cooking_complete before writing ([172d1f0](https://github.com/miguelangel-nubla/mcp-grocy/commit/172d1f0089b1e401736b258cec652a30d90e0215)), closes [#2](https://github.com/miguelangel-nubla/mcp-grocy/issues/2)
+- send correct meal plan payload in recipes_mealplan_add_recipe ([2b180b0](https://github.com/miguelangel-nubla/mcp-grocy/commit/2b180b02b58ab03db69efab727ee53ab88caa0d0)), closes [#2](https://github.com/miguelangel-nubla/mcp-grocy/issues/2)
 
 # [2.7.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.6.0...v2.7.0) (2026-08-03)
 

package/build/resources/README.md

@@ -6,6 +6,20 @@
 [![Configuration Status](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/validate-config.yml/badge.svg)](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/validate-config.yml)
 [![CI/CD Pipeline](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/pipeline.yml/badge.svg)](https://github.com/miguelangel-nubla/mcp-grocy/actions/workflows/pipeline.yml)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![Recommended Backend: grocy-next](https://img.shields.io/badge/Recommended%20Backend-grocy--next-brightgreen?logo=docker)](https://github.com/miguelangel-nubla/grocy-next)
+
+> ### 🌟 Recommended Companion: [grocy-next](https://github.com/miguelangel-nubla/grocy-next)
+>
+> While **mcp-grocy** works great with standard upstream [Grocy](https://grocy.info/) (v4.x+), it is primarily developed and daily-driven with **[grocy-next](https://github.com/miguelangel-nubla/grocy-next)**.
+>
+> **grocy-next** is an enhanced, 100% compatible drop-in Docker distribution of Grocy featuring:
+>
+> - 📦 **Container Inventory Management:** Barcode-driven container packing, location hierarchies, and rapid transfers.
+> - ⚖️ **Hardware & Home Assistant Integration:** Native helper integration for smart scales and wireless barcode scanners.
+> - 🖥️ **Live Screens & Pending Scans:** Dedicated live inventory dashboards and async scan queues.
+> - 🥗 **Enhanced Meal Planning:** Calorie breakdown per serving and streamlined meal plan workflows.
+>
+> 👉 If you want the most seamless experience with this MCP, deploy **[miguelangel-nubla/grocy-next](https://github.com/miguelangel-nubla/grocy-next)**!
 
 > **🍴 Opinionated Fork Notice**
 >
@@ -26,10 +40,6 @@
 >
 > If you need complete API access, use the [original fork](https://github.com/saya6k/mcp-grocy-api). This version trades flexibility for focused, dependable grocery management workflows.
 
-> **⚡ Supported Grocy Backends**
->
-> This MCP server is compatible with standard [Grocy](https://grocy.info/) (v4.x+) as well as [grocy-next](https://github.com/miguelangel-nubla/grocy-next) (an enhanced fork with container inventory management and live workflows). The primary environment used by the author is `grocy-next`.
-
 ## 🎯 What This MCP Does
 
 Transform your LLM into an intelligent household management assistant with focused tools for:
@@ -64,7 +74,7 @@ Transform your LLM into an intelligent household management assistant with focus
 
 ## ⚡ Quick Start
 
-1. **Get your Grocy API key** from your Grocy instance (User Settings → API Keys)
+1. **Get your Grocy API key** from your Grocy or [grocy-next](https://github.com/miguelangel-nubla/grocy-next) instance (User Settings → API Keys)
 2. **Set up with Docker Compose:**
 
    ```bash

package/build/resources/api-reference.md

@@ -1,6 +1,6 @@
 # Grocy API Reference
 
-> Auto-generated from https://demo.grocy.info/api/openapi/specification on 2025-05-17T16:56:10.327Z
+> Auto-generated from https://demo.grocy.info/api/openapi/specification on 2026-09-10T20:59:54.572Z
 
 | Path                                                           | Method | Summary                                                                                                                                                                 |
 | -------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -51,6 +51,7 @@
 | /stock/products/{productId}                                    | GET    | Returns details of the given product                                                                                                                                    |
 | /stock/products/{productId}/add                                | POST   | Adds the given amount of the given product to stock                                                                                                                     |
 | /stock/products/{productId}/consume                            | POST   | Removes the given amount of the given product from stock                                                                                                                |
+| /stock/products/{productId}/copy                               | POST   | Copies a product                                                                                                                                                        |
 | /stock/products/{productId}/entries                            | GET    | Returns all stock entries of the given product in order of next use (Opened first, then first due first, then first in first out)                                       |
 | /stock/products/{productId}/inventory                          | POST   | Inventories the given product (adds/removes based on the given new amount)                                                                                              |
 | /stock/products/{productId}/locations                          | GET    | Returns all locations where the given product currently has stock                                                                                                       |

package/build/resources/response-format.md

@@ -159,9 +159,7 @@ If **`system_dev_test_request`** encounters an API error (e.g., authentication f
     "statusCode": 401,
     "statusText": "Unauthorized",
     "timing": "50ms",
-    "headers": {
-      /* ... headers ... */
-    },
+    "headers": {/* ... headers ... */},
     "body": {
       "error_message": "API key is missing or invalid."
     }