mcp-grocy 1.9.0

package/build/resources/examples.md

@@ -0,0 +1,319 @@
+# Grocy API Testing Examples
+
+## Setting Up Your Private Demo Instance
+
+Before testing the API, you can create your own private Grocy demo instance:
+
+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:
+   ```
+   GROCY_BASE_URL=https://your-name-xxxxx.demo.grocy.info
+   GROCY_APIKEY_VALUE=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 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"`
+
+## Basic API Tools
+
+### Get Current Stock
+```typescript
+use_mcp_tool('grocy-api', 'get_stock', {});
+```
+
+### Get Volatile Stock Information
+```typescript
+use_mcp_tool('grocy-api', 'get_stock_volatile', {
+  "includeDetails": true
+});
+```
+
+### Get All Products
+```typescript
+use_mcp_tool('grocy-api', 'get_products', {});
+```
+
+### Get All Shopping List Items
+```typescript
+use_mcp_tool('grocy-api', 'get_shopping_list', {});
+```
+
+### Add Item to Shopping List
+```typescript
+use_mcp_tool('grocy-api', 'add_shopping_list_item', {
+  "productId": 1,
+  "amount": 2,
+  "shoppingListId": 1,
+  "note": "Get the organic variety"
+});
+```
+
+### Purchase a Product
+```typescript
+use_mcp_tool('grocy-api', 'purchase_product', {
+  "productId": 1,
+  "amount": 2,
+  "bestBeforeDate": "2024-12-31",
+  "price": 3.99,
+  "storeId": 1
+});
+```
+
+### Consume a Product
+```typescript
+use_mcp_tool('grocy-api', 'consume_product', {
+  "productId": 1,
+  "amount": 1,
+  "spoiled": false
+});
+```
+
+## Recipe and Meal Planning
+
+### Get All Recipes
+```typescript
+use_mcp_tool('grocy-api', 'get_recipes', {});
+```
+
+### Check Recipe Fulfillment
+```typescript
+use_mcp_tool('grocy-api', 'get_recipe_fulfillment', {
+  "recipeId": 1,
+  "servings": 2
+});
+```
+
+### Get Meal Plan for a Date
+```typescript
+use_mcp_tool('grocy-api', 'get_meal_plan', {
+  "date": "2024-07-01"
+});
+```
+
+### Get Meal Plan Sections
+```typescript
+use_mcp_tool('grocy-api', 'get_meal_plan_sections', {});
+```
+
+### 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
+});
+```
+
+Note: Use get_meal_plan_sections to find valid section IDs for your Grocy instance.
+
+### 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
+});
+```
+
+Note: Use get_meal_plan to find the meal_plan_entry_id of the entry you want to remove.
+
+### Consume Recipe Ingredients
+```typescript
+use_mcp_tool('grocy-api', 'consume_recipe', {
+  "recipeId": 1,
+  "servings": 2
+});
+```
+
+## Chores and Tasks
+
+### Get All Chores
+```typescript
+use_mcp_tool('grocy-api', 'get_chores', {});
+```
+
+### Track Chore Execution
+```typescript
+use_mcp_tool('grocy-api', 'track_chore_execution', {
+  "choreId": 1,
+  "executedBy": 1,
+  "tracked_time": "2024-06-30 15:30:00"
+});
+```
+
+### Get All Tasks
+```typescript
+use_mcp_tool('grocy-api', 'get_tasks', {});
+```
+
+### Complete a Task
+```typescript
+use_mcp_tool('grocy-api', 'complete_task', {
+  "taskId": 1,
+  "note": "Task completed successfully"
+});
+```
+
+## Locations and Organization
+
+### Get All Locations
+```typescript
+use_mcp_tool('grocy-api', 'get_locations', {});
+```
+
+### Get All Shopping Locations (Stores)
+```typescript
+use_mcp_tool('grocy-api', 'get_shopping_locations', {});
+```
+
+### Transfer Product Between Locations
+```typescript
+use_mcp_tool('grocy-api', 'transfer_product', {
+  "productId": 1,
+  "amount": 1,
+  "locationIdFrom": 1,
+  "locationIdTo": 2,
+  "note": "Moving to kitchen"
+});
+```
+
+## Advanced API Usage
+
+### Custom API Call
+If you need to access a Grocy API endpoint not covered by the specialized tools:
+
+```typescript
+use_mcp_tool('grocy-api', 'call_grocy_api', {
+  "endpoint": "objects/product_barcodes",
+  "method": "GET"
+});
+```
+
+### Raw API Testing
+For detailed testing with full control over the request:
+
+```typescript
+use_mcp_tool('grocy-api', '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"
+  }
+]
+```
+
+### 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

package/build/resources/installation.md

