mcp-grocy 2.2.0 → 2.6.0

package/build/resources/config.md

@@ -1,40 +1,56 @@
-# MCP Grocy Configuration Guide
+# mcp-grocy configuration guide
 
-Advanced configuration reference for the MCP Grocy server. For basic setup, see the [README](../../README.md).
+Advanced configuration reference for the **mcp-grocy** npm package (this MCP server). It connects to your **Grocy** instance via `GROCY_BASE_URL` / `GROCY_API_KEY`. 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_API_KEY` | Your Grocy API key | - | ✅ |
+| Variable         | Description             | Default                 | Required |
+| ---------------- | ----------------------- | ----------------------- | -------- |
+| `GROCY_BASE_URL` | Your Grocy instance URL | `http://localhost:9283` | ✅       |
+| `GROCY_API_KEY`  | 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` |
+| 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` |
+| Variable                        | Description                                          | Default  | Example  |
+| ------------------------------- | ---------------------------------------------------- | -------- | -------- |
+| `ENABLE_HTTP_SERVER`            | Enable HTTP/SSE transport                            | `false`  | `true`   |
+| `HTTP_SERVER_PORT`              | HTTP server port                                     | `8080`   | `3000`   |
+| `MCP_SESSION_IDLE_TIMEOUT_MS`   | Reap an idle MCP session after this many ms          | `300000` | `600000` |
+| `MCP_SESSION_SWEEP_INTERVAL_MS` | How often, in ms, to sweep for idle sessions to reap | `60000`  | `30000`  |
+
+The matching YAML keys are `server.session_idle_timeout_ms` and `server.session_sweep_interval_ms`.
 
 ### 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`)
 
+### Session Reaping (HTTP mode)
+
+In HTTP mode the server keeps a transport and per-session MCP server instance for
+each session. Clients that disconnect without sending `DELETE /mcp`, or that
+reconnect with a new session id, would otherwise leave those instances in memory.
+The server reaps any session with no requests for `MCP_SESSION_IDLE_TIMEOUT_MS`,
+freeing its resources. A reaped client transparently re-initializes on its next
+request, so the default of 5 minutes is safe for normal use; lower it on
+memory-constrained hosts or raise it if a client legitimately idles for long
+periods between calls.
+
 ## 🛠️ Tool Configuration
 
-Tools are configured using the YAML configuration file `mcp-grocy.yaml`. 
+Tools are configured using the YAML configuration file `mcp-grocy.yaml`.
 
 Copy `mcp-grocy.yaml.example` to `mcp-grocy.yaml` and customize the `tools` section to enable/disable specific functionality.
 
@@ -57,16 +73,19 @@ Configuration examples for common use cases are provided in `mcp-grocy.yaml.exam
 ## 🔒 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 (`inventory_transactions_purchase`, `inventory_stock_entry_consume`, etc.)
 
 ### Network Security
+
 - Use HTTPS for production Grocy instances
 - Consider SSL verification settings carefully
 - Limit response sizes to prevent memory issues
@@ -74,6 +93,7 @@ Configuration examples for common use cases are provided in `mcp-grocy.yaml.exam
 ## 📝 Environment File Examples
 
 ### Development Configuration
+
 ```bash
 # .env for development
 GROCY_BASE_URL=http://localhost:9283
@@ -87,6 +107,7 @@ HTTP_SERVER_PORT=8080
 ```
 
 ### Production Configuration
