mcp-grocy 2.2.0 → 2.5.0

package/build/resources/response-format.md

@@ -1,8 +1,8 @@
 # Grocy API Response Format Documentation
 
-The Grocy API testing tool (`test_request`) returns a comprehensive JSON response containing request details, response information, and validation results. Other specialized Grocy tools (e.g., `get_stock`, `add_shopping_list_item`) return the direct JSON response from the Grocy API, which is then stringified.
+The dev tool **`system_dev_test_request`** returns a JSON payload with request details, response information, and validation results. Other tools (e.g. `inventory_stock_get_all`, `shopping_list_add_item`) return the Grocy API body as text content (typically stringified JSON).
 
-## `test_request` Tool Response Structure
+## `system_dev_test_request` tool response structure
 
 ```json
 {
@@ -29,7 +29,7 @@ The Grocy API testing tool (`test_request`) returns a comprehensive JSON respons
       "id": "1",
       "name": "Cookies",
       "description": null,
-      "product_group_id": "1",
+      "product_group_id": "1"
       // ... other product fields ...
     }
   },
@@ -72,9 +72,10 @@ GROCY_API_KEY=your-private-api-key
 
 These values can be set in your `.env` file for local development or in your project configuration for production use.
 
-## Response Fields for `test_request`
+## Response Fields for `system_dev_test_request`
 
 ### Request Details (`request`)
+
 - `url`: Full URL of the Grocy API endpoint called, including base URL and path.
 - `method`: HTTP method used (e.g., GET, POST, PUT, DELETE).
 - `headers`: Request headers sent to the Grocy API. Sensitive headers like `GROCY-API-KEY` will have their values redacted.
@@ -82,6 +83,7 @@ These values can be set in your `.env` file for local development or in your pro
 - `authMethod`: Authentication method used. For Grocy, this will typically be `apikey` if `GROCY_API_KEY` is configured, or `none`.
 
 ### Response Details (`response`)
+
 - `statusCode`: HTTP status code returned by the Grocy API (e.g., 200, 400, 401).
 - `statusText`: HTTP status message (e.g., "OK", "Bad Request").
 - `timing`: Duration of the API request in milliseconds.
@@ -89,6 +91,7 @@ These values can be set in your `.env` file for local development or in your pro
 - `body`: Response body content from the Grocy API. This will be the JSON data returned by Grocy.
 
 ### Validation (`validation`)
+
 - `isError`: Boolean, `true` if the HTTP status code is 400 or higher, indicating an error.
 - `messages`: Array of messages, including success messages or error details.
 - `truncated` (optional): If the response body exceeds `REST_RESPONSE_SIZE_LIMIT`, this object will contain details about the truncation.
@@ -99,9 +102,10 @@ These values can be set in your `.env` file for local development or in your pro
 
 ## Specialized Grocy Tools Response Format
 
-Tools like `get_stock`, `get_products`, `add_shopping_list_item`, etc., directly return the JSON response from the Grocy API, stringified within the MCP tool response content.
+Tools like `inventory_stock_get_all`, `inventory_products_get`, `shopping_list_add_item`, etc., return the Grocy API response as MCP text content (usually stringified JSON).
+
+Example shape for a product-related read (illustrative):
 
-Example for `get_product` (if it existed as a specialized tool for a single product):
 ```json
 {
   "content": [
@@ -119,6 +123,7 @@ Example for `get_product` (if it existed as a specialized tool for a single prod
 ```
 
 If an error occurs with a specialized tool, the response will typically look like:
+
 ```json
 {
   "content": [
@@ -131,9 +136,10 @@ If an error occurs with a specialized tool, the response will typically look lik
 }
 ```
 
-## Error Response Example for `test_request`
+## Error response example for `system_dev_test_request`
+
+If **`system_dev_test_request`** encounters an API error (e.g., authentication failure):
 
-If the `test_request` tool encounters an API error (e.g., authentication failure):
 ```json
 {
   "request": {
@@ -149,17 +155,16 @@ If the `test_request` tool encounters an API error (e.g., authentication failure
     "statusCode": 401,
     "statusText": "Unauthorized",
     "timing": "50ms",
-    "headers": { /* ... headers ... */ },
+    "headers": {
+      /* ... headers ... */
+    },
     "body": {
       "error_message": "API key is missing or invalid."
     }
   },
   "validation": {
     "isError": true,
-    "messages": [
-      "Request failed with status 401",
-      "API key is missing or invalid."
-    ]
+    "messages": ["Request failed with status 401", "API key is missing or invalid."]
   }
 }
 ```

package/build/server/http-server.js

@@ -1,39 +1,106 @@
 import express from 'express';
-import { randomUUID } from 'crypto';
+import { randomUUID, timingSafeEqual } from 'crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { VERSION, PACKAGE_NAME as SERVER_NAME } from '../version.js';
 import cors from 'cors';
 import http from 'http';
 import { logger } from '../utils/logger.js';
+/** Constant-time string comparison to prevent timing attacks on token validation. */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+function createMcpAccessGate(accessToken) {
+    return (req, res, next) => {
+        if (!accessToken) {
+            next();
+            return;
+        }
+        if (req.method === 'OPTIONS') {
+            next();
+            return;
+        }
+        const bearer = req.headers.authorization;
+        const headerToken = req.headers['x-mcp-access-token'];
+        const headerTokenStr = Array.isArray(headerToken) ? headerToken[0] : headerToken;
+        const q = req.query.access_token;
+        const queryToken = typeof q === 'string' ? q : undefined;
+        const ok = (typeof bearer === 'string' && safeEqual(bearer, `Bearer ${accessToken}`)) ||
+            (typeof headerTokenStr === 'string' && safeEqual(headerTokenStr, accessToken)) ||
+            (req.method === 'GET' &&
+                typeof queryToken === 'string' &&
+                safeEqual(queryToken, accessToken));
+        if (ok) {
+            next();
+            return;
+        }
+        res.status(401).json({
+            jsonrpc: '2.0',
+            error: {
+                code: -32000,
+                message: 'Unauthorized: configure MCP_HTTP_ACCESS_TOKEN and send Authorization: Bearer, X-MCP-Access-Token, or access_token query (GET only)',
+            },
+            id: (req.body && typeof req.body === 'object' && 'id' in req.body
+                ? req.body.id
+                : null) ?? null,
+        });
+    };
+}
 // HTTP Transport for MCP (Context7 style)
-export function startHttpServer(mcpServer, port = 8080) {
+export function startHttpServer(mcpServer, port = 8080, security) {
     return new Promise((resolve, reject) => {
         const app = express();
+        const mcpAccessGate = createMcpAccessGate(security.accessToken);
+        if (security.accessToken) {
+            logger.config('HTTP MCP access token is enabled (Bearer, X-MCP-Access-Token, or access_token on GET)');
+        }
         // Enable JSON body parsing with increased limit
         app.use(express.json({
-            limit: '10mb'
+            limit: '10mb',
         }));
-        // Enable CORS for all routes
         app.use(cors({
-            origin: '*',
-            methods: ['GET', 'POST', 'OPTIONS'],
-            allowedHeaders: ['Origin', 'X-Requested-With', 'Content-Type', 'Accept', 'Mcp-Session-Id', 'Authorization'],
+            origin: security.corsOrigin,
+            methods: ['GET', 'POST', 'OPTIONS', 'DELETE'],
+            allowedHeaders: [
+                'Origin',
+                'X-Requested-With',
+                'Content-Type',
+                'Accept',
+                'Mcp-Session-Id',
+                'Mcp-Protocol-Version',
+                'Authorization',
+                'X-MCP-Access-Token',
+            ],
             exposedHeaders: ['Mcp-Session-Id', 'Content-Type'],
-            optionsSuccessStatus: 200
+            optionsSuccessStatus: 200,
         }));
-        // Simple health check endpoint
-        app.get('/', (_req, res) => {
+        // Health check endpoint — always accessible for monitoring/load balancers,
+        // but only exposes service details when no access token is configured or request is authenticated.
+        app.get('/', (req, res) => {
+            const minimal = { status: 'ok' };
+            if (security.accessToken) {
+                const bearer = req.headers.authorization;
+                const headerToken = req.headers['x-mcp-access-token'];
+                const headerTokenStr = Array.isArray(headerToken) ? headerToken[0] : headerToken;
+                const authenticated = (typeof bearer === 'string' && safeEqual(bearer, `Bearer ${security.accessToken}`)) ||
+                    (typeof headerTokenStr === 'string' && safeEqual(headerTokenStr, security.accessToken));
+                if (!authenticated) {
+                    res.json(minimal);
+                    return;
+                }
+            }
             res.json({
-                status: 'ok',
+                ...minimal,
                 service: SERVER_NAME,
                 version: VERSION,
                 message: 'MCP server is running',
                 endpoints: {
                     streamable: '/mcp',
                     sse: '/mcp/sse',
-                    sseMessages: '/mcp/messages'
-                }
+                    sseMessages: '/mcp/messages',
+                },
             });
         });
         // Session management for transports
@@ -55,40 +122,50 @@ export function startHttpServer(mcpServer, port = 8080) {
             }
         };
         // Streamable HTTP endpoint (Context7 modern)
-        app.post('/mcp', async (req, res) => {
+        app.all('/mcp', mcpAccessGate, async (req, res) => {
             try {
-                const clientSessionId = req.headers['mcp-session-id'];
+                const clientSessionId = req.headers['mcp-session-id'] ||
+                    req.query.sessionId ||
+                    req.query['mcp-session-id'];
                 let transport = undefined;
                 // Accept header check (can be done early)
                 const accept = req.headers.accept || '';
+                // Home Assistant might not send perfect accept headers, so we log a warning instead of blocking
                 if (!accept.includes('application/json') && !accept.includes('text/event-stream')) {
-                    logger.error('Client must accept application/json or text/event-stream', 'server');
-                    res.status(406).json({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: 'Not Acceptable: Client must accept application/json or text/event-stream'
-                        },
-                        id: req.body?.id || null
-                    });
-                    return;
+                    logger.warn('Client should accept application/json or text/event-stream', 'server');
                 }
-                if (clientSessionId) {
+                const isInitializeRequest = req.method === 'POST' && req.body?.method === 'initialize';
+                if (clientSessionId && !isInitializeRequest) {
+                    // Existing session: look up transport
                     transport = streamableTransports[clientSessionId];
                     if (!transport) {
+                        logger.warn(`Session ${clientSessionId} not found, returning 400`, 'server');
                         res.status(400).json({
                             jsonrpc: '2.0',
-                            error: { code: -32001, message: `Invalid or expired session ID: ${clientSessionId}. Please re-initialize.` },
-                            id: req.body?.id || null
+                            error: {
+                                code: -32001,
+                                message: `Invalid or expired session ID: ${clientSessionId}. Please re-initialize.`,
+                            },
+                            id: req.body?.id || null,
                         });
                         return;
                     }
                 }
-                else {
-                    // No session ID provided by client, create new transport
+                else if (isInitializeRequest) {
+                    // POST initialize: create new transport and session
+                    if (clientSessionId) {
+                        logger.info(`Initialize request included prior session ID ${clientSessionId} (non-graceful reconnect), starting fresh session`, 'server');
+                        // Clean up the stale transport to prevent memory leaks
+                        const staleTransport = streamableTransports[clientSessionId];
+                        if (staleTransport) {
+                            delete streamableTransports[clientSessionId];
+                            staleTransport.close?.().catch(() => { });
+                        }
+                    }
                     const newGeneratedSessionId = randomUUID();
                     const newTransportInstance = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: () => newGeneratedSessionId
+                        sessionIdGenerator: () => newGeneratedSessionId,
+                        enableJsonResponse: true,
                     });
                     transport = newTransportInstance;
                     streamableTransports[newGeneratedSessionId] = transport;
@@ -97,11 +174,31 @@ export function startHttpServer(mcpServer, port = 8080) {
                         delete streamableTransports[closedSessionId];
                     };
                     const serverInstance = getServerInstance();
-                    await serverInstance.connect(transport); // Type assertion to work around SDK type issue
+                    await serverInstance.connect(transport);
+                }
+                else {
+                    // Non-initialize request without a session ID (e.g. GET SSE before session established)
+                    // Return 405 so clients that probe for SSE support handle it gracefully
+                    res
+                        .status(405)
+                        .set('Allow', 'POST')
+                        .json({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Method not allowed: session not established. Send a POST initialize request first.',
+                        },
+                        id: req.body?.id || null,
+                    });
+                    return;
                 }
                 if (!transport) {
                     logger.error('Transport is undefined before handling request. This should not happen.', 'server');
-                    res.status(500).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Internal server error: Transport not available' }, id: req.body?.id || null });
+                    res.status(500).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32000, message: 'Internal server error: Transport not available' },
+                        id: req.body?.id || null,
+                    });
                     return;
                 }
                 if (transport.sessionId) {
@@ -117,15 +214,15 @@ export function startHttpServer(mcpServer, port = 8080) {
                         jsonrpc: '2.0',
                         error: {
                             code: -32000,
-                            message: `Internal server error: ${error instanceof Error ? error.message : String(error)}`
+                            message: `Internal server error: ${error instanceof Error ? error.message : String(error)}`,
                         },
-                        id: req.body?.id || null
+                        id: req.body?.id ?? null,
                     });
                 }
             }
         });
         // SSE endpoint
-        app.get('/mcp/sse', async (_req, res) => {
+        app.get('/mcp/sse', mcpAccessGate, async (_req, res) => {
             try {
                 // Set SSE headers before creating transport
                 res.setHeader('Content-Type', 'text/event-stream');
@@ -133,6 +230,7 @@ export function startHttpServer(mcpServer, port = 8080) {
                 res.setHeader('Connection', 'keep-alive');
                 const transport = new SSEServerTransport('/mcp/messages', res);
                 const sessionId = transport.sessionId;
+                logger.info(`Created SSE session: ${sessionId}`, 'DEBUG');
                 sseTransports[sessionId] = transport;
                 // Handle connection cleanup
                 const cleanup = () => {
@@ -149,7 +247,9 @@ export function startHttpServer(mcpServer, port = 8080) {
                 sseServerInstances[sessionId] = isolatedServer;
                 // Connect transport to isolated MCP server (non-blocking)
                 isolatedServer.connect(transport).catch((error) => {
-                    logger.error(`Failed to connect SSE transport for session ${sessionId}`, 'server', { error });
+                    logger.error(`Failed to connect SSE transport for session ${sessionId}`, 'server', {
+                        error,
+                    });
                     cleanup();
                     if (!res.headersSent) {
                         res.status(500).end();
@@ -169,35 +269,47 @@ export function startHttpServer(mcpServer, port = 8080) {
             }
         });
         // Message endpoint for SSE
-        app.post('/mcp/messages', async (req, res) => {
+        app.post('/mcp/messages', mcpAccessGate, async (req, res) => {
             const sessionId = req.query.sessionId;
             if (!sessionId) {
+                logger.error('Missing sessionId parameter in SSE message', 'server');
                 res.status(400).json({
                     error: 'Missing sessionId parameter',
-                    status: 400
+                    status: 400,
                 });
                 return;
             }
             const transport = sseTransports[sessionId];
             if (transport) {
+                logger.info(`Found active transport for session ${sessionId}`, 'DEBUG');
                 try {
                     await transport.handlePostMessage(req, res, req.body);
                 }
                 catch (error) {
-                    logger.error(`Failed to handle SSE message for session ${sessionId}`, 'server', { error });
+                    logger.error(`Failed to handle SSE message for session ${sessionId}`, 'server', {
+                        error,
+                    });
                     res.status(500).json({
                         error: `Internal server error: ${error instanceof Error ? error.message : String(error)}`,
-                        status: 500
+                        status: 500,
                     });
                 }
             }
             else {
                 res.status(404).json({
                     error: `No active SSE connection found for session ID: ${sessionId}`,
-                    status: 404
+                    status: 404,
                 });
             }
         });
+        // Catch-all for undefined routes — return JSON instead of Express default HTML
+        app.use((_req, res) => {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Not found' },
+                id: null,
+            });
+        });
         // Create HTTP server with explicit error handling
         const server = http.createServer(app);
         server.on('error', (error) => {