mcp-grocy 1.9.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2024 Christian Pedersen
+Copyright (c) 2024 saya6k
+Copyright (c) 2025 miguelangel-nubla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# MCP Grocy
+
+[![npm version](https://img.shields.io/npm/v/mcp-grocy.svg)](https://www.npmjs.com/package/mcp-grocy)
+[![Docker Image](https://img.shields.io/badge/docker%20image-ghcr.io-blue)](https://github.com/miguelangel-nubla/mcp-grocy/pkgs/container/mcp-grocy)
+[![License](https://img.shields.io/github/license/miguelangel-nubla/mcp-grocy)](LICENSE)
+[![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)
+
+> **🍴 Opinionated Fork Notice**
+> 
+> This is a heavily opinionated fork of [saya6k/mcp-grocy-api](https://github.com/saya6k/mcp-grocy-api) that has diverged significantly to warrant a separate identity. This MCP prioritizes **usability over features**.
+>
+> **Why This Fork Exists:**
+> - The original wrapper exposes the entire Grocy API unprocessed, leading to context overload and LLM confusion
+> - Grocy's API design choices and limitations cause error-prone interactions
+> - Generic API exposure increases hallucination and near-miss results
+> 
+> **This Fork's Philosophy:**
+> - **Filters and augments data** with relevant context for better LLM comprehension
+> - **Reduces API calls** by combining common operations to minimize error chains
+> - **Optimizes for reliability and repeatability** over feature completeness
+> - **Opinionated workflows** that may not match everyone's preferences
+> 
+> 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.
+
+## 🎯 What This MCP Does
+
+Transform your LLM into an intelligent household management assistant with focused tools for:
+
+### 📦 **Stock Management**
+- Track inventory across multiple locations with precision
+- Record purchases and consumption with automatic stock updates
+- Monitor expiry dates and get volatile stock alerts
+- Transfer products between storage locations
+
+### 🛒 **Smart Shopping & Planning**
+- Maintain shopping lists with intelligent quantity management
+- Plan meals with recipe scheduling and fulfillment checking
+- Automatically add missing ingredients to shopping lists
+- Track shopping locations and optimize store visits
+
+### 🍽️ **Recipe & Meal Workflows** 
+- Find recipes with fuzzy search capabilities
+- Check if recipes can be made with current stock
+- Complete cooking workflows with portion control
+- Integrate meal planning with inventory consumption
+
+### 🏠 **Household Management**
+- Manage chores, tasks, and battery tracking
+- Get product price history for budgeting
+- Organize products by groups and categories
+- Print labels for stock entries
+
+## ⚡ Quick Start
+
+1. **Get your Grocy API key** from your Grocy instance (User Settings → API Keys)
+2. **Set up with Docker Compose:**
+   ```bash
+   # Get the project
+   git clone https://github.com/miguelangel-nubla/mcp-grocy.git
+   cd mcp-grocy
+   
+   # Configure
+   cp .env.example .env
+   # Edit .env with your GROCY_BASE_URL and GROCY_APIKEY_VALUE
+   
+   # Run
+   docker compose up -d
+   ```
+
+### Try Without Grocy
+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
+
+npm install && npm run dev
+```
+
+## Installation
+
+### NPM
+
+```bash
+git clone -b main https://github.com/miguelangel-nubla/mcp-grocy.git
+cd mcp-grocy
+npm install
+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 Compose (Recommended)
+
+Create a `docker-compose.yml`:
+```yaml
+services:
+  mcp-grocy:
+    image: ghcr.io/miguelangel-nubla/mcp-grocy:latest
+    env_file:
+      - .env
+    restart: unless-stopped
+```
+
+Then:
+```bash
+cp .env.example .env
+# Edit .env with your configuration
+docker compose up -d
+```
+
+## ⚙️ Configuration
+
+### Quick Setup
+
+1. **Get your Grocy API key:**
+   - Open your Grocy instance → **User Settings** → **API Keys**
+   - Create a new API key and copy it
+
+2. **Configure the server:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your GROCY_BASE_URL and GROCY_APIKEY_VALUE
+   ```
+
+3. **Essential variables:**
+   - `GROCY_BASE_URL` - Your Grocy instance URL
+   - `GROCY_APIKEY_VALUE` - 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` |
+| **Tool toggles** | Customize functionality | Edit `TOOL__*` variables in `.env` |
+
+📖 **For complete configuration reference:** See [Configuration Guide](src/resources/config.md)
+
+## 🚀 Usage Modes
+
+### Production Mode
+Start with your real Grocy instance:
+```bash
+npm start
+```
+
+### Development/Testing Mode
+Use mock data (no Grocy instance required):
+```bash
+npm run dev
+```
+
+### HTTP Server Mode  
+Enable web-based access via HTTP/SSE:
+```bash
+# In .env: ENABLE_HTTP_SERVER=true
+npm start
+# Access via http://localhost:8080/mcp
+```
+
+
+## 📚 Documentation & Resources
+
+| Resource | Purpose | When to Use |
+|----------|---------|-------------|
+| [📖 API Reference](src/resources/api-reference.md) | Complete tool documentation | Tool usage and examples |
+| [⚙️ Configuration Guide](src/resources/config.md) | Advanced configuration reference | Detailed setup, presets, troubleshooting |
+| [📋 .env.example](.env.example) | Configuration template with ALL tools | Copy and customize for your setup |
+| [🧪 MCP Inspector](https://github.com/modelcontextprotocol/inspector) | Protocol debugging | Debug MCP interactions |
+
+### 🆘 Troubleshooting
+
+#### Common Issues
+
+**"Connection refused" or "Cannot connect to Grocy"**
+- Verify `GROCY_BASE_URL` is correct and accessible
+- Check that your Grocy instance is running
+- 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
+- Check that the API key exists in your Grocy instance (User Settings → API Keys)
+- Ensure the API key has proper permissions
+
+**"Tool not found" errors**
+- Check if the tool is enabled in your `.env` file (tool toggles)
+- Verify you're using the correct tool names from the API reference
+
+**Large response errors**
+- Increase `REST_RESPONSE_SIZE_LIMIT` if you have many products/stock entries
+- Consider using tool toggles to disable unused functionality
+
+#### Debug Mode
+
+Enable detailed logging and use the MCP inspector:
+```bash
+# Launch MCP inspector for protocol debugging
+npm run inspector
+
+# Run with mock data for testing
+npm run dev
+```
+
+## 🛠️ Development
+
+### Prerequisites
+
+- Node.js 18 or higher
+- Grocy instance (optional with mock mode)
+
+### Development Setup
+
+```bash
+# Clone and install
+git clone https://github.com/miguelangel-nubla/mcp-grocy.git
+cd mcp-grocy
+npm install
+
+# Configure for development
+cp .env.example .env
+# Edit .env with your settings (or use mock values)
+
+# Build and run
+npm run build
+npm start
+```
+
+### Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build TypeScript to JavaScript |
+| `npm run watch` | Watch mode for development |
+| `npm run dev` | Start with mock data (no Grocy needed) |
+| `npm test` | Run test suite |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run inspector` | Launch MCP protocol inspector |
+
+### Debugging
+
+Use the MCP inspector to debug protocol interactions:
+```bash
+npm run inspector
+```
+
+This launches a web interface for testing MCP tools and viewing protocol messages.
+
+## 🤝 Contributing
+
+This is an **opinionated fork** focused on LLM usability and workflow reliability. Contributions are welcome but must align with the core philosophy:
+
+### ✅ Welcome Contributions
+- Bug fixes and reliability improvements
+- Better error handling and validation  
+- Documentation improvements
+- Test coverage enhancements
+- Performance optimizations
+
+### ❌ Contributions Requiring Discussion
+- New tool additions (must demonstrate clear LLM workflow benefits)
+- API design changes that increase complexity
+- Features that expose raw Grocy API behavior
+
+### Development Workflow
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Run `npm test` and ensure all tests pass  
+5. Submit a pull request with clear description
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+**🏠 Made for reliable household management with LLMs**  
+*Prioritizing workflow efficiency over feature completeness*

package/build/api/client.js

@@ -0,0 +1,154 @@
+import axios from 'axios';
+import https from 'https';
+import config from '../config/environment.js';
+export class ApiError extends Error {
+    status;
+    response;
+    constructor(message, status, response) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.response = response;
+    }
+}
+export class GrocyApiClient {
+    axiosInstance;
+    API_KEY_HEADER = 'GROCY-API-KEY';
+    constructor() {
+        const { GROCY_ENABLE_SSL_VERIFY, GROCY_APIKEY_VALUE } = config.get();
+        this.axiosInstance = axios.create({
+            baseURL: config.getGrocyBaseUrl(),
+            validateStatus: () => true, // Allow any status code
+            timeout: 30000, // 30 seconds timeout
+            httpsAgent: GROCY_ENABLE_SSL_VERIFY ? undefined : new https.Agent({
+                rejectUnauthorized: false
+            })
+        });
+        // Set default authentication if available
+        if (GROCY_APIKEY_VALUE) {
+            this.axiosInstance.defaults.headers.common[this.API_KEY_HEADER] = GROCY_APIKEY_VALUE;
+        }
+        // Add request interceptor for logging
+        this.axiosInstance.interceptors.request.use((config) => {
+            console.error(`[API] ${config.method?.toUpperCase()} ${config.url}`);
+            if (config.data) {
+                console.error(`[API] Request body: ${JSON.stringify(config.data)}`);
+            }
+            return config;
+        }, (error) => {
+            console.error('[API] Request error:', error);
+            return Promise.reject(error);
+        });
+        // Add response interceptor for error handling
+        this.axiosInstance.interceptors.response.use((response) => {
+            if (response.status >= 400) {
+                console.error(`[API] Error response (${response.status}): ${JSON.stringify(response.data)}`);
+            }
+            return response;
+        }, (error) => {
+            console.error('[API] Response error:', error);
+            return Promise.reject(error);
+        });
+    }
+    normalizeEndpoint(endpoint) {
+        // Standardize path handling
+        let normalizedEndpoint = endpoint;
+        // Check if endpoint explicitly starts with /api/ - use it as is
+        if (endpoint.startsWith('/api/')) {
+            normalizedEndpoint = endpoint;
+        }
+        // Handle endpoints that start with api/ without leading slash
+        else if (endpoint.startsWith('api/')) {
+            normalizedEndpoint = `/${endpoint}`;
+        }
+        // All other endpoints - ensure they start with /api/
+        else {
+            if (endpoint.startsWith('/')) {
+                normalizedEndpoint = `/api${endpoint}`;
+            }
+            else {
+                normalizedEndpoint = `/api/${endpoint}`;
+            }
+        }
+        console.error(`[API] Normalized endpoint: ${normalizedEndpoint}`);
+        return normalizedEndpoint;
+    }
+    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;
+        let url = this.normalizeEndpoint(endpoint);
+        // Add query parameters
+        if (Object.keys(queryParams).length > 0) {
+            const queryString = this.buildQueryString(queryParams);
+            url += `?${queryString}`;
+        }
+        const requestConfig = {
+            method,
+            url,
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+                ...config.getCustomHeaders(),
+                ...headers
+            },
+            timeout
+        };
+        if (['POST', 'PUT', 'PATCH'].includes(method) && body !== null) {
+            requestConfig.data = body;
+        }
+        try {
+            const response = await this.axiosInstance.request(requestConfig);
+            if (response.status >= 400) {
+                throw new ApiError(`API error (${response.status}): ${JSON.stringify(response.data)}`, response.status, response.data);
+            }
+            return {
+                data: response.data,
+                status: response.status,
+                headers: response.headers
+            };
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const axiosError = error;
+                if (axiosError.code === 'ECONNABORTED') {
+                    throw new ApiError('Connection timeout: The server took too long to respond');
+                }
+                else if (axiosError.code === 'ECONNRESET' || axiosError.message.includes('socket hang up')) {
+                    throw new ApiError('Connection reset: The server unexpectedly closed the connection');
+                }
+                else if (!axiosError.response) {
+                    throw new ApiError('Network error: Unable to reach the Grocy server');
+                }
+            }
+            // Re-throw ApiError instances
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            // Wrap other errors
+            throw new ApiError(`Request failed: ${error.message || error}`);
+        }
+    }
+    // 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 a singleton instance
+export const apiClient = new GrocyApiClient();
+export default apiClient;

package/build/config/environment.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+// Environment variable schema with validation and defaults
+const EnvironmentSchema = z.object({
+    // Grocy Configuration
+    GROCY_BASE_URL: z.string().url().default('http://localhost:9283'),
+    GROCY_APIKEY_VALUE: z.string().optional(),
+    GROCY_ENABLE_SSL_VERIFY: z.string().default('true').transform(val => val !== 'false'),
+    // Server Configuration
+    ENABLE_HTTP_SERVER: z.string().default('false').transform(val => ['true', 'yes', '1', 'on', 'enabled'].includes(val.toLowerCase())),
+    HTTP_SERVER_PORT: z.string().default('8080').transform(val => parseInt(val, 10)),
+    // API Configuration
+    REST_RESPONSE_SIZE_LIMIT: z.string().default('10000').transform(val => {
+        const parsed = parseInt(val, 10);
+        if (isNaN(parsed) || parsed <= 0) {
+            throw new Error('REST_RESPONSE_SIZE_LIMIT must be a positive number');
+        }
+        return parsed;
+    }),
+    // Build Configuration
+    RELEASE_VERSION: z.string().optional(),
+});
+export class ConfigManager {
+    static instance;
+    config;
+    constructor() {
+        try {
+            this.config = EnvironmentSchema.parse(process.env);
+            this.validateConfiguration();
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                console.error('[CONFIG ERROR] Invalid environment variables:');
+                error.errors.forEach(err => {
+                    console.error(`  - ${err.path.join('.')}: ${err.message}`);
+                });
+                process.exit(1);
+            }
+            throw error;
+        }
+    }
+    static getInstance() {
+        if (!ConfigManager.instance) {
+            ConfigManager.instance = new ConfigManager();
+        }
+        return ConfigManager.instance;
+    }
+    validateConfiguration() {
+        // Custom validation logic
+        if (this.config.HTTP_SERVER_PORT < 1 || this.config.HTTP_SERVER_PORT > 65535) {
+            throw new Error('HTTP_SERVER_PORT must be between 1 and 65535');
+        }
+        // Log important configuration
+        console.error(`[CONFIG] Grocy Base URL: ${this.config.GROCY_BASE_URL}`);
+        console.error(`[CONFIG] SSL Verification: ${this.config.GROCY_ENABLE_SSL_VERIFY ? 'enabled' : 'disabled'}`);
+        console.error(`[CONFIG] HTTP Server: ${this.config.ENABLE_HTTP_SERVER ? `enabled on port ${this.config.HTTP_SERVER_PORT}` : 'disabled'}`);
+        console.error(`[CONFIG] Response Size Limit: ${this.config.REST_RESPONSE_SIZE_LIMIT} bytes`);
+    }
+    get() {
+        return this.config;
+    }
+    getGrocyBaseUrl() {
+        return this.config.GROCY_BASE_URL.replace(/\/+$/, '');
+    }
+    getApiUrl() {
+        return `${this.getGrocyBaseUrl()}/api`;
+    }
+    hasApiKeyAuth() {
+        return !!this.config.GROCY_APIKEY_VALUE;
+    }
+    getCustomHeaders() {
+        const headers = {};
+        const headerPrefix = /^header_/i;
+        for (const [key, value] of Object.entries(process.env)) {
+            if (headerPrefix.test(key) && value !== undefined) {
+                const headerName = key.replace(headerPrefix, '');
+                headers[headerName] = value;
+            }
+        }
+        return headers;
+    }
+    parseToolConfiguration() {
+        const enabledTools = new Set();
+        const disabledTools = new Set();
+        const toolSubConfigs = new Map();
+        const errors = [];
+        // Scan all environment variables for TOOL__ patterns
+        for (const [key, value] of Object.entries(process.env)) {
+            if (!key.startsWith('TOOL__'))
+                continue;
+            const parts = key.split('__');
+            if (parts.length === 3) {
+                // TOOL__tool_name__sub_config
+                const toolName = parts[1];
+                const subConfig = parts[2];
+                if (!toolSubConfigs.has(toolName)) {
+                    toolSubConfigs.set(toolName, new Map());
+                }
+                toolSubConfigs.get(toolName).set(subConfig, value === 'true');
+            }
+            else if (parts.length === 2) {
+                // TOOL__tool_name
+                const toolName = parts[1];
+                if (value === 'true') {
+                    enabledTools.add(toolName);
+                }
+                else if (value === 'false') {
+                    disabledTools.add(toolName);
+                }
+                else {
+                    errors.push(`${key}=${value} (must be 'true' or 'false')`);
+                }
+            }
+        }
+        // Error out if invalid values found
+        if (errors.length > 0) {
+            console.error('[CONFIG ERROR] Invalid TOOL_ configuration values:');
+            errors.forEach(error => console.error(`  - ${error}`));
+            console.error('All TOOL_ variables must be set to either "true" or "false"');
+            process.exit(1);
+        }
+        if (enabledTools.size > 0) {
+            console.error(`[CONFIG] Enabled tools (${enabledTools.size}): ${Array.from(enabledTools).sort().join(', ')}`);
+        }
+        else {
+            console.error('[CONFIG] No tools enabled - all tools are disabled by default');
+        }
+        if (disabledTools.size > 0) {
+            console.error(`[CONFIG] Explicitly disabled tools (${disabledTools.size}): ${Array.from(disabledTools).sort().join(', ')}`);
+        }
+        // Log sub-configurations
+        if (toolSubConfigs.size > 0) {
+            console.error('[CONFIG] Tool sub-configurations:');
+            for (const [toolName, subConfigs] of toolSubConfigs) {
+                const subConfigList = Array.from(subConfigs.entries()).map(([key, value]) => `${key}=${value}`);
+                console.error(`  - ${toolName}: ${subConfigList.join(', ')}`);
+            }
+        }
+        return { enabledTools, toolSubConfigs };
+    }
+}
+export const config = ConfigManager.getInstance();
+export default config;

package/build/main.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Load environment variables from .env file
+import 'dotenv/config';
+import { GrocyMcpServer } from './server/mcp-server.js';
+import config from './config/environment.js';
+import { VERSION, PACKAGE_NAME as SERVER_NAME } from './version.js';
+// Debug output to help identify version and naming issues
+console.error(`Starting ${SERVER_NAME} server version ${VERSION}`);
+async function main() {
+    try {
+        // Validate configuration early
+        const envConfig = config.get();
+        // Ensure required environment variables
+        if (!config.hasApiKeyAuth()) {
+            console.error('[WARNING] No GROCY_APIKEY_VALUE configured. Some API calls may fail.');
+        }
+        // Create and start the server
+        const server = new GrocyMcpServer();
+        await server.start();
+    }
+    catch (error) {
+        console.error('[ERROR] Failed to start server:', error);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error('[FATAL] Unhandled error:', error);
+    process.exit(1);
+});