+
 ```bash
 # .env for production
 GROCY_BASE_URL=https://grocy.yourdomain.com
@@ -100,16 +121,19 @@ Tool configuration should be done via `mcp-grocy.yaml` file.
 ## 🔄 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
@@ -119,28 +143,32 @@ Tool configuration should be done via `mcp-grocy.yaml` file.
 ### Common Issues
 
 **Tool configuration not working**
+
 - Check YAML syntax and indentation
 - Verify tool names match current naming convention
 - Ensure `mcp-grocy.yaml` file is in the correct location
 
 **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  
+# Enable MCP inspector for protocol debugging
 npm run inspector
 
 # Check configuration loading
 # (Server logs show loaded configuration at startup)
-```
+```

package/build/resources/examples.md

@@ -1,319 +1,218 @@
-# Grocy API Testing Examples
+# Grocy MCP usage examples
 
-## Setting Up Your Private Demo Instance
+> **MCP server name:** Your client names this server in its config (`mcp-grocy`, `grocy`, etc.). The first argument to helpers like `use_mcp_tool` must match **your** setup. Examples below use `mcp-grocy`.
 
-Before testing the API, you can create your own private Grocy demo instance:
+## Setting up a private Grocy demo
 
 1. Visit [https://demo.grocy.info](https://demo.grocy.info).
-2. Look for "Create a private demo instance" section
-3. Create your personal instance which will remain available for testing
-4. Use the provided API key and URL in your `.env` file:
+2. Use **Create a private demo instance**.
+3. Put URL and API key in `.env`:
+
    ```
    GROCY_BASE_URL=https://your-name-xxxxx.demo.grocy.info
    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.
+For **`system_dev_call_api`** / **`system_dev_test_request`**, pass endpoint **paths** only (no full URL), e.g. `objects/products` or `/api/stock`—the client resolves them against `GROCY_BASE_URL`.
 
-For example, if the base URL is `https://your-own-demo.grocy.info`:
-✅ Correct: `"/api/objects/products"` → Resolves to: `https://your-own-demo.grocy.info/api/objects/products`
-❌ Incorrect: `"https://your-own-demo.grocy.info/api/objects/products"` or `"www.grocy.example.com/api/objects/products"`
+## Inventory and shopping
 
-## Basic API Tools
+### All stock entries
 
-### Get Current Stock
 ```typescript
-use_mcp_tool('grocy-api', 'get_stock', {});
+use_mcp_tool('mcp-grocy', 'inventory_stock_get_all', {});
 ```
 
-### Get Volatile Stock Information
+### Volatile stock (due / overdue / missing)
+
 ```typescript
-use_mcp_tool('grocy-api', 'get_stock_volatile', {
-  "includeDetails": true
+use_mcp_tool('mcp-grocy', 'inventory_stock_get_volatile', {
+  includeDetails: true,
 });
 ```
 
-### Get All Products
-```typescript
-use_mcp_tool('grocy-api', 'get_products', {});
-```
+### Products (pick fields)
 
-### Get All Shopping List Items
 ```typescript
-use_mcp_tool('grocy-api', 'get_shopping_list', {});
+use_mcp_tool('mcp-grocy', 'inventory_products_get', {
+  fields: ['id', 'name', 'description'],
+});
 ```
 
-### Add Item to Shopping List
+### Shopping list
+
 ```typescript
-use_mcp_tool('grocy-api', 'add_shopping_list_item', {
-  "productId": 1,
-  "amount": 2,
-  "shoppingListId": 1,
-  "note": "Get the organic variety"
+use_mcp_tool('mcp-grocy', 'shopping_list_get', {});
+
+use_mcp_tool('mcp-grocy', 'shopping_list_add_item', {
+  productId: 1,
+  amount: 2,
+  shoppingListId: 1,
+  note: 'Get the organic variety',
 });
 ```
 
-### Purchase a Product
+### Purchase (product-level)
+
 ```typescript
-use_mcp_tool('grocy-api', 'inventory_transactions_purchase', {
-  "productId": 1,
-  "amount": 2,
-  "bestBeforeDate": "2024-12-31",
-  "price": 3.99,
-  "storeId": 1
+use_mcp_tool('mcp-grocy', 'inventory_transactions_purchase', {
+  productId: 1,
+  amount: 2,
+  bestBeforeDate: '2024-12-31',
+  price: 3.99,
+  locationId: 1,
 });
 ```
 
-### Consume a Product
+### Consume one stock row (`stockId` from `inventory_stock_get_by_product`)
+
 ```typescript
-use_mcp_tool('grocy-api', 'inventory_stock_entry_consume', {
-  "productId": 1,
-  "amount": 1,
-  "spoiled": false
+use_mcp_tool('mcp-grocy', 'inventory_stock_entry_consume', {
+  stockId: 10,
+  productId: 1,
+  amount: 1,
+  spoiled: false,
 });
 ```
 
-## Recipe and Meal Planning
+## Recipes and meal plan
+
+### List recipes (selected fields)
 