@@ -0,0 +1,117 @@
+# Installation
+
+Instructions on how to install this project.
+
+## Claude
+
+Edit `claude_desktop_config.json`(for Claude Desktop) or `.cursor/mcp.json`(for Cursor):
+
+```json
+{
+  "mcpServers": {
+    "mcp-grocy": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "miguelangel-nubla/mcp-grocy"
+      ], 
+      "env": {
+        "GROCY_BASE_URL": "",
+        "GROCY_APIKEY_VALUE": "",
+        "GROCY_ENABLE_SSL_VERIFY": "False",
+        "REST_RESPONSE_SIZE_LIMIT": "10000"
+      }
+    }
+  }
+}
+```
+Or you can use Docker:
+```json
+{
+  "mcpServers": {
+    "mcp-grocy": {
+      "command": "docker",
+      "args": [
+        "run",
+        "ghcr.io/miguelangel-nubla/mcp-grocy",
+        "tini",
+        "--",
+        "node",
+        "build/main.js"
+        ],
+      "env": {
+        "GROCY_BASE_URL": "",
+        "GROCY_APIKEY_VALUE": "",
+        "GROCY_ENABLE_SSL_VERIFY": "False",
+        "REST_RESPONSE_SIZE_LIMIT": "10000"
+      }
+    }
+  }
+}
+```
+
+## Node.js
+
+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
+yarn install
+```
+
+Then you can run the server:
+```bash
+npm start
+# or
+yarn start
+```
+
+## npx
+
+You can also run the server directly using npx (Node.js 12.x or newer):
+
+```bash
+npx -y mcp-grocy
+```
+
+## Docker
+
+To run using Docker, you first need to build the Docker image:
+
+```bash
+docker build -t ghcr.io/miguelangel-nubla/mcp-grocy .
+```
+
+Then run the container with tini:
+
+```bash
+docker run -p mcp-grocy tini -- node build/main.js
+```
+
+## HTTP/SSE Transport
+
+The MCP Grocy API server supports the following transports:
+
+- **stdio** (default, Context7 MCP protocol)
+- **HTTP** (streamable, Context7-compatible, opt-in)
+- **SSE** (Server-Sent Events, for backward compatibility)
+
+To enable HTTP/SSE transport, set the following environment variable:
+
+```bash
+ENABLE_HTTP_SERVER=true
+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.

package/build/resources/response-format.md

