# Ziggy MCP

A Model Context Protocol (MCP) server that connects Claude AI to Google Sheets for automated revenue tracking, lead management, and business operations.

## Features

- 📊 **Dashboard**: Real-time revenue metrics and KPIs
- 🎯 **Lead Pipeline**: Track prospects from first contact to close
- 📧 **Gmail Integration**: Search emails and automate outreach
- 📅 **Calendar Sync**: Track meetings and follow-ups
- 📝 **Knowledge Matrix**: Development log with timestamp tracking
- ✅ **Task Management**: Prioritize and track project tasks
- 📈 **Analytics**: Daily metrics and performance tracking

## Prerequisites

- **Node.js** 18.0.0 or higher
- **Google Account** with Sheets and Gmail access
- **Claude Desktop** or compatible MCP client
- **Google Apps Script** (for backend API)
- **Playwright** (for browser automation)

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/yourusername/ziggy-mcp.git
cd ziggy-mcp
```

### 2. Install Dependencies

```bash
npm run setup
# This installs Node packages AND Playwright browsers
```

**Manual alternative:**
```bash
npm install
npx playwright install chromium
```

### 3. Set Up Google Sheets Backend

1. Create a new [Google Sheet](https://sheets.google.com)
2. Go to **Extensions > Apps Script**
3. Delete any existing code
4. Copy all files from `/apps-script` directory:
   - `Code.js` - Sheet setup script
   - `API.js` - Main API handlers
   - `calendarSync.js` - Calendar integration
   - `appsscript.json` - Manifest
5. Click **Save** (disk icon)
6. Click **Run > setupRevenueEngine**
7. Authorize the script when prompted
8. Wait 30-60 seconds for completion
9. Deploy as web app:
   - Click **Deploy > New deployment**
   - Type: **Web app**
   - Execute as: **Me**
   - Who has access: **Anyone**
   - Click **Deploy**
   - Copy the **Web app URL**

### 4. Configure the MCP Server

Edit `index.js` and update the API URL:

```javascript
const API_URL = "YOUR_GOOGLE_APPS_SCRIPT_WEB_APP_URL";
```

### 5. Connect to Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "ziggy": {
      "command": "node",
      "args": ["/absolute/path/to/ziggy-mcp/index.js"]
    }
  }
}
```

Replace `/absolute/path/to/ziggy-mcp/` with your actual installation path.

### 6. Restart Claude Desktop

Quit and reopen Claude Desktop to load the MCP server.

---

## Browser Automation Setup

### Setting Up Authenticated Sessions

For Upwork, LinkedIn, and other platforms:

**Step 1: Open browser in visible mode**
```
Open Upwork in browser with visible mode
```

**Step 2: I'll open a browser window - YOU log in manually**

**Step 3: Save the session**
```
Save browser session as "upwork"
```

**Step 4: Test it**
```
Browse upwork.com using saved session
```

### Supported Platforms

- ✅ **Upwork** - Job search, proposal submission
- ✅ **LinkedIn** - Profile research, connection requests
- ✅ **Any website** - Custom scraping and automation

### Security Notes

- Sessions stored locally in `sessions/` folder
- **NEVER** commit session files to git
- Sessions contain your auth tokens
- Expire after ~30 days
- Re-authenticate when needed

---

## Usage

### Basic Commands

**Get Dashboard:**
```
Show me my revenue dashboard
```

**View Pipeline:**
```
What leads are in my pipeline?
```

**Add a Lead:**
```
Add a new lead: Acme Corp, contact John Smith, email john@acme.com
```

**Check Gmail:**
```
Search my unread emails
```

**Log Development Work:**
```
Log to knowledge matrix: Fixed authentication bug in Gmail integration [45m]
```

### Knowledge Matrix

The Knowledge Matrix is a structured development log that tracks:

- 🐛 **Bugs & Fixes** - Issues and resolutions
- ✨ **Features Added** - New functionality
- 🧪 **Testing Results** - Test outcomes
- 🎯 **Decisions & Direction** - Strategic choices
- 📚 **Documentation Updates** - Doc changes
- 🚀 **Next Session Goals** - Future work

**Write Entry:**
```
Write matrix entry for Bugs & Fixes: "3:45pm EST 🐛[BUG-001] Fixed Gmail auth timeout [30m]"
```

**Query Matrix:**
```
Search matrix for "authentication"
```

**Daily Summary:**
```
Generate matrix summary for today
```

### Browser Automation

**Take Screenshot:**
```
Take a screenshot of competitor-site.com
```

**Extract Data:**
```
Extract pricing from acme.com/pricing
```

**Fill Form:**
```
Fill the contact form at example.com with lead data for John Doe
```

**Research:**
```
Browse to linkedin.com/company/acme and extract company info
```

**Automated Outreach** (after session setup):
```
Search Upwork for "web automation" jobs and show top 5
```

---

## Project Structure

```
ziggy-mcp/
├── index.js                 # Main MCP server
├── package.json            # Node dependencies
├── browser/                # Browser automation
│   ├── playwright.js      # Core browser functions
│   ├── upwork.js          # Upwork automation
│   └── linkedin.js        # LinkedIn automation
├── apps-script/            # Google Apps Script files
│   ├── Code.js            # Sheet setup
│   ├── API.js             # API endpoints
│   ├── calendarSync.js    # Calendar integration
│   └── appsscript.json    # Manifest
├── sessions/               # Saved browser sessions (gitignored)
├── screenshots/            # Captured screenshots (gitignored)
├── docs/                   # Documentation
│   ├── MATRIX.md          # Knowledge Matrix guide
│   ├── BUG-TRACKING.md    # Bug tracking system
│   └── BROWSER-GUIDE.md   # Browser automation guide
└── README.md              # This file
```

## Security & Privacy

- All data stored in **your** Google Sheets
- API calls authenticated through Google Apps Script
- No external databases or third-party services
- File system access restricted to project directory
- Gmail read-only access (send requires explicit approval)

## Troubleshooting

### MCP Server Not Connecting

1. Check Claude Desktop config path is correct
2. Verify Node.js version: `node --version` (should be ≥18.0.0)
3. Check console: `Cmd+Shift+I` in Claude Desktop
4. Verify API_URL is set correctly in `index.js`

### Google Apps Script Issues

1. Ensure script is deployed as web app
2. Check execution permissions (should be "Anyone")
3. Re-authorize if needed: Run > setupRevenueEngine
4. Check Apps Script logs: View > Logs

### Gmail Integration

1. Ensure Gmail API is enabled in Apps Script
2. Check OAuth scopes in `appsscript.json`
3. Re-authorize if permissions changed

## Development

### Running Locally

```bash
node index.js
```

### Managing Apps Script

Install clasp for local Apps Script development:

```bash
npm install -g @google/clasp
clasp login
clasp pull  # Download from Google
clasp push  # Upload to Google
```

### Debugging

Enable debug logging in `index.js`:

```javascript
const DEBUG = true;
```

Logs written to `debug.log` in project directory.

## Roadmap

- [ ] Add Slack integration
- [ ] Export reports to PDF
- [ ] AI-powered lead scoring
- [ ] Automated follow-up reminders
- [ ] Invoice generation
- [ ] Team collaboration features

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## License

MIT License - see LICENSE file for details

## Support

- 📧 Email: support@example.com
- 💬 Issues: [GitHub Issues](https://github.com/yourusername/ziggy-mcp/issues)
- 📖 Docs: [Wiki](https://github.com/yourusername/ziggy-mcp/wiki)

## Acknowledgments

- Built with [Model Context Protocol](https://modelcontextprotocol.io)
- Powered by [Claude AI](https://claude.ai)
- Google Sheets integration via Apps Script

---

**Made with ❤️ for solopreneurs and small teams**