-### Get All Recipes
 ```typescript
-use_mcp_tool('grocy-api', 'get_recipes', {});
+use_mcp_tool('mcp-grocy', 'recipes_management_get', {
+  fields: ['id', 'name', 'description', 'base_servings'],
+});
 ```
 
-### Check Recipe Fulfillment
+### Fulfillment for one recipe
+
 ```typescript
-use_mcp_tool('grocy-api', 'get_recipe_fulfillment', {
-  "recipeId": 1,
-  "servings": 2
+use_mcp_tool('mcp-grocy', 'recipes_fulfillment_get', {
+  recipeId: 1,
+  onlyMissing: false,
 });
 ```
 
-### Get Meal Plan for a Date
+### Meal plan for a date
+
 ```typescript
-use_mcp_tool('grocy-api', 'get_meal_plan', {
-  "date": "2024-07-01"
+use_mcp_tool('mcp-grocy', 'recipes_mealplan_get', {
+  date: '2024-07-01',
+  weekly: false,
 });
 ```
 
-### Get Meal Plan Sections
+### Meal plan sections (Breakfast / Dinner / …)
+
 ```typescript
-use_mcp_tool('grocy-api', 'get_meal_plan_sections', {});
+use_mcp_tool('mcp-grocy', 'recipes_mealplan_get_sections', {});
 ```
 
-### Add Recipe to Meal Plan
+### Add recipe to meal plan
+
 ```typescript
-use_mcp_tool('grocy-api', 'add_recipe_to_meal_plan', {
-  "recipeId": 1,
-  "day": "2024-07-01", 
-  "servings": 2,
-  "section_id": 3
+use_mcp_tool('mcp-grocy', 'recipes_mealplan_add_recipe', {
+  recipeId: 1,
+  day: '2024-07-01',
+  servings: 2,
+  sectionId: 3,
 });
 ```
 
-Note: Use get_meal_plan_sections to find valid section IDs for your Grocy instance.
+Use **`recipes_mealplan_get_sections`** for valid `sectionId` values.
+
+### Remove a meal plan entry
 
-### Delete Recipe from Meal Plan
 ```typescript
-use_mcp_tool('grocy-api', 'delete_recipe_from_meal_plan', {
-  "date": "2024-07-01",
-  "meal_plan_entry_id": 123
+use_mcp_tool('mcp-grocy', 'recipes_mealplan_delete_entry', {
+  mealPlanEntryId: 123,
 });
 ```
 
-Note: Use get_meal_plan to find the meal_plan_entry_id of the entry you want to remove.
+Use **`recipes_mealplan_get`** to find `mealPlanEntryId`.
+
+### Cook / consume recipe ingredients
 
-### Consume Recipe Ingredients
 ```typescript
-use_mcp_tool('grocy-api', 'consume_recipe', {
-  "recipeId": 1,
-  "servings": 2
+use_mcp_tool('mcp-grocy', 'recipes_cooking_consume', {
+  recipeId: 1,
+  servings: 2,
 });
 ```
 
-## Chores and Tasks
+## Chores, tasks, locations
+
+### Chores (recurring) vs tasks (to-dos)
 
-### Get All Chores
 ```typescript
-use_mcp_tool('grocy-api', 'get_chores', {});
+use_mcp_tool('mcp-grocy', 'household_chores_get', {});
+use_mcp_tool('mcp-grocy', 'household_tasks_get', {});
 ```
 
-### Track Chore Execution
+### Track chore execution
+
 ```typescript
-use_mcp_tool('grocy-api', 'track_chore_execution', {
-  "choreId": 1,
-  "executedBy": 1,
-  "tracked_time": "2024-06-30 15:30:00"
+use_mcp_tool('mcp-grocy', 'household_chores_execute', {
+  choreId: 1,
+  executedBy: 1,
+  trackedTime: '2024-06-30 15:30:00',
 });
 ```
 
-### Get All Tasks
-```typescript
-use_mcp_tool('grocy-api', 'get_tasks', {});
-```
+### Complete a task
 
