# Lotus MCP

Create browser automation skills by demonstration. Works with **Cursor** and **Claude Code**.

## What is Lotus?

Lotus lets you create reusable browser automations ("skills") just by showing what you want to do. Demonstrate a workflow in a browser, narrate what you're doing, and Lotus converts it into an executable skill you can run anytime.

---

## Prerequisites

**macOS:**
```bash
brew install sox
```

**Linux:**
```bash
sudo apt-get install sox libsox-fmt-all
```

**Windows:**
Download and install SoX from https://sox.sourceforge.net/

---

## Cursor Setup

### 1. Install

```bash
# Install the MCP
npm install -g github:chrisvin-jabamani/lotus-mcp --ignore-scripts

# Install the Cursor extension
curl -L -o /tmp/lotus.vsix https://github.com/chrisvin-jabamani/lotus-mcp/raw/main/extension/lotus-0.1.0.vsix
cursor --install-extension /tmp/lotus.vsix
```

### 2. Configure

Create a file at `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "lotus": {
      "command": "lotus-mcp-cursor",
      "env": {
        "LOTUS_API_KEY": "your-api-key",
        "LOTUS_URL": "https://www.uselotus.ai"
      }
    }
  }
}
```

**Quick setup (copy-paste into terminal):**
```bash
mkdir -p ~/.cursor
cat > ~/.cursor/mcp.json << 'EOF'
{
  "mcpServers": {
    "lotus": {
      "command": "lotus-mcp-cursor",
      "env": {
        "LOTUS_API_KEY": "your-api-key",
        "LOTUS_URL": "https://www.uselotus.ai"
      }
    }
  }
}
EOF
```

Get your API key at [uselotus.ai](https://www.uselotus.ai)

### 3. Restart Cursor

Quit and reopen Cursor. Look for the green dot next to "lotus" in Cursor Settings → MCP.

### 4. Create your first skill

Ask Claude:
> "Create a skill to check court availability on Rec.us"

The browser opens **inside Cursor**. Demonstrate the workflow, then say "I'm done."

---

## Claude Code Setup

### 1. Install

```bash
npm install -g github:chrisvin-jabamani/lotus-mcp --ignore-scripts
```

### 2. Configure

```bash
claude mcp add lotus -- lotus-mcp-cli
```

Set environment variables when prompted:
- `LOTUS_API_KEY` — Get yours at [uselotus.ai](https://www.uselotus.ai)
- `LOTUS_URL` — `https://www.uselotus.ai`

### 3. Create your first skill

Ask Claude:
> "Create a skill to check court availability on Rec.us"

The browser opens in Chrome/Safari. Demonstrate the workflow, then say "I'm done."

---

## How It Works

```
"Create a skill to book a tennis court"
              ↓
    Browser opens automatically
              ↓
    You demonstrate the workflow
    (narrate what you're doing)
              ↓
         "I'm done"
              ↓
    ✅ Skill created and ready to use
```

---

## Tools

| Tool | Description |
|------|-------------|
| `lotus_start_recording` | Start recording a workflow |
| `lotus_stop_recording` | Stop and analyze |
| `lotus_refine_skill` | Convert to executable skill |
| `lotus_refine_status` | Check progress |
| `lotus_refine_answer` | Answer AI questions |
| `lotus_cancel_session` | Cancel current session |

---

## Troubleshooting

**Installation fails with ENOENT error?**
- Make sure to use `--ignore-scripts` flag: `npm install -g github:chrisvin-jabamani/lotus-mcp --ignore-scripts`

**"spawn sox ENOENT" or audio errors?**
- Install SoX: `brew install sox` (macOS) or `apt-get install sox` (Linux)

**Browser doesn't open in Cursor?**
- Check extension installed: `Cmd+Shift+P` → "Lotus: Open Browser"
- Look for "Lotus" in the status bar (bottom right)
- Run command manually if needed

**"Failed to connect to Lotus" or "API returned HTML"?**
- Verify your API key is correct at [uselotus.ai](https://www.uselotus.ai)
- Check `LOTUS_URL` is exactly `https://www.uselotus.ai`
- Check MCP server logs: In Cursor, go to Output panel → select "Lotus" from dropdown

**MCP not loading in Cursor?**
- Verify `~/.cursor/mcp.json` exists and has valid JSON
- Check for green dot in Cursor Settings → MCP
- Try restarting Cursor completely

---

## License

MIT