mk-liquor 0.1.0

MCP server for Korona Cloud POS - AI-powered liquor store inventory

🥃 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

Option 0: Install via pip (Recommended)

# 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"
      }
    }
  }
}

4. Restart LM Studio and enable the MCP server
5. 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

• Korona POS Manual
• Korona API Documentation
• MCP Protocol
• LM Studio Docs

---

🤝 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!