kickload-watcher-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,233 +1,164 @@
-# KickLoad Watcher MCP
-
-Automated API performance testing for Claude Enterprise teams.
-
-When a developer writes an API using Claude Code, this watcher **automatically**:
-1. Detects the new endpoint
-2. Generates smart load test parameters using Claude
-3. Runs the full test pipeline via KickLoad
-4. Emails the developer their results
-
-**No GitHub required. Works directly with Claude Code CLI.**
-
----
-
-## How It Works
-
-```
-Developer writes API with Claude Code
-        ↓
-Watcher detects new session (Compliance API) + saved file (file watcher)
-        ↓
-Claude generates optimal test parameters for the endpoint
-        ↓
-KickLoad runs: generate JMX → run test → analyze JTL → return PDF
-        ↓
-Developer receives email with PASS/FAIL + latency + error rate + PDF link
-```
-
----
-
-## Prerequisites
-
-| Requirement | Where to Get It |
-|---|---|
-| Claude Enterprise plan | Required for Compliance API |
-| KickLoad API token | kickload.neeyatai.com → API's → Generate API Key |
-| Anthropic API key | platform.claude.com → API Keys |
-| Node.js 18+ | nodejs.org |
-
----
-
-## Setup (3 Steps)
-
-### Step 1 — Install
-
-```bash
-git clone <this-repo>
-cd kickload-watcher-mcp
-npm install
-```
-
-### Step 2 — Configure
-
-```bash
-cp .env.example .env
-```
-
-Fill in your `.env`:
-
-```env
-ANTHROPIC_API_KEY=sk-ant-api03-...
-ANTHROPIC_COMPLIANCE_API_KEY=    # From Anthropic Console → Data and Privacy
-KICKLOAD_API_TOKEN=kl-...        # From kickload.neeyatai.com → API's
-EMAIL_PROVIDER=smtp
-SMTP_HOST=smtp.gmail.com
-SMTP_USER=your@gmail.com
-SMTP_PASS=your-app-password
-EMAIL_FROM_ADDRESS=your@gmail.com
-WATCH_PATHS=/home/user/projects
-```
-
-### Step 3 — Map Developers
-
-Edit `users.json` to map Claude user IDs to emails:
-
-```json
-{
-  "usr_abc123": "john@company.com",
-  "usr_xyz789": "jane@company.com"
-}
-```
-
-Find Claude user IDs in: **Anthropic Console → Members**
-
----
-
-## Add to Claude Code
-
-**Option A — Claude Desktop** (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "kickload-watcher": {
-      "command": "npx",
-      "args": ["-y", "@kickload/watcher-mcp"],
-      "env": {
-        "KICKLOAD_API_TOKEN": "your-token",
-        "ANTHROPIC_API_KEY": "your-key",
-        "EMAIL_PROVIDER": "smtp",
-        "SMTP_HOST": "smtp.gmail.com",
-        "SMTP_USER": "your@gmail.com",
-        "SMTP_PASS": "your-password",
-        "EMAIL_FROM_ADDRESS": "your@gmail.com",
-        "WATCH_PATHS": "/home/user/projects"
-      }
-    }
-  }
-}
-```
-
-**Option B — Claude Code CLI**:
-
-```bash
-claude mcp add kickload-watcher --type stdio --command "node /path/to/index.js"
-```
-
-**Option C — Run directly**:
-
-```bash
-node index.js
-```
-
----
-
-## Enable Compliance API (Enterprise Required)
-
-1. Go to **platform.claude.com**
-2. Organization Settings → Data and Privacy
-3. Enable Compliance API
-4. Create a key and add it to `.env` as `ANTHROPIC_COMPLIANCE_API_KEY`
-
-> Only Primary Owners can enable the Compliance API.
-
----
-
-## MCP Tools Available to Claude
-
-Once connected, Claude can call these tools directly:
-
-| Tool | What It Does |
-|---|---|
-| `run_kickload_test` | Manually trigger a test for any endpoint |
-| `get_test_status` | Check watcher status and configuration |
-| `lookup_developer` | Find email for a Claude user ID |
-| `send_test_email` | Verify email configuration |
-
-**Example — Claude can say:**
-> "Run a load test on /api/checkout and email results to dev@company.com"
-
----
-
-## Email Providers
-
-| Provider | Config |
-|---|---|
-| SMTP (Gmail) | `EMAIL_PROVIDER=smtp` + SMTP_* vars |
-| SendGrid | `EMAIL_PROVIDER=sendgrid` + `SENDGRID_API_KEY` |
-| AWS SES | `EMAIL_PROVIDER=ses` + AWS_* vars |
-
-**Gmail tip**: Use an App Password, not your account password.
-Generate at: Google Account → Security → 2-Step Verification → App passwords
-
----
-
-## Project Structure
-
-```
-kickload-watcher-mcp/
-├── index.js              ← MCP server + tool handlers
-├── orchestrator.js       ← Main pipeline coordinator
-├── compliance-poller.js  ← Anthropic Compliance API watcher
-├── file-watcher.js       ← Filesystem watcher for saved code
-├── test-generator.js     ← Claude API test parameter generator
-├── kickload-runner.js    ← KickLoad API integration (/cra-line)
-├── email-sender.js       ← Email delivery (SMTP/SendGrid/SES)
-├── identity-map.js       ← Claude user ID → email mapping
-├── config.js             ← All configuration
-├── users.json            ← Developer identity map (you fill this)
-├── .env.example          ← Environment variable template
-└── package.json
-```
-
----
-
-## What the Email Looks Like
-
-```
-Subject: [KickLoad Watcher] ✅ PASS — /api/checkout tested
-
-Hi John,
-
-Your API endpoint was automatically tested by KickLoad Watcher.
-
-STATUS:     ✅ PASS
-ENDPOINT:   /api/checkout
-TESTED AT:  2 Apr 2026, 14:32 IST
-
-RESULTS:
-  Average Latency:   123ms
-  Error Rate:        0.5%
-  Throughput:        4,500 req/s
-  Test Duration:     47s
-
-📄 Download Full Report → [link expires in 24hrs]
-
-— KickLoad Watcher | Automated by NeeyatAI
-```
-
----
-
-## Troubleshooting
-
-**No email received?**
-- Run `send_test_email` MCP tool to verify email config
-- Check `users.json` has the correct Claude user ID mapped
-- Gmail: ensure App Password is used, not account password
-
-**Compliance API not working?**
-- Verify Enterprise plan is active
-- Only Primary Owners can enable Compliance API
-- File watcher still works without it
-
-**Test not triggering?**
-- Check `WATCH_PATHS` includes your project directories
-- Ensure files have supported extensions (.js, .ts, .py, etc.)
-- Check console logs for "API code detected" messages
-
----
-
-## License
-
-MIT © NeeyatAI
+# KickLoad Watcher MCP
+
+Automated API performance testing for Claude Code workflows.
+
+This tool automatically detects API endpoints, runs load tests via KickLoad, and sends results via email.
+
+---
+
+## 🚀 Installation
+
+```bash
+npx kickload-watcher-mcp@beta
+```
+
+---
+
+## 🧠 First Run Setup
+
+On first run, you will be prompted to enter:
+
+* ANTHROPIC_API_KEY
+* KICKLOAD_API_TOKEN
+* Gmail address + App Password
+* NGROK_AUTHTOKEN
+
+These values are saved in a local `.env` file.
+
+---
+
+## 🔑 Required Services
+
+| Service            | Link                                      |
+| ------------------ | ----------------------------------------- |
+| Anthropic          | https://console.anthropic.com             |
+| KickLoad           | https://kickload.neeyatai.com             |
+| Gmail App Password | https://myaccount.google.com/apppasswords |
+| Ngrok              | https://dashboard.ngrok.com               |
+
+---
+
+## ⚙️ Example `.env`
+
+```env
+ANTHROPIC_API_KEY=your_key
+KICKLOAD_API_TOKEN=your_token
+
+EMAIL_PROVIDER=smtp
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=465
+SMTP_USER=your@gmail.com
+SMTP_PASS=your-app-password
+EMAIL_FROM_ADDRESS=your@gmail.com
+
+NGROK_AUTHTOKEN=your_ngrok_token
+
+WATCH_PATHS=.
+TRIGGER_MODE=claudecode
+LOG_LEVEL=info
+```
+
+---
+
+## 🔁 Workflow
+
+1. Save backend API file
+2. Watcher detects endpoints
+3. Ngrok exposes local server (if needed)
+4. Claude generates test parameters
+5. KickLoad runs performance test
+6. Results sent via email
+
+---
+
+## 📡 Features
+
+* Automatic API detection (Express, Flask, FastAPI, etc.)
+* Claude-powered test generation
+* Auto ngrok tunneling for localhost
+* Email reporting system
+* Smart batching + deduplication
+* Retry + error handling
+
+---
+
+## ⚠️ Important Notes
+
+* `.env` is required after setup
+* Use Gmail App Password (not normal password)
+* Ngrok token is required for localhost testing
+* Backend must be running
+
+---
+
+## 🧪 Troubleshooting
+
+### Setup runs twice
+
+Delete `.env` and run again.
+
+---
+
+### Missing config error
+
+Check `.env` contains:
+
+* ANTHROPIC_API_KEY
+* KICKLOAD_API_TOKEN
+* SMTP_USER
+* SMTP_PASS
+
+---
+
+### Ngrok not working
+
+Add:
+
+```env
+NGROK_AUTHTOKEN=your-token
+```
+
+---
+
+### Email not sending
+
+* Check Gmail App Password
+* Verify SMTP_USER and SMTP_PASS
+
+---
+
+## 📁 Project Structure
+
+```
+index.js              → entry point
+setup.js              → first-run setup
+pipeline.js           → core logic
+kickload-client.js    → API communication
+email-sender.js       → email system
+file-watcher.js       → file detection
+compliance-poller.js  → Claude session tracking
+ngrok-manager.js      → tunnel handling
+config.js             → configuration
+```
+
+---
+
+## 🏁 Run Locally
+
+```bash
+node index.js
+```
+
+---
+
+## 📦 NPM Usage
+
+```bash
+npx kickload-watcher-mcp@beta
+```
+
+---
+
+## 📜 License
+
+MIT © NeeyatAI