Inventory LLM Demo

Inventory demo app that combines:

• React frontend
• ASP.NET Core backend
• SQLite persistence
• Model Context Protocol (MCP) tools
• LM Studio-compatible local LLM
• Browser-native speech-to-text and text-to-speech (Web Speech API)

Architecture

• Frontend: client (Vite + React)
• Backend: server (ASP.NET Core + Dapper + SQLite)
• Database: db/001_schema.sql, db/002_seed.sql
• Prompts:
  • SYSTEM_PROMPT.md
  • STARTUP_PROMPT.md
  • FEW_SHOT_PROMPTS.json

The backend serves both API endpoints and MCP tools at /mcp.

The chat layer proxies completions to an OpenAI-compatible endpoint (LM Studio by default).

Prerequisites

• Docker Desktop (for containerized run)
• LM Studio local server running on http://localhost:1234
• macOS, Windows, or Linux

Configuration

Copy .env.example to .env (only if .env does not exist yet).

Default .env values:

LLM_BASE_URL=http://host.docker.internal:1234
LLM_MODEL=auto
LLM_COMPLETION_PATH=/v1/chat/completions
LLM_HEALTH_PATH=/v1/models
MCP_SERVER_URL=http://localhost:8080/mcp

LLM_MODEL=auto means the backend picks the first model returned by GET /v1/models.

Quick Start (Docker)

macOS:

chmod +x scripts/*.command
./scripts/start.command

Windows:

scripts\start.bat

Linux:

cp -n .env.example .env
mkdir -p docker/data/sqlite
docker compose up -d --build

App URL: http://localhost:8080

Stop:

• macOS: ./scripts/stop.command
• Windows: scripts\stop.bat
• Linux: docker compose down

Linux note: if LM Studio is running on your host machine (not in Docker), set LLM_BASE_URL in .env to a host-reachable address like http://172.17.0.1:1234 instead of host.docker.internal.

Local Dev (without app container)

1. Stop app container:

docker compose stop app

2. Run backend:

cd server
dotnet run

3. Run frontend:

cd client
npm install
npm start

Dev URLs:

• Frontend: http://localhost:5173
• Backend: http://localhost:5184

Current Features

• Inventory management (list/create/update/delete)
• Inventory transaction log
• Chat assistant with MCP tool calling
• Orders workflow:
  • create multi-item orders
  • append items to latest order across turns
  • view orders page with expandable order lines
• Browser STT/TTS voice interaction (no Whisper/Piper containers)

API Endpoints

• GET /api/health
• GET /api/config
• GET /api/items
• GET /api/items/{id}
• GET /api/items/validate-sku?sku=...
• POST /api/items
• PUT /api/items/{id}
• DELETE /api/items/{id}
• GET /api/transactions
• GET /api/orders
• GET /api/orders/latest
• GET /api/orders/{orderNumber}
• POST /api/orders
• POST /api/orders/latest/items
• POST /api/chat/complete
• GET /api/chat/system-prompt
• GET /api/chat/hello-prompt
• GET /api/chat/few-shot-prompts

MCP Tools

• inventory_list_items
• inventory_search_status
• inventory_add_transaction
• orders_get_latest
• orders_create
• orders_add_items_to_latest

Troubleshooting

The diagnostics page in the app can help troubleshoot issues with configuration and running services.

• Verify LM Studio is reachable: http://localhost:1234/v1/models
• If chat works but tool calling fails, verify backend MCP URL config:
  • MCP_SERVER_URL=http://localhost:8080/mcp
• If no seed data appears, check DB volume at docker/data/sqlite

Minimal AI Setup Notes

• Confirm tools are installed: docker, docker compose, dotnet, node, npm.
• Ensure .env exists (cp -n .env.example .env).
• For Linux + Docker + host LM Studio, verify LLM_BASE_URL is reachable from containers.
• Use diagnostics page at http://localhost:8080/diagnostics for quick health checks.

First Files to Customize

• SYSTEM_PROMPT.md
• STARTUP_PROMPT.md
• FEW_SHOT_PROMPTS.json
• db/002_seed.sql
• server/appsettings.json
• client/src/styles.css

Branch Localization Workflow

• main is the English baseline (en-US).
• es-MX keeps Spanish locale defaults and prompts.
• To sync feature changes from main into es-MX while preserving Spanish locale files:

git switch es-MX
./scripts/merge-main-into-es-mx.sh
git push