mcp-grocy 2.7.0 → 2.7.2

package/build/server/resources.js

@@ -0,0 +1,73 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+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: STATIC_MCP_RESOURCE_ENTRIES.map((e) => ({
+                uri: `${SERVER_NAME}://${e.slug}`,
+                name: e.name,
+                description: e.description,
+                mimeType: e.mimeType,
+            })),
+        };
+    }
+    async readResource(uri) {
+        const uriPattern = new RegExp(`^${SERVER_NAME}://(.+)$`);
+        const match = uri.match(uriPattern);
+        if (!match) {
+            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: [
+                    {
+                        uri,
+                        mimeType: 'text/markdown',
+                        text: content,
+                    },
+                ],
+            };
+        }
+        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

@@ -0,0 +1,157 @@
+/**
+ * Simplified base tool handler
+ */
+import apiClient from '../api/client.js';
+import { config } from '../config/index.js';
+import { ErrorHandler, ValidationError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+export class BaseToolHandler {
+    /**
+     * Create a standardized success result
+     */
+    createSuccess(data, message) {
+        let serializeStructured;
+        try {
+            serializeStructured = config?.server?.serialize_structured_to_content ?? false;
+        }
+        catch {
+            serializeStructured = false;
+        }
+        const textContent = serializeStructured && data !== undefined && data !== null
+            ? message
+                ? `${message}\n${this.safeStringify(data)}`
+                : this.safeStringify(data)
+            : message || 'Operation completed successfully';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: textContent,
+                },
+            ],
+            structuredContent: {
+                data: data ?? null,
+            },
+        };
+    }
+    /**
+     * Create a standardized error result
+     */
+    createError(message, details) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${message}`,
+                },
+                ...(details
+                    ? [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(details, null, 2),
+                        },
+                    ]
+                    : []),
+            ],
+            isError: true,
+        };
+    }
+    /**
+     * Validate required parameters
+     */
+    validateRequired(params, required) {
+        const missing = required.filter((field) => {
+            const value = params[field];
+            return value === undefined || value === null || value === '';
+        });
+        if (missing.length > 0) {
+            throw new ValidationError(`Missing required parameters: ${missing.join(', ')}`, 'parameter validation');
+        }
+    }
+    /**
+     * Safely make API calls with error handling
+     */
+    async apiCall(endpoint, method = 'GET', data, options) {
+        return ErrorHandler.handleAsync(async () => {
+            const response = await apiClient.request(endpoint, {
+                method,
+                body: data,
+                queryParams: options?.queryParams || {},
+            });
+            return response.data;
+        }, `API ${method} ${endpoint}`);
+    }
+    /**
+     * Handle tool execution with standardized error handling
+     */
+    async executeToolHandler(handler) {
+        try {
+            return await handler();
+        }
+        catch (error) {
+            ErrorHandler.logError(error, 'tool execution');
+            if (error instanceof ValidationError) {
+                return this.createError(error.message);
+            }
+            const message = error instanceof Error ? error.message : 'Internal error';
+            return this.createError(`Tool execution failed: ${message}`);
+        }
+    }
+    /**
+     * Safe JSON formatting
+     */
+    safeStringify(data) {
+        try {
+            return JSON.stringify(data, null, 2);
+        }
+        catch (error) {
+            logger.warn('Failed to stringify data', 'TOOLS', { error });
+            return '[Unable to format data]';
+        }
+    }
+    /**
+     * Filter object fields based on allowlist
+     */
+    filterFields(objects, fields) {
+        return objects.map((obj) => {
+            const filtered = {};
+            fields.forEach((field) => {
+                if (field in obj) {
+                    filtered[field] = obj[field];
+                }
+            });
+            return filtered;
+        });
+    }
+    /**
+     * Parse and validate array parameter
+     */
+    parseArrayParam(value, paramName) {
+        if (!value) {
+            throw new ValidationError(`${paramName} is required`);
+        }
+        if (!Array.isArray(value)) {
+            throw new ValidationError(`${paramName} must be an array`);
+        }
+        if (value.length === 0) {
+            throw new ValidationError(`${paramName} cannot be empty`);
+        }
+        return value.map((v) => String(v));
+    }
+    /**
+     * Parse and validate numeric parameter
+     */
+    parseNumberParam(value, paramName, required = true) {
+        if (value === undefined || value === null) {
+            if (required) {
+                throw new ValidationError(`${paramName} is required`);
+            }
+            return undefined;
+        }
+        const num = Number(value);
+        if (isNaN(num)) {
+            throw new ValidationError(`${paramName} must be a valid number`);
+        }
+        return num;
+    }
+}

package/build/tools/household/definitions.js

@@ -0,0 +1,161 @@
+export const householdToolDefinitions = [
+    // ==================== CHORE MANAGEMENT ====================
+    {
+        name: 'household_chores_get',
+        description: '[HOUSEHOLD/CHORES] List **Grocy Chores** (recurring household routines: cleaning schedule, maintenance cadence). Not the same as Tasks—use household_tasks_get for one-off to-dos.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'household_chores_execute',
+        description: '[HOUSEHOLD/CHORES] Track the execution of a chore in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                choreId: {
+                    type: 'number',
+                    description: 'ID of the chore to track execution for. Use household_chores_get tool to find the correct chore ID.',
+                },
+                executedBy: {
+                    type: 'number',
+                    description: 'ID of the user who executed the chore (optional). Use system_users_get tool to find user IDs.',
+                },
+                trackedTime: {
+                    type: 'string',
+                    description: 'Time when the chore was executed in YYYY-MM-DD HH:mm:ss format (optional, defaults to current time)',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note for the chore execution',
+                },
+            },
+            required: ['choreId'],
+        },
+    },
+    // ==================== TASK MANAGEMENT ====================
+    {
+        name: 'household_tasks_get',
+        description: '[HOUSEHOLD/TASKS] List **Grocy Tasks** (discrete to-dos / task tracker). Not recurring Chores—use household_chores_get for scheduled recurring chores.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'household_tasks_complete',
+        description: '[HOUSEHOLD/TASKS] Mark a task as completed in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                taskId: {
+                    type: 'number',
+                    description: 'ID of the task to complete. Use household_tasks_get tool to find the correct task ID.',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note for the task completion',
+                },
+            },
+            required: ['taskId'],
+        },
+    },
+    // ==================== BATTERY MANAGEMENT ====================
+    {
+        name: 'household_batteries_get',
+        description: '[HOUSEHOLD/BATTERIES] Get all batteries from your Grocy instance.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'household_batteries_charge',
+        description: '[HOUSEHOLD/BATTERIES] Track battery charging in your Grocy instance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                batteryId: {
+                    type: 'number',
+                    description: 'ID of the battery to charge. Use household_batteries_get tool to find the correct battery ID.',
+                },
+                trackedTime: {
+                    type: 'string',
+                    description: 'Time when the battery was charged in YYYY-MM-DD HH:mm:ss format (optional, defaults to current time)',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Optional note for the battery charge',
+                },
+            },
+            required: ['batteryId'],
+        },
+    },
+    {
+        name: 'household_batteries_print_label',
+        description: '[HOUSEHOLD/BATTERIES] Print a Grocycode label for a battery. Use household_batteries_get to find valid batteryId values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                batteryId: {
+                    type: 'number',
+                    description: 'ID of the battery to print label for. Use household_batteries_get tool to find the correct battery ID.',
+                },
+            },
+            required: ['batteryId'],
+        },
+    },
+    // ==================== CHORE LABEL PRINTING ====================
+    {
+        name: 'household_chores_print_label',
+        description: '[HOUSEHOLD/CHORES] Print a Grocycode label for a chore. Use household_chores_get to find valid choreId values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                choreId: {
+                    type: 'number',
+                    description: 'ID of the chore to print label for. Use household_chores_get tool to find the correct chore ID.',
+                },
+            },
+            required: ['choreId'],
+        },
+    },
+    // ==================== EQUIPMENT MANAGEMENT ====================
+    {
+        name: 'household_equipment_get',
+        description: '[HOUSEHOLD/EQUIPMENT] List **equipment** assets tracked in Grocy (appliances, tools—not chore definitions). For recurring chore definitions use household_chores_get.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    // ==================== ACTION UTILITIES ====================
+    {
+        name: 'household_actions_undo',
+        description: '[HOUSEHOLD/ACTIONS] Undo a previously executed action (chore execution, task completion, or battery charge).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                entityType: {
+                    type: 'string',
+                    enum: ['chore', 'chores', 'task', 'tasks', 'battery', 'batteries'],
+                    description: 'Type of entity to undo action for',
+                },
+                id: {
+                    type: 'number',
+                    description: 'ID of the specific execution/completion/charge to undo',
+                },
+            },
+            required: ['entityType', 'id'],
+        },
+    },
+];

package/build/tools/household/handlers.js

@@ -0,0 +1,109 @@
+import { BaseToolHandler } from '../base.js';
+export class HouseholdToolHandlers extends BaseToolHandler {
+    // ==================== CHORE MANAGEMENT ====================
+    getChores = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/objects/chores');
+            return this.createSuccess(data);
+        });
+    };
+    trackChoreExecution = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { choreId, executedBy, trackedTime, note } = args || {};
+            this.validateRequired({ choreId }, ['choreId']);
+            const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19);
+            const body = {
+                tracked_time: trackedTime || timestamp,
+                ...(executedBy ? { done_by: executedBy } : {}),
+                ...(note ? { note } : {}),
+            };
+            const result = await this.apiCall(`/chores/${choreId}/execute`, 'POST', body);
+            return this.createSuccess(result, 'Chore execution tracked successfully');
+        });
+    };
+    // ==================== TASK MANAGEMENT ====================
+    getTasks = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/objects/tasks');
+            return this.createSuccess(data);
+        });
+    };
+    completeTask = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { taskId, note } = args || {};
+            this.validateRequired({ taskId }, ['taskId']);
+            const result = await this.apiCall(`/tasks/${taskId}/complete`, 'POST', note ? { note } : {});
+            return this.createSuccess(result, 'Task completed successfully');
+        });
+    };
+    // ==================== BATTERY MANAGEMENT ====================
+    getBatteries = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/objects/batteries');
+            return this.createSuccess(data);
+        });
+    };
+    chargeBattery = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { batteryId, trackedTime, note } = args || {};
+            this.validateRequired({ batteryId }, ['batteryId']);
+            const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19);
+            const body = {
+                tracked_time: trackedTime || timestamp,
+                ...(note ? { note } : {}),
+            };
+            const result = await this.apiCall(`/batteries/${batteryId}/charge`, 'POST', body);
+            return this.createSuccess(result, 'Battery charged successfully');
+        });
+    };
+    // ==================== EQUIPMENT MANAGEMENT ====================
+    getEquipment = async () => {
+        return this.executeToolHandler(async () => {
+            const data = await this.apiCall('/objects/equipment');
+            return this.createSuccess(data);
+        });
+    };
+    // ==================== LABEL PRINTING ====================
+    printBatteryLabel = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { batteryId } = args || {};
+            this.validateRequired({ batteryId }, ['batteryId']);
+            const result = await this.apiCall(`/batteries/${batteryId}/printlabel`);
+            return this.createSuccess(result, 'Battery label printed successfully');
+        });
+    };
+    printChoreLabel = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { choreId } = args || {};
+            this.validateRequired({ choreId }, ['choreId']);
+            const result = await this.apiCall(`/chores/${choreId}/printlabel`);
+            return this.createSuccess(result, 'Chore label printed successfully');
+        });
+    };
+    // ==================== ACTION UTILITIES ====================
+    undoAction = async (args) => {
+        return this.executeToolHandler(async () => {
+            const { entityType, id } = args;
+            this.validateRequired({ entityType, id }, ['entityType', 'id']);
+            let endpoint;
+            switch (entityType.toLowerCase()) {
+                case 'chore':
+                case 'chores':
+                    endpoint = `/chores/executions/${id}/undo`;
+                    break;
+                case 'battery':
+                case 'batteries':
+                    endpoint = `/batteries/charge-cycles/${id}/undo`;
+                    break;
+                case 'task':
+                case 'tasks':
+                    endpoint = `/tasks/${id}/undo`;
+                    break;
+                default:
+                    return this.createError(`Unsupported entity type: ${entityType}`);
+            }
+            const result = await this.apiCall(endpoint, 'POST');
+            return this.createSuccess(result, `${entityType} action undone successfully`);
+        });
+    };
+}

package/build/tools/household/index.js

@@ -0,0 +1,25 @@
+import { householdToolDefinitions } from './definitions.js';
+import { HouseholdToolHandlers } from './handlers.js';
+const handlers = new HouseholdToolHandlers();
+export const householdModule = {
+    definitions: householdToolDefinitions,
+    handlers: {
+        // Chore Management
+        household_chores_get: handlers.getChores,
+        household_chores_execute: handlers.trackChoreExecution,
+        // Task Management
+        household_tasks_get: handlers.getTasks,
+        household_tasks_complete: handlers.completeTask,
+        // Battery Management
+        household_batteries_get: handlers.getBatteries,
+        household_batteries_charge: handlers.chargeBattery,
+        household_batteries_print_label: handlers.printBatteryLabel,
+        // Chore Label Printing
+        household_chores_print_label: handlers.printChoreLabel,
+        // Equipment Management
+        household_equipment_get: handlers.getEquipment,
+        // Action Utilities
+        household_actions_undo: handlers.undoAction,
+    },
+};
+export * from './definitions.js';

package/build/tools/index.js

@@ -0,0 +1,2 @@
+// Re-export simplified module loader functionality
+export { createToolRegistry } from './module-loader.js';