mcp-grocy 2.2.0 → 2.5.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# [2.5.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.4.4...v2.5.0) (2026-03-30)
+
+
+### Bug Fixes
+
+* add read permissions for contents in release workflow to support nested publish-docker job ([5a055a6](https://github.com/miguelangel-nubla/mcp-grocy/commit/5a055a62cf07fa3f0f03d4319e485350c111804a))
+* improve test build isolation and commit-specific tagging ([b1875cc](https://github.com/miguelangel-nubla/mcp-grocy/commit/b1875ccc080111c6d56700aab9c493e418d155be))
+
+
+### Features
+
+* improve tool call error handling, and implement multi-server shutdown management ([4d19cfb](https://github.com/miguelangel-nubla/mcp-grocy/commit/4d19cfb35dc238a41a92d2fba505998b6a59e1ae))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Release notes are appended automatically by [semantic-release](https://semantic-release.gitbook.io/) using `@semantic-release/changelog`.
+
+## [Unreleased]
+
+### ⚠️ Breaking Changes
+
+- **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.
+
+### Added
+
+- **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

@@ -8,20 +8,22 @@
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
 
 > **🍴 Opinionated Fork Notice**
-> 
+>
 > 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**.
 >
 > **Why This Fork Exists:**
+>
 > - The original wrapper exposes the entire Grocy API unprocessed, leading to context overload and LLM confusion
 > - Grocy's API design choices and limitations cause error-prone interactions
 > - Generic API exposure increases hallucination and near-miss results
-> 
+>
 > **This Fork's Philosophy:**
+>
 > - **Filters and augments data** with relevant context for better LLM comprehension
 > - **Reduces API calls** by combining common operations to minimize error chains
 > - **Optimizes for reliability and repeatability** over feature completeness
 > - **Opinionated workflows** that may not match everyone's preferences
-> 
+>
 > 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.
 
 ## 🎯 What This MCP Does
@@ -29,24 +31,28 @@
 Transform your LLM into an intelligent household management assistant with focused tools for:
 
 ### 📦 **Stock Management**
+
 - Track inventory across multiple locations with precision
 - Record purchases and consumption with automatic stock updates
 - Monitor expiry dates and get volatile stock alerts
 - Transfer products between storage locations
 
 ### 🛒 **Smart Shopping & Planning**
+
 - Maintain shopping lists with intelligent quantity management
 - Plan meals with recipe scheduling and fulfillment checking
 - Automatically add missing ingredients to shopping lists
 - Track shopping locations and optimize store visits
 
-### 🍽️ **Recipe & Meal Workflows** 
+### 🍽️ **Recipe & Meal Workflows**
+
 - Find recipes with fuzzy search capabilities
 - Check if recipes can be made with current stock
 - Complete cooking workflows with portion control
 - Integrate meal planning with inventory consumption
 
 ### 🏠 **Household Management**
+
 - Manage chores, tasks, and battery tracking
 - Get product price history for budgeting
 - Organize products by groups and categories
@@ -56,21 +62,24 @@ Transform your LLM into an intelligent household management assistant with focus
 
 1. **Get your Grocy API key** from your Grocy instance (User Settings → API Keys)
 2. **Set up with Docker Compose:**
+
    ```bash
    # Get the project
    git clone https://github.com/miguelangel-nubla/mcp-grocy.git
    cd mcp-grocy
-   
+
    # Configure
    cp .env.example .env
    # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
-   
+
    # Run
    docker compose up -d
    ```
 
 ### Try Without Grocy
+
 Test with mock data (no real Grocy instance needed):
+
 ```bash
 # In .env file, any values work for mock mode
 GROCY_BASE_URL=http://mock
@@ -79,6 +88,14 @@ GROCY_API_KEY=mock
 npm install && npm run dev
 ```
 
+## Requirements (Node.js & tooling)
+
+- **Node.js:** **22 or newer** as declared in `package.json` `engines`. **GitHub Actions** and **`.nvmrc`** use **Node 22** for CI and local alignment.
+- **Docker:** the default image is **`node:22-alpine`** so the container matches that major version (Home Assistant addon builds still override the base image).
+- **TypeScript:** **5.9** in this repo; **TypeScript 6** is waiting on **`typescript-eslint`** to declare compatible peer support.
+- **`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.
+- **Quality checks:** `npm run lint` (ESLint), `npm run format:check` (Prettier), `npm test` (Vitest).
+
 ## Installation
 
 ### NPM
@@ -99,6 +116,7 @@ docker run -e GROCY_API_KEY=your_api_key -e GROCY_BASE_URL=http://your-grocy-ins
 ### Docker Compose (Recommended)
 
 Create a `docker-compose.yml`:
+
 ```yaml
 services:
   mcp-grocy:
@@ -109,6 +127,7 @@ services:
 ```
 
 Then:
+
 ```bash
 cp .env.example .env
 # Edit .env with your configuration
@@ -124,6 +143,7 @@ docker compose up -d
    - Create a new API key and copy it
 
 2. **Configure the server:**
+
    ```bash
    cp .env.example .env
    # Edit .env with your GROCY_BASE_URL and GROCY_API_KEY
@@ -135,71 +155,83 @@ docker compose up -d
 
 ### Configuration Options
 
-| Method | Use Case | Command |
-|--------|----------|---------|
-| **`.env` file** | Recommended for most users | `cp .env.example .env` |
-| **Environment variables** | CI/CD, containers | `GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy` |
-| **Tool configuration** | Customize functionality | Edit `tools` section in `mcp-grocy.yaml` |
+| Method                    | Use Case                   | Command                                          |
+| ------------------------- | -------------------------- | ------------------------------------------------ |
+| **`.env` file**           | Recommended for most users | `cp .env.example .env`                           |
+| **Environment variables** | CI/CD, containers          | `GROCY_BASE_URL=... GROCY_API_KEY=... mcp-grocy` |
+| **Tool configuration**    | Customize functionality    | Edit `tools` section in `mcp-grocy.yaml`         |
 
 📖 **For complete configuration reference:** See [Configuration Guide](src/resources/config.md)
 
 ## 🚀 Usage Modes
 
 ### Production Mode
+
 Start with your real Grocy instance:
+
 ```bash
 npm start
 ```
 
 ### Development/Testing Mode
+
 Use mock data (no Grocy instance required):
+
 ```bash
 npm run dev
 ```
 
-### HTTP Server Mode  
+### HTTP Server Mode
+
 Enable web-based access via HTTP/SSE:
+
 ```bash
 # In .env: ENABLE_HTTP_SERVER=true
 npm start
 # Access via http://localhost:8080/mcp
 ```
 
-
 ## 📚 Documentation & Resources
 
-| Resource | Purpose | When to Use |
-|----------|---------|-------------|
-| [📖 API Reference](src/resources/api-reference.md) | Complete tool documentation | Tool usage and examples |
-| [⚙️ Configuration Guide](src/resources/config.md) | Advanced configuration reference | Detailed setup, presets, troubleshooting |
-| [📋 .env.example](.env.example) | Environment configuration template | Copy and customize for your setup |
-| [🧪 MCP Inspector](https://github.com/modelcontextprotocol/inspector) | Protocol debugging | Debug MCP interactions |
+| Resource                                                              | Purpose                            | When to Use                              |
+| --------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------- |
+| [📖 API Reference](src/resources/api-reference.md)                    | Complete tool documentation        | Tool usage and examples                  |
+| [⚙️ Configuration Guide](src/resources/config.md)                     | Advanced configuration reference   | Detailed setup, presets, troubleshooting |
+| [📋 .env.example](.env.example)                                       | Environment configuration template | Copy and customize for your setup        |
+| [🧪 MCP Inspector](https://github.com/modelcontextprotocol/inspector) | Protocol debugging                 | Debug MCP interactions                   |
+
+**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).
 
 ### 🆘 Troubleshooting
 
 #### Common Issues
 
 **"Connection refused" or "Cannot connect to Grocy"**
+
 - Verify `GROCY_BASE_URL` is correct and accessible
 - Check that your Grocy instance is running
 - For HTTPS URLs, ensure SSL certificate is valid or disable verification with `GROCY_ENABLE_SSL_VERIFY=false`
 
 **"Invalid API key" or "Authentication failed"**
+
 - Verify your `GROCY_API_KEY` is correct
 - Check that the API key exists in your Grocy instance (User Settings → API Keys)
 - Ensure the API key has proper permissions
 
 **"Tool not found" errors**
+
 - Check if the tool is enabled in your `mcp-grocy.yaml` file
 - Verify you're using the correct tool names from the API reference
 
 **Large response errors**
+
 - Increase `REST_RESPONSE_SIZE_LIMIT` if you have many products/stock entries
 - Consider disabling unused tools in `mcp-grocy.yaml`
 
 #### Debug Mode
 
 Enable detailed logging and use the MCP inspector:
+
 ```bash
 # Launch MCP inspector for protocol debugging
 npm run inspector
@@ -212,8 +244,8 @@ npm run dev
 
 ### Prerequisites
 
-- Node.js 18 or higher
-- Grocy instance (optional with mock mode)
+- Node.js 22 or newer (see **Requirements** above)
+- Grocy instance (optional: use placeholder URLs/keys in `.env` for local runs)
 
 ### Development Setup
 
@@ -234,18 +266,63 @@ npm start
 
 ### Development Commands
 
-| Command | Description |
-|---------|-------------|
-| `npm run build` | Build TypeScript to JavaScript |
-| `npm run watch` | Watch mode for development |
-| `npm run dev` | Start with mock data (no Grocy needed) |
-| `npm test` | Run test suite |
-| `npm run test:watch` | Run tests in watch mode |
-| `npm run inspector` | Launch MCP protocol inspector |
+| Command                  | Description                                                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run build`          | Build TypeScript to JavaScript                                                                                                      |
+| `npm start`              | Run the built server (`build/main.js`)                                                                                              |
+| `npm run dev`            | Build, then run (use mock `.env` for local testing)                                                                                 |
+| `npm run watch`          | Watch mode for development                                                                                                          |
+| `npm test`               | Run test suite                                                                                                                      |
+| `npm run test:watch`     | Run tests in watch mode                                                                                                             |
+| `npm run inspector`      | Launch MCP protocol inspector                                                                                                       |
+| `npm run dev:mcp-tef`    | Run [mcp-tef](https://github.com/StacklokLabs/mcp-tef) locally (needs **uv** + **Ollama**) for tool-description / similarity checks |
+| `npm run report:mcp-tef` | One command: build, temporary mcp-grocy HTTP + mcp-tef, write `reports/mcp-tef/<timestamp>/` (similarity JSON + `SUMMARY.md`)       |
+
+### Optional: mcp-tef (local tool evaluation)
+
+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):
+
+1. Install [uv](https://docs.astral.sh/uv/) and start Ollama; pull a small model, e.g. `ollama pull llama3.2:3b`.
+2. Build and start **mcp-grocy over HTTP** in another terminal (SSE endpoint for mcp-tef):
+
+   ```bash
+   npm run build
+   MCP_HTTP_TRANSPORT_ONLY=true ENABLE_HTTP_SERVER=true HTTP_SERVER_PORT=8790 npm start
+   ```
+
+3. Start mcp-tef:
+
+   ```bash
+   npm run dev:mcp-tef
+   ```
+
+4. Open `http://127.0.0.1:8000/docs` and point workflows at **`http://127.0.0.1:8790/mcp/sse`** (or your port).
+
+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`.
+
+**One-shot report (no manual API calls):**
+
+```bash
+npm run report:mcp-tef
+```
+
+Writes under `reports/mcp-tef/<timestamp>/`:
+
+- **`REPORT.md`** — human-readable: tools by domain, flagged pairs as a **markdown table** (short tool names, similarity %).
+- **`REPORT.html`** — same pairs in a simple table; open in a browser if you prefer.
+- **`SUMMARY.md`** — one-screen pointer + counts.
+- **`similarity.json`** — full API response (matrix, composite ids).
+
+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.
+
+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).
+
+Optional per-tool **`title`** and **`meta`** (→ MCP `_meta`) can be set in definitions when they add real signal; otherwise clients use **`name`** only.
 
 ### Debugging
 
 Use the MCP inspector to debug protocol interactions:
+
 ```bash
 npm run inspector
 ```
@@ -257,22 +334,25 @@ This launches a web interface for testing MCP tools and viewing protocol message
 This is an **opinionated fork** focused on LLM usability and workflow reliability. Contributions are welcome but must align with the core philosophy:
 
 ### ✅ Welcome Contributions
+
 - Bug fixes and reliability improvements
-- Better error handling and validation  
+- Better error handling and validation
 - Documentation improvements
 - Test coverage enhancements
 - Performance optimizations
 
 ### ❌ Contributions Requiring Discussion
+
 - New tool additions (must demonstrate clear LLM workflow benefits)
 - API design changes that increase complexity
 - Features that expose raw Grocy API behavior
 
 ### Development Workflow
+
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes with tests
-4. Run `npm test` and ensure all tests pass  
+4. Run `npm test` and ensure all tests pass
 5. Submit a pull request with clear description
 
 ## 📄 License
@@ -282,4 +362,4 @@ This project is licensed under the [MIT License](LICENSE).
 ---
 
 **🏠 Made for reliable household management with LLMs**  
-*Prioritizing workflow efficiency over feature completeness*
+_Prioritizing workflow efficiency over feature completeness_

package/build/api/client.js

@@ -8,7 +8,6 @@ import { logger } from '../utils/logger.js';
 import { ApiError, ErrorHandler } from '../utils/errors.js';
 export class GrocyApiClient {
     axiosInstance;
-    API_KEY_HEADER = 'GROCY-API-KEY';
     constructor() {
         this.axiosInstance = this.createAxiosInstance();
         this.setupInterceptors();
@@ -18,14 +17,13 @@ export class GrocyApiClient {
             baseURL: config.grocy.base_url,
             validateStatus: () => true, // Handle all status codes manually
             timeout: 30000,
-            httpsAgent: config.grocy.enable_ssl_verify ? undefined : new https.Agent({
-                rejectUnauthorized: false
-            })
+            maxContentLength: config.grocy.max_response_bytes,
+            httpsAgent: config.grocy.enable_ssl_verify
+                ? undefined
+                : new https.Agent({
+                    rejectUnauthorized: false,
+                }),
         });
-        // Set default authentication
-        if (config.grocy.api_key) {
-            instance.defaults.headers.common[this.API_KEY_HEADER] = config.grocy.api_key;
-        }
         return instance;
     }
     setupInterceptors() {
@@ -42,7 +40,7 @@ export class GrocyApiClient {
             if (response.status >= 400) {
                 logger.warn(`HTTP ${response.status}`, 'API', {
                     url: response.config?.url,
-                    status: response.status
+                    status: response.status,
                 });
             }
             return response;
@@ -76,12 +74,12 @@ export class GrocyApiClient {
                 method,
                 url,
                 headers: {
-                    'Accept': 'application/json',
+                    Accept: 'application/json',
                     'Content-Type': 'application/json',
                     ...config.getCustomHeaders(),
-                    ...headers
+                    ...headers,
                 },
-                ...(timeout && { timeout })
+                ...(timeout && { timeout }),
             };
             if (['POST', 'PUT', 'PATCH'].includes(method) && body !== null) {
                 requestConfig.data = body;
@@ -93,7 +91,7 @@ export class GrocyApiClient {
             return {
                 data: response.data,
                 status: response.status,
-                headers: response.headers
+                headers: response.headers,
             };
         }, `API ${method} ${endpoint}`);
     }

package/build/config/index.js

@@ -9,16 +9,21 @@ import { fileURLToPath } from 'url';
 import YAML from 'yaml';
 import { logger } from '../utils/logger.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Default cap for Grocy HTTP response bodies (axios maxContentLength), in bytes */
+export const DEFAULT_MAX_RESPONSE_BYTES = 52_428_800; // 50 MiB
 // Environment schema
 const EnvironmentSchema = z.object({
     // Grocy Configuration
     GROCY_BASE_URL: z.string().url().optional(),
     GROCY_API_KEY: z.string().optional(),
     GROCY_ENABLE_SSL_VERIFY: z.enum(['true', 'false']).optional(),
-    // Server Configuration  
+    GROCY_MAX_RESPONSE_BYTES: z.string().regex(/^\d+$/).optional(),
+    // Server Configuration
     REST_RESPONSE_SIZE_LIMIT: z.string().regex(/^\d+$/).optional(),
     ENABLE_HTTP_SERVER: z.enum(['true', 'false']).optional(),
     HTTP_SERVER_PORT: z.string().regex(/^\d+$/).optional(),
+    HTTP_CORS_ORIGIN: z.string().optional(),
+    MCP_HTTP_ACCESS_TOKEN: z.string().optional(),
     // Logging Configuration
     LOG_LEVEL: z.enum(['DEBUG', 'INFO', 'WARN', 'ERROR']).optional(),
     LOG_CATEGORIES: z.string().optional(),
@@ -27,22 +32,49 @@ const EnvironmentSchema = z.object({
     NODE_ENV: z.enum(['development', 'production', 'test']).optional(),
 });
 // YAML configuration schema
-const YamlConfigSchema = z.object({
-    server: z.object({
+const YamlConfigSchema = z
+    .object({
+    server: z
+        .object({
         enable_http_server: z.boolean().default(false),
         http_server_port: z.number().min(1).max(65535).default(8080),
-    }).default({}),
-    grocy: z.object({
+        /** CORS `Access-Control-Allow-Origin` for HTTP MCP endpoints (`*` or a single origin URL) */
+        http_cors_origin: z.string().min(1).default('*'),
+        /** When set, MCP HTTP/SSE routes require `Authorization: Bearer <token>`, `X-MCP-Access-Token`, or `access_token` query (GET only). */
+        http_access_token: z.string().optional(),
+    })
+        .strict()
+        .default({
+        enable_http_server: false,
+        http_server_port: 8080,
+        http_cors_origin: '*',
+    }),
+    grocy: z
+        .object({
         base_url: z.string().url().default('http://localhost:9283'),
         api_key: z.string().optional(),
         enable_ssl_verify: z.boolean().default(true),
         response_size_limit: z.number().positive().default(10000),
-    }).default({}),
-    tools: z.record(z.string(), z.object({
+        /** Max Grocy API response body size in bytes (all tools); larger responses fail fast */
+        max_response_bytes: z.number().positive().default(DEFAULT_MAX_RESPONSE_BYTES),
+    })
+        .strict()
+        .default({
+        base_url: 'http://localhost:9283',
+        enable_ssl_verify: true,
+        response_size_limit: 10000,
+        max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
+    }),
+    tools: z
+        .record(z.string(), z
+        .object({
         enabled: z.boolean().default(false),
         ack_token: z.string().optional(),
-    }).catchall(z.unknown())).default({}),
-});
+    })
+        .catchall(z.unknown()))
+        .default({}),
+})
+    .strict();
 export class ConfigManager {
     static instance;
     config;
@@ -55,13 +87,21 @@ export class ConfigManager {
         // Expose final resolved values
         this.grocy = {
             base_url: this.config.yaml.grocy.base_url,
-            ...(this.config.yaml.grocy.api_key !== undefined && { api_key: this.config.yaml.grocy.api_key }),
+            ...(this.config.yaml.grocy.api_key !== undefined && {
+                api_key: this.config.yaml.grocy.api_key,
+            }),
             enable_ssl_verify: this.config.yaml.grocy.enable_ssl_verify,
-            response_size_limit: this.config.yaml.grocy.response_size_limit
+            response_size_limit: this.config.yaml.grocy.response_size_limit,
+            max_response_bytes: this.config.yaml.grocy.max_response_bytes,
         };
         this.server = {
             enable_http_server: this.config.yaml.server.enable_http_server,
-            http_server_port: this.config.yaml.server.http_server_port
+            http_server_port: this.config.yaml.server.http_server_port,
+            http_cors_origin: this.config.yaml.server.http_cors_origin,
+            ...(this.config.yaml.server.http_access_token !== undefined &&
+                this.config.yaml.server.http_access_token !== '' && {
+                http_access_token: this.config.yaml.server.http_access_token,
+            }),
         };
         this.tools = this.config.yaml.tools;
     }
@@ -87,9 +127,10 @@ export class ConfigManager {
         catch (error) {
             if (error instanceof z.ZodError) {
                 logger.error('Invalid environment variables', 'CONFIG');
-                error.errors.forEach(err => {
-                    logger.error(`${err.path.join('.')}: ${err.message}`, 'CONFIG');
-                });
+                for (const issue of error.issues) {
+                    const path = issue.path?.length ? issue.path.join('.') : '(root)';
+                    logger.error(`${path}: ${issue.message}`, 'CONFIG');
+                }
                 process.exit(1);
             }
             throw error;
@@ -112,9 +153,10 @@ export class ConfigManager {
         catch (error) {
             if (error instanceof z.ZodError) {
                 logger.error('Invalid YAML configuration', 'CONFIG');
-                error.errors.forEach(err => {
-                    logger.error(`${err.path.join('.')}: ${err.message}`, 'CONFIG');
-                });
+                for (const issue of error.issues) {
+                    const path = issue.path?.length ? issue.path.join('.') : '(root)';
+                    logger.error(`${path}: ${issue.message}`, 'CONFIG');
+                }
                 process.exit(1);
             }
             throw error;
@@ -133,14 +175,16 @@ export class ConfigManager {
             resolve(projectRoot, 'mcp-grocy.yaml'),
             resolve(projectRoot, 'mcp-grocy.yml'),
         ];
-        return possiblePaths.find(path => existsSync(path)) ?? possiblePaths[0];
+        return possiblePaths.find((path) => existsSync(path)) ?? possiblePaths[0];
     }
     // Public getters
     getConfig() {
         return this.config;
     }
     getApiUrl() {
-        return this.grocy.base_url.endsWith('/') ? `${this.grocy.base_url}api` : `${this.grocy.base_url}/api`;
+        return this.grocy.base_url.endsWith('/')
+            ? `${this.grocy.base_url}api`
+            : `${this.grocy.base_url}/api`;
     }
     getCustomHeaders() {
         const headers = {};
@@ -166,6 +210,9 @@ export class ConfigManager {
         if (env.REST_RESPONSE_SIZE_LIMIT !== undefined) {
             yaml.grocy.response_size_limit = parseInt(env.REST_RESPONSE_SIZE_LIMIT, 10);
         }
+        if (env.GROCY_MAX_RESPONSE_BYTES !== undefined) {
+            yaml.grocy.max_response_bytes = parseInt(env.GROCY_MAX_RESPONSE_BYTES, 10);
+        }
         // Server configuration overrides
         if (env.ENABLE_HTTP_SERVER !== undefined) {
             yaml.server.enable_http_server = env.ENABLE_HTTP_SERVER === 'true';
@@ -173,6 +220,13 @@ export class ConfigManager {
         if (env.HTTP_SERVER_PORT !== undefined) {
             yaml.server.http_server_port = parseInt(env.HTTP_SERVER_PORT, 10);
         }
+        if (env.HTTP_CORS_ORIGIN !== undefined && env.HTTP_CORS_ORIGIN.length > 0) {
+            yaml.server.http_cors_origin = env.HTTP_CORS_ORIGIN;
+        }
+        if (env.MCP_HTTP_ACCESS_TOKEN !== undefined) {
+            yaml.server.http_access_token =
+                env.MCP_HTTP_ACCESS_TOKEN.length > 0 ? env.MCP_HTTP_ACCESS_TOKEN : undefined;
+        }
     }
     parseToolConfiguration() {
         const enabledTools = new Set();

package/build/resources/CHANGELOG.md

@@ -0,0 +1,31 @@
+# [2.5.0](https://github.com/miguelangel-nubla/mcp-grocy/compare/v2.4.4...v2.5.0) (2026-03-30)
+
+
+### Bug Fixes
+
+* add read permissions for contents in release workflow to support nested publish-docker job ([5a055a6](https://github.com/miguelangel-nubla/mcp-grocy/commit/5a055a62cf07fa3f0f03d4319e485350c111804a))
+* improve test build isolation and commit-specific tagging ([b1875cc](https://github.com/miguelangel-nubla/mcp-grocy/commit/b1875ccc080111c6d56700aab9c493e418d155be))
+
+
+### Features
+
+* improve tool call error handling, and implement multi-server shutdown management ([4d19cfb](https://github.com/miguelangel-nubla/mcp-grocy/commit/4d19cfb35dc238a41a92d2fba505998b6a59e1ae))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Release notes are appended automatically by [semantic-release](https://semantic-release.gitbook.io/) using `@semantic-release/changelog`.
+
+## [Unreleased]
+
+### ⚠️ Breaking Changes
+
+- **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.
+
+### Added
+
+- **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.