mcp-grocy 2.7.2 → 2.8.0

package/CHANGELOG.md

@@ -1,9 +1,22 @@
-## [2.7.2](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.1...v2.7.2) (2026-09-10)
+# [2.8.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.2...v2.8.0) (2026-09-25)
+
+
+### Bug Fixes
+
+* accept numbers and booleans encoded as strings in tool arguments ([5dfbbc7](https://github.com/miguelangel-nubla/mcp-grocy/commit/5dfbbc799fdfde36255f6fcc3665e0113f36cf14))
+* advertise tool parameter descriptions in tools/list ([0418bf5](https://github.com/miguelangel-nubla/mcp-grocy/commit/0418bf5be83428f19e52c2952e2f3e5bdd078d73))
+* **tools:** normalize created_object_id and id to numbers in responses ([5f613d6](https://github.com/miguelangel-nubla/mcp-grocy/commit/5f613d6b6c87f860ac3a79e6d8a473a91d19d3a7))
 
 
+### Features
+
+* add recipes_mealplan_add_note tool for meal plan notes with sections ([e80aa65](https://github.com/miguelangel-nubla/mcp-grocy/commit/e80aa651e9653bf765d361a4ebc3d285d325a23e)), closes [#2](https://github.com/miguelangel-nubla/mcp-grocy/issues/2)
+
+## [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))
+- 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)
 

package/README.md

@@ -54,7 +54,7 @@ Transform your LLM into an intelligent household management assistant with focus
 ### 🛒 **Smart Shopping & Planning**
 
 - Maintain shopping lists with intelligent quantity management
-- Plan meals with recipe scheduling and fulfillment checking
+- Plan meals with recipe scheduling, free-text notes per meal plan section, and fulfillment checking
 - Automatically add missing ingredients to shopping lists
 - Track shopping locations and optimize store visits
 

package/build/resources/CHANGELOG.md

@@ -1,9 +1,22 @@
-## [2.7.2](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.1...v2.7.2) (2026-09-10)
+# [2.8.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.7.2...v2.8.0) (2026-09-25)
+
+
+### Bug Fixes
+
+* accept numbers and booleans encoded as strings in tool arguments ([5dfbbc7](https://github.com/miguelangel-nubla/mcp-grocy/commit/5dfbbc799fdfde36255f6fcc3665e0113f36cf14))
+* advertise tool parameter descriptions in tools/list ([0418bf5](https://github.com/miguelangel-nubla/mcp-grocy/commit/0418bf5be83428f19e52c2952e2f3e5bdd078d73))
+* **tools:** normalize created_object_id and id to numbers in responses ([5f613d6](https://github.com/miguelangel-nubla/mcp-grocy/commit/5f613d6b6c87f860ac3a79e6d8a473a91d19d3a7))
 
 
+### Features
+
+* add recipes_mealplan_add_note tool for meal plan notes with sections ([e80aa65](https://github.com/miguelangel-nubla/mcp-grocy/commit/e80aa651e9653bf765d361a4ebc3d285d325a23e)), closes [#2](https://github.com/miguelangel-nubla/mcp-grocy/issues/2)
+
+## [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))
+- 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)
 

package/build/resources/README.md

@@ -54,7 +54,7 @@ Transform your LLM into an intelligent household management assistant with focus
 ### 🛒 **Smart Shopping & Planning**
 
 - Maintain shopping lists with intelligent quantity management
-- Plan meals with recipe scheduling and fulfillment checking
+- Plan meals with recipe scheduling, free-text notes per meal plan section, and fulfillment checking
 - Automatically add missing ingredients to shopping lists
 - Track shopping locations and optimize store visits
 

package/build/resources/examples.md

@@ -122,6 +122,18 @@ use_mcp_tool('mcp-grocy', 'recipes_mealplan_add_recipe', {
 
 Use **`recipes_mealplan_get_sections`** for valid `sectionId` values.
 
+### Add a note to the meal plan (no recipe)
+
+```typescript
+use_mcp_tool('mcp-grocy', 'recipes_mealplan_add_note', {
+  day: '2024-07-01',
+  note: 'Leftovers from Sunday',
+  sectionId: 3,
+});
+```
+
+Same `sectionId` values as above (`-1` = Grocy's built-in "no section").
+
 ### Remove a meal plan entry
 
 ```typescript
@@ -130,7 +142,7 @@ use_mcp_tool('mcp-grocy', 'recipes_mealplan_delete_entry', {
 });
 ```
 
-Use **`recipes_mealplan_get`** to find `mealPlanEntryId`.
+Use **`recipes_mealplan_get`** to find `mealPlanEntryId`. Works for recipe and note entries.
 
 ### Cook / consume recipe ingredients
 

package/build/server/tool-input-zod.js

@@ -6,6 +6,36 @@ import { z } from 'zod';
 function isStringTupleEnum(values) {
     return values.length > 0 && values.every((v) => typeof v === 'string');
 }
+/**
+ * Some MCP clients serialize every tool argument as a string ("12", "true"). Accept those
+ * encodings for number/boolean properties: z.preprocess converts them before validation, and the
+ * JSON Schema advertised by tools/list still shows the wrapped type because Zod 4's toJSONSchema
+ * (io: 'input', which the SDK uses) resolves a preprocess pipe to its output schema — pinned by
+ * tests/tool-input-zod.test.ts. Only JSON number syntax and "true"/"false" are converted;
+ * anything else is passed through unchanged so the usual type error is still raised.
+ */
+const JSON_NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
+function numericStringToNumber(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!JSON_NUMBER.test(trimmed))
+        return value;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : value;
+}
+function booleanStringToBoolean(value) {
+    if (typeof value !== 'string')
+        return value;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    return value;
+}
+const lenientNumber = () => z.preprocess(numericStringToNumber, z.number());
+const lenientBoolean = () => z.preprocess(booleanStringToBoolean, z.boolean());
 function propertyToZod(prop, required) {
     const t = prop.type;
     let inner;
@@ -21,10 +51,10 @@ function propertyToZod(prop, required) {
         }
         case 'number':
         case 'integer':
-            inner = z.number();
+            inner = lenientNumber();
             break;
         case 'boolean':
-            inner = z.boolean();
+            inner = lenientBoolean();
             break;
         case 'array': {
             const items = prop.items;
@@ -35,10 +65,10 @@ function propertyToZod(prop, required) {
                 inner = z.array(z.string());
             }
             else if (items?.type === 'number' || items?.type === 'integer') {
-                inner = z.array(z.number());
+                inner = z.array(lenientNumber());
             }
             else if (items?.type === 'boolean') {
-                inner = z.array(z.boolean());
+                inner = z.array(lenientBoolean());
             }
             else {
                 inner = z.array(z.unknown());
@@ -62,7 +92,9 @@ function propertyToZod(prop, required) {
         default:
             inner = z.unknown();
     }
-    return required ? inner : inner.optional();
+    // Keep the per-property description in the advertised JSON Schema (LLM clients read it).
+    const described = prop.description ? inner.describe(prop.description) : inner;
+    return required ? described : described.optional();
 }
 function objectPropsToZod(properties, requiredList) {
     const required = new Set(requiredList ?? []);

package/build/tools/base.js

@@ -6,10 +6,43 @@ import { config } from '../config/index.js';
 import { ErrorHandler, ValidationError } from '../utils/errors.js';
 import { logger } from '../utils/logger.js';
 export class BaseToolHandler {
+    /**
+     * Normalizes response data so IDs (like created_object_id or entity id) are numeric.
+     */
+    normalizeResponseData(data) {
+        if (!data || typeof data !== 'object') {
+            return data;
+        }
+        if (Array.isArray(data)) {
+            return data.map((item) => this.normalizeResponseData(item));
+        }
+        if (Object.prototype.toString.call(data) !== '[object Object]') {
+            return data;
+        }
+        const normalized = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key === 'created_object_id' && value !== null && value !== undefined) {
+                const num = Number(value);
+                normalized[key] = Number.isInteger(num) && num > 0 ? num : value;
+            }
+            else if (key === 'id' && typeof value === 'string') {
+                const num = Number(value);
+                normalized[key] = Number.isInteger(num) && num > 0 ? num : value;
+            }
+            else if (value && typeof value === 'object') {
+                normalized[key] = this.normalizeResponseData(value);
+            }
+            else {
+                normalized[key] = value;
+            }
+        }
+        return normalized;
+    }
     /**
      * Create a standardized success result
      */
     createSuccess(data, message) {
+        const normalizedData = this.normalizeResponseData(data);
         let serializeStructured;
         try {
             serializeStructured = config?.server?.serialize_structured_to_content ?? false;
@@ -17,10 +50,10 @@ export class BaseToolHandler {
         catch {
             serializeStructured = false;
         }
-        const textContent = serializeStructured && data !== undefined && data !== null
+        const textContent = serializeStructured && normalizedData !== undefined && normalizedData !== null
             ? message
-                ? `${message}\n${this.safeStringify(data)}`
-                : this.safeStringify(data)
+                ? `${message}\n${this.safeStringify(normalizedData)}`
+                : this.safeStringify(normalizedData)
             : message || 'Operation completed successfully';
         return {
             content: [
@@ -30,7 +63,7 @@ export class BaseToolHandler {
                 },
             ],
             structuredContent: {
-                data: data ?? null,
+                data: normalizedData ?? null,
             },
         };
     }

package/build/tools/base.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { BaseToolHandler } from './base.js';
+class TestHandler extends BaseToolHandler {
+    testNormalize(data) {
+        return this.normalizeResponseData(data);
+    }
+    testSuccess(data, message) {
+        return this.createSuccess(data, message);
+    }
+}
+describe('BaseToolHandler normalization', () => {
+    const handler = new TestHandler();
+    it('normalizes created_object_id string to number', () => {
+        const input = { created_object_id: '1330' };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({ created_object_id: 1330 });
+    });
+    it('leaves created_object_id untouched if already a number', () => {
+        const input = { created_object_id: 1330 };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({ created_object_id: 1330 });
+    });
+    it('normalizes string id to number', () => {
+        const input = { id: '46', name: 'Arroz redondo' };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({ id: 46, name: 'Arroz redondo' });
+    });
+    it('normalizes nested objects and arrays', () => {
+        const input = {
+            list: { id: '1', name: 'Groceries' },
+            items: [
+                { id: '10', product: { id: '46', name: 'Rice' } },
+                { id: '11', product: { id: '55', name: 'Beans' } },
+            ],
+        };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({
+            list: { id: 1, name: 'Groceries' },
+            items: [
+                { id: 10, product: { id: 46, name: 'Rice' } },
+                { id: 11, product: { id: 55, name: 'Beans' } },
+            ],
+        });
+    });
+    it('does not touch barcodes, dates, or non-id fields', () => {
+        const input = {
+            id: '1',
+            barcode: '012345678905',
+            created_at: '2026-09-11 12:00:00',
+            note: '46',
+        };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({
+            id: 1,
+            barcode: '012345678905',
+            created_at: '2026-09-11 12:00:00',
+            note: '46',
+        });
+    });
+    it('createSuccess automatically applies normalization to structuredContent and textContent', () => {
+        const res = handler.testSuccess({ created_object_id: '1330' }, 'Created');
+        expect(res.structuredContent?.data).toEqual({ created_object_id: 1330 });
+    });
+});

package/build/tools/recipes/definitions.js

@@ -121,7 +121,7 @@ export const recipeToolDefinitions = [
     // ==================== MEAL PLANNING ====================
     {
         name: 'recipes_mealplan_get',
-        description: '[RECIPES/MEALPLAN] Get your meal plan data from Grocy instance with corresponding recipe details. Returns planned meals for the requested date plus surrounding days for context. Use this to find out what recipes/meals are planned for a specific date (e.g., "what\'s for dinner tomorrow", "recipes for today", "meal plan for next week"). The returned data includes the id field (meal plan entry ID) which can be used with recipes_mealplan_delete_entry.',
+        description: '[RECIPES/MEALPLAN] Get your meal plan data from Grocy instance with corresponding recipe details. Returns planned entries for the requested date plus surrounding days for context. Each entry has a type: "recipe" (recipe_id + recipe_servings; names in recipes) or "note" (free text in note, no recipe); other values (e.g., "product") are not handled by these tools. section_id maps to the returned sections. Use this to find out what is planned for a specific date (e.g., "what\'s for dinner tomorrow", "recipes for today", "meal plan for next week"). The returned id field (meal plan entry ID) can be used with recipes_mealplan_delete_entry.',
         annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
@@ -140,7 +140,7 @@ export const recipeToolDefinitions = [
     },
     {
         name: 'recipes_mealplan_get_sections',
-        description: '[RECIPES/MEALPLAN] **Read-only:** list meal plan section names/IDs (Breakfast, Dinner, …). Does not return planned meals or dates—use recipes_mealplan_get for the calendar. Needed before recipes_mealplan_add_recipe to pick sectionId; the row with id -1 and name null is Grocy\'s built-in "no section".',
+        description: '[RECIPES/MEALPLAN] **Read-only:** list meal plan section names/IDs (Breakfast, Dinner, …). Does not return planned meals or dates—use recipes_mealplan_get for the calendar. Needed before recipes_mealplan_add_recipe or recipes_mealplan_add_note to pick sectionId; the row with id -1 and name null is Grocy\'s built-in "no section".',
         annotations: { readOnlyHint: true },
         inputSchema: {
             type: 'object',
@@ -150,7 +150,7 @@ export const recipeToolDefinitions = [
     },
     {
         name: 'recipes_mealplan_add_recipe',
-        description: '[RECIPES/MEALPLAN] **Write:** put a recipe on the calendar (date + section + servings). Not for listing sections (recipes_mealplan_get_sections) or viewing the plan (recipes_mealplan_get).',
+        description: '[RECIPES/MEALPLAN] **Write:** put a recipe on the calendar (date + section + servings). For free text without a recipe use recipes_mealplan_add_note. Not for listing sections (recipes_mealplan_get_sections) or viewing the plan (recipes_mealplan_get).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -174,15 +174,37 @@ export const recipeToolDefinitions = [
             required: ['recipeId', 'day', 'servings', 'sectionId'],
         },
     },
+    {
+        name: 'recipes_mealplan_add_note',
+        description: '[RECIPES/MEALPLAN] **Write:** add a free-text note (e.g., "Leftovers", "Eating out") to a meal plan day and section—no recipe involved, nothing is consumed from stock. To plan an actual recipe use recipes_mealplan_add_recipe.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                day: {
+                    type: 'string',
+                    description: 'Day to add the note to in YYYY-MM-DD format (e.g., "2024-12-25").',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Text shown on the meal plan for that day (e.g., "Leftovers from Sunday", "Dinner at grandma\'s"). Must not be empty.',
+                },
+                sectionId: {
+                    type: 'number',
+                    description: 'ID of the meal plan section (e.g., breakfast, lunch, dinner) to file the note under. Use recipes_mealplan_get_sections tool to discover available sections and their IDs. Use -1 for Grocy\'s built-in "no section"; if the user names no meal or section, use -1 rather than guessing.',
+                },
+            },
+            required: ['day', 'note', 'sectionId'],
+        },
+    },
     {
         name: 'recipes_mealplan_delete_entry',
-        description: '[RECIPES/MEALPLAN] Delete a specific recipe entry from the meal plan. Use recipes_mealplan_get to find the mealPlanEntryId of the entry you want to remove.',
+        description: '[RECIPES/MEALPLAN] Delete one meal plan entry of any type (recipe, note, product) by its mealPlanEntryId. Use recipes_mealplan_get to find the mealPlanEntryId of the entry you want to remove.',
         inputSchema: {
             type: 'object',
             properties: {
                 mealPlanEntryId: {
                     type: 'number',
-                    description: 'ID of the specific meal plan entry to delete. Use recipes_mealplan_get to find the correct entry ID.',
+                    description: 'ID of the specific meal plan entry to delete (works for any entry type). Use recipes_mealplan_get to find the correct entry ID.',
                 },
             },
             required: ['mealPlanEntryId'],
@@ -259,7 +281,7 @@ export const recipeToolDefinitions = [
                         : {
                             mealPlanEntryId: {
                                 type: 'number',
-                                description: `ID of the meal plan entry. Must be a recipe entry; note and product entries cannot be completed with this tool.${allowAlreadyDone ? '' : ' Note: This will fail if the meal plan entry is already marked as done (done=1).'}`,
+                                description: `ID of the meal plan entry. Must be a recipe entry (type 'recipe' in recipes_mealplan_get); note and product entries cannot be completed with this tool.${allowAlreadyDone ? '' : ' Note: This will fail if the meal plan entry is already marked as done (done=1).'}`,
                             },
                         }),
                     stockAmounts: {

package/build/tools/recipes/handlers.js

@@ -121,6 +121,20 @@ export class RecipeToolHandlers extends BaseToolHandler {
             return this.createSuccess(result, 'Recipe added to meal plan successfully');
         });
     };
+    /**
+     * Add free-text note to meal plan
+     */
+    addNoteToMealPlan = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { day, note, sectionId } = args || {};
+            this.validateRequired({ day, note, sectionId }, ['day', 'note', 'sectionId']);
+            if (typeof note !== 'string' || note.trim() === '') {
+                throw new ValidationError('note must be non-empty text', 'recipes_mealplan_add_note');
+            }
+            const result = await this.createMealPlanEntry(day, sectionId, { type: 'note', note }, 'recipes_mealplan_add_note');
+            return this.createSuccess(result, 'Note added to meal plan successfully');
+        });
+    };
     /**
      * Cook recipe - consume ingredients from stock
      */
@@ -241,6 +255,7 @@ export class RecipeToolHandlers extends BaseToolHandler {
                 simplifiedMealPlanByDate[entryDate].push({
                     id: entry.id,
                     day: entry.day,
+                    type: entry.type,
                     section_id: entry.section_id,
                     recipe_id: entry.recipe_id,
                     recipe_servings: entry.recipe_servings,
@@ -275,14 +290,14 @@ export class RecipeToolHandlers extends BaseToolHandler {
         });
     };
     /**
-     * Delete recipe from meal plan
+     * Delete a meal plan entry (any type)
      */
-    deleteRecipeFromMealPlan = async (args) => {
+    deleteMealPlanEntry = async (args) => {
         return this.executeToolHandler(async () => {
             const { mealPlanEntryId } = args || {};
             this.validateRequired({ mealPlanEntryId }, ['mealPlanEntryId']);
             const result = await this.apiCall(`/objects/meal_plan/${mealPlanEntryId}`, 'DELETE');
-            return this.createSuccess(result, 'Recipe deleted from meal plan successfully');
+            return this.createSuccess(result, 'Meal plan entry deleted successfully');
         });
     };
     // ==================== RECIPE CREATION ====================

package/build/tools/recipes/index.js

@@ -18,7 +18,8 @@ export const recipeModule = {
         recipes_mealplan_get: handlers.getMealPlan,
         recipes_mealplan_get_sections: handlers.getMealPlanSections,
         recipes_mealplan_add_recipe: handlers.addRecipeToMealPlan,
-        recipes_mealplan_delete_entry: handlers.deleteRecipeFromMealPlan,
+        recipes_mealplan_add_note: handlers.addNoteToMealPlan,
+        recipes_mealplan_delete_entry: handlers.deleteMealPlanEntry,
         // Recipe Cooking
         recipes_cooking_consume: handlers.consumeRecipe,
         recipes_cooking_complete: handlers.cookedSomething,

package/build/version.js

@@ -1,4 +1,4 @@
 // Auto-generated file - DO NOT MODIFY
-export const VERSION = '2.7.2';
+export const VERSION = '2.8.0';
 export const PACKAGE_NAME = 'mcp-grocy';
 export const SERVER_NAME = 'mcp-grocy';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-grocy",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "description": "Model Context Protocol (MCP) server for Grocy integration",
   "license": "MIT",
   "type": "module",