-### Complete a Task
 ```typescript
-use_mcp_tool('grocy-api', 'complete_task', {
-  "taskId": 1,
-  "note": "Task completed successfully"
+use_mcp_tool('mcp-grocy', 'household_tasks_complete', {
+  taskId: 1,
+  note: 'Task completed successfully',
 });
 ```
 
-## Locations and Organization
+### Storage locations vs shopping (store) locations
 
-### Get All Locations
 ```typescript
-use_mcp_tool('grocy-api', 'get_locations', {});
+use_mcp_tool('mcp-grocy', 'system_locations_get', {});
+use_mcp_tool('mcp-grocy', 'shopping_locations_get', {});
 ```
 
-### Get All Shopping Locations (Stores)
-```typescript
-use_mcp_tool('grocy-api', 'get_shopping_locations', {});
-```
+### Transfer one stock row to another location
 
-### Transfer Product Between Locations
 ```typescript
-use_mcp_tool('grocy-api', 'inventory_stock_entry_transfer', {
-  "productId": 1,
-  "amount": 1,
-  "locationIdFrom": 1,
-  "locationIdTo": 2,
-  "note": "Moving to kitchen"
+use_mcp_tool('mcp-grocy', 'inventory_stock_entry_transfer', {
+  stockId: 10,
+  productId: 1,
+  amount: 1,
+  locationIdTo: 2,
+  note: 'Moving to kitchen',
 });
 ```
 
-## Advanced API Usage
+For moving by product without a `stockId`, use **`inventory_transactions_transfer`**.
+
+## Advanced / escape hatches
 
-### Custom API Call
-If you need to access a Grocy API endpoint not covered by the specialized tools:
+### Arbitrary Grocy API object path
 
 ```typescript
-use_mcp_tool('grocy-api', 'call_grocy_api', {
-  "endpoint": "objects/product_barcodes",
-  "method": "GET"
+use_mcp_tool('mcp-grocy', 'system_dev_call_api', {
+  endpoint: 'objects/product_barcodes',
+  method: 'GET',
 });
 ```
 
-### Raw API Testing
-For detailed testing with full control over the request:
+### Raw request with full diagnostics
 
 ```typescript
-use_mcp_tool('grocy-api', 'test_request', {
-  "method": "GET",
-  "endpoint": "/api/stock/products/by-barcode/1234567890",
-  "headers": {
-    "Accept-Language": "en-US"
-  }
+use_mcp_tool('mcp-grocy', 'system_dev_test_request', {
+  method: 'GET',
+  endpoint: '/api/stock/products/by-barcode/1234567890',
+  headers: {
+    'Accept-Language': 'en-US',
+  },
 });
 ```
 
-# MCP Grocy API - Endpoint Reference
-
-This document provides a comprehensive reference of all available endpoints in the MCP Grocy API.
-
-## Recipes
-
-### GET `/api/grocy/recipes`
-Retrieves a list of all recipes.
-
-**Response:**
-```json
-[
-  {
-    "id": 1,
-    "name": "Pizza",
-    "description": "Homemade pizza recipe"
-  }
-]
-```
+## Tool reference
 
