mcp-grocy 2.2.0 → 2.5.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 +31 -0
- package/README.md +112 -32
- package/build/api/client.js +11 -13
- package/build/config/index.js +74 -20
- package/build/resources/CHANGELOG.md +31 -0
- package/build/resources/DOCS.md +8 -3
- package/build/resources/README.md +112 -32
- package/build/resources/api-reference.md +88 -88
- package/build/resources/config.md +30 -17
- package/build/resources/examples.md +120 -221
- package/build/resources/installation.md +9 -14
- package/build/resources/response-format.md +18 -13
- package/build/server/http-server.js +154 -42
- package/build/server/mcp-server.js +143 -96
- package/build/server/resources.js +37 -24
- package/build/server/tool-input-zod.js +86 -0
- package/build/tools/base.js +19 -15
- package/build/tools/household/definitions.js +47 -43
- package/build/tools/household/handlers.js +2 -2
- package/build/tools/household/index.js +2 -2
- package/build/tools/inventory/definitions.js +150 -113
- package/build/tools/inventory/handlers.js +55 -42
- package/build/tools/inventory/index.js +2 -2
- package/build/tools/module-loader.js +15 -12
- package/build/tools/recipes/definitions.js +103 -86
- package/build/tools/recipes/handlers.js +44 -38
- package/build/tools/recipes/index.js +3 -3
- package/build/tools/recipes/validations.js +8 -2
- package/build/tools/shopping/definitions.js +22 -20
- package/build/tools/shopping/handlers.js +1 -1
- package/build/tools/shopping/index.js +2 -2
- package/build/tools/system/definitions.js +25 -22
- package/build/tools/system/handlers.js +74 -12
- package/build/tools/system/index.js +2 -2
- package/build/tools/validation-helpers.js +10 -7
- package/build/types/index.js +12 -10
- package/build/utils/errors.js +10 -5
- package/build/utils/logger.js +16 -15
- package/build/version.js +2 -2
- package/package.json +38 -23
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.
|
|
@@ -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,83 @@ 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
|
|
|
200
231
|
#### Debug Mode
|
|
201
232
|
|
|
202
233
|
Enable detailed logging and use the MCP inspector:
|
|
234
|
+
|
|
203
235
|
```bash
|
|
204
236
|
# Launch MCP inspector for protocol debugging
|
|
205
237
|
npm run inspector
|
|
@@ -212,8 +244,8 @@ npm run dev
|
|
|
212
244
|
|
|
213
245
|
### Prerequisites
|
|
214
246
|
|
|
215
|
-
- Node.js
|
|
216
|
-
- Grocy instance (optional
|
|
247
|
+
- Node.js 22 or newer (see **Requirements** above)
|
|
248
|
+
- Grocy instance (optional: use placeholder URLs/keys in `.env` for local runs)
|
|
217
249
|
|
|
218
250
|
### Development Setup
|
|
219
251
|
|
|
@@ -234,18 +266,63 @@ npm start
|
|
|
234
266
|
|
|
235
267
|
### Development Commands
|
|
236
268
|
|
|
237
|
-
| Command
|
|
238
|
-
|
|
239
|
-
| `npm run build`
|
|
240
|
-
| `npm
|
|
241
|
-
| `npm run dev`
|
|
242
|
-
| `npm
|
|
243
|
-
| `npm
|
|
244
|
-
| `npm run
|
|
269
|
+
| Command | Description |
|
|
270
|
+
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
271
|
+
| `npm run build` | Build TypeScript to JavaScript |
|
|
272
|
+
| `npm start` | Run the built server (`build/main.js`) |
|
|
273
|
+
| `npm run dev` | Build, then run (use mock `.env` for local testing) |
|
|
274
|
+
| `npm run watch` | Watch mode for development |
|
|
275
|
+
| `npm test` | Run test suite |
|
|
276
|
+
| `npm run test:watch` | Run tests in watch mode |
|
|
277
|
+
| `npm run inspector` | Launch MCP protocol inspector |
|
|
278
|
+
| `npm run dev:mcp-tef` | Run [mcp-tef](https://github.com/StacklokLabs/mcp-tef) locally (needs **uv** + **Ollama**) for tool-description / similarity checks |
|
|
279
|
+
| `npm run report:mcp-tef` | One command: build, temporary mcp-grocy HTTP + mcp-tef, write `reports/mcp-tef/<timestamp>/` (similarity JSON + `SUMMARY.md`) |
|
|
280
|
+
|
|
281
|
+
### Optional: mcp-tef (local tool evaluation)
|
|
282
|
+
|
|
283
|
+
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):
|
|
284
|
+
|
|
285
|
+
1. Install [uv](https://docs.astral.sh/uv/) and start Ollama; pull a small model, e.g. `ollama pull llama3.2:3b`.
|
|
286
|
+
2. Build and start **mcp-grocy over HTTP** in another terminal (SSE endpoint for mcp-tef):
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
npm run build
|
|
290
|
+
MCP_HTTP_TRANSPORT_ONLY=true ENABLE_HTTP_SERVER=true HTTP_SERVER_PORT=8790 npm start
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
3. Start mcp-tef:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
npm run dev:mcp-tef
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
4. Open `http://127.0.0.1:8000/docs` and point workflows at **`http://127.0.0.1:8790/mcp/sse`** (or your port).
|
|
300
|
+
|
|
301
|
+
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`.
|
|
302
|
+
|
|
303
|
+
**One-shot report (no manual API calls):**
|
|
304
|
+
|
|
305
|
+
```bash
|
|
306
|
+
npm run report:mcp-tef
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Writes under `reports/mcp-tef/<timestamp>/`:
|
|
310
|
+
|
|
311
|
+
- **`REPORT.md`** — human-readable: tools by domain, flagged pairs as a **markdown table** (short tool names, similarity %).
|
|
312
|
+
- **`REPORT.html`** — same pairs in a simple table; open in a browser if you prefer.
|
|
313
|
+
- **`SUMMARY.md`** — one-screen pointer + counts.
|
|
314
|
+
- **`similarity.json`** — full API response (matrix, composite ids).
|
|
315
|
+
|
|
316
|
+
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.
|
|
317
|
+
|
|
318
|
+
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).
|
|
319
|
+
|
|
320
|
+
Optional per-tool **`title`** and **`meta`** (→ MCP `_meta`) can be set in definitions when they add real signal; otherwise clients use **`name`** only.
|
|
245
321
|
|
|
246
322
|
### Debugging
|
|
247
323
|
|
|
248
324
|
Use the MCP inspector to debug protocol interactions:
|
|
325
|
+
|
|
249
326
|
```bash
|
|
250
327
|
npm run inspector
|
|
251
328
|
```
|
|
@@ -257,22 +334,25 @@ This launches a web interface for testing MCP tools and viewing protocol message
|
|
|
257
334
|
This is an **opinionated fork** focused on LLM usability and workflow reliability. Contributions are welcome but must align with the core philosophy:
|
|
258
335
|
|
|
259
336
|
### ✅ Welcome Contributions
|
|
337
|
+
|
|
260
338
|
- Bug fixes and reliability improvements
|
|
261
|
-
- Better error handling and validation
|
|
339
|
+
- Better error handling and validation
|
|
262
340
|
- Documentation improvements
|
|
263
341
|
- Test coverage enhancements
|
|
264
342
|
- Performance optimizations
|
|
265
343
|
|
|
266
344
|
### ❌ Contributions Requiring Discussion
|
|
345
|
+
|
|
267
346
|
- New tool additions (must demonstrate clear LLM workflow benefits)
|
|
268
347
|
- API design changes that increase complexity
|
|
269
348
|
- Features that expose raw Grocy API behavior
|
|
270
349
|
|
|
271
350
|
### Development Workflow
|
|
351
|
+
|
|
272
352
|
1. Fork the repository
|
|
273
353
|
2. Create a feature branch
|
|
274
354
|
3. Make your changes with tests
|
|
275
|
-
4. Run `npm test` and ensure all tests pass
|
|
355
|
+
4. Run `npm test` and ensure all tests pass
|
|
276
356
|
5. Submit a pull request with clear description
|
|
277
357
|
|
|
278
358
|
## 📄 License
|
|
@@ -282,4 +362,4 @@ This project is licensed under the [MIT License](LICENSE).
|
|
|
282
362
|
---
|
|
283
363
|
|
|
284
364
|
**🏠 Made for reliable household management with LLMs**
|
|
285
|
-
|
|
365
|
+
_Prioritizing workflow efficiency over feature completeness_
|
|
@@ -2,91 +2,91 @@
|
|
|
2
2
|
|
|
3
3
|
> Auto-generated from https://demo.grocy.info/api/openapi/specification on 2025-05-17T16:56:10.327Z
|
|
4
4
|
|
|
5
|
-
| Path
|
|
6
|
-
|
|
7
|
-
| /batteries
|
|
8
|
-
| /batteries/charge-cycles/{chargeCycleId}/undo
|
|
9
|
-
| /batteries/{batteryId}
|
|
10
|
-
| /batteries/{batteryId}/charge
|
|
11
|
-
| /batteries/{batteryId}/printlabel
|
|
12
|
-
| /calendar/ical
|
|
13
|
-
| /calendar/ical/sharing-link
|
|
14
|
-
| /chores
|
|
15
|
-
| /chores/executions/calculate-next-assignments
|
|
16
|
-
| /chores/executions/{executionId}/undo
|
|
17
|
-
| /chores/{choreIdToKeep}/merge/{choreIdToRemove}
|
|
18
|
-
| /chores/{choreId}
|
|
19
|
-
| /chores/{choreId}/execute
|
|
20
|
-
| /chores/{choreId}/printlabel
|
|
21
|
-
| /files/{group}/{fileName}
|
|
22
|
-
| /files/{group}/{fileName}
|
|
23
|
-
| /files/{group}/{fileName}
|
|
24
|
-
| /objects/{entity}
|
|
25
|
-
| /objects/{entity}
|
|
26
|
-
| /objects/{entity}/{objectId}
|
|
27
|
-
| /objects/{entity}/{objectId}
|
|
28
|
-
| /objects/{entity}/{objectId}
|
|
29
|
-
| /print/shoppinglist/thermal
|
|
30
|
-
| /recipes/fulfillment
|
|
31
|
-
| /recipes/{recipeId}/add-not-fulfilled-products-to-shoppinglist | POST
|
|
32
|
-
| /recipes/{recipeId}/consume
|
|
33
|
-
| /recipes/{recipeId}/copy
|
|
34
|
-
| /recipes/{recipeId}/fulfillment
|
|
35
|
-
| /recipes/{recipeId}/printlabel
|
|
36
|
-
| /stock
|
|
37
|
-
| /stock/barcodes/external-lookup/{barcode}
|
|
38
|
-
| /stock/bookings/{bookingId}
|
|
39
|
-
| /stock/bookings/{bookingId}/undo
|
|
40
|
-
| /stock/entry/{entryId}
|
|
41
|
-
| /stock/entry/{entryId}
|
|
42
|
-
| /stock/entry/{entryId}/printlabel
|
|
43
|
-
| /stock/locations/{locationId}/entries
|
|
44
|
-
| /stock/products/by-barcode/{barcode}
|
|
45
|
-
| /stock/products/by-barcode/{barcode}/add
|
|
46
|
-
| /stock/products/by-barcode/{barcode}/consume
|
|
47
|
-
| /stock/products/by-barcode/{barcode}/inventory
|
|
48
|
-
| /stock/products/by-barcode/{barcode}/open
|
|
49
|
-
| /stock/products/by-barcode/{barcode}/transfer
|
|
50
|
-
| /stock/products/{productIdToKeep}/merge/{productIdToRemove}
|
|
51
|
-
| /stock/products/{productId}
|
|
52
|
-
| /stock/products/{productId}/add
|
|
53
|
-
| /stock/products/{productId}/consume
|
|
54
|
-
| /stock/products/{productId}/entries
|
|
55
|
-
| /stock/products/{productId}/inventory
|
|
56
|
-
| /stock/products/{productId}/locations
|
|
57
|
-
| /stock/products/{productId}/open
|
|
58
|
-
| /stock/products/{productId}/price-history
|
|
59
|
-
| /stock/products/{productId}/printlabel
|
|
60
|
-
| /stock/products/{productId}/transfer
|
|
61
|
-
| /stock/shoppinglist/add-expired-products
|
|
62
|
-
| /stock/shoppinglist/add-missing-products
|
|
63
|
-
| /stock/shoppinglist/add-overdue-products
|
|
64
|
-
| /stock/shoppinglist/add-product
|
|
65
|
-
| /stock/shoppinglist/clear
|
|
66
|
-
| /stock/shoppinglist/remove-product
|
|
67
|
-
| /stock/transactions/{transactionId}
|
|
68
|
-
| /stock/transactions/{transactionId}/undo
|
|
69
|
-
| /stock/volatile
|
|
70
|
-
| /system/config
|
|
71
|
-
| /system/db-changed-time
|
|
72
|
-
| /system/info
|
|
73
|
-
| /system/localization-strings
|
|
74
|
-
| /system/log-missing-localization
|
|
75
|
-
| /system/time
|
|
76
|
-
| /tasks
|
|
77
|
-
| /tasks/{taskId}/complete
|
|
78
|
-
| /tasks/{taskId}/undo
|
|
79
|
-
| /user
|
|
80
|
-
| /user/settings
|
|
81
|
-
| /user/settings/{settingKey}
|
|
82
|
-
| /user/settings/{settingKey}
|
|
83
|
-
| /user/settings/{settingKey}
|
|
84
|
-
| /userfields/{entity}/{objectId}
|
|
85
|
-
| /userfields/{entity}/{objectId}
|
|
86
|
-
| /users
|
|
87
|
-
| /users
|
|
88
|
-
| /users/{userId}
|
|
89
|
-
| /users/{userId}
|
|
90
|
-
| /users/{userId}/permissions
|
|
91
|
-
| /users/{userId}/permissions
|
|
92
|
-
| /users/{userId}/permissions
|
|
5
|
+
| Path | Method | Summary |
|
|
6
|
+
| -------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
7
|
+
| /batteries | GET | Returns all batteries incl. the next estimated charge time per battery |
|
|
8
|
+
| /batteries/charge-cycles/{chargeCycleId}/undo | POST | Undoes a battery charge cycle |
|
|
9
|
+
| /batteries/{batteryId} | GET | Returns details of the given battery |
|
|
10
|
+
| /batteries/{batteryId}/charge | POST | Tracks a charge cycle of the given battery |
|
|
11
|
+
| /batteries/{batteryId}/printlabel | GET | Prints the Grocycode label of the given battery on the configured label printer |
|
|
12
|
+
| /calendar/ical | GET | Returns the calendar in iCal format |
|
|
13
|
+
| /calendar/ical/sharing-link | GET | Returns a (public) sharing link for the calendar in iCal format |
|
|
14
|
+
| /chores | GET | Returns all chores incl. the next estimated execution time per chore |
|
|
15
|
+
| /chores/executions/calculate-next-assignments | POST | (Re)calculates all next user assignments of all chores |
|
|
16
|
+
| /chores/executions/{executionId}/undo | POST | Undoes a chore execution |
|
|
17
|
+
| /chores/{choreIdToKeep}/merge/{choreIdToRemove} | POST | Merges two chores into one |
|
|
18
|
+
| /chores/{choreId} | GET | Returns details of the given chore |
|
|
19
|
+
| /chores/{choreId}/execute | POST | Tracks an execution of the given chore |
|
|
20
|
+
| /chores/{choreId}/printlabel | GET | Prints the Grocycode label of the given chore on the configured label printer |
|
|
21
|
+
| /files/{group}/{fileName} | GET | Serves the given file |
|
|
22
|
+
| /files/{group}/{fileName} | PUT | Uploads a single file |
|
|
23
|
+
| /files/{group}/{fileName} | DELETE | Deletes the given file |
|
|
24
|
+
| /objects/{entity} | GET | Returns all objects of the given entity |
|
|
25
|
+
| /objects/{entity} | POST | Adds a single object of the given entity |
|
|
26
|
+
| /objects/{entity}/{objectId} | GET | Returns a single object of the given entity |
|
|
27
|
+
| /objects/{entity}/{objectId} | PUT | Edits the given object of the given entity |
|
|
28
|
+
| /objects/{entity}/{objectId} | DELETE | Deletes a single object of the given entity |
|
|
29
|
+
| /print/shoppinglist/thermal | GET | Prints the shoppinglist with a thermal printer |
|
|
30
|
+
| /recipes/fulfillment | GET | Get stock fulfillment information for all recipe |
|
|
31
|
+
| /recipes/{recipeId}/add-not-fulfilled-products-to-shoppinglist | POST | Adds all missing products for the given recipe to the shopping list |
|
|
32
|
+
| /recipes/{recipeId}/consume | POST | Consumes all in stock ingredients of the given recipe (for ingredients that are only partially in stock, the in stock amount will be consumed) |
|
|
33
|
+
| /recipes/{recipeId}/copy | POST | Copies a recipe |
|
|
34
|
+
| /recipes/{recipeId}/fulfillment | GET | Get stock fulfillment information for the given recipe |
|
|
35
|
+
| /recipes/{recipeId}/printlabel | GET | Prints the Grocycode label of the given recipe on the configured label printer |
|
|
36
|
+
| /stock | GET | Returns all products which are currently in stock incl. the next due date per product |
|
|
37
|
+
| /stock/barcodes/external-lookup/{barcode} | GET | Executes an external barcode lookoup via the configured plugin with the given barcode |
|
|
38
|
+
| /stock/bookings/{bookingId} | GET | Returns the given stock booking |
|
|
39
|
+
| /stock/bookings/{bookingId}/undo | POST | Undoes a booking |
|
|
40
|
+
| /stock/entry/{entryId} | GET | Returns details of the given stock |
|
|
41
|
+
| /stock/entry/{entryId} | PUT | Edits the stock entry |
|
|
42
|
+
| /stock/entry/{entryId}/printlabel | GET | Prints the Grocycode / stock entry label of the given entry on the configured label printer |
|
|
43
|
+
| /stock/locations/{locationId}/entries | GET | Returns all stock entries of the given location |
|
|
44
|
+
| /stock/products/by-barcode/{barcode} | GET | Returns details of the given product by its barcode |
|
|
45
|
+
| /stock/products/by-barcode/{barcode}/add | POST | Adds the given amount of the by its barcode given product to stock |
|
|
46
|
+
| /stock/products/by-barcode/{barcode}/consume | POST | Removes the given amount of the by its barcode given product from stock |
|
|
47
|
+
| /stock/products/by-barcode/{barcode}/inventory | POST | Inventories the by its barcode given product (adds/removes based on the given new amount) |
|
|
48
|
+
| /stock/products/by-barcode/{barcode}/open | POST | Marks the given amount of the by its barcode given product as opened |
|
|
49
|
+
| /stock/products/by-barcode/{barcode}/transfer | POST | Transfers the given amount of the by its barcode given product from one location to another (this is currently not supported for tare weight handling enabled products) |
|
|
50
|
+
| /stock/products/{productIdToKeep}/merge/{productIdToRemove} | POST | Merges two products into one |
|
|
51
|
+
| /stock/products/{productId} | GET | Returns details of the given product |
|
|
52
|
+
| /stock/products/{productId}/add | POST | Adds the given amount of the given product to stock |
|
|
53
|
+
| /stock/products/{productId}/consume | POST | Removes the given amount of the given product from stock |
|
|
54
|
+
| /stock/products/{productId}/entries | GET | Returns all stock entries of the given product in order of next use (Opened first, then first due first, then first in first out) |
|
|
55
|
+
| /stock/products/{productId}/inventory | POST | Inventories the given product (adds/removes based on the given new amount) |
|
|
56
|
+
| /stock/products/{productId}/locations | GET | Returns all locations where the given product currently has stock |
|
|
57
|
+
| /stock/products/{productId}/open | POST | Marks the given amount of the given product as opened |
|
|
58
|
+
| /stock/products/{productId}/price-history | GET | Returns the price history of the given product |
|
|
59
|
+
| /stock/products/{productId}/printlabel | GET | Prints the Grocycode label of the given product on the configured label printer |
|
|
60
|
+
| /stock/products/{productId}/transfer | POST | Transfers the given amount of the given product from one location to another (this is currently not supported for tare weight handling enabled products) |
|
|
61
|
+
| /stock/shoppinglist/add-expired-products | POST | Adds expired products to the given shopping list |
|
|
62
|
+
| /stock/shoppinglist/add-missing-products | POST | Adds currently missing products (below defined min. stock amount) to the given shopping list |
|
|
63
|
+
| /stock/shoppinglist/add-overdue-products | POST | Adds overdue products to the given shopping list |
|
|
64
|
+
| /stock/shoppinglist/add-product | POST | Adds the given amount of the given product to the given shopping list |
|
|
65
|
+
| /stock/shoppinglist/clear | POST | Removes all items from the given shopping list |
|
|
66
|
+
| /stock/shoppinglist/remove-product | POST | Removes the given amount of the given product from the given shopping list, if it is on it |
|
|
67
|
+
| /stock/transactions/{transactionId} | GET | Returns all stock bookings of the given transaction id |
|
|
68
|
+
| /stock/transactions/{transactionId}/undo | POST | Undoes a transaction |
|
|
69
|
+
| /stock/volatile | GET | Returns all products which are due soon, overdue, expired or currently missing |
|
|
70
|
+
| /system/config | GET | Returns all config settings |
|
|
71
|
+
| /system/db-changed-time | GET | Returns the time when the database was last changed |
|
|
72
|
+
| /system/info | GET | Returns information about the installed Grocy version, PHP runtime and OS |
|
|
73
|
+
| /system/localization-strings | GET | Returns all localization strings (in the by the user desired language) |
|
|
74
|
+
| /system/log-missing-localization | POST | Logs a missing localization string |
|
|
75
|
+
| /system/time | GET | Returns the current server time |
|
|
76
|
+
| /tasks | GET | Returns all tasks which are not done yet |
|
|
77
|
+
| /tasks/{taskId}/complete | POST | Marks the given task as completed |
|
|
78
|
+
| /tasks/{taskId}/undo | POST | Marks the given task as not completed |
|
|
79
|
+
| /user | GET | Returns the currently authenticated user |
|
|
80
|
+
| /user/settings | GET | Returns all settings of the currently logged in user |
|
|
81
|
+
| /user/settings/{settingKey} | GET | Returns the given setting of the currently logged in user |
|
|
82
|
+
| /user/settings/{settingKey} | PUT | Sets the given setting of the currently logged in user |
|
|
83
|
+
| /user/settings/{settingKey} | DELETE | Deletes the given setting of the currently logged in user |
|
|
84
|
+
| /userfields/{entity}/{objectId} | GET | Returns all userfields with their values of the given object of the given entity |
|
|
85
|
+
| /userfields/{entity}/{objectId} | PUT | Edits the given userfields of the given object of the given entity |
|
|
86
|
+
| /users | GET | Returns all users |
|
|
87
|
+
| /users | POST | Creates a new user |
|
|
88
|
+
| /users/{userId} | PUT | Edits the given user |
|
|
89
|
+
| /users/{userId} | DELETE | Deletes the given user |
|
|
90
|
+
| /users/{userId}/permissions | GET | Returns the assigned permissions of the given user |
|
|
91
|
+
| /users/{userId}/permissions | POST | Adds a permission to the given user |
|
|
92
|
+
| /users/{userId}/permissions | PUT | Replaces the assigned permissions of the given user |
|