mcp-grocy 2.2.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +125 -32
  3. package/build/resources/CHANGELOG.md +47 -0
  4. package/build/resources/DOCS.md +8 -3
  5. package/build/resources/README.md +125 -32
  6. package/build/resources/api-reference.md +88 -88
  7. package/build/resources/config.md +45 -17
  8. package/build/resources/examples.md +120 -221
  9. package/build/resources/installation.md +9 -14
  10. package/build/resources/response-format.md +29 -20
  11. package/build/version.js +2 -2
  12. package/package.json +50 -24
  13. package/build/api/client.js +0 -121
  14. package/build/config/index.js +0 -205
  15. package/build/main.js +0 -44
  16. package/build/server/http-server.js +0 -218
  17. package/build/server/mcp-server.js +0 -163
  18. package/build/server/resources.js +0 -60
  19. package/build/tools/base.js +0 -141
  20. package/build/tools/household/definitions.js +0 -157
  21. package/build/tools/household/handlers.js +0 -109
  22. package/build/tools/household/index.js +0 -25
  23. package/build/tools/index.js +0 -2
  24. package/build/tools/inventory/definitions.js +0 -379
  25. package/build/tools/inventory/handlers.js +0 -430
  26. package/build/tools/inventory/index.js +0 -32
  27. package/build/tools/module-loader.js +0 -151
  28. package/build/tools/recipes/definitions.js +0 -261
  29. package/build/tools/recipes/handlers.js +0 -471
  30. package/build/tools/recipes/index.js +0 -33
  31. package/build/tools/recipes/validations.js +0 -23
  32. package/build/tools/shopping/definitions.js +0 -71
  33. package/build/tools/shopping/handlers.js +0 -43
  34. package/build/tools/shopping/index.js +0 -14
  35. package/build/tools/system/definitions.js +0 -86
  36. package/build/tools/system/handlers.js +0 -94
  37. package/build/tools/system/index.js +0 -16
  38. package/build/tools/types.js +0 -1
  39. package/build/tools/validation-helpers.js +0 -36
  40. package/build/types/index.js +0 -62
  41. package/build/utils/errors.js +0 -138
  42. package/build/utils/logger.js +0 -141
