AL1S-WMS

<div align="center"> # AL1S WMS [English](README.md) | [中文](README.zh-CN.md) AL1S WMS is a lightweight, self-hosted warehouse manager for the home. <a href="https://github.com/RicterZ/AL1S-WMS/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/RicterZ/AL1S-WMS?display_name=tag" /></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/RicterZ/AL1S-WMS" /></a> <a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=RicterZ&repository=AL1S-WMS&category=integration"><img alt="Install with HACS" src="https://my.home-assistant.io/badges/hacs_repository.svg" /></a> <img width="1600" height="448" alt="AL1S-WMS-README-banner" src="https://github.com/user-attachments/assets/1aeb25ec-4633-4d3b-9655-8b1a7ce13350" /> </div> It helps a household answer practical questions: what is on hand, where it is stored, what needs buying, what is nearing expiry, and how much has been spent this month. Inspired by Grocy (https://grocy.info/). Stocktaking, purchasing, and finance share one data trail. Receiving a purchase creates a stock batch and transaction; recording its cost updates actual spending, price history, and inventory value. AL1S WMS also exposes an MCP interface so an AI agent can assist within an explicitly authorized scope. ## Who It Is For - Households organizing food, household supplies, medicine, consumables, or storage rooms. - Anyone tracking the same item across rooms, cabinets, and refrigerator zones. - People who want purchase plans, actual costs, and monthly budgets to stay connected instead of maintaining separate spreadsheets. - Users who want an AI agent to help check stock, expiry, and replenishment suggestions while retaining approval over consequential actions. <img width="1585" height="986" alt="image" src="https://github.com/user-attachments/assets/00117ee5-ac0e-41e2-8045-b5356c5bbe11" /> ## How It Compares | Feature | AL1S WMS | [Grocy](https://grocy.info/) | [HomeBox](https://homebox.software/) | | --- | --- | --- | --- | | Cute | Tendou Arisu is indisputably cute | - | - | | Core focus | Household consumables | Food and household routines | Durable household assets | | Inventory model | Batches and stock ledger | Comprehensive, configurable inventory | Quantity as an item attribute | | Consumption | Issue, open, and exhaust | Consume and open | Manual quantity changes | | Expiry | Batch expiry and FEFO | Expiry rules and prioritized consumption | - | | Replenishment | Stock alerts, purchase plans, and receiving | Shopping lists and automatic replenishment | - | | Household finance | Budgets, planned and actual spending | Price history and spending reports | Purchase value of assets | | Broader scope | Inventory, purchasing, and spending | Recipes, meal plans, chores, and tasks | Documents, warranties, and maintenance | | Agent integration | Built-in MCP | REST API and community MCP servers | REST API | ## Features ### Inventory and Batches - Manage item names, barcodes, units, default locations, reorder points, and reorder quantities. - Organize household inventory through hierarchical locations and categories, with tree views for both. - Each receipt creates an independent batch with optional production date, expiry date, actual cost, purchase date, and purchase channel. - A batch may exist in several locations. Stock can be issued from a selected batch or automatically by FEFO, first expiry first out. - Record receipts, issues, transfers, stocktakes, and batch changes in a complete transaction history. - Item details bring together stock, batches, purchase records, price trends, and paginated transaction history. <img width="1585" height="986" alt="image" src="https://github.com/user-attachments/assets/a9b3002f-b90a-4393-a5e8-da09e5e201cf" /> ### Alerts and Stocktakes - Classify stock as insufficient, critical, or depleted from its reorder threshold. - Highlight expired and soon-to-expire batches so they can be used or handled first. - Filter inventory by item, location, status, and expiry; sort by receipt time or urgency. - Enter a physical count directly. Differences are recorded as a receipt or issue with a stocktake reason. ### Purchasing - Create shopping items with a planned date, destination, purchase channel, and estimated amount; review them in a purchase calendar. - Linked inventory items bring along their category, unit, and default location. A selected channel can estimate cost from its latest recorded price. - Low stock produces dynamic replenishment suggestions. Suggestions do not create stock; they become a real shopping item only after a purchase is planned. - Receiving records the actual quantity, cost, and date as a new batch. The completed item leaves the active list while its purchase and finance history remain traceable. - Maintain purchase channels and look up products by barcode. Barcode lookup checks household data and local cache before public product sources. <img width="1585" height="986" alt="image" src="https://github.com/user-attachments/assets/9876cb1f-9f54-47e5-b3de-fcbe1aadfc79" /> ### Finance - Set a monthly total budget and category budgets; a future month can inherit the latest saved budget until it is changed. - Track actual spending, planned spending, forecast spending, remaining budget, and budget execution together. - Category budgets support parent and child categories: a parent cap covers descendant spending while more specific child caps can still be set. - Review monthly spending trends, budget comparisons, category and channel rankings, paginated purchase records, and inventory valuation. - Actual spending belongs to the month of stock receipt. Planned amounts affect the forecast only and never replace actual costs. - Item price history keeps batch-level and channel-level prices for comparing the latest, lowest, and average prices. <img width="1585" height="986" alt="image" src="https://github.com/user-attachments/assets/835318bd-0119-4588-8040-da61be1e0f7d" /> ### Multiple Homes and AI Agents - One account can create and switch between multiple homes. Inventory, locations, purchases, and finance data are isolated per home. - Household-scoped MCP tokens restrict an agent to one home; account-scoped tokens can select an authorized home. - MCP covers home status, items, locations, categories, batches, receipts, issues, transfers, stocktakes, purchasing, price history, and financial analysis. - Agents should obtain explicit confirmation before budget changes, deletions, or other consequential operations. Inventory writes use idempotency keys for safe retries. <img width="1196" height="875" alt="image" src="https://github.com/user-attachments/assets/1d966aa9-2f0e-4e80-8695-6bcb57c75046" /> ## What It Is Not For - Businesses, studios, stores, or other commercial settings that need approvals, supplier contracts, fulfillment, and complex role models. - Professional finance workflows such as bank synchronization, income, invoices, reimbursement, tax, freight allocation, coupons, double-entry bookkeeping, or currency conversion. - ERP, WMS, POS, or supply-chain workloads requiring bulk operations, warehouse slotting, wave picking, or compliance-grade audit controls. - Turning the household into a logistics center solely because a three-month-old cucumber appeared in the refrigerator. It can, however, help deal with that cucumber first. ## TODOs - [ ] Multi-user support, including household membership and role-based access control (RBAC). - [ ] Import, export, backup, and restore for household data. - [ ] Recurring shopping templates and replenishment rules for regularly purchased items. - [ ] Configurable expiry and stock reminders, exposed through MCP so an AI agent or external automation can deliver them. ## Home Assistant Connect a household to view stock alerts and opened items on separate HA dashboard cards, or use inventory status in automations. Install AL1S WMS from HACS as a custom integration, then add it from **Settings → Devices & services** using an AL1S address and access token. Add **Inventory attention** and **In use** separately from your dashboard's **Add card** menu. See the [Home Assistant guide](docs/home-assistant.md) for setup steps, card details, and YAML dashboard instructions. ## Deployment ### Docker Docker with Compose is required. The following commands build the image, start the service, and persist SQLite data in a Docker volume: ```bash git clone https://github.com/RicterZ/AL1S-WMS.git cd AL1S-WMS docker compose up -d --build ``` Open `http://localhost:8080` and complete the initial setup. The SQLite database is stored at `/data/al1s-wms.db` inside the container. Persist `/data`, or all household data will be lost when the container is recreated. A host directory can be easier to integrate with an existing backup policy: ```bash mkdir -p /srv/al1s-wms/data docker run -d \ --name al1s-wms \ --restart unless-stopped \ -p 8080:8080 \ -v /srv/al1s-wms/data:/data \ al1s-wms:local ``` Back up `/data/al1s-wms.db` regularly. For an internet-facing deployment, place the application behind a reverse proxy with HTTPS and restrict access to its management surface. ### Optional Environment Variables | Variable | Default | Purpose | | --- | --- | --- | | `PORT` | `8080` | HTTP service port. | | `BIND_ADDRESS` | `0.0.0.0` | HTTP listen address. | | `DATABASE_URL` | `/data/al1s-wms.db` in the image | SQLite database path. | | `APIZERO_API_KEY` | unset | Enables authenticated ApiZero barcode lookup; without it, AL1S WMS uses an anonymous quota and public sources. | ## MCP and AI Agents AL1S WMS exposes a Streamable HTTP MCP endpoint: ```text https://your-domain.example/mcp ``` Create a token under **Settings -> MCP Access Tokens**, then configure an MCP client: ```json { "mcpServers": { "al1s-wms": { "url": "https://your-domain.example/mcp", "headers": { "Authorization": "Bearer al1s_REPLACE_WITH_YOUR_TOKEN" } } } } ``` An agent should begin with `get_home_context` and `get_home_overview`, then inspect items, locations, batches, or shopping plans for the task at hand. `get_agent_guide` describes the supported receipt, purchase, expiry-handling, and stocktake workflows. - A household-scoped token needs no `homeId` and can access only its bound home. - An account-scoped token can access multiple homes, so the agent must select and provide a `homeId`. - Confirm targets and amounts before writes such as budgeting, deletion, issuing, or receiving. Every inventory write needs a unique `idempotencyKey`; reuse it only to retry the same operation. ## Development and Verification The project uses a pnpm workspace. After installing dependencies: ```bash pnpm install pnpm dev ``` Run the full verification suite with: ```bash pnpm typecheck pnpm test pnpm build ```