Skip to main content

🥃 MK LIQUOR - AI-Powered Inventory Dashboard

A local AI backend system for your liquor store that connects to Korona Cloud POS. Stop clicking through endless back-office pages - just ask questions about your inventory!


🎯 What This Does

Like what you saw in Chad's video, this system lets you:

  • Search inventory instantly - Type "Hennessy" and see all stock in seconds
  • Ask natural questions - "How much Patron do I have?" via your local LLM
  • One-page dashboard - See everything without clicking through Korona's back-office
  • AI-powered insights - Connect to LM Studio, Ollama, or any local LLM

📦 What's Included

mk-liquor-dashboard/
├── korona_mcp_server.py    # MCP server for local LLM integration
├── dashboard.html          # Web dashboard for quick lookups
├── requirements.txt        # Python dependencies
├── mcp_config.json         # Configuration for LM Studio/Claude Desktop
├── .env.example            # Environment variable template
└── README.md               # This guide

🚀 Quick Start

# Install from source
pip install -e .

# Run the MCP server (connects to LM Studio, Claude Desktop, etc.)
mk-liquor-server

# Serve the dashboard locally
mk-liquor-serve --port 8080
# Then open http://127.0.0.1:8080/dashboard.html

For MCP client config, use:

{
  "mcpServers": {
    "mk-liquor": {
      "command": "mk-liquor-server",
      "env": {
        "KORONA_HOST": "your-account.koronacloud.com",
        "KORONA_ACCOUNT_ID": "your-account-id",
        "KORONA_USERNAME": "your-username",
        "KORONA_PASSWORD": "your-password"
      }
    }
  }
}

Option 1: Web Dashboard (Easiest)

Just open dashboard.html in your browser!

  1. Open dashboard.html in Chrome/Firefox/Edge
  2. Enter your Korona Cloud credentials:
    • Host: your-store.koronacloud.com
    • Account ID: Found in Korona Settings → Data Exchange → API
    • Username/Password: Create API credentials in Korona
  3. Start searching!

Note: Due to browser security (CORS), you may need to run a local server. See "Running Locally" below.


Option 2: MCP Server + Local LLM (Full Power)

This gives you the full AI experience - ask questions in natural language!

Step 1: Install Python & Dependencies

# Make sure you have Python 3.10+
python --version

# Install dependencies
pip install -r requirements.txt

Step 2: Get Your Korona API Credentials

  1. Log into Korona Studio (koronacloud.com)
  2. Go to Settings → Data Exchange → API
  3. Find your Account ID (shown at the top)
  4. Click "Add" to create API credentials
  5. Set permissions (at minimum: Read Products, Read Inventory)
  6. Save the username and password

Step 3: Configure Environment

Create a .env file:

cp .env.example .env

Edit .env with your credentials:

KORONA_HOST=mk-liquor.koronacloud.com
KORONA_ACCOUNT_ID=abc123-def456-ghi789
KORONA_USERNAME=api_user
KORONA_PASSWORD=your_password

Step 4: Test the MCP Server

python korona_mcp_server.py

If it starts without errors, you're good!


🤖 Connecting to Your Local LLM

LM Studio

  1. Install LM Studio
  2. Download a model (recommend: Llama 3.1 8B, Qwen 2.5, or Mistral)
  3. Edit ~/.config/lmstudio/mcp.json (or use LM Studio's MCP settings):
{
  "mcpServers": {
    "mk-liquor": {
      "command": "python",
      "args": ["/path/to/mk-liquor-dashboard/korona_mcp_server.py"],
      "env": {
        "KORONA_HOST": "mk-liquor.koronacloud.com",
        "KORONA_ACCOUNT_ID": "your-account-id",
        "KORONA_USERNAME": "your-username",
        "KORONA_PASSWORD": "your-password"
      }
    }
  }
}
  1. Restart LM Studio and enable the MCP server
  2. Now ask: "What's my stock on Hennessy VS?"

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "mk-liquor": {
      "command": "python",
      "args": ["/path/to/korona_mcp_server.py"],
      "env": {
        "KORONA_HOST": "...",
        "KORONA_ACCOUNT_ID": "...",
        "KORONA_USERNAME": "...",
        "KORONA_PASSWORD": "..."
      }
    }
  }
}

