mk-liquor 0.1.0
MCP server for Korona Cloud POS - AI-powered liquor store inventory
License: MIT
Requires Python: >=3.10
Keywords: mcp, korona, pos, inventory, liquor, dashboard

# 🥃 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)

```bash
# 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:
```json
{
  "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

```bash
# 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:

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```env
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

```bash
python korona_mcp_server.py
```

If it starts without errors, you're good!

---

## 🤖 Connecting to Your Local LLM

### LM Studio

1. Install [LM Studio](https://lmstudio.ai)
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):

```json
{
  "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`):

```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

```bash
# 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:

```bash
# 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](https://manual.koronapos.com/)
- [Korona API Documentation](https://www.koronacloud.com/api)
- [MCP Protocol](https://github.com/modelcontextprotocol)
- [LM Studio Docs](https://lmstudio.ai/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!