mcp-grocy 2.7.1 → 2.8.0

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,118 @@
+/**
+ * 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');
+}
+/**
+ * Some MCP clients serialize every tool argument as a string ("12", "true"). Accept those
+ * encodings for number/boolean properties: z.preprocess converts them before validation, and the
+ * JSON Schema advertised by tools/list still shows the wrapped type because Zod 4's toJSONSchema
+ * (io: 'input', which the SDK uses) resolves a preprocess pipe to its output schema — pinned by
+ * tests/tool-input-zod.test.ts. Only JSON number syntax and "true"/"false" are converted;
+ * anything else is passed through unchanged so the usual type error is still raised.
+ */
+const JSON_NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
+function numericStringToNumber(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!JSON_NUMBER.test(trimmed))
+        return value;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : value;
+}
+function booleanStringToBoolean(value) {
+    if (typeof value !== 'string')
+        return value;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    return value;
+}
+const lenientNumber = () => z.preprocess(numericStringToNumber, z.number());
+const lenientBoolean = () => z.preprocess(booleanStringToBoolean, z.boolean());
+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 = lenientNumber();
+            break;
+        case 'boolean':
+            inner = lenientBoolean();
+            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(lenientNumber());
+            }
+            else if (items?.type === 'boolean') {
+                inner = z.array(lenientBoolean());
+            }
+            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();
+    }
+    // Keep the per-property description in the advertised JSON Schema (LLM clients read it).
+    const described = prop.description ? inner.describe(prop.description) : inner;
+    return required ? described : described.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,190 @@
+/**
+ * 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 {
+    /**
+     * Normalizes response data so IDs (like created_object_id or entity id) are numeric.
+     */
+    normalizeResponseData(data) {
+        if (!data || typeof data !== 'object') {
+            return data;
+        }
+        if (Array.isArray(data)) {
+            return data.map((item) => this.normalizeResponseData(item));
+        }
+        if (Object.prototype.toString.call(data) !== '[object Object]') {
+            return data;
+        }
+        const normalized = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key === 'created_object_id' && value !== null && value !== undefined) {
+                const num = Number(value);
+                normalized[key] = Number.isInteger(num) && num > 0 ? num : value;
+            }
+            else if (key === 'id' && typeof value === 'string') {
+                const num = Number(value);
+                normalized[key] = Number.isInteger(num) && num > 0 ? num : value;
+            }
+            else if (value && typeof value === 'object') {
+                normalized[key] = this.normalizeResponseData(value);
+            }
+            else {
+                normalized[key] = value;
+            }
+        }
+        return normalized;
+    }
+    /**
+     * Create a standardized success result
+     */
+    createSuccess(data, message) {
+        const normalizedData = this.normalizeResponseData(data);
+        let serializeStructured;
+        try {
+            serializeStructured = config?.server?.serialize_structured_to_content ?? false;
+        }
+        catch {
+            serializeStructured = false;
+        }
+        const textContent = serializeStructured && normalizedData !== undefined && normalizedData !== null
+            ? message
+                ? `${message}\n${this.safeStringify(normalizedData)}`
+                : this.safeStringify(normalizedData)
+            : message || 'Operation completed successfully';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: textContent,
+                },
+            ],
+            structuredContent: {
+                data: normalizedData ?? 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/base.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { BaseToolHandler } from './base.js';
+class TestHandler extends BaseToolHandler {
+    testNormalize(data) {
+        return this.normalizeResponseData(data);
+    }
+    testSuccess(data, message) {
+        return this.createSuccess(data, message);
+    }
+}
+describe('BaseToolHandler normalization', () => {
+    const handler = new TestHandler();
+    it('normalizes created_object_id string to number', () => {
+        const input = { created_object_id: '1330' };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({ created_object_id: 1330 });
+    });
+    it('leaves created_object_id untouched if already a number', () => {
+        const input = { created_object_id: 1330 };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({ created_object_id: 1330 });
+    });
+    it('normalizes string id to number', () => {
+        const input = { id: '46', name: 'Arroz redondo' };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({ id: 46, name: 'Arroz redondo' });
+    });
+    it('normalizes nested objects and arrays', () => {
+        const input = {
+            list: { id: '1', name: 'Groceries' },
+            items: [
+                { id: '10', product: { id: '46', name: 'Rice' } },
+                { id: '11', product: { id: '55', name: 'Beans' } },
+            ],
+        };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({
+            list: { id: 1, name: 'Groceries' },
+            items: [
+                { id: 10, product: { id: 46, name: 'Rice' } },
+                { id: 11, product: { id: 55, name: 'Beans' } },
+            ],
+        });
+    });
+    it('does not touch barcodes, dates, or non-id fields', () => {
+        const input = {
+            id: '1',
+            barcode: '012345678905',
+            created_at: '2026-09-11 12:00:00',
+            note: '46',
+        };
+        const output = handler.testNormalize(input);
+        expect(output).toEqual({
+            id: 1,
+            barcode: '012345678905',
+            created_at: '2026-09-11 12:00:00',
+            note: '46',
+        });
+    });
+    it('createSuccess automatically applies normalization to structuredContent and textContent', () => {
+        const res = handler.testSuccess({ created_object_id: '1330' }, 'Created');
+        expect(res.structuredContent?.data).toEqual({ created_object_id: 1330 });
+    });
+});

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'],
+        },
+    },
+];