Tanpin

Item-by-item inventory that reorders itself. Per-SKU demand forecasts, automatic purchase orders, supplier email and delivery ETAs — with a REST API, an MCP server, a daemon, and a dashboard. Pure Node 22, zero runtime dependencies (node:* built-ins only).

Live demo: huggingface.co/spaces/willykeenan/tanpin (read-only, seeded sample data)

_{Real screenshot of the demo; the data in it is invented sample data.}

Per-SKU forecast with weekday and trend factors, safety stock, reorder point and a manager hypothesis.

Purchase orders the cycle raised, grouped by supplier.

Why tanpin kanri

Tanpin kanri (単品管理, “single-item management”) treats every SKU as its own business. A store manager forms a hypothesis about tomorrow’s demand for that item — weather, a local event, day of week — orders against it, then verifies the result against actual sales. High-velocity items get tight control and frequent replenishment. The long tail gets simpler rules, and is the first to be delisted.

Tanpin encodes that loop in software:

1. Forecast each SKU from recent sales, weekday seasonality, short-term trend, and manager-entered hypotheses (events, weather, promotions).
2. Compute the order — safety stock at a chosen service level, reorder point, EOQ, pack-size rounding, minimum order quantity, and a JIT cap on days of supply.
3. Buy and track — purchase orders grouped by supplier, emailed automatically, with a delivery ETA from lead time, cut-off hour, and delivery windows.
4. Stop stocking what does not sell — dead and slow SKUs are flagged to delist.

ABC classification follows the same idea: a small set of A items drives most value and gets the freshest reorder cadence; C items are the delist pool.

Features

• Per-SKU forecasting — recency-weighted moving average, day-of-week factors, trend (±40%), compounding hypotheses
• Automatic reorder — safety stock, reorder point, EOQ, pack size, MOQ, max days of supply
• ABC + delist — A/B/C by revenue contribution; dead (no demand) and slow (too many days of supply) flags
• Daemon — every N minutes (default 15): re-forecast, reclassify, raise draft POs, optionally email and auto-receive
• Supplier email — SMTP over implicit TLS (port 465) when SMTP_HOST is set; otherwise .eml files in the outbox
• Delivery ETAs — lead time snapped to the next delivery window, honoring cut-off hours (UTC today)
• REST API — products addressed by SKU, OpenAPI 3.1 at /openapi.json, agent guide at /llms.txt
• MCP server — newline-delimited JSON-RPC over stdio for Claude Code, Codex, Cursor, and any MCP client
• Dashboard — vanilla JS SPA at / (products, orders, suppliers, forecast, activity, API, settings)
• Webhooks — HMAC-SHA256 signed JSON POSTs (X-Inventory-Signature)
• CSV — import/export products; export the movement audit trail
• API keys — stored as SHA-256 hashes, full key shown once
• Idempotency-Key — 24h replay window on sales and purchase-order writes
• Plugins — TANPIN_PLUGIN loads extra HTTP routes and usage limits
• Storage — SQLite (node:sqlite, WAL, incremental row writes; data/inventory.sqlite) shared safely by the server and a standalone daemon; JSON fallback with TANPIN_STORE=json

60-second quickstart

Requires Node.js 22 or newer.

npx github:willykeenan/tanpin serve

Open http://localhost:4173 and click Load demo data. That loads a convenience-store catalog, about 35 days of sales, live forecasts, and reorder recommendations.

From a clone of this repo:

node bin/tanpin serve

Docker

Public demo image (the Hugging Face Space):

docker build -f space/Dockerfile -t tanpin-demo .
docker run --rm -p 7860:7860 tanpin-demo

Open http://localhost:7860. The image runs DEMO_MODE=1 PORT=7860 HOST=0.0.0.0 node bin/tanpin serve: reads are open, writes are limited to the demo catalog (sales, adjustments, POs, hypotheses, seed, cycles) and need no key, webhooks and SMTP are off, and the catalog reseeds every 30 minutes.

Self-hosted image (root Dockerfile / compose.yml): requests reach the container through Docker's port mapping, so they are not "this machine" and every API call needs a key. Start it with a master key and paste that key into the dashboard's prompt:

docker build -t tanpin .
docker run --rm -p 4173:4173 -e TANPIN_ADMIN_KEY="$(openssl rand -hex 24)" -v tanpin-data:/app/data tanpin
# or: echo "TANPIN_ADMIN_KEY=$(openssl rand -hex 24)" > .env && docker compose up

More detail, including the first sale and first purchase order: docs/QUICKSTART.md.

API

Send Authorization: Bearer <key> or X-API-Key: <key>. Requests made on the server's own machine straight to localhost need no key by default; anything through a reverse proxy, a container port mapping, or another browser origin does (see Security model).

Five calls that cover the store:

# Whole world in one response: KPIs, products with live math, open POs, suppliers
curl http://localhost:4173/api/state

# Record a sale (SKU everywhere; Idempotency-Key for safe retries)
curl -X POST http://localhost:4173/api/sales \
  -H 'Content-Type: application/json' \
  -d '{"sku":"COFFEE-HOT","qty":2}'

# Dry run of the ordering engine, grouped by supplier
curl http://localhost:4173/api/recommendations

# Turn a recommendation into a real PO (and email it)
curl -X POST http://localhost:4173/api/purchase-orders \
  -H 'Content-Type: application/json' \
  -d '{"supplierId":"FreshFoods Distribution","fromRecommendations":true,"autoSend":true}'

# Forward-looking demand bump — forecasts and auto-orders adjust immediately
curl -X POST http://localhost:4173/api/hypotheses \
  -H 'Content-Type: application/json' \
  -d '{"note":"heatwave next week","multiplier":1.4,"category":"beverage"}'

Errors are {"error":"<message>","code":"<machine_code>"}. /api/... and /api/v1/... are equivalent.

Full reference: docs/API.md. Live contract: GET /openapi.json. Agent-oriented guide: GET /llms.txt.

MCP

Start the inventory server, then point an MCP client at tanpin mcp. The process speaks JSON-RPC on stdio and calls the HTTP API.

Environment: INVENTORY_URL (default http://localhost:4173), INVENTORY_API_KEY when the server requires a key.

Claude Code

claude mcp add tanpin --env INVENTORY_URL=http://localhost:4173 -- npx -y github:willykeenan/tanpin mcp

Or a project .mcp.json:

{
  "mcpServers": {
    "tanpin": {
      "command": "npx",
      "args": ["-y", "github:willykeenan/tanpin", "mcp"],
      "env": {
        "INVENTORY_URL": "http://localhost:4173"
      }
    }
  }
}

From a local checkout, use "command": "node" and "args": ["src/mcp.js"] (or ["bin/tanpin", "mcp"]) instead of npx.

Codex

In ~/.codex/config.toml (or the project Codex config):

[mcp_servers.tanpin]
command = "npx"
args = ["-y", "github:willykeenan/tanpin", "mcp"]

[mcp_servers.tanpin.env]
INVENTORY_URL = "http://localhost:4173"

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "tanpin": {
      "command": "npx",
      "args": ["-y", "github:willykeenan/tanpin", "mcp"],
      "env": {
        "INVENTORY_URL": "http://localhost:4173"
      }
    }
  }
}

Call get_overview first. Typical flow: get_overview → get_reorder_recommendations → create_purchase_order with from_recommendations=true.

Tool list and schemas: docs/MCP.md.

Security model