Ollama + MCP-Use

# Install MCP-Use
pip install mcp-use langchain

# Use with Ollama
python -c "
from mcp_use import MCPAgent
agent = MCPAgent(model='ollama/llama3.1:8b')
agent.connect_server('python korona_mcp_server.py')
print(agent.chat('How much Hennessy do I have?'))
"

💬 Example Questions to Ask

Once connected, try these:

Question What It Does
"How much Hennessy VS do I have?" Quick stock check
"Search for Patron" Find all Patron products
"What are today's top sellers?" Sales ranking
"Show me low stock items" Reorder alerts
"What did we sell today?" Daily sales summary
"List all suppliers" Vendor information
"How many Corona cases?" Specific product lookup

🛠️ Running the Dashboard Locally

If the dashboard has CORS issues, run a local server:

# Python 3
cd mk-liquor-dashboard
python -m http.server 8000

Then open: http://localhost:8000/dashboard.html


🔧 Available MCP Tools

The MCP server provides these tools to your LLM:

Tool Description
search_products Search by product name
lookup_barcode Find product by UPC/barcode
get_stock_status Check inventory levels
quick_stock_check Fast name → stock lookup
list_stores Show all locations
get_store_inventory Full inventory for a store
get_todays_sales Today's transactions
get_sales_report Revenue for date range
get_top_sellers Best selling products
list_categories Product groups
list_suppliers All distributors
list_employees Cashiers/staff

🔒 Security Notes

  • Never commit your .env file - it contains passwords!
  • API credentials should have minimal permissions
  • For production, consider using environment variables instead of config files
  • The dashboard stores credentials in browser localStorage

🐛 Troubleshooting

"Connection Error"

  • Check your Korona host URL (no https:// prefix needed)
  • Verify Account ID is correct
  • Test credentials by logging into koronacloud.com

"API Error 401"

  • Wrong username/password
  • API credentials may have expired
  • Check permissions on the API user

"API Error 403"

  • Your API user lacks required permissions
  • Add read access for Products, Inventory, Receipts

Dashboard shows "CORS Error"

  • Run a local server (see "Running Locally" above)
  • Or use a CORS browser extension (for testing only)

📚 Resources


🤝 Credits

Inspired by Chad the POS Guy and built for small business liquor store owners who are tired of clicking through endless back-office pages!

Built with ❤️ for MK LIQUOR


📝 License

MIT License - Use freely, modify as needed!

Metadata

Release files for mk-liquor 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mk-liquor 0.1.0
File Size Uploaded Provenance Actions
mk_liquor-0.1.0.tar.gz 20.1 kB Without provenance Details for mk_liquor-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mk-liquor 0.1.0
File Interpreter ABI Platform Actions
mk_liquor-0.1.0-py3-none-any.whl Python 3 none any Details for mk_liquor-0.1.0-py3-none-any.whl

Total release size: 37.4 kB

Release files / mk_liquor-0.1.0.tar.gz

Download URL mk_liquor-0.1.0.tar.gz
Size 20.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7b885995f4bf5b310d9a690a6b8b29d4e28b2be1a9d9d6143a5913a051bcb085
BLAKE2b-256 checksum
How to use checksums
121248508ebc13ce92338ef6a4fbfd4c9ae87423f92daea998c37c051f5c0e34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.2

Release files / mk_liquor-0.1.0-py3-none-any.whl

Download URL mk_liquor-0.1.0-py3-none-any.whl
Size 17.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88ff81a6d93b1ccad3beb67f745ef35a07cd4285e5ee706efa2467d700f7b30b
BLAKE2b-256 checksum
How to use checksums
79dccc6ea8794b64d72322f291d31fc0bf182f921674e5c9e9325e8f4e519f8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.2

Security for mk-liquor 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page