-### GET `/api/grocy/recipes/:recipeId`
-Retrieves details of a specific recipe by ID.
-
-**Parameters:**
-- `recipeId`: ID of the recipe to retrieve
-
-**Response:**
-```json
-{
-  "id": 1,
-  "name": "Pizza",
-  "description": "Homemade pizza recipe",
-  "base_servings": 4,
-  "desired_servings": 4,
-  "preparation": "Mix ingredients and bake at 450°F"
-}
-
-### Get Recipe Fulfillment
-- **GET** `/api/grocy/recipes/:recipeId/fulfillment`
-- Returns fulfillment information for a specific recipe including:
-  - Whether ingredients are in stock
-  - Missing products count
-  - Costs
-  - Calories
-  - Due score
-
-### Get All Recipes Fulfillment
-- **GET** `/api/grocy/recipes-fulfillment`
-- Returns fulfillment information for all recipes including:
-  - Recipe ID
-  - Fulfillment status
-  - Missing products count
-  - Costs
-
-### Add Not Fulfilled Products to Shopping List
-- **POST** `/api/grocy/recipes/:recipeId/add-not-fulfilled-products-to-shoppinglist`
-- Adds all missing ingredients for a recipe to the shopping list
-- Returns the result of the operation
-
-## Stock
-
-### Get All Stock
-- **GET** `/api/grocy/stock`
-- Returns a list of all stock items
-
-### Get Stock Item by ID
-- **GET** `/api/grocy/stock/:stockId`
-- Returns details of a specific stock item
-
-## Chores
-
-### Get All Chores
-- **GET** `/api/grocy/chores`
-- Returns a list of all chores
-
-### Undo Chore Execution
-- **POST** `/api/grocy/chores/executions/:executionId/undo`
-- Undoes a chore execution
-- Returns the result of the operation
-
-## Batteries
-
-### Get All Batteries
-- **GET** `/api/grocy/batteries`
-- Returns a list of all batteries
-
-### Undo Battery Charge Cycle
-- **POST** `/api/grocy/batteries/charge-cycles/:chargeCycleId/undo`
-- Undoes a battery charge cycle
-- Returns the result of the operation
-
-## Tasks
-
-### Get All Tasks
-- **GET** `/api/grocy/tasks`
-- Returns a list of all tasks
-
-### Undo Task Completion
-- **POST** `/api/grocy/tasks/:taskId/undo`
-- Undoes a task completion
-- Returns the result of the operation
-
-## Generic Undo Endpoint
-
-### Undo Action
-- **POST** `/api/grocy/undo/:entityType/:id`
-- Unified endpoint for undoing various actions
-- `entityType` can be 'chores', 'batteries', or 'tasks'
-- `id` is the ID of the execution, charge cycle, or task
-- Returns the result of the undo operation
+Authoritative names and parameters live in **`src/tools/*/definitions.ts`** in this repository. Grocy’s own HTTP API is documented at [Grocy API](https://github.com/grocy/grocy#api).

package/build/resources/installation.md

@@ -11,10 +11,7 @@ Edit `claude_desktop_config.json`(for Claude Desktop) or `.cursor/mcp.json`(for
   "mcpServers": {
     "mcp-grocy": {
       "command": "npx",
-      "args": [
-        "-y",
-        "miguelangel-nubla/mcp-grocy"
-      ], 
+      "args": ["-y", "miguelangel-nubla/mcp-grocy"],
       "env": {
         "GROCY_BASE_URL": "",
         "GROCY_API_KEY": "",
@@ -25,20 +22,15 @@ Edit `claude_desktop_config.json`(for Claude Desktop) or `.cursor/mcp.json`(for
   }
 }
 ```
+
 Or you can use Docker:
+
 ```json
 {
   "mcpServers": {
     "mcp-grocy": {
       "command": "docker",
-      "args": [
-        "run",
-        "ghcr.io/miguelangel-nubla/mcp-grocy",
-        "tini",
-        "--",
-        "node",
-        "build/main.js"
-        ],
+      "args": ["run", "ghcr.io/miguelangel-nubla/mcp-grocy", "tini", "--", "node", "build/main.js"],
       "env": {
         "GROCY_BASE_URL": "",
         "GROCY_API_KEY": "",
@@ -55,12 +47,14 @@ Or you can use Docker:
 To install using Node.js, you will need to have Node.js and npm (or yarn) installed.
 
 Clone the repository:
+
 ```bash
 git clone -b main https://github.com/miguelangel-nubla/mcp-grocy.git
 cd mcp-grocy
 ```
 
 Install dependencies:
+
 ```bash
 npm install
 # or
@@ -68,6 +62,7 @@ yarn install
 ```
 
 Then you can run the server:
+
 ```bash
 npm start
 # or
@@ -76,7 +71,7 @@ yarn start
 
 ## npx
 
-You can also run the server directly using npx (Node.js 12.x or newer):
+You can also run the server directly using npx (Node.js 22 or newer; see `package.json` `engines`):
 
 ```bash
 npx -y mcp-grocy
@@ -114,4 +109,4 @@ HTTP_SERVER_PORT=8080 # (optional, default: 8080)
 - POST requests to `/mcp` for streamable HTTP (NDJSON or JSON)
 - GET requests to `/mcp/sse` for SSE (Server-Sent Events)
 
-All transports use the same MCP protocol and core logic.
+All transports use the same MCP protocol and core logic.