mcp-grocy 1.9.0

package/build/resources/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/resources/api-reference.md

@@ -0,0 +1,92 @@
+# Grocy API Reference
+
+> Auto-generated from https://demo.grocy.info/api/openapi/specification on 2025-05-17T16:56:10.327Z
+
+| Path | Method | Summary |
+|------|--------|---------|
+| /batteries | GET | Returns all batteries incl. the next estimated charge time per battery |
+| /batteries/charge-cycles/{chargeCycleId}/undo | POST | Undoes a battery charge cycle |
+| /batteries/{batteryId} | GET | Returns details of the given battery |
+| /batteries/{batteryId}/charge | POST | Tracks a charge cycle of the given battery |
+| /batteries/{batteryId}/printlabel | GET | Prints the Grocycode label of the given battery on the configured label printer |
+| /calendar/ical | GET | Returns the calendar in iCal format |
+| /calendar/ical/sharing-link | GET | Returns a (public) sharing link for the calendar in iCal format |
+| /chores | GET | Returns all chores incl. the next estimated execution time per chore |
+| /chores/executions/calculate-next-assignments | POST | (Re)calculates all next user assignments of all chores |
+| /chores/executions/{executionId}/undo | POST | Undoes a chore execution |
+| /chores/{choreIdToKeep}/merge/{choreIdToRemove} | POST | Merges two chores into one |
+| /chores/{choreId} | GET | Returns details of the given chore |
+| /chores/{choreId}/execute | POST | Tracks an execution of the given chore |
+| /chores/{choreId}/printlabel | GET | Prints the Grocycode label of the given chore on the configured label printer |
+| /files/{group}/{fileName} | GET | Serves the given file |
+| /files/{group}/{fileName} | PUT | Uploads a single file |
+| /files/{group}/{fileName} | DELETE | Deletes the given file |
+| /objects/{entity} | GET | Returns all objects of the given entity |
+| /objects/{entity} | POST | Adds a single object of the given entity |
+| /objects/{entity}/{objectId} | GET | Returns a single object of the given entity |
+| /objects/{entity}/{objectId} | PUT | Edits the given object of the given entity |
+| /objects/{entity}/{objectId} | DELETE | Deletes a single object of the given entity |
+| /print/shoppinglist/thermal | GET | Prints the shoppinglist with a thermal printer |
+| /recipes/fulfillment | GET | Get stock fulfillment information for all recipe |
+| /recipes/{recipeId}/add-not-fulfilled-products-to-shoppinglist | POST | Adds all missing products for the given recipe to the shopping list |
+| /recipes/{recipeId}/consume | POST | Consumes all in stock ingredients of the given recipe (for ingredients that are only partially in stock, the in stock amount will be consumed) |
+| /recipes/{recipeId}/copy | POST | Copies a recipe |
+| /recipes/{recipeId}/fulfillment | GET | Get stock fulfillment information for the given recipe |
+| /recipes/{recipeId}/printlabel | GET | Prints the Grocycode label of the given recipe on the configured label printer |
+| /stock | GET | Returns all products which are currently in stock incl. the next due date per product |
+| /stock/barcodes/external-lookup/{barcode} | GET | Executes an external barcode lookoup via the configured plugin with the given barcode |
+| /stock/bookings/{bookingId} | GET | Returns the given stock booking |
+| /stock/bookings/{bookingId}/undo | POST | Undoes a booking |
+| /stock/entry/{entryId} | GET | Returns details of the given stock |
+| /stock/entry/{entryId} | PUT | Edits the stock entry |
+| /stock/entry/{entryId}/printlabel | GET | Prints the Grocycode / stock entry label of the given entry on the configured label printer |
+| /stock/locations/{locationId}/entries | GET | Returns all stock entries of the given location |
+| /stock/products/by-barcode/{barcode} | GET | Returns details of the given product by its barcode |
+| /stock/products/by-barcode/{barcode}/add | POST | Adds the given amount of the by its barcode given product to stock |
+| /stock/products/by-barcode/{barcode}/consume | POST | Removes the given amount of the by its barcode given product from stock |
+| /stock/products/by-barcode/{barcode}/inventory | POST | Inventories the by its barcode given product (adds/removes based on the given new amount) |
+| /stock/products/by-barcode/{barcode}/open | POST | Marks the given amount of the by its barcode given product as opened |
+| /stock/products/by-barcode/{barcode}/transfer | POST | Transfers the given amount of the by its barcode given product from one location to another (this is currently not supported for tare weight handling enabled products) |
+| /stock/products/{productIdToKeep}/merge/{productIdToRemove} | POST | Merges two products into one |
+| /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}/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 |
+| /stock/products/{productId}/open | POST | Marks the given amount of the given product as opened |
+| /stock/products/{productId}/price-history | GET | Returns the price history of the given product |
+| /stock/products/{productId}/printlabel | GET | Prints the Grocycode label of the given product on the configured label printer |
+| /stock/products/{productId}/transfer | POST | Transfers the given amount of the given product from one location to another (this is currently not supported for tare weight handling enabled products) |
+| /stock/shoppinglist/add-expired-products | POST | Adds expired products to the given shopping list |
+| /stock/shoppinglist/add-missing-products | POST | Adds currently missing products (below defined min. stock amount) to the given shopping list |
+| /stock/shoppinglist/add-overdue-products | POST | Adds overdue products to the given shopping list |
+| /stock/shoppinglist/add-product | POST | Adds the given amount of the given product to the given shopping list |
+| /stock/shoppinglist/clear | POST | Removes all items from the given shopping list |
+| /stock/shoppinglist/remove-product | POST | Removes the given amount of the given product from the given shopping list, if it is on it |
+| /stock/transactions/{transactionId} | GET | Returns all stock bookings of the given transaction id |
+| /stock/transactions/{transactionId}/undo | POST | Undoes a transaction |
+| /stock/volatile | GET | Returns all products which are due soon, overdue, expired or currently missing |
+| /system/config | GET | Returns all config settings |
+| /system/db-changed-time | GET | Returns the time when the database was last changed |
+| /system/info | GET | Returns information about the installed Grocy version, PHP runtime and OS |
+| /system/localization-strings | GET | Returns all localization strings (in the by the user desired language) |
+| /system/log-missing-localization | POST | Logs a missing localization string |
+| /system/time | GET | Returns the current server time |
+| /tasks | GET | Returns all tasks which are not done yet |
+| /tasks/{taskId}/complete | POST | Marks the given task as completed |
+| /tasks/{taskId}/undo | POST | Marks the given task as not completed |
+| /user | GET | Returns the currently authenticated user |
+| /user/settings | GET | Returns all settings of the currently logged in user |
+| /user/settings/{settingKey} | GET | Returns the given setting of the currently logged in user |
+| /user/settings/{settingKey} | PUT | Sets the given setting of the currently logged in user |
+| /user/settings/{settingKey} | DELETE | Deletes the given setting of the currently logged in user |
+| /userfields/{entity}/{objectId} | GET | Returns all userfields with their values of the given object of the given entity |
+| /userfields/{entity}/{objectId} | PUT | Edits the given userfields of the given object of the given entity |
+| /users | GET | Returns all users |
+| /users | POST | Creates a new user |
+| /users/{userId} | PUT | Edits the given user |
+| /users/{userId} | DELETE | Deletes the given user |
+| /users/{userId}/permissions | GET | Returns the assigned permissions of the given user |
+| /users/{userId}/permissions | POST | Adds a permission to the given user |
+| /users/{userId}/permissions | PUT | Replaces the assigned permissions of the given user |

