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.

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.

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.

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.

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.

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.

Deployment

Docker

Docker is required. The following commands build the image, start the service, and persist SQLite data in a Docker volume:

git clone https://github.com/RicterZ/AL1S-WMS.git
cd AL1S-WMS
docker build -t al1s-wms .
docker run -d \
  --name al1s-wms \
  --restart unless-stopped \
  -p 8080:8080 \
  -v al1s-wms-data:/data \
  al1s-wms

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:

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

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.
STATIC_ROOT	/app/public in the image	Web static asset directory.
APIZERO_API_KEY	unset	Enables authenticated ApiZero barcode lookup; without it, AL1S WMS uses an anonymous quota and public sources.
BARCODE_USER_AGENT	built-in value	Overrides the User-Agent used for public barcode data sources.

MCP and AI Agents

AL1S WMS exposes a Streamable HTTP MCP endpoint:

https://your-domain.example/mcp

Create a token under Settings -> MCP Access Tokens, then configure an MCP client:

{
  "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:

pnpm install
pnpm dev

Run the full verification suite with:

pnpm typecheck
pnpm test
pnpm build