package/CHANGELOG.md ADDED
@@ -0,0 +1,45 @@
1
+ # [2.6.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.5.0...v2.6.0) (2026-07-06)
2
+
3
+ ### Bug Fixes
4
+
5
+ - reap idle streamable HTTP sessions to prevent McpServer leak ([c55b2c4](https://github.com/miguelangel-nubla/mcp-grocy/commit/c55b2c4808dac4ac5f0c55a45936c8f995d5efc3))
6
+
7
+ ### Features
8
+
9
+ - add shopping_list_update_item tool to allow modifying list items ([dcbc974](https://github.com/miguelangel-nubla/mcp-grocy/commit/dcbc9746630667bbe89330bab7f7e9f84a3f060f))
10
+ - add shopping*lists*\* configurations to example yaml ([204f03d](https://github.com/miguelangel-nubla/mcp-grocy/commit/204f03dca8c9ca17f3cfc476274f0a5b844912c7))
11
+ - configure husky git hooks ([c8ac158](https://github.com/miguelangel-nubla/mcp-grocy/commit/c8ac1582f477c6dc074166b5a9753a06608c8007))
12
+ - enhance shopping list tools with manual item support and enriched metadata resolution ([a1a8ce3](https://github.com/miguelangel-nubla/mcp-grocy/commit/a1a8ce341b61e5b24a366ae74a95a2c92e93e07c))
13
+ - enrich shopping list tool responses with product and quantity unit details ([56bd553](https://github.com/miguelangel-nubla/mcp-grocy/commit/56bd553e17d913db1f2c61fc963a900f6477f45f))
14
+ - expand shopping module with get, update, and filtered list capabilities ([d7e0e5d](https://github.com/miguelangel-nubla/mcp-grocy/commit/d7e0e5d94962c1b4daf0835a91fc275c25188673))
15
+ - make productId optional in shopping list add tool ([a427e18](https://github.com/miguelangel-nubla/mcp-grocy/commit/a427e1832a9b70e579dae062c7665ec472656359))
16
+
17
+ # [2.5.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.4.4...v2.5.0) (2026-03-30)
18
+
19
+ ### Bug Fixes
20
+
21
+ - add read permissions for contents in release workflow to support nested publish-docker job ([5a055a6](https://github.com/miguelangel-nubla/mcp-grocy/commit/5a055a62cf07fa3f0f03d4319e485350c111804a))
22
+ - improve test build isolation and commit-specific tagging ([b1875cc](https://github.com/miguelangel-nubla/mcp-grocy/commit/b1875ccc080111c6d56700aab9c493e418d155be))
23
+
24
+ ### Features
25
+
26
+ - improve tool call error handling, and implement multi-server shutdown management ([4d19cfb](https://github.com/miguelangel-nubla/mcp-grocy/commit/4d19cfb35dc238a41a92d2fba505998b6a59e1ae))
27
+
28
+ # Changelog
29
+
30
+ All notable changes to this project will be documented in this file.
31
+
32
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
33
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
34
+
35
+ Release notes are appended automatically by [semantic-release](https://semantic-release.gitbook.io/) using `@semantic-release/changelog`.
36
+
37
+ ## [Unreleased]
38
+
39
+ ### ⚠️ Breaking Changes
40
+
41
+ - **MCP resource URIs** use the **`mcp-grocy://`** scheme (from `package.json` `name`, generated into `SERVER_NAME` at build time). Bundled docs: `mcp-grocy://examples`, `mcp-grocy://response-format`, `mcp-grocy://config`. Clients, prompts, or bookmarks that used **`grocy-api://…`** must be updated.
42
+
43
+ ### Added
44
+
45
+ - **MCP tool `annotations.readOnlyHint: true`** on read-only tools (inventory/recipes/shopping/household/system getters and lookups only—no `*_print_*`, dev tools, or mutating calls). Optional hint for clients; not a security boundary.
package/README.md CHANGED
@@ -8,20 +8,22 @@
8
8
  [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
9
9
 
10
10
  > **🍴 Opinionated Fork Notice**
11
- >
11
+ >
12
12
  > 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**.
13
13
  >
14
14
  > **Why This Fork Exists:**
15
+ >
15
16
  > - The original wrapper exposes the entire Grocy API unprocessed, leading to context overload and LLM confusion
16
17
  > - Grocy's API design choices and limitations cause error-prone interactions
17
18
  > - Generic API exposure increases hallucination and near-miss results
18
- >
19
+ >
19
20
  > **This Fork's Philosophy:**
21
+ >
20
22
  > - **Filters and augments data** with relevant context for better LLM comprehension
21
23
  > - **Reduces API calls** by combining common operations to minimize error chains
22
24
  > - **Optimizes for reliability and repeatability** over feature completeness
23
25
  > - **Opinionated workflows** that may not match everyone's preferences
24
- >
26
+ >
25
27
  > 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.
26
28
 
27
29
  ## 🎯 What This MCP Does
@@ -29,24 +31,28 @@
29
31
  Transform your LLM into an intelligent household management assistant with focused tools for:
30
32
 
31
33
  ### 📦 **Stock Management**
34
+
32
35
  - Track inventory across multiple locations with precision
33
36
  - Record purchases and consumption with automatic stock updates
34
37
  - Monitor expiry dates and get volatile stock alerts
35
38
  - Transfer products between storage locations
36
39
 
37
40
  ### 🛒 **Smart Shopping & Planning**
41
+
38
42
  - Maintain shopping lists with intelligent quantity management
39
43
  - Plan meals with recipe scheduling and fulfillment checking
40
44
  - Automatically add missing ingredients to shopping lists
41
45
  - Track shopping locations and optimize store visits
42
46
 
43
- ### 🍽️ **Recipe & Meal Workflows**
47
+ ### 🍽️ **Recipe & Meal Workflows**
48
+
44
49
  - Find recipes with fuzzy search capabilities
45
50
  - Check if recipes can be made with current stock
46
51
  - Complete cooking workflows with portion control
47
52
  - Integrate meal planning with inventory consumption
48
53
 
49
54
  ### 🏠 **Household Management**
55
+
50
56
  - Manage chores, tasks, and battery tracking
51
57
  - Get product price history for budgeting
52
58
  - Organize products by groups and categories
@@ -56,21 +62,24 @@ Transform your LLM into an intelligent household management assistant with focus
56
62
 
57
63
  1. **Get your Grocy API key** from your Grocy instance (User Settings → API Keys)
58
64
  2. **Set up with Docker Compose:**
65
+
59
66
  ```bash
60
67
  # Get the project
61
68
  git clone https://github.com/miguelangel-nubla/mcp-grocy.git
62
69
  cd mcp-grocy
63
-
70
+
64
71
  # Configure
65
72
  cp .env.example .env
66
73
  # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
67
-
74
+
68
75
  # Run
69
76
  docker compose up -d
70
77
  ```
71
78
 
72
79
  ### Try Without Grocy
80
+
73
81
  Test with mock data (no real Grocy instance needed):
82
+
74
83
  ```bash
75
84
  # In .env file, any values work for mock mode
76
85
  GROCY_BASE_URL=http://mock
@@ -79,6 +88,14 @@ GROCY_API_KEY=mock
79
88
  npm install && npm run dev
80
89
  ```
81
90
 
91
+ ## Requirements (Node.js & tooling)
92
+
93
+ - **Node.js:** **22 or newer** as declared in `package.json` `engines`. **GitHub Actions** and **`.nvmrc`** use **Node 22** for CI and local alignment.
94
+ - **Docker:** the default image is **`node:22-alpine`** so the container matches that major version (Home Assistant addon builds still override the base image).
95
+ - **TypeScript:** **5.9** in this repo; **TypeScript 6** is waiting on **`typescript-eslint`** to declare compatible peer support.
96
+ - **`npm audit`:** any remaining findings are often inside **nested tooling** (e.g. bundled `npm`), not application dependencies. Use `npm audit` / `npm audit fix` on a branch when refreshing the lockfile.
97
+ - **Quality checks:** `npm run lint` (ESLint), `npm run format:check` (Prettier), `npm test` (Vitest).
98
+
82
99
  ## Installation
83
100
 
84
101
  ### NPM
@@ -99,6 +116,7 @@ docker run -e GROCY_API_KEY=your_api_key -e GROCY_BASE_URL=http://your-grocy-ins
99
116
  ### Docker Compose (Recommended)
100
117
 
101
118
  Create a `docker-compose.yml`:
119
+
102
120
  ```yaml
103
121
  services:
104
122
  mcp-grocy:
@@ -109,6 +127,7 @@ services:
109
127
  ```
110
128
 
111
129
  Then:
130
+
112
131
  ```bash
113
132
  cp .env.example .env
114
133
  # Edit .env with your configuration
@@ -124,6 +143,7 @@ docker compose up -d
124
143
  - Create a new API key and copy it
125
144
 
126
145
  2. **Configure the server:**
146
+
127
147
  ```bash
128
148
  cp .env.example .env
129
149
  # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
@@ -135,71 +155,96 @@ docker compose up -d
135
155
 
136
156
  ### Configuration Options
137
157
 
138
- | Method | Use Case | Command |
139
- |--------|----------|---------|
140
- | **`.env` file** | Recommended for most users | `cp .env.example .env` |
141
- | **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy` |
142
- | **Tool configuration** | Customize functionality | Edit `tools` section in `mcp-grocy.yaml` |
158
+ | Method | Use Case | Command |
159
+ | ------------------------- | -------------------------- | ------------------------------------------------ |
160
+ | **`.env` file** | Recommended for most users | `cp .env.example .env` |
161
+ | **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy` |
162
+ | **Tool configuration** | Customize functionality | Edit `tools` section in `mcp-grocy.yaml` |
143
163
 
144
164
  📖 **For complete configuration reference:** See [Configuration Guide](src/resources/config.md)
145
165
 
146
166
  ## 🚀 Usage Modes
147
167
 
148
168
  ### Production Mode
169
+
149
170
  Start with your real Grocy instance:
171
+
150
172
  ```bash
151
173
  npm start
152
174
  ```
153
175
 
154
176
  ### Development/Testing Mode
177
+
155
178
  Use mock data (no Grocy instance required):
179
+
156
180
  ```bash
157
181
  npm run dev
158
182
  ```
159
183
 
160
- ### HTTP Server Mode
184
+ ### HTTP Server Mode
185
+
161
186
  Enable web-based access via HTTP/SSE:
187
+
162
188
  ```bash
163
189
  # In .env: ENABLE_HTTP_SERVER=true
164
190
  npm start
165
191
  # Access via http://localhost:8080/mcp
166
192
  ```
167
193
 
168
-
169
194
  ## 📚 Documentation & Resources
170
195
 
171
- | Resource | Purpose | When to Use |
172
- |----------|---------|-------------|
173
- | [📖 API Reference](src/resources/api-reference.md) | Complete tool documentation | Tool usage and examples |
174
- | [⚙️ Configuration Guide](src/resources/config.md) | Advanced configuration reference | Detailed setup, presets, troubleshooting |
175
- | [📋 .env.example](.env.example) | Environment configuration template | Copy and customize for your setup |
176
- | [🧪 MCP Inspector](https://github.com/modelcontextprotocol/inspector) | Protocol debugging | Debug MCP interactions |
196
+ | Resource | Purpose | When to Use |
197
+ | --------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------- |
198
+ | [📖 API Reference](src/resources/api-reference.md) | Complete tool documentation | Tool usage and examples |
199
+ | [⚙️ Configuration Guide](src/resources/config.md) | Advanced configuration reference | Detailed setup, presets, troubleshooting |
200
+ | [📋 .env.example](.env.example) | Environment configuration template | Copy and customize for your setup |
201
+ | [🧪 MCP Inspector](https://github.com/modelcontextprotocol/inspector) | Protocol debugging | Debug MCP interactions |
202
+
203
+ **Bundled MCP resources** (from `resources/list`): `mcp-grocy://examples`, `mcp-grocy://response-format`, `mcp-grocy://config` — markdown docs shipped with the server. The URI scheme matches **`package.json` `name`** (previously some builds used `grocy-api://…`; update pinned URIs in clients or prompts if you relied on that).
177
204
 
178
205
  ### 🆘 Troubleshooting
179
206
 
180
207
  #### Common Issues
181
208
 
182
209
  **"Connection refused" or "Cannot connect to Grocy"**
210
+
183
211
  - Verify `GROCY_BASE_URL` is correct and accessible
184
212
  - Check that your Grocy instance is running
185
213
  - For HTTPS URLs, ensure SSL certificate is valid or disable verification with `GROCY_ENABLE_SSL_VERIFY=false`
186
214
 
187
215
  **"Invalid API key" or "Authentication failed"**
216
+
188
217
  - Verify your `GROCY_API_KEY` is correct
189
218
  - Check that the API key exists in your Grocy instance (User Settings → API Keys)
190
219
  - Ensure the API key has proper permissions
191
220
 
192
221
  **"Tool not found" errors**
222
+
193
223
  - Check if the tool is enabled in your `mcp-grocy.yaml` file
194
224
  - Verify you're using the correct tool names from the API reference
195
225
 
196
226
  **Large response errors**
227
+
197
228
  - Increase `REST_RESPONSE_SIZE_LIMIT` if you have many products/stock entries
198
229
  - Consider disabling unused tools in `mcp-grocy.yaml`
199
230
 
231
+ **High memory usage / RAM grows over time (HTTP mode)**
232
+
233
+ - In HTTP mode the server automatically reaps idle MCP sessions (by default, after
234
+ 5 minutes with no requests), so clients that disconnect without `DELETE /mcp` —
235
+ or that repeatedly reconnect with a new session — no longer leak per-session
236
+ server instances. No action is required.
237
+ - Tune via `MCP_SESSION_IDLE_TIMEOUT_MS` / `MCP_SESSION_SWEEP_INTERVAL_MS` (or the
238
+ `server.session_idle_timeout_ms` / `server.session_sweep_interval_ms` YAML keys):
239
+ lower the timeout on memory-constrained hosts, raise it if a client legitimately
240
+ idles for long periods between calls.
241
+ - For the lowest overhead, prefer an MCP client that reuses its `Mcp-Session-Id`
242
+ across requests and sends `DELETE /mcp` when it disconnects.
243
+
200
244
  #### Debug Mode
201
245
 
202
246
  Enable detailed logging and use the MCP inspector:
247
+
203
248
  ```bash
204
249
  # Launch MCP inspector for protocol debugging
205
250
  npm run inspector
@@ -212,8 +257,8 @@ npm run dev
212
257
 
213
258
  ### Prerequisites
214
259
 
215
- - Node.js 18 or higher
216
- - Grocy instance (optional with mock mode)
260
+ - Node.js 22 or newer (see **Requirements** above)
261
+ - Grocy instance (optional: use placeholder URLs/keys in `.env` for local runs)
217
262
 
218
263
  ### Development Setup
219
264
 
@@ -234,18 +279,63 @@ npm start
234
279
 
235
280
  ### Development Commands
236
281
 
237
- | Command | Description |
238
- |---------|-------------|
239
- | `npm run build` | Build TypeScript to JavaScript |
240
- | `npm run watch` | Watch mode for development |
241
- | `npm run dev` | Start with mock data (no Grocy needed) |
242
- | `npm test` | Run test suite |
243
- | `npm run test:watch` | Run tests in watch mode |
244
- | `npm run inspector` | Launch MCP protocol inspector |
282
+ | Command | Description |
283
+ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
284
+ | `npm run build` | Build TypeScript to JavaScript |
285
+ | `npm start` | Run the built server (`build/main.js`) |
286
+ | `npm run dev` | Build, then run (use mock `.env` for local testing) |
287
+ | `npm run watch` | Watch mode for development |
288
+ | `npm test` | Run test suite |
289
+ | `npm run test:watch` | Run tests in watch mode |
290
+ | `npm run inspector` | Launch MCP protocol inspector |
291
+ | `npm run dev:mcp-tef` | Run [mcp-tef](https://github.com/StacklokLabs/mcp-tef) locally (needs **uv** + **Ollama**) for tool-description / similarity checks |
292
+ | `npm run report:mcp-tef` | One command: build, temporary mcp-grocy HTTP + mcp-tef, write `reports/mcp-tef/<timestamp>/` (similarity JSON + `SUMMARY.md`) |
293
+
294
+ ### Optional: mcp-tef (local tool evaluation)
295
+
296
+ When you change tool descriptions or add tools, you can run [StacklokLabs/mcp-tef](https://github.com/StacklokLabs/mcp-tef) against **Ollama** (no cloud API key required):
297
+
298
+ 1. Install [uv](https://docs.astral.sh/uv/) and start Ollama; pull a small model, e.g. `ollama pull llama3.2:3b`.
299
+ 2. Build and start **mcp-grocy over HTTP** in another terminal (SSE endpoint for mcp-tef):
300
+
301
+ ```bash
302
+ npm run build
303
+ MCP_HTTP_TRANSPORT_ONLY=true ENABLE_HTTP_SERVER=true HTTP_SERVER_PORT=8790 npm start
304
+ ```
305
+
306
+ 3. Start mcp-tef:
307
+
308
+ ```bash
309
+ npm run dev:mcp-tef
310
+ ```
311
+
312
+ 4. Open `http://127.0.0.1:8000/docs` and point workflows at **`http://127.0.0.1:8790/mcp/sse`** (or your port).
313
+
314
+ The first run clones mcp-tef into `.cache/mcp-tef` (ignored by git). Override the Ollama model with `MCP_TEF_OLLAMA_MODEL`, the listen port with `MCP_TEF_PORT`, or the clone ref with `MCP_TEF_REF`.
315
+
316
+ **One-shot report (no manual API calls):**
317
+
318
+ ```bash
319
+ npm run report:mcp-tef
320
+ ```
321
+
322
+ Writes under `reports/mcp-tef/<timestamp>/`:
323
+
324
+ - **`REPORT.md`** — human-readable: tools by domain, flagged pairs as a **markdown table** (short tool names, similarity %).
325
+ - **`REPORT.html`** — same pairs in a simple table; open in a browser if you prefer.
326
+ - **`SUMMARY.md`** — one-screen pointer + counts.
327
+ - **`similarity.json`** — full API response (matrix, composite ids).
328
+
329
+ Uses ephemeral ports **8792** (mcp-grocy) and **8020** (mcp-tef) by default (`MCP_GROCY_HTTP_PORT`, `MCP_TEF_REPORT_PORT` to override). If you do not set `MCP_GROCY_YAML`, the script drops a temporary `mcp-grocy.yaml` next to the report by copying `mcp-grocy.yaml.example` with every `enabled: false` flipped to `true`, so `tools/list` is complete for analysis.
330
+
331
+ Add `--with-recommendations` for LLM suggestions on flagged pairs, or `--quality` for per-tool quality scoring (slow; both need Ollama). The report calls mcp-tef’s similarity API with **`transport: sse`** against `/mcp/sse` (current [mcp-tef](https://github.com/StacklokLabs/mcp-tef) request shape). Default similarity threshold is **0.9** (set `SIMILARITY_THRESHOLD=0.85` for the previous, noisier report).
332
+
333
+ Optional per-tool **`title`** and **`meta`** (→ MCP `_meta`) can be set in definitions when they add real signal; otherwise clients use **`name`** only.
245
334
 
246
335
  ### Debugging
247
336
 
248
337
  Use the MCP inspector to debug protocol interactions:
338
+
249
339
  ```bash
250
340
  npm run inspector
251
341
  ```
@@ -257,22 +347,25 @@ This launches a web interface for testing MCP tools and viewing protocol message
257
347
  This is an **opinionated fork** focused on LLM usability and workflow reliability. Contributions are welcome but must align with the core philosophy:
258
348
 
259
349
  ### ✅ Welcome Contributions
350
+
260
351
  - Bug fixes and reliability improvements
261
- - Better error handling and validation
352
+ - Better error handling and validation
262
353
  - Documentation improvements
263
354
  - Test coverage enhancements
264
355
  - Performance optimizations
265
356
 
266
357
  ### ❌ Contributions Requiring Discussion
358
+
267
359
  - New tool additions (must demonstrate clear LLM workflow benefits)
268
360
  - API design changes that increase complexity
269
361
  - Features that expose raw Grocy API behavior
270
362
 
271
363
  ### Development Workflow
364
+
272
365
  1. Fork the repository
273
366
  2. Create a feature branch
274
367
  3. Make your changes with tests
275
- 4. Run `npm test` and ensure all tests pass
368
+ 4. Run `npm test` and ensure all tests pass
276
369
  5. Submit a pull request with clear description
277
370
 
278
371
  ## 📄 License
@@ -282,4 +375,4 @@ This project is licensed under the [MIT License](LICENSE).
282
375
  ---
283
376
 
284
377
  **🏠 Made for reliable household management with LLMs**
285
- *Prioritizing workflow efficiency over feature completeness*
378
+ _Prioritizing workflow efficiency over feature completeness_
@@ -0,0 +1,47 @@
1
+ # [2.6.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.5.0...v2.6.0) (2026-07-06)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * reap idle streamable HTTP sessions to prevent McpServer leak ([c55b2c4](https://github.com/miguelangel-nubla/mcp-grocy/commit/c55b2c4808dac4ac5f0c55a45936c8f995d5efc3))
7
+
8
+
9
+ ### Features
10
+
11
+ * add shopping_list_update_item tool to allow modifying list items ([dcbc974](https://github.com/miguelangel-nubla/mcp-grocy/commit/dcbc9746630667bbe89330bab7f7e9f84a3f060f))
12
+ * add shopping_lists_* configurations to example yaml ([204f03d](https://github.com/miguelangel-nubla/mcp-grocy/commit/204f03dca8c9ca17f3cfc476274f0a5b844912c7))
13
+ * configure husky git hooks ([c8ac158](https://github.com/miguelangel-nubla/mcp-grocy/commit/c8ac1582f477c6dc074166b5a9753a06608c8007))
14
+ * enhance shopping list tools with manual item support and enriched metadata resolution ([a1a8ce3](https://github.com/miguelangel-nubla/mcp-grocy/commit/a1a8ce341b61e5b24a366ae74a95a2c92e93e07c))
15
+ * enrich shopping list tool responses with product and quantity unit details ([56bd553](https://github.com/miguelangel-nubla/mcp-grocy/commit/56bd553e17d913db1f2c61fc963a900f6477f45f))
16
+ * expand shopping module with get, update, and filtered list capabilities ([d7e0e5d](https://github.com/miguelangel-nubla/mcp-grocy/commit/d7e0e5d94962c1b4daf0835a91fc275c25188673))
17
+ * make productId optional in shopping list add tool ([a427e18](https://github.com/miguelangel-nubla/mcp-grocy/commit/a427e1832a9b70e579dae062c7665ec472656359))
18
+
19
+ # [2.5.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.4.4...v2.5.0) (2026-03-30)
20
+
21
+ ### Bug Fixes
22
+
23
+ - add read permissions for contents in release workflow to support nested publish-docker job ([5a055a6](https://github.com/miguelangel-nubla/mcp-grocy/commit/5a055a62cf07fa3f0f03d4319e485350c111804a))
24
+ - improve test build isolation and commit-specific tagging ([b1875cc](https://github.com/miguelangel-nubla/mcp-grocy/commit/b1875ccc080111c6d56700aab9c493e418d155be))
25
+
26
+ ### Features
27
+
28
+ - improve tool call error handling, and implement multi-server shutdown management ([4d19cfb](https://github.com/miguelangel-nubla/mcp-grocy/commit/4d19cfb35dc238a41a92d2fba505998b6a59e1ae))
29
+
30
+ # Changelog
31
+
32
+ All notable changes to this project will be documented in this file.
33
+
34
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
35
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
36
+
37
+ Release notes are appended automatically by [semantic-release](https://semantic-release.gitbook.io/) using `@semantic-release/changelog`.
38
+
39
+ ## [Unreleased]
40
+
41
+ ### ⚠️ Breaking Changes
42
+
43
+ - **MCP resource URIs** use the **`mcp-grocy://`** scheme (from `package.json` `name`, generated into `SERVER_NAME` at build time). Bundled docs: `mcp-grocy://examples`, `mcp-grocy://response-format`, `mcp-grocy://config`. Clients, prompts, or bookmarks that used **`grocy-api://…`** must be updated.
44
+
45
+ ### Added
46
+
47
+ - **MCP tool `annotations.readOnlyHint: true`** on read-only tools (inventory/recipes/shopping/household/system getters and lookups only—no `*_print_*`, dev tools, or mutating calls). Optional hint for clients; not a security boundary.
@@ -4,12 +4,11 @@ This addon allows you to run MCP server that communicates with Grocy API in your
4
4
 
5
5
  ## Installation
6
6
 
7
- 1. Add this repository to your Home Assistant addon store:
7
+ 1. Add this repository to your Home Assistant addon store:
8
8
  [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https://github.com/miguelangel-nubla/hassio-addons)
9
9
 
10
10
  2. Find the "MCP Grocy API" addon and click Install.
11
11
 
12
-
13
12
  ## How-to-use
14
13
 
15
14
  You cannot use this with [Model Context Protocol](https://www.home-assistant.io/integrations/mcp) alone.
@@ -30,26 +29,32 @@ http_server_port: 8080
30
29
  ```
31
30
 
32
31
  ### Option: `grocy_base_url` (required)
32
+
33
33
  - The URL to your Grocy instance.
34
34
  - Example: `https://grocy.example.com`
35
35
 
36
36
  ### Option: `grocy_api_key` (required)
37
+
37
38
  - Your Grocy API key.
38
39
  - You can find this in your Grocy settings.
39
40
 
40
41
  ### Option: `enable_ssl_verify` (optional)
42
+
41
43
  - Set to `false` to disable SSL verification (useful for self-signed certificates).
42
44
  - Default: `true`
43
45
 
44
46
  ### Option: `response_size_limit` (optional)
47
+
45
48
  - Maximum size of API responses.
46
49
  - Default: `10000`
47
50
 
48
51
  ### Option: `enable_http_server` (optional)
52
+
49
53
  - Set to `false` to disable streamable http and sse protocol server.
50
54
  - Default: `true`
51
55
 
52
56
  ### Option: `http_server_port` (optional)
57
+
53
58
  - Set to port you want to use in streamable http and sse protocol server.
54
59
  - Default: `8080`
55
60
 
@@ -59,4 +64,4 @@ This addon communicates with Home Assistant via standard input/output (stdio) or
59
64
 
60
65
  ## Support
61
66
 
62
- If you have any issues or questions, please file an issue on the GitHub repository.
67
+ If you have any issues or questions, please file an issue on the GitHub repository.