package/build/resources/config.md

@@ -0,0 +1,282 @@
+# MCP Grocy Configuration Guide
+
+Advanced configuration reference for the MCP Grocy server. For basic setup, see the [README](../../README.md).
+
+## 🔧 Configuration Variables
+
+### Core Variables
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `GROCY_BASE_URL` | Your Grocy instance URL | `http://localhost:9283` | ✅ |
+| `GROCY_APIKEY_VALUE` | Your Grocy API key | - | ✅ |
+
+### Optional Variables
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `GROCY_ENABLE_SSL_VERIFY` | SSL certificate verification | `true` | `false` |
+| `REST_RESPONSE_SIZE_LIMIT` | Response size limit (bytes) | `10000` | `50000` |
+
+## 🌐 HTTP Server Configuration
+
+Enable HTTP/SSE transport for web-based access:
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `ENABLE_HTTP_SERVER` | Enable HTTP/SSE transport | `false` | `true` |
+| `HTTP_SERVER_PORT` | HTTP server port | `8080` | `3000` |
+
+### Transport Modes
+- **stdio** (default) - Standard MCP protocol for CLI/desktop clients
+- **HTTP** - Streamable HTTP for web applications (`POST /mcp`)
+- **SSE** - Server-Sent Events for real-time web clients (`GET /mcp/sse`)
+
+## 🛠️ Tool Configuration
+
+### Tool Toggle System
+
+Enable/disable specific tools using the `TOOL__` prefix pattern:
+
+```bash
+# Stock management
+TOOL__get_all_stock=true
+TOOL__purchase_product=true
+TOOL__consume_product=false
+
+# Shopping lists  
+TOOL__get_shopping_list=true
+TOOL__add_shopping_list_item=true
+
+# Meal planning
+TOOL__get_meal_plan=true
+TOOL__add_recipe_to_meal_plan=true
+```
+
+### Available Tool Categories
+
+#### 📦 Stock Management Tools
+```bash
+TOOL__get_all_stock=true                     # Get all stock entries
+TOOL__get_stock_volatile=true                # Get due/expired products
+TOOL__get_stock_by_location=true             # Stock by specific location
+TOOL__inventory_product=true                 # Set stock amounts
+TOOL__purchase_product=true                  # Record purchases
+TOOL__consume_product=true                   # Record consumption
+TOOL__transfer_product=true                  # Move stock between locations
+TOOL__open_product=true                      # Mark products as opened
+```
+
+#### 🛒 Shopping & Planning Tools
+```bash
+TOOL__get_shopping_list=true                 # Get shopping lists
+TOOL__add_shopping_list_item=true            # Add to shopping list
+TOOL__remove_shopping_list_item=true         # Remove from shopping list
+TOOL__get_shopping_locations=true            # Get store locations
+```
+
+#### 🍽️ Recipe & Meal Planning Tools
+```bash
+TOOL__get_recipes=true                       # Get all recipes
+TOOL__get_recipe_by_id=true                  # Get specific recipe
+TOOL__create_recipe=true                     # Create new recipes
+TOOL__get_recipe_fulfillment=true            # Check recipe availability
+TOOL__consume_recipe=true                    # Cook a recipe
+TOOL__get_meal_plan=true                     # Get meal plans
+TOOL__add_recipe_to_meal_plan=true           # Schedule meals
+TOOL__delete_recipe_from_meal_plan=true      # Remove from meal plan
+TOOL__cooked_something=true                  # Complete cooking workflow
+```
+
+#### 🏠 Household Management Tools
+```bash
+TOOL__track_chore_execution=true             # Record chore completion
+TOOL__complete_task=true                     # Mark tasks as done
+TOOL__charge_battery=true                    # Record battery charging
+TOOL__get_chores=true                        # Get all chores
+TOOL__get_tasks=true                         # Get all tasks
+TOOL__get_batteries=true                     # Get battery info
+```
+
+#### 🔧 System & Utility Tools
+```bash
+TOOL__get_products=true                      # Get product information
+TOOL__lookup_product=true                    # Fuzzy product search
+TOOL__get_locations=true                     # Get storage locations
+TOOL__get_quantity_units=true                # Get quantity units
+TOOL__get_users=true                         # Get user information
+TOOL__call_grocy_api=true                    # Make custom API calls
+TOOL__test_request=true                      # Test API endpoints
+```
+
+### Tool Sub-Configuration
+
+Some tools have additional configuration options:
+
+```bash
+# cooked_something tool options
+TOOL__cooked_something__allow_meal_plan_entry_already_done=false
+TOOL__cooked_something__allow_no_meal_plan=false
+TOOL__cooked_something__print_labels=true
+```
+
+## 📋 Configuration Presets
+
+### Read-Only Mode
+Safe for information gathering only:
+```bash
+# Enable only GET operations
+TOOL__get_all_stock=true
+TOOL__get_recipes=true
+TOOL__get_meal_plan=true
+TOOL__get_shopping_list=true
+TOOL__get_products=true
+TOOL__lookup_product=true
+# Disable all modification tools
+TOOL__purchase_product=false
+TOOL__consume_product=false
+TOOL__add_shopping_list_item=false
+```
+
+### Meal Planning Focus
+For meal planning and recipe management:
+```bash
+# Recipe and meal planning tools
+TOOL__get_recipes=true
+TOOL__get_recipe_by_id=true
+TOOL__get_recipe_fulfillment=true
+TOOL__get_meal_plan=true
+TOOL__add_recipe_to_meal_plan=true
+TOOL__delete_recipe_from_meal_plan=true
+TOOL__cooked_something=true
+
+# Supporting tools
+TOOL__get_products=true
+TOOL__lookup_product=true
+TOOL__get_all_stock=true
+TOOL__add_missing_products_to_shopping_list=true
+```
+
+### Stock Management Focus
+For inventory and shopping management:
+```bash
+# Stock operations
+TOOL__get_all_stock=true
+TOOL__get_stock_volatile=true
+TOOL__purchase_product=true
+TOOL__consume_product=true
+TOOL__inventory_product=true
+
+# Shopping management  
+TOOL__get_shopping_list=true
+TOOL__add_shopping_list_item=true
+TOOL__remove_shopping_list_item=true
+
+# Product management
+TOOL__get_products=true
+TOOL__lookup_product=true
+```
+
+## 🔒 Security Considerations
+
+### API Key Security
+- Never commit API keys to version control
+- Use `.env` files for local development
+- Use secure environment variable management in production
+
+### Tool Access Control
+- Disable unused tools to reduce attack surface
+- Use read-only mode for information-gathering use cases
+- Be cautious with tools that modify data (`purchase_product`, `consume_product`, etc.)
+
+### Network Security
+- Use HTTPS for production Grocy instances
+- Consider SSL verification settings carefully
+- Limit response sizes to prevent memory issues
+
+## 📝 Environment File Examples
+
+### Development Configuration
+```bash
+# .env for development
+GROCY_BASE_URL=http://localhost:9283
+GROCY_APIKEY_VALUE=dev_api_key_here
+GROCY_ENABLE_SSL_VERIFY=false
+REST_RESPONSE_SIZE_LIMIT=50000
+
+# Enable HTTP server for testing
+ENABLE_HTTP_SERVER=true
+HTTP_SERVER_PORT=8080
+
+# Enable commonly used tools
+TOOL__get_all_stock=true
+TOOL__get_recipes=true
+TOOL__get_meal_plan=true
+TOOL__lookup_product=true
+```
+
+### Production Configuration
+```bash
+# .env for production
+GROCY_BASE_URL=https://grocy.yourdomain.com
+GROCY_APIKEY_VALUE=secure_production_key
+GROCY_ENABLE_SSL_VERIFY=true
+REST_RESPONSE_SIZE_LIMIT=20000
+
+# Selective tool enablement for security
+TOOL__get_all_stock=true
+TOOL__get_recipes=true
+TOOL__add_recipe_to_meal_plan=true
+TOOL__get_shopping_list=true
+# Explicitly disable sensitive operations
+TOOL__call_grocy_api=false
+TOOL__test_request=false
+```
+
+## 🔄 Configuration Management
+
+### Loading Order
+1. Default values
+2. Environment variables
+3. `.env` file (if present)
+
+### Validation
+- Server validates all tool names at startup
+- Invalid configuration prevents server start
+- Error messages show valid options
+
+### Runtime Changes
+- Configuration changes require server restart
+- Use process managers (PM2, systemd) for production restarts
+- Docker containers need to be recreated with new environment
+
+## 🐛 Troubleshooting Configuration
+
+### Common Issues
+
+**Tool toggle not working**
+- Check exact spelling of tool names
+- Ensure `TOOL__` prefix is correct
+- Verify boolean values (`true`/`false`)
+
+**SSL/TLS connection errors**
+- Set `GROCY_ENABLE_SSL_VERIFY=false` for self-signed certificates
+- Verify Grocy URL is accessible
+- Check firewall and network settings
+
+**Large response errors**
+- Increase `REST_RESPONSE_SIZE_LIMIT`
+- Consider disabling unused tools to reduce response size
+- Check Grocy instance has reasonable data volumes
+
+### Debugging Configuration
+```bash
+# Use mock mode to test configuration
+npm run dev
+
+# Enable MCP inspector for protocol debugging  
+npm run inspector
+
+# Check configuration loading
+# (Server logs show loaded configuration at startup)
+```