mcp-grocy 2.5.0 → 2.7.0

package/build/tools/system/definitions.js

@@ -1,89 +0,0 @@
-import { config } from '../../config/index.js';
-export const systemToolDefinitions = [
-    // ==================== CORE SYSTEM UTILITIES ====================
-    {
-        name: 'system_locations_get',
-        description: '[SYSTEM/LOCATIONS] Get **home storage / stock** locations (freezer, pantry, fridge—where inventory lives). NOT retail stores—use shopping_locations_get for shop/store IDs (storeId). Use this for locationId on stock, transfers, and purchases.',
-        annotations: { readOnlyHint: true },
-        inputSchema: {
-            type: 'object',
-            properties: {},
-            required: [],
-        },
-    },
-    {
-        name: 'system_units_get',
-        description: '[SYSTEM/UNITS] Get all quantity units from your Grocy instance.',
-        annotations: { readOnlyHint: true },
-        inputSchema: {
-            type: 'object',
-            properties: {},
-            required: [],
-        },
-    },
-    {
-        name: 'system_users_get',
-        description: '[SYSTEM/USERS] Get all users from your Grocy instance.',
-        annotations: { readOnlyHint: true },
-        inputSchema: {
-            type: 'object',
-            properties: {},
-            required: [],
-        },
-    },
-    // ==================== DEVELOPER UTILITIES ====================
-    {
-        name: 'system_dev_call_api',
-        description: '[SYSTEM/DEV] Call a specific Grocy API endpoint with custom parameters.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                endpoint: {
-                    type: 'string',
-                    description: 'Grocy API endpoint to call (e.g., "objects/products"). Do not include /api/ prefix.',
-                },
-                method: {
-                    type: 'string',
-                    enum: ['GET', 'POST', 'PUT', 'DELETE'],
-                    description: 'HTTP method to use',
-                    default: 'GET',
-                },
-                body: {
-                    type: 'object',
-                    description: 'Optional request body for POST/PUT requests',
-                },
-            },
-            required: ['endpoint'],
-        },
-    },
-    {
-        name: 'system_dev_test_request',
-        description: `[SYSTEM/DEV] Test a REST API endpoint and get detailed response information. Base URL: ${config.grocy.base_url} | SSL Verification enabled | Authentication: ${config.grocy.api_key ? 'API Key using header: GROCY-API-KEY' : 'No authentication configured'}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                method: {
-                    type: 'string',
-                    enum: ['GET', 'POST', 'PUT', 'DELETE'],
-                    description: 'HTTP method to use',
-                },
-                endpoint: {
-                    type: 'string',
-                    description: 'Endpoint path (e.g. "/users"). Do not include full URLs - only the path.',
-                },
-                body: {
-                    type: 'object',
-                    description: 'Optional request body for POST/PUT requests',
-                },
-                headers: {
-                    type: 'object',
-                    description: 'Optional request headers for one-time use.',
-                    additionalProperties: {
-                        type: 'string',
-                    },
-                },
-            },
-            required: ['method', 'endpoint'],
-        },
-    },
-];

package/build/tools/system/handlers.js

@@ -1,156 +0,0 @@
-import { BaseToolHandler } from '../base.js';
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import apiClient from '../../api/client.js';
-import { config } from '../../config/index.js';
-import { logger } from '../../utils/logger.js';
-export class SystemToolHandlers extends BaseToolHandler {
-    redactHeaders(headers) {
-        const redacted = { ...headers };
-        const sensitiveHeaders = new Set([
-            'grocy-api-key',
-            'authorization',
-            'x-api-key',
-            'proxy-authorization',
-        ]);
-        for (const key of Object.keys(redacted)) {
-            if (sensitiveHeaders.has(key.toLowerCase())) {
-                redacted[key] = '[REDACTED]';
-            }
-        }
-        return redacted;
-    }
-    /**
-     * Truncate a string to at most `maxBytes` UTF-8 bytes without splitting a codepoint.
-     */
-    truncateStringToUtf8Bytes(str, maxBytes) {
-        const buf = Buffer.from(str, 'utf8');
-        if (buf.length <= maxBytes) {
-            return { text: str, byteLength: buf.length };
-        }
-        let end = maxBytes;
-        while (end > 0) {
-            while (end > 0 && (buf[end - 1] & 0xc0) === 0x80) {
-                end--;
-            }
-            if (end === 0) {
-                break;
-            }
-            const text = buf.subarray(0, end).toString('utf8');
-            if (Buffer.byteLength(text, 'utf8') === end) {
-                return { text, byteLength: end };
-            }
-            end--;
-        }
-        return { text: '', byteLength: 0 };
-    }
-    applyResponseSizeLimit(body) {
-        const sizeLimit = config.grocy.response_size_limit;
-        const jsonBody = JSON.stringify(body);
-        const originalSize = Buffer.byteLength(jsonBody, 'utf8');
-        if (originalSize <= sizeLimit) {
-            return { body };
-        }
-        const { text: truncatedJsonBody, byteLength: prefixBytes } = this.truncateStringToUtf8Bytes(jsonBody, sizeLimit);
-        const returnedSize = Buffer.byteLength(truncatedJsonBody, 'utf8');
-        return {
-            body: `${truncatedJsonBody}...[TRUNCATED]`,
-            truncated: {
-                originalSize,
-                returnedSize,
-                truncationPoint: prefixBytes,
-                sizeLimit,
-            },
-        };
-    }
-    // ==================== CORE SYSTEM UTILITIES ====================
-    getLocations = async () => {
-        return this.executeToolHandler(async () => {
-            const data = await this.apiCall('/objects/locations');
-            return this.createSuccess(data);
-        });
-    };
-    getQuantityUnits = async () => {
-        return this.executeToolHandler(async () => {
-            const data = await this.apiCall('/objects/quantity_units');
-            return this.createSuccess(data);
-        });
-    };
-    getUsers = async () => {
-        return this.executeToolHandler(async () => {
-            const data = await this.apiCall('/users');
-            return this.createSuccess(data);
-        });
-    };
-    // ==================== DEVELOPER UTILITIES ====================
-    callGrocyApi = async (args) => {
-        const { endpoint, method = 'GET', body = null } = args;
-        if (!endpoint) {
-            throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: endpoint');
-        }
-        // Remove leading /api/ if present
-        const cleanEndpoint = endpoint.replace(/^\/?(?:api\/)?/, '');
-        try {
-            const response = await apiClient.request(`/${cleanEndpoint}`, {
-                method,
-                body,
-            });
-            return this.createSuccess(response.data);
-        }
-        catch (error) {
-            logger.error(`Error calling Grocy API endpoint ${endpoint}`, 'api', { error });
-            return this.createError(`Failed to call Grocy API endpoint ${endpoint}: ${error.message}`);
-        }
-    };
-    testRequest = async (args) => {
-        const { method, endpoint, body, headers = {} } = args;
-        if (!method || !endpoint) {
-            throw new McpError(ErrorCode.InvalidParams, 'method and endpoint are required');
-        }
-        const normalizedEndpoint = `/${endpoint.replace(/^\/+|\/+$/g, '')}`;
-        const requestHeaders = { ...config.getCustomHeaders(), ...headers };
-        const safeRequestHeaders = this.redactHeaders(requestHeaders);
-        try {
-            const startTime = Date.now();
-            const response = await apiClient.request(normalizedEndpoint, {
-                method,
-                body,
-                headers: requestHeaders,
-            });
-            const endTime = Date.now();
-            const responseWithLimit = this.applyResponseSizeLimit(response.data);
-            const responseObj = {
-                request: {
-                    url: `${config.grocy.base_url}${normalizedEndpoint}`,
-                    method,
-                    headers: safeRequestHeaders,
-                    body,
-                    authMethod: config.grocy.api_key ? 'apikey' : 'none',
-                },
-                response: {
-                    statusCode: response.status,
-                    timing: `${endTime - startTime}ms`,
-                    headers: response.headers,
-                    body: responseWithLimit.body,
-                },
-                validation: {
-                    isError: response.status >= 400,
-                    messages: response.status >= 400
-                        ? [`Request failed with status ${response.status}`]
-                        : ['Request completed successfully'],
-                    ...(responseWithLimit.truncated ? { truncated: responseWithLimit.truncated } : {}),
-                },
-            };
-            return this.createSuccess(responseObj);
-        }
-        catch (error) {
-            return this.createError(`Test request failed: ${error.message}`, {
-                request: {
-                    url: `${config.grocy.base_url}${normalizedEndpoint}`,
-                    method,
-                    headers: safeRequestHeaders,
-                    body,
-                },
-            });
-        }
-    };
-}

package/build/tools/system/index.js

@@ -1,16 +0,0 @@
-import { systemToolDefinitions } from './definitions.js';
-import { SystemToolHandlers } from './handlers.js';
-const handlers = new SystemToolHandlers();
-export const systemModule = {
-    definitions: systemToolDefinitions,
-    handlers: {
-        // Core System Utilities
-        system_locations_get: handlers.getLocations,
-        system_units_get: handlers.getQuantityUnits,
-        system_users_get: handlers.getUsers,
-        // Developer Utilities
-        system_dev_call_api: handlers.callGrocyApi,
-        system_dev_test_request: handlers.testRequest,
-    },
-};
-export * from './definitions.js';

package/build/tools/types.js

@@ -1 +0,0 @@
-export {};

package/build/tools/validation-helpers.js

@@ -1,39 +0,0 @@
-/**
- * Common validation utility functions
- */
-import { ValidationError } from '../utils/errors.js';
-export class ValidationHelpers {
-    static validateBoolean(value, fieldName) {
-        if (value !== undefined && typeof value !== 'boolean') {
-            throw new ValidationError(`${fieldName} must be a boolean`, 'sub-config validation');
-        }
-    }
-    static validateString(value, fieldName) {
-        if (value !== undefined && typeof value !== 'string') {
-            throw new ValidationError(`${fieldName} must be a string`, 'sub-config validation');
-        }
-    }
-    static validateNumber(value, fieldName, options) {
-        if (value !== undefined) {
-            if (typeof value !== 'number') {
-                throw new ValidationError(`${fieldName} must be a number`, 'sub-config validation');
-            }
-            if (options?.min !== undefined && value < options.min) {
-                throw new ValidationError(`${fieldName} must be at least ${options.min}`, 'sub-config validation');
-            }
-            if (options?.max !== undefined && value > options.max) {
-                throw new ValidationError(`${fieldName} must be at most ${options.max}`, 'sub-config validation');
-            }
-        }
-    }
-    static validateKnownOptions(subConfigs, knownOptions, toolName) {
-        for (const [key] of subConfigs) {
-            if (!knownOptions.has(key)) {
-                const validOptions = Array.from(knownOptions)
-                    .filter((k) => k !== 'ack_token')
-                    .join(', ');
-                throw new ValidationError(`Unknown sub-configuration option '${key}' for ${toolName} tool. Valid options are: ${validOptions}`, 'sub-config validation');
-            }
-        }
-    }
-}

package/build/types/index.js

@@ -1,64 +0,0 @@
-/**
- * Improved type definitions for better type safety
- */
-import { z } from 'zod';
-// Configuration types
-export const ConfigSchema = z.object({
-    env: z.object({
-        GROCY_API_KEY: z.string().optional(),
-        RELEASE_VERSION: z.string().optional(),
-        NODE_ENV: z.enum(['development', 'production', 'test']).optional(),
-    }),
-    yaml: z.object({
-        server: z.object({
-            enable_http_server: z.boolean().default(false),
-            http_server_port: z.number().min(1).max(65535).default(8080),
-        }),
-        grocy: z.object({
-            base_url: z.string().url(),
-            enable_ssl_verify: z.boolean().default(true),
-            response_size_limit: z.number().positive().default(10000),
-        }),
-        tools: z.record(z.string(), z
-            .object({
-            enabled: z.boolean().default(false),
-            ack_token: z.string().optional(),
-        })
-            .catchall(z.unknown())),
-    }),
-});
-// Validation schemas for runtime type checking
-export const ToolResultSchema = z.object({
-    success: z.boolean(),
-    data: z.any().optional(),
-    error: z.string().optional(),
-    message: z.string().optional(),
-    details: z.any().optional(),
-});
-export const ToolDefinitionSchema = z.object({
-    name: z.string(),
-    description: z.string(),
-    inputSchema: z.object({
-        type: z.literal('object'),
-        properties: z.record(z.string(), z.any()),
-        required: z.array(z.string()).optional(),
-    }),
-});
-export const ToolModuleSchema = z.object({
-    definitions: z.array(ToolDefinitionSchema),
-    handlers: z.record(z.string(), z.custom((v) => typeof v === 'function')),
-});
-// Type guards
-export function isToolResult(obj) {
-    return ToolResultSchema.safeParse(obj).success;
-}
-export function isToolDefinition(obj) {
-    return ToolDefinitionSchema.safeParse(obj).success;
-}
-export function isToolModule(obj) {
-    return (obj &&
-        typeof obj === 'object' &&
-        Array.isArray(obj.definitions) &&
-        typeof obj.handlers === 'object' &&
-        obj.definitions.every((def) => isToolDefinition(def)));
-}

package/build/utils/errors.js

@@ -1,143 +0,0 @@
-/**
- * Simplified error handling system
- */
-import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
-import { logger } from './logger.js';
-/**
- * Simplified application error
- */
-export class AppError extends Error {
-    category;
-    statusCode;
-    operation;
-    details;
-    timestamp = new Date();
-    constructor(message, category, statusCode, operation, details) {
-        super(message);
-        this.name = 'AppError';
-        this.category = category;
-        this.statusCode = statusCode;
-        this.operation = operation;
-        this.details = details;
-        Object.setPrototypeOf(this, AppError.prototype);
-    }
-    toMcpError() {
-        const errorCode = this.getErrorCode();
-        return new McpError(errorCode, this.message);
-    }
-    getErrorCode() {
-        switch (this.category) {
-            case 'VALIDATION':
-                return ErrorCode.InvalidParams;
-            case 'AUTH':
-                return ErrorCode.InvalidRequest;
-            case 'API':
-                if (this.statusCode === 404)
-                    return ErrorCode.InvalidRequest;
-                if (this.statusCode === 401 || this.statusCode === 403)
-                    return ErrorCode.InvalidRequest;
-                return ErrorCode.InternalError;
-            default:
-                return ErrorCode.InternalError;
-        }
-    }
-}
-/**
- * API-specific error
- */
-export class ApiError extends AppError {
-    constructor(message, statusCode, operation, details) {
-        super(message, 'API', statusCode, operation, details);
-        this.name = 'ApiError';
-    }
-    static fromAxiosError(error, operation) {
-        if (error.response) {
-            return new ApiError(error.response.data?.message || `HTTP ${error.response.status}`, error.response.status, operation, { url: error.config?.url, method: error.config?.method });
-        }
-        if (error.request) {
-            return new ApiError('Network error - unable to reach server', undefined, operation, {
-                url: error.config?.url,
-            });
-        }
-        return new ApiError(error.message || 'Request error', undefined, operation);
-    }
-}
-/**
- * Validation error
- */
-export class ValidationError extends AppError {
-    constructor(message, operation, details) {
-        super(message, 'VALIDATION', undefined, operation, details);
-        this.name = 'ValidationError';
-    }
-}
-/**
- * Configuration error
- */
-export class ConfigError extends AppError {
-    constructor(message, operation, details) {
-        super(message, 'CONFIG', undefined, operation, details);
-        this.name = 'ConfigError';
-    }
-}
-/**
- * Centralized error handler
- */
-export class ErrorHandler {
-    /**
-     * Handle async operations with error wrapping
-     */
-    static async handleAsync(operation, context) {
-        try {
-            return await operation();
-        }
-        catch (error) {
-            this.logError(error, context);
-            throw this.wrapError(error, context);
-        }
-    }
-    /**
-     * Log error with context
-     */
-    static logError(error, context) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const fullContext = context ? `${context}: ${errorMessage}` : errorMessage;
-        if (error instanceof AppError) {
-            logger.warn(fullContext, 'ERROR', {
-                category: error.category,
-                statusCode: error.statusCode,
-                operation: error.operation,
-                details: error.details,
-            });
-        }
-        else {
-            logger.error(fullContext, 'ERROR', { error });
-        }
-    }
-    /**
-     * Wrap unknown errors in AppError
-     */
-    static wrapError(error, context) {
-        if (error instanceof AppError) {
-            return error;
-        }
-        if (error instanceof McpError) {
-            return new AppError(error.message, 'INTERNAL', undefined, context);
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        return new AppError(message, 'INTERNAL', undefined, context);
-    }
-    /**
-     * Convert error to MCP error
-     */
-    static toMcpError(error, fallbackMessage = 'Internal error') {
-        if (error instanceof McpError) {
-            return error;
-        }
-        if (error instanceof AppError) {
-            return error.toMcpError();
-        }
-        const message = error instanceof Error ? error.message : fallbackMessage;
-        return new McpError(ErrorCode.InternalError, message);
-    }
-}

package/build/utils/logger.js

@@ -1,142 +0,0 @@
-/**
- * Centralized logging utility with configurable levels and structured output
- */
-export var LogLevel;
-(function (LogLevel) {
-    LogLevel[LogLevel["ERROR"] = 0] = "ERROR";
-    LogLevel[LogLevel["WARN"] = 1] = "WARN";
-    LogLevel[LogLevel["INFO"] = 2] = "INFO";
-    LogLevel[LogLevel["DEBUG"] = 3] = "DEBUG";
-    LogLevel[LogLevel["TRACE"] = 4] = "TRACE";
-})(LogLevel || (LogLevel = {}));
-export class Logger {
-    static instance;
-    logLevel;
-    enabledCategories = null;
-    constructor() {
-        // Default to INFO level, but allow override via environment
-        this.logLevel = this.parseLogLevel(process.env.LOG_LEVEL || 'INFO');
-        // Allow filtering by categories
-        const categories = process.env.LOG_CATEGORIES;
-        if (categories) {
-            this.enabledCategories = new Set(categories.split(',').map((c) => c.trim().toUpperCase()));
-        }
-    }
-    static getInstance() {
-        if (!Logger.instance) {
-            Logger.instance = new Logger();
-        }
-        return Logger.instance;
-    }
-    parseLogLevel(level) {
-        const upperLevel = level.toUpperCase();
-        switch (upperLevel) {
-            case 'ERROR':
-                return LogLevel.ERROR;
-            case 'WARN':
-                return LogLevel.WARN;
-            case 'INFO':
-                return LogLevel.INFO;
-            case 'DEBUG':
-                return LogLevel.DEBUG;
-            case 'TRACE':
-                return LogLevel.TRACE;
-            default:
-                return LogLevel.INFO;
-        }
-    }
-    shouldLog(level, category) {
-        // Check log level
-        if (level > this.logLevel) {
-            return false;
-        }
-        // Check category filter
-        if (this.enabledCategories && category) {
-            return this.enabledCategories.has(category.toUpperCase());
-        }
-        return true;
-    }
-    formatMessage(entry) {
-        const timestamp = entry.timestamp.toISOString();
-        const level = LogLevel[entry.level].padEnd(5);
-        const category = entry.category ? `[${entry.category}]` : '';
-        const data = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
-        return `${timestamp} ${level} ${category} ${entry.message}${data}`;
-    }
-    log(level, message, category, data) {
-        if (!this.shouldLog(level, category)) {
-            return;
-        }
-        const entry = {
-            level,
-            message,
-            category: category || undefined,
-            data,
-            timestamp: new Date(),
-        };
-        const formattedMessage = this.formatMessage(entry);
-        // Use stderr for all logs to avoid interfering with MCP stdio protocol
-        console.error(formattedMessage);
-    }
-    error(message, category, data) {
-        this.log(LogLevel.ERROR, message, category, data);
-    }
-    warn(message, category, data) {
-        this.log(LogLevel.WARN, message, category, data);
-    }
-    info(message, category, data) {
-        this.log(LogLevel.INFO, message, category, data);
-    }
-    debug(message, category, data) {
-        this.log(LogLevel.DEBUG, message, category, data);
-    }
-    trace(message, category, data) {
-        this.log(LogLevel.TRACE, message, category, data);
-    }
-    // Convenience methods for common categories
-    config(message, data) {
-        this.info(message, 'CONFIG', data);
-    }
-    api(message, data) {
-        this.debug(message, 'API', data);
-    }
-    module(message, data) {
-        this.debug(message, 'MODULE', data);
-    }
-    tools(message, data) {
-        this.info(message, 'TOOLS', data);
-    }
-    server(message, data) {
-        this.info(message, 'SERVER', data);
-    }
-    // Testing utilities
-    setLogLevel(level) {
-        this.logLevel = level;
-    }
-    setEnabledCategories(categories) {
-        this.enabledCategories = categories ? new Set(categories.map((c) => c.toUpperCase())) : null;
-    }
-}
-// Export singleton instance
-export const logger = Logger.getInstance();
-// Convenience function for quick logging
-export function log(level, message, category, data) {
-    // Access the private log method through the public methods
-    switch (level) {
-        case LogLevel.ERROR:
-            logger.error(message, category, data);
-            break;
-        case LogLevel.WARN:
-            logger.warn(message, category, data);
-            break;
-        case LogLevel.INFO:
-            logger.info(message, category, data);
-            break;
-        case LogLevel.DEBUG:
-            logger.debug(message, category, data);
-            break;
-        case LogLevel.TRACE:
-            logger.trace(message, category, data);
-            break;
-    }
-}