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.
- package/CHANGELOG.md +45 -0
- package/README.md +125 -32
- package/build/resources/CHANGELOG.md +47 -0
- package/build/resources/DOCS.md +8 -3
- package/build/resources/README.md +125 -32
- package/build/resources/api-reference.md +88 -88
- package/build/resources/config.md +45 -17
- package/build/resources/examples.md +120 -221
- package/build/resources/installation.md +9 -14
- package/build/resources/response-format.md +29 -20
- package/build/version.js +2 -2
- package/package.json +50 -24
- package/build/api/client.js +0 -121
- package/build/config/index.js +0 -205
- package/build/main.js +0 -44
- package/build/server/http-server.js +0 -218
- package/build/server/mcp-server.js +0 -163
- package/build/server/resources.js +0 -60
- package/build/tools/base.js +0 -141
- package/build/tools/household/definitions.js +0 -157
- package/build/tools/household/handlers.js +0 -109
- package/build/tools/household/index.js +0 -25
- package/build/tools/index.js +0 -2
- package/build/tools/inventory/definitions.js +0 -379
- package/build/tools/inventory/handlers.js +0 -430
- package/build/tools/inventory/index.js +0 -32
- package/build/tools/module-loader.js +0 -151
- package/build/tools/recipes/definitions.js +0 -261
- package/build/tools/recipes/handlers.js +0 -471
- package/build/tools/recipes/index.js +0 -33
- package/build/tools/recipes/validations.js +0 -23
- package/build/tools/shopping/definitions.js +0 -71
- package/build/tools/shopping/handlers.js +0 -43
- package/build/tools/shopping/index.js +0 -14
- package/build/tools/system/definitions.js +0 -86
- package/build/tools/system/handlers.js +0 -94
- package/build/tools/system/index.js +0 -16
- package/build/tools/types.js +0 -1
- package/build/tools/validation-helpers.js +0 -36
- package/build/types/index.js +0 -62
- package/build/utils/errors.js +0 -138
- 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
|
[](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
|
|
139
|
-
|
|
140
|
-
| **`.env` file**
|
|
141
|
-
| **Environment variables** | CI/CD, containers
|
|
142
|
-
| **Tool configuration**
|
|
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
|
|
172
|
-
|
|
173
|
-
| [📖 API Reference](src/resources/api-reference.md)
|
|
174
|
-
| [⚙️ Configuration Guide](src/resources/config.md)
|
|
175
|
-
| [📋 .env.example](.env.example)
|
|
176
|
-
| [🧪 MCP Inspector](https://github.com/modelcontextprotocol/inspector) | Protocol debugging
|
|
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
|
|
216
|
-
- Grocy instance (optional
|
|
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
|
|
238
|
-
|
|
239
|
-
| `npm run build`
|
|
240
|
-
| `npm
|
|
241
|
-
| `npm run dev`
|
|
242
|
-
| `npm
|
|
243
|
-
| `npm
|
|
244
|
-
| `npm run
|
|
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
|
-
|
|
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.
|
package/build/resources/DOCS.md
CHANGED
|
@@ -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
|
[](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.
|