@@ -0,0 +1,165 @@
+# Grocy API Response Format Documentation
+
+The Grocy API testing tool (`test_request`) returns a comprehensive JSON response containing request details, response information, and validation results. Other specialized Grocy tools (e.g., `get_stock`, `add_shopping_list_item`) return the direct JSON response from the Grocy API, which is then stringified.
+
+## `test_request` Tool Response Structure
+
+```json
+{
+  "request": {
+    "url": "https://your-own-demo.grocy.info/api/objects/products/1",
+    "method": "GET",
+    "headers": {
+      "GROCY-API-KEY": "[REDACTED]",
+      "Accept": "application/json",
+      "Content-Type": "application/json"
+    },
+    "body": null,
+    "authMethod": "apikey"
+  },
+  "response": {
+    "statusCode": 200,
+    "statusText": "OK",
+    "timing": "123ms",
+    "headers": {
+      "content-type": "application/json; charset=utf-8",
+      "date": "Mon, 01 Jul 2024 12:00:00 GMT"
+    },
+    "body": {
+      "id": "1",
+      "name": "Cookies",
+      "description": null,
+      "product_group_id": "1",
+      // ... other product fields ...
+    }
+  },
+  "validation": {
+    "isError": false,
+    "messages": ["Request completed successfully"]
+  }
+}
+```
+
+## Setting Up Your Own Private Demo Instance
+
+Before testing the API, you may want to set up your own private Grocy demo instance. This gives you a persistent environment for development and testing without having to install Grocy locally.
+
+### Creating a Private Demo Instance
+
+1. Visit [https://demo.grocy.info](https://demo.grocy.info)
+2. At the top of the page, find the "Create a private demo instance" section
+3. Fill in the form to create your personalized demo
+4. Once created, you'll receive:
+   - A unique URL for your instance (e.g., `https://your-name-xxxxx.demo.grocy.info`)
+   - An API key for API access
+   - Login credentials (username/password) for web access
+
+### Benefits of Private Demo Instances
+
+- **Persistence**: Your data remains available for a longer period (compared to the temporary demo)
+- **Privacy**: Only you have access to your instance
+- **Testing**: Ideal for testing API integrations without affecting production data
+- **No Installation**: No need to host Grocy on your own server
+
+### Using Your Private Demo in API Requests
+
+Configure your environment with the private demo details:
+
+```
+GROCY_BASE_URL=https://your-name-xxxxx.demo.grocy.info
+GROCY_APIKEY_VALUE=your-private-api-key
+```
+
+These values can be set in your `.env` file for local development or in your project configuration for production use.
+
+## Response Fields for `test_request`
+
+### Request Details (`request`)
+- `url`: Full URL of the Grocy API endpoint called, including base URL and path.
+- `method`: HTTP method used (e.g., GET, POST, PUT, DELETE).
+- `headers`: Request headers sent to the Grocy API. Sensitive headers like `GROCY-API-KEY` will have their values redacted.
+- `body`: Request body sent (if applicable, e.g., for POST/PUT requests).
+- `authMethod`: Authentication method used. For Grocy, this will typically be `apikey` if `GROCY_APIKEY_VALUE` is configured, or `none`.
+
+### Response Details (`response`)
+- `statusCode`: HTTP status code returned by the Grocy API (e.g., 200, 400, 401).
+- `statusText`: HTTP status message (e.g., "OK", "Bad Request").
+- `timing`: Duration of the API request in milliseconds.
+- `headers`: Response headers received from the Grocy API.
+- `body`: Response body content from the Grocy API. This will be the JSON data returned by Grocy.
+
+### Validation (`validation`)
+- `isError`: Boolean, `true` if the HTTP status code is 400 or higher, indicating an error.
+- `messages`: Array of messages, including success messages or error details.
+- `truncated` (optional): If the response body exceeds `REST_RESPONSE_SIZE_LIMIT`, this object will contain details about the truncation.
+  - `originalSize`: The original size of the response body in bytes.
+  - `returnedSize`: The size of the truncated response body returned.
+  - `truncationPoint`: The byte offset where truncation occurred.
+  - `sizeLimit`: The configured `REST_RESPONSE_SIZE_LIMIT`.
+
+## Specialized Grocy Tools Response Format
+
+Tools like `get_stock`, `get_products`, `add_shopping_list_item`, etc., directly return the JSON response from the Grocy API, stringified within the MCP tool response content.
+
+Example for `get_product` (if it existed as a specialized tool for a single product):
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"id\": \"1\",\n  \"name\": \"Cookies\",\n  \"description\": null,\n  \"product_group_id\": \"1\",\n  \"qu_id_purchase\": \"2\",\n  \"qu_id_stock\": \"2\",\n  \"qu_factor_purchase_to_stock\": \"1.0\",\n  \"barcode\": null,\n  \"min_stock_amount\": \"0\",\n  \"default_best_before_days\": \"0\",\n  \"default_best_before_days_after_open\": \"0\",\n  \"default_best_before_days_after_freezing\": \"0\",\n  \"default_best_before_days_after_thawing\": \"0\",\n  \"picture_file_name\": null,\n  \"allow_partial_units_in_stock\": \"0\",\n  \"row_created_timestamp\": \"2023-01-01 10:00:00\",\n  \"show_in_recipes_list\": \"1\",\n  \"has_sub_products\": \"0\",\n  \"active\": \"1\",\n  \"calories\": null,\n  \"cumulate_min_stock_amount_of_sub_products\": \"0\",\n  \"due_type\": \"1\",\n  \"quick_consume_amount\": \"1.0\",\n  \"hide_on_stock_overview\": \"0\",\n  \"default_stock_label_type\": \"0\",\n  \"should_not_be_frozen\": \"0\",\n  \"treat_opened_as_out_of_stock\": \"1\",
+  \"no_own_stock\": \"0\",
+  \"default_consume_location_id\": null,
+  \"move_on_open\": \"0\",
+  \"userfields\": null
+}"
+    }
+  ]
+}
+```
+
+If an error occurs with a specialized tool, the response will typically look like:
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"error\": \"Failed to get stock: API error (401) Unauthorized - Please check your API key and permissions.\"}"
+    }
+  ],
+  "isError": true
+}
+```
+
+## Error Response Example for `test_request`
+
+If the `test_request` tool encounters an API error (e.g., authentication failure):
+```json
+{
+  "request": {
+    "url": "https://your-own-demo.grocy.info/api/objects/products",
+    "method": "GET",
+    "headers": {
+      "GROCY-API-KEY": "[REDACTED]"
+    },
+    "body": null,
+    "authMethod": "apikey"
+  },
+  "response": {
+    "statusCode": 401,
+    "statusText": "Unauthorized",
+    "timing": "50ms",
+    "headers": { /* ... headers ... */ },
+    "body": {
+      "error_message": "API key is missing or invalid."
+    }
+  },
+  "validation": {
+    "isError": true,
+    "messages": [
+      "Request failed with status 401",
+      "API key is missing or invalid."
+    ]
+  }
+}
+```