hermes-grocy-mcp/docs/api-coverage.md

API coverage

Catalog baseline: Grocy 4.7.1. All remote operations use the enrolled /api prefix, including files and diagnostics. Record fields are a reviewed factual catalog derived from that version's schema; new server fields require a catalog update.

Household records cover products/barcodes/groups, locations, units/conversions, shopping lists/items/stores, recipes/ingredients/nesting, meal plans/sections, chores, tasks/categories, batteries, equipment and custom fields/entities/objects. Supported history and stock views are read-only.

Account mutation, API keys, sessions, permissions, configuration secrets, public sharing links, external lookup and printing are excluded. Stock-unit changes require a positive unambiguous Grocy conversion. Grocy 4.7.1's database cascade rescales stock and related records; its API result is read back. These preflight checks do not prevent simultaneous edits by other clients.

Source: Grocy API specification.

Household entity inventory

Use records_describe for required creation fields, then records_list/records_lookup to find explicit IDs. records_create, records_update and records_delete are limited to editable entities. userfields_get/userfields_update read/change defined household values. For a custom object use entity: userobjects and its object ID; the MCP resolves its custom entity from the stored definition. Define its fields against userentity-<name> after creating that household entity. Account custom-field definitions are filtered from reads and cannot be mutated. For stock batch values, pass the numeric entry row ID plus an exact stock_transaction_id from a purchase/inventory-correction/entry-edit receipt or history. Grocy inserts these fields via transactions; reads resolve the batch ID automatically. A transaction spanning other batch IDs is refused.

Entity	Access
products	Read/create/update/delete
chores	Read/create/update/delete
product_barcodes	Read/create/update/delete
batteries	Read/create/update/delete
locations	Read/create/update/delete
quantity_units	Read/create/update/delete
quantity_unit_conversions	Read/create/update/delete
shopping_list	Read/create/update/delete
shopping_lists	Read/create/update/delete
shopping_locations	Read/create/update/delete
recipes	Read/create/update/delete
recipes_pos	Read/create/update/delete
recipes_nestings	Read/create/update/delete
tasks	Read/create/update/delete
task_categories	Read/create/update/delete
product_groups	Read/create/update/delete
equipment	Read/create/update/delete
userfields	Read/create/update/delete
userentities	Read/create/update/delete
userobjects	Read/create/update/delete
meal_plan	Read/create/update/delete
stock_log	Read only
stock	Read only
stock_current_locations	Read only
chores_log	Read only
meal_plan_sections	Read/create/update/delete
products_last_purchased	Read only
products_average_price	Read only
quantity_unit_conversions_resolved	Read only
recipes_pos_resolved	Read only
battery_charge_cycles	Read only
product_barcodes_view	Read only
uihelper_shopping_list	Read only

Named upstream operations

All routes below are relative to the enrolled API base. Local descriptions/validation and credential loading do not make HTTP requests. Generic record tools use /objects/{entity} or /objects/{entity}/{id}; custom values use /userfields/{entity}/{id}. An unavailable server route/record returns NOT_FOUND, rejected inputs/permissions return sanitized errors, and an interrupted mutation can return UNKNOWN_WRITE_OUTCOME.

Tool	Method	API route
database_changed_time	GET	/system/db-changed-time
server_time	GET	/system/time
stock_list	GET	/stock
stock_entry	GET	/stock/entry/{entryId}
stock_entry_put	PUT	/stock/entry/{entryId}
stock_volatile	GET	/stock/volatile
stock_product	GET	/stock/products/{productId}
stock_locations	GET	/stock/products/{productId}/locations
stock_entries	GET	/stock/products/{productId}/entries
stock_price_history	GET	/stock/products/{productId}/price-history
stock_add	POST	/stock/products/{productId}/add
stock_consume	POST	/stock/products/{productId}/consume
stock_transfer	POST	/stock/products/{productId}/transfer
stock_inventory	POST	/stock/products/{productId}/inventory
stock_open	POST	/stock/products/{productId}/open
stock_copy	POST	/stock/products/{productId}/copy
stock_merge	POST	/stock/products/{productIdToKeep}/merge/{productIdToRemove}
stock_product_by_barcode	GET	/stock/products/by-barcode/{barcode}
stock_add_by_barcode	POST	/stock/products/by-barcode/{barcode}/add
stock_consume_by_barcode	POST	/stock/products/by-barcode/{barcode}/consume
stock_transfer_by_barcode	POST	/stock/products/by-barcode/{barcode}/transfer
stock_inventory_by_barcode	POST	/stock/products/by-barcode/{barcode}/inventory
stock_open_by_barcode	POST	/stock/products/by-barcode/{barcode}/open
stock_location_entries	GET	/stock/locations/{locationId}/entries
shopping_add_missing_products	POST	/stock/shoppinglist/add-missing-products
shopping_add_overdue_products	POST	/stock/shoppinglist/add-overdue-products
shopping_add_expired_products	POST	/stock/shoppinglist/add-expired-products
shopping_clear	POST	/stock/shoppinglist/clear
shopping_add_product	POST	/stock/shoppinglist/add-product
shopping_remove_product	POST	/stock/shoppinglist/remove-product
stock_booking	GET	/stock/bookings/{bookingId}
stock_undo_booking	POST	/stock/bookings/{bookingId}/undo
stock_transaction	GET	/stock/transactions/{transactionId}
stock_undo_transaction	POST	/stock/transactions/{transactionId}/undo
recipe_add_not_fulfilled_products_to_shoppinglist	POST	/recipes/{recipeId}/add-not-fulfilled-products-to-shoppinglist
recipe_fulfillment	GET	/recipes/{recipeId}/fulfillment
recipe_consume	POST	/recipes/{recipeId}/consume
recipes_fulfillment	GET	/recipes/fulfillment
recipe_copy	POST	/recipes/{recipeId}/copy
chores_list	GET	/chores
chore_details	GET	/chores/{choreId}
chore_execute	POST	/chores/{choreId}/execute
chore_undo_execution	POST	/chores/executions/{executionId}/undo
chores_recalculate_assignments	POST	/chores/executions/calculate-next-assignments
chore_merge	POST	/chores/{choreIdToKeep}/merge/{choreIdToRemove}
batteries_list	GET	/batteries
battery_details	GET	/batteries/{batteryId}
battery_charge	POST	/batteries/{batteryId}/charge
battery_undo_charge	POST	/batteries/charge-cycles/{chargeCycleId}/undo
tasks_list	GET	/tasks
task_complete	POST	/tasks/{taskId}/complete
task_undo	POST	/tasks/{taskId}/undo
file_get / file_upload / file_delete	GET / PUT / DELETE	/files/{group}/{base64Filename}
calendar_export	GET	/calendar/ical
shopping_export	GET	/objects/shopping_list (filter explicit list ID)
assignment_users	GET	/users (return only IDs/display names)

File groups: equipmentmanuals, recipepictures, productpictures, userfiles; avatars are excluded. Stock log/history views remain read-only, while supported booking/transaction undo has named action tools. Recipe-derived shopping additions use Grocy's API default list; the endpoint has no explicit list selector. This server does not invent one.

Explicit exclusions

No arbitrary API request tool. No system configuration/user-settings secrets, API-key/session/permission administration, user/account mutation, public sharing-link routes, barcode external lookup, printer/webhook endpoints or attachments outside /api. Assignment labels are the only account projection. Server-configured hooks can still run as part of Grocy's own household policies.

The catalog covers the reviewed household API surface, not undocumented plugins, server internals, database maintenance, filesystem or orphan-file enumeration. The Docker contract exercises a meaningful scenario per domain; it does not claim every possible parameter combination or server-version behavior has been tested.