mcp-grocy 2.2.0 → 2.5.0

package/build/server/mcp-server.js

@@ -1,62 +1,64 @@
 /**
- * Simplified MCP Server implementation
- * Reduced complexity and improved performance
+ * Grocy MCP server — McpServer API (registerTool / registerResource).
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
-import { VERSION, PACKAGE_NAME as SERVER_NAME } from '../version.js';
+import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { VERSION, PACKAGE_NAME, SERVER_NAME as RESOURCE_URI_SCHEME } from '../version.js';
 import { createToolRegistry } from '../tools/index.js';
 import { config } from '../config/index.js';
 import { startHttpServer } from './http-server.js';
-import { ResourceHandler } from './resources.js';
+import { ResourceHandler, STATIC_MCP_RESOURCE_ENTRIES } from './resources.js';
+import { toolDefinitionInputZod } from './tool-input-zod.js';
 import { logger } from '../utils/logger.js';
 import { ErrorHandler } from '../utils/errors.js';
+/** Janix mcp-validator (2025-03-26) checks `tools.asyncSupported`; merge keeps this when SDK adds `listChanged`. */
+const GROCY_SERVER_CAPABILITIES = {
+    tools: {
+        asyncSupported: true,
+    },
+    resources: {},
+    prompts: {},
+};
+const SERVER_INFO = {
+    name: PACKAGE_NAME,
+    version: VERSION,
+    websiteUrl: 'https://github.com/miguelangel-nubla/mcp-grocy',
+    description: 'MCP server for Grocy. Documentation: https://github.com/miguelangel-nubla/mcp-grocy/blob/main/README.md',
+};
 export class GrocyMcpServer {
-    server;
+    static sigintHandlerRegistered = false;
+    static activeServers = new Set();
+    mcp;
     enabledTools = new Set();
     toolSubConfigs = new Map();
     toolAckTokens = new Map();
     resourceHandler;
     toolRegistry;
-    constructor(server, toolRegistry, resourceHandler) {
-        this.server = server;
+    constructor(mcp, toolRegistry, resourceHandler) {
+        this.mcp = mcp;
         this.toolRegistry = toolRegistry;
         this.resourceHandler = resourceHandler;
         this.parseToolConfiguration();
-        this.setupHandlers();
-        this.setupErrorHandling();
+        this.registerToolsAndResources(this.mcp);
+        this.setupErrorHandling(this.mcp);
     }
     static async create() {
-        // Initialize components
-        const [toolRegistry, resourceHandler] = await Promise.all([
-            createToolRegistry(),
-            Promise.resolve(new ResourceHandler())
-        ]);
-        // Create server
-        const server = new Server({
-            name: SERVER_NAME,
-            version: VERSION,
-            serverUrl: "https://github.com/miguelangel-nubla/mcp-grocy",
-            documentationUrl: "https://github.com/miguelangel-nubla/mcp-grocy/blob/main/README.md"
-        }, {
-            capabilities: {
-                tools: {},
-                resources: {},
-                prompts: {}
-            }
+        const toolRegistry = await createToolRegistry();
+        const resourceHandler = new ResourceHandler();
+        const mcp = new McpServer(SERVER_INFO, {
+            capabilities: GROCY_SERVER_CAPABILITIES,
         });
-        return new GrocyMcpServer(server, toolRegistry, resourceHandler);
+        GrocyMcpServer.activeServers.add(mcp);
+        return new GrocyMcpServer(mcp, toolRegistry, resourceHandler);
     }
     parseToolConfiguration() {
         const { enabledTools, toolSubConfigs, toolAckTokens } = config.parseToolConfiguration();
         this.toolSubConfigs = toolSubConfigs;
         this.toolAckTokens = toolAckTokens;
-        // Validate tool names
         const validToolNames = new Set(this.toolRegistry.getToolNames());
         if (enabledTools.size > 0) {
-            const invalidTools = Array.from(enabledTools).filter(tool => !validToolNames.has(tool));
+            const invalidTools = Array.from(enabledTools).filter((tool) => !validToolNames.has(tool));
             if (invalidTools.length > 0) {
                 const validNames = Array.from(validToolNames).sort().join(', ');
                 logger.error(`Invalid tools: ${invalidTools.join(', ')}. Valid: ${validNames}`, 'CONFIG');
@@ -69,84 +71,130 @@ export class GrocyMcpServer {
             logger.warn('No tools enabled', 'CONFIG');
         }
     }
-    setupHandlers() {
-        // Initialize handler
-        this.server.setRequestHandler(z.object({ method: z.literal('initialize'), params: z.any().optional() }), async (request) => {
-            logger.debug('Initialize request', 'MCP');
-            return {
-                protocolVersion: request.params?.protocolVersion || '2024-11-05',
-                capabilities: { tools: {}, resources: {}, prompts: {} },
-                serverInfo: { name: SERVER_NAME, version: VERSION }
-            };
-        });
-        // List tools
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            const allTools = this.toolRegistry.getDefinitions();
-            const filteredTools = allTools.filter(tool => this.enabledTools.has(tool.name));
-            logger.config(`Available tools: ${filteredTools.map(t => t.name).join(', ')}`);
-            return { tools: filteredTools };
-        });
-        // Call tool
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            const { name: toolName, arguments: args } = request.params;
-            // Check if tool is enabled
-            if (!this.enabledTools.has(toolName)) {
-                throw new McpError(ErrorCode.InvalidRequest, `Tool '${toolName}' is not enabled. Enable it in your configuration.`);
-            }
-            // Get handler
-            const handler = this.toolRegistry.getHandler(toolName);
-            if (!handler) {
-                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+    registerToolsAndResources(mcp) {
+        for (const def of this.toolRegistry.getDefinitions()) {
+            const inputSchema = toolDefinitionInputZod(def);
+            const registered = mcp.registerTool(def.name, {
+                ...(def.title?.trim() ? { title: def.title.trim() } : {}),
+                description: def.description,
+                inputSchema,
+                ...(def.annotations ? { annotations: def.annotations } : {}),
+                ...(def.meta && Object.keys(def.meta).length > 0 ? { _meta: def.meta } : {}),
+            }, async (args) => this.invokeTool(def.name, args));
+            if (!this.enabledTools.has(def.name)) {
+                registered.disable();
             }
-            try {
-                const subConfigs = this.toolSubConfigs.get(toolName);
-                const result = await handler(args, subConfigs);
-                // Automatically add ack_token to successful responses (at the beginning)
-                if (!result.isError) {
-                    const ackToken = this.toolAckTokens.get(toolName);
-                    if (ackToken) {
-                        result.content.unshift({
-                            type: 'text',
-                            text: `Acknowledgment token: ${ackToken}`
-                        });
-                    }
-                }
-                return result;
+        }
+        for (const entry of STATIC_MCP_RESOURCE_ENTRIES) {
+            const uri = `${RESOURCE_URI_SCHEME}://${entry.slug}`;
+            mcp.registerResource(entry.name, uri, { description: entry.description, mimeType: entry.mimeType }, async (resourceUrl) => this.resourceHandler.readResource(resourceUrl.toString()));
+        }
+        logger.config(`Registered ${this.toolRegistry.getDefinitions().length} tool(s) (${this.enabledTools.size} enabled) and ${STATIC_MCP_RESOURCE_ENTRIES.length} resource(s) via McpServer`);
+        this.installStrictToolsCallHandling(mcp);
+    }
+    /**
+     * MCP SDK maps most tool errors to CallToolResult with isError, but compliance harnesses expect
+     * JSON-RPC errors for unknown/disabled tool names.
+     *
+     * WARNING: accesses SDK internals (_requestHandlers, _registeredTools).
+     * Tested against @modelcontextprotocol/sdk ^1.28.0 — verify after upgrades.
+     */
+    installStrictToolsCallHandling(mcp) {
+        const server = mcp.server;
+        const previous = server._requestHandlers?.get('tools/call');
+        if (!previous) {
+            logger.warn('Could not install strict tools/call handling — SDK internals may have changed', 'MCP');
+            return;
+        }
+        const toolsMap = mcp
+            ._registeredTools;
+        if (!toolsMap) {
+            logger.warn('Could not install strict tools/call handling — _registeredTools not found', 'MCP');
+            return;
+        }
+        mcp.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const name = request.params.name;
+            const registered = toolsMap[name];
+            if (!registered) {
+                throw new McpError(ErrorCode.MethodNotFound, `Tool '${name}' not found`);
             }
-            catch (error) {
-                ErrorHandler.logError(error, `tool: ${toolName}`);
-                throw ErrorHandler.toMcpError(error, `${toolName} failed`);
+            if (!registered.enabled) {
+                throw new McpError(ErrorCode.InvalidParams, `Tool '${name}' is disabled`);
             }
-        });
-        // Resources
-        this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-            return this.resourceHandler.listResources();
-        });
-        this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-            return this.resourceHandler.readResource(request.params.uri);
+            return previous(request, extra);
         });
     }
-    setupErrorHandling() {
-        this.server.onerror = (error) => {
+    async invokeTool(toolName, args) {
+        const handler = this.toolRegistry.getHandler(toolName);
+        if (!handler) {
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+        }
+        try {
+            const subConfigs = this.toolSubConfigs.get(toolName);
+            const result = await handler(args, subConfigs);
+            if (!result.isError) {
+                const ackToken = this.toolAckTokens.get(toolName);
+                if (ackToken) {
+                    result.content.unshift({
+                        type: 'text',
+                        text: `Acknowledgment token: ${ackToken}`,
+                    });
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            ErrorHandler.logError(error, `tool: ${toolName}`);
+            throw ErrorHandler.toMcpError(error, `${toolName} failed`);
+        }
+    }
+    setupErrorHandling(mcp) {
+        mcp.server.onerror = (error) => {
             logger.error('MCP protocol error', 'MCP', { error });
         };
+        if (GrocyMcpServer.sigintHandlerRegistered) {
+            return;
+        }
+        GrocyMcpServer.sigintHandlerRegistered = true;
         process.on('SIGINT', async () => {
             logger.info('Shutting down server...', 'SERVER');
-            await this.server.close();
+            await Promise.all(Array.from(GrocyMcpServer.activeServers).map((s) => s.close().catch(() => { })));
             process.exit(0);
         });
     }
+    createMcpServer() {
+        const mcp = new McpServer(SERVER_INFO, {
+            capabilities: GROCY_SERVER_CAPABILITIES,
+        });
+        GrocyMcpServer.activeServers.add(mcp);
+        this.registerToolsAndResources(mcp);
+        this.setupErrorHandling(mcp);
+        return mcp;
+    }
     async start() {
-        // Start STDIO transport
-        const transport = new StdioServerTransport();
-        await this.server.connect(transport);
-        logger.info('MCP server running on stdio', 'SERVER');
-        // Start HTTP/SSE if enabled
+        const httpTransportOnly = process.env.MCP_HTTP_TRANSPORT_ONLY === 'true' || process.env.MCP_HTTP_TRANSPORT_ONLY === '1';
+        if (httpTransportOnly && !config.server.enable_http_server) {
+            logger.error('MCP_HTTP_TRANSPORT_ONLY is set but HTTP server is disabled; enable server.enable_http_server or ENABLE_HTTP_SERVER', 'SERVER');
+            process.exit(1);
+        }
+        if (!httpTransportOnly) {
+            const transport = new StdioServerTransport();
+            await this.mcp.connect(transport);
+            logger.info('MCP server running on stdio', 'SERVER');
+        }
+        else {
+            logger.info('MCP_HTTP_TRANSPORT_ONLY: stdio transport skipped', 'SERVER');
+        }
         if (config.server.enable_http_server) {
             try {
                 logger.config(`Starting HTTP server on port ${config.server.http_server_port}`);
-                const serverFactory = () => this.server;
-                await startHttpServer(serverFactory, config.server.http_server_port);
+                const serverFactory = () => this.createMcpServer();
+                await startHttpServer(serverFactory, config.server.http_server_port, {
+                    corsOrigin: config.server.http_cors_origin,
+                    ...(config.server.http_access_token !== undefined && {
+                        accessToken: config.server.http_access_token,
+                    }),
+                });
             }
             catch (error) {
                 logger.error('Failed to start HTTP server', 'SERVER', { error });
@@ -155,9 +203,8 @@ export class GrocyMcpServer {
             }
         }
     }
-    // Expose server for HTTP transport
     get serverInstance() {
-        return this.server;
+        return this.mcp;
     }
 }
 export default GrocyMcpServer;

package/build/server/resources.js

@@ -3,34 +3,42 @@ import { SERVER_NAME } from '../version.js';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+/** Static docs exposed as MCP resources (used by ResourceHandler and McpServer registration). */
+export const STATIC_MCP_RESOURCE_ENTRIES = [
+    {
+        slug: 'examples',
+        name: 'mcp-grocy usage examples',
+        description: 'Examples of calling this MCP server’s tools against Grocy',
+        mimeType: 'text/markdown',
+    },
+    {
+        slug: 'response-format',
+        name: 'Tool response format',
+        description: 'How tool results and system_dev_test_request responses are shaped',
+        mimeType: 'text/markdown',
+    },
+    {
+        slug: 'config',
+        name: 'Configuration',
+        description: 'YAML and environment configuration for mcp-grocy',
+        mimeType: 'text/markdown',
+    },
+];
 export class ResourceHandler {
     __dirname;
+    allowedResources = new Set(STATIC_MCP_RESOURCE_ENTRIES.map((e) => e.slug));
     constructor() {
         const __filename = fileURLToPath(import.meta.url);
         this.__dirname = path.dirname(__filename);
     }
     async listResources() {
         return {
-            resources: [
-                {
-                    uri: `${SERVER_NAME}://examples`,
-                    name: 'Grocy API Usage Examples',
-                    description: 'Detailed examples of using the Grocy API',
-                    mimeType: 'text/markdown'
-                },
-                {
-                    uri: `${SERVER_NAME}://response-format`,
-                    name: 'Response Format Documentation',
-                    description: 'Documentation of the response format and structure',
-                    mimeType: 'text/markdown'
-                },
-                {
-                    uri: `${SERVER_NAME}://config`,
-                    name: 'Configuration Documentation',
-                    description: 'Documentation of all configuration options and how to use them',
-                    mimeType: 'text/markdown'
-                }
-            ]
+            resources: STATIC_MCP_RESOURCE_ENTRIES.map((e) => ({
+                uri: `${SERVER_NAME}://${e.slug}`,
+                name: e.name,
+                description: e.description,
+                mimeType: e.mimeType,
+            })),
         };
     }
     async readResource(uri) {
@@ -40,20 +48,25 @@ export class ResourceHandler {
             throw new McpError(ErrorCode.InvalidRequest, `Invalid resource URI format: ${uri}`);
         }
         const resource = match[1];
+        if (!resource || !this.allowedResources.has(resource)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${resource}`);
+        }
         try {
             // In the built app, resources are in build/resources
             // In development, they're in src/resources
             const resourcePath = path.join(this.__dirname, '../resources', `${resource}.md`);
             const content = await fs.promises.readFile(resourcePath, 'utf8');
             return {
-                contents: [{
+                contents: [
+                    {
                         uri,
                         mimeType: 'text/markdown',
-                        text: content
-                    }]
+                        text: content,
+                    },
+                ],
             };
         }
-        catch (error) {
+        catch {
             throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${resource}`);
         }
     }

package/build/server/tool-input-zod.js

@@ -0,0 +1,86 @@
+/**
+ * Builds Zod input schemas from tool definitions (JSON Schema subset used by this repo)
+ * so McpServer.registerTool can validate and advertise tools.
+ */
+import { z } from 'zod';
+function isStringTupleEnum(values) {
+    return values.length > 0 && values.every((v) => typeof v === 'string');
+}
+function propertyToZod(prop, required) {
+    const t = prop.type;
+    let inner;
+    switch (t) {
+        case 'string': {
+            if (Array.isArray(prop.enum) && isStringTupleEnum(prop.enum)) {
+                inner = z.enum(prop.enum);
+            }
+            else {
+                inner = z.string();
+            }
+            break;
+        }
+        case 'number':
+        case 'integer':
+            inner = z.number();
+            break;
+        case 'boolean':
+            inner = z.boolean();
+            break;
+        case 'array': {
+            const items = prop.items;
+            if (items?.type === 'string' && Array.isArray(items.enum) && isStringTupleEnum(items.enum)) {
+                inner = z.array(z.enum(items.enum));
+            }
+            else if (items?.type === 'string') {
+                inner = z.array(z.string());
+            }
+            else if (items?.type === 'number' || items?.type === 'integer') {
+                inner = z.array(z.number());
+            }
+            else if (items?.type === 'boolean') {
+                inner = z.array(z.boolean());
+            }
+            else {
+                inner = z.array(z.unknown());
+            }
+            break;
+        }
+        case 'object': {
+            if (prop.properties && typeof prop.properties === 'object') {
+                inner = objectPropsToZod(prop.properties, prop.required);
+            }
+            else if (prop.additionalProperties &&
+                typeof prop.additionalProperties === 'object' &&
+                prop.additionalProperties.type === 'string') {
+                inner = z.record(z.string(), z.string());
+            }
+            else {
+                inner = z.record(z.string(), z.unknown());
+            }
+            break;
+        }
+        default:
+            inner = z.unknown();
+    }
+    return required ? inner : inner.optional();
+}
+function objectPropsToZod(properties, requiredList) {
+    const required = new Set(requiredList ?? []);
+    const shape = {};
+    for (const [key, raw] of Object.entries(properties)) {
+        shape[key] = propertyToZod(raw, required.has(key));
+    }
+    return z.object(shape);
+}
+/** Converts a tool definition's JSON Schema object input into a Zod schema for MCP. */
+export function toolDefinitionInputZod(def) {
+    const schema = def.inputSchema;
+    if (schema?.type !== 'object') {
+        return z.record(z.string(), z.unknown());
+    }
+    const props = schema.properties;
+    if (!props || typeof props !== 'object' || Object.keys(props).length === 0) {
+        return z.object({});
+    }
+    return objectPropsToZod(props, schema.required);
+}

package/build/tools/base.js

@@ -13,13 +13,13 @@ export class BaseToolHandler {
             content: [
                 {
                     type: 'text',
-                    text: message || 'Operation completed successfully'
+                    text: message || 'Operation completed successfully',
                 },
                 {
                     type: 'text',
-                    text: JSON.stringify(data, null, 2)
-                }
-            ]
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
         };
     }
     /**
@@ -30,21 +30,25 @@ export class BaseToolHandler {
             content: [
                 {
                     type: 'text',
-                    text: `Error: ${message}`
+                    text: `Error: ${message}`,
                 },
-                ...(details ? [{
-                        type: 'text',
-                        text: JSON.stringify(details, null, 2)
-                    }] : [])
+                ...(details
+                    ? [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(details, null, 2),
+                        },
+                    ]
+                    : []),
             ],
-            isError: true
+            isError: true,
         };
     }
     /**
      * Validate required parameters
      */
     validateRequired(params, required) {
-        const missing = required.filter(field => {
+        const missing = required.filter((field) => {
             const value = params[field];
             return value === undefined || value === null || value === '';
         });
@@ -60,7 +64,7 @@ export class BaseToolHandler {
             const response = await apiClient.request(endpoint, {
                 method,
                 body: data,
-                queryParams: options?.queryParams || {}
+                queryParams: options?.queryParams || {},
             });
             return response.data;
         }, `API ${method} ${endpoint}`);
@@ -97,9 +101,9 @@ export class BaseToolHandler {
      * Filter object fields based on allowlist
      */
     filterFields(objects, fields) {
-        return objects.map(obj => {
+        return objects.map((obj) => {
             const filtered = {};
-            fields.forEach(field => {
+            fields.forEach((field) => {
                 if (field in obj) {
                     filtered[field] = obj[field];
                 }
@@ -120,7 +124,7 @@ export class BaseToolHandler {
         if (value.length === 0) {
             throw new ValidationError(`${paramName} cannot be empty`);
         }
-        return value.map(v => String(v));
+        return value.map((v) => String(v));
     }
     /**
      * Parse and validate numeric parameter