kickload-watcher-mcp 0.1.0

package/README.md

@@ -0,0 +1,233 @@
+# 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

package/compliance-poller.js

@@ -0,0 +1,215 @@
+// compliance-poller.js — Polls Anthropic Compliance API for new Claude Code sessions
+// Enterprise plan required. Enable at:
+// platform.claude.com → Organization Settings → Data and Privacy → Compliance API
+
+import { config } from "./config.js";
+
+let lastEventTimestamp = null;
+let pollingInterval = null;
+const sessionCallbacks = [];
+
+/**
+ * Register a callback to be called when a new API-related session is detected.
+ * Callback receives: { userId, sessionId, generatedCode, prompt, timestamp }
+ */
+export function onNewSession(callback) {
+  sessionCallbacks.push(callback);
+}
+
+/**
+ * Start polling the Compliance API on the configured interval.
+ */
+export function startCompliancePoller() {
+  if (!config.anthropic.complianceApiKey) {
+    console.warn("⚠️  ANTHROPIC_COMPLIANCE_API_KEY not set.");
+    console.warn("   Compliance API polling disabled.");
+    console.warn("   File watcher will be the only trigger.");
+    return;
+  }
+
+  console.log(
+    `🔍 Compliance API poller started (every ${config.anthropic.pollIntervalMs / 1000}s)`
+  );
+
+  // Set initial timestamp to now so we only pick up new events
+  lastEventTimestamp = new Date().toISOString();
+
+  pollingInterval = setInterval(async () => {
+    try {
+      await pollComplianceEvents();
+    } catch (err) {
+      console.error("❌ Compliance API poll failed:", err.message);
+    }
+  }, config.anthropic.pollIntervalMs);
+
+  // Run immediately on start
+  pollComplianceEvents().catch((err) =>
+    console.error("❌ Initial compliance poll failed:", err.message)
+  );
+}
+
+/**
+ * Stop the compliance poller.
+ */
+export function stopCompliancePoller() {
+  if (pollingInterval) {
+    clearInterval(pollingInterval);
+    pollingInterval = null;
+    console.log("⏹  Compliance API poller stopped.");
+  }
+}
+
+/**
+ * Fetch recent events from the Compliance API and filter for API-related code.
+ */
+async function pollComplianceEvents() {
+  const url = new URL(`${config.anthropic.complianceBaseUrl}/organizations/audit-log`);
+
+  if (lastEventTimestamp) {
+    url.searchParams.set("after", lastEventTimestamp);
+  }
+
+  url.searchParams.set("limit", "50");
+
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers: {
+      "anthropic-organization-key": config.anthropic.complianceApiKey,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Compliance API ${response.status}: ${body}`);
+  }
+
+  const data = await response.json();
+  const events = data.events || data.data || [];
+
+  if (events.length === 0) return;
+
+  // Update timestamp to latest event so we don't re-process
+  const latest = events[events.length - 1];
+  if (latest.created_at) {
+    lastEventTimestamp = latest.created_at;
+  }
+
+  // Filter events that contain API-related code
+  for (const event of events) {
+    const session = extractApiSession(event);
+    if (session) {
+      console.log(`📡 New API session detected from user: ${session.userId}`);
+      for (const cb of sessionCallbacks) {
+        try {
+          await cb(session);
+        } catch (err) {
+          console.error("❌ Session callback error:", err.message);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Extract relevant session data from a compliance event.
+ * Returns null if the event doesn't contain API-related code.
+ */
+function extractApiSession(event) {
+  try {
+    // Compliance API event structure
+    const userId =
+      event.actor?.id ||
+      event.user_id ||
+      event.actor?.user_id ||
+      null;
+
+    const sessionId = event.id || event.session_id || null;
+    const timestamp = event.created_at || new Date().toISOString();
+
+    // Get message content — structure varies by event type
+    const messages =
+      event.payload?.messages ||
+      event.messages ||
+      event.content?.messages ||
+      [];
+
+    // Look through messages for generated code with API endpoints
+    let generatedCode = null;
+    let userPrompt = null;
+
+    for (const msg of messages) {
+      // Capture the user's original prompt
+      if (msg.role === "user" && typeof msg.content === "string") {
+        userPrompt = msg.content;
+      }
+
+      // Look for assistant response containing API code
+      if (msg.role === "assistant") {
+        const content =
+          typeof msg.content === "string"
+            ? msg.content
+            : Array.isArray(msg.content)
+            ? msg.content.map((b) => b.text || "").join("\n")
+            : "";
+
+        // Detect if this looks like API endpoint code
+        if (containsApiCode(content)) {
+          generatedCode = content;
+        }
+      }
+    }
+
+    // Only return if we found actual API code
+    if (!generatedCode || !userId) return null;
+
+    return {
+      userId,
+      sessionId,
+      generatedCode,
+      prompt: userPrompt || "No prompt captured",
+      timestamp,
+      source: "compliance_api",
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Detect if code content contains API endpoint definitions.
+ * Covers Express, Flask, FastAPI, Django, Spring, Go, Rails patterns.
+ */
+function containsApiCode(content) {
+  const apiPatterns = [
+    // JavaScript/Node.js (Express, Fastify, Hapi)
+    /app\.(get|post|put|patch|delete|use)\s*\(\s*['"`]/i,
+    /router\.(get|post|put|patch|delete)\s*\(\s*['"`]/i,
+    /fastify\.(get|post|put|patch|delete)\s*\(\s*['"`]/i,
+
+    // Python (Flask, FastAPI, Django)
+    /@app\.route\s*\(\s*['"`]/i,
+    /@router\.(get|post|put|patch|delete)\s*\(\s*['"`]/i,
+    /path\s*\(\s*['"`][^'"]+['"`]\s*,/i,
+    /@app\.(get|post|put|patch|delete)\s*\(\s*['"`]/i,
+
+    // Go (net/http, gin, echo)
+    /http\.HandleFunc\s*\(\s*['"`]/i,
+    /r\.(GET|POST|PUT|PATCH|DELETE)\s*\(\s*['"`]/i,
+    /e\.(GET|POST|PUT|PATCH|DELETE)\s*\(\s*['"`]/i,
+
+    // Java/Spring
+    /@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*['"`]/i,
+    /@RequestMapping\s*\(/i,
+
+    // Ruby on Rails
+    /resources\s+:/i,
+    /get\s+['"`][^'"]+['"`]\s*,\s*to:/i,
+
+    // General endpoint patterns
+    /\/api\//i,
+    /endpoint/i,
+  ];
+
+  return apiPatterns.some((pattern) => pattern.test(content));
+}

package/config.js

@@ -0,0 +1,103 @@
+import dotenv from "dotenv";
+dotenv.config();
+
+export const config = {
+  anthropic: {
+    apiKey:           process.env.ANTHROPIC_API_KEY            || "",
+    complianceApiKey: process.env.ANTHROPIC_COMPLIANCE_API_KEY || "",
+    complianceBaseUrl:"https://api.anthropic.com/v1",
+    pollIntervalMs:   parseInt(process.env.POLL_INTERVAL_MS    || "60000"),
+    model:            "claude-sonnet-4-20250514",
+  },
+
+  kickload: {
+    apiToken:         process.env.KICKLOAD_API_TOKEN || "",
+    baseUrl:          process.env.KICKLOAD_BASE_URL  || "https://kickload.neeyatai.com/api",
+    defaultThreads:   parseInt(process.env.DEFAULT_THREADS || "5"),
+    defaultLoopCount: parseInt(process.env.DEFAULT_LOOPS   || "2"),
+    defaultRampTime:  parseInt(process.env.DEFAULT_RAMP    || "2"),
+  },
+
+  targetApiBaseUrl: process.env.TARGET_API_BASE_URL || null,
+
+  // ngrok.enabled is now advisory only — pipeline auto-enables for localhost
+  ngrok: {
+    enabled:   process.env.NGROK_ENABLED !== "false", // default true
+    authToken: process.env.NGROK_AUTHTOKEN || "",
+    binDir:    ".bin",
+  },
+
+  email: {
+    provider: process.env.EMAIL_PROVIDER || "smtp",
+    smtp: {
+      host: process.env.SMTP_HOST || "smtp.gmail.com",
+      port: parseInt(process.env.SMTP_PORT || "465"),
+      user: process.env.SMTP_USER || "",
+      pass: process.env.SMTP_PASS || "",
+    },
+    sendgrid: { apiKey: process.env.SENDGRID_API_KEY || "" },
+    ses: {
+      accessKey: process.env.AWS_ACCESS_KEY_ID     || "",
+      secretKey: process.env.AWS_SECRET_ACCESS_KEY || "",
+      region:    process.env.AWS_REGION            || "us-east-1",
+    },
+    fromName:    process.env.EMAIL_FROM_NAME    || "KickLoad Watcher",
+    fromAddress: process.env.EMAIL_FROM_ADDRESS || "",
+  },
+
+  watcher: {
+    watchPaths: (process.env.WATCH_PATHS || ".").split(",").map(p => p.trim()),
+    extensions: [".js", ".ts", ".py", ".go", ".java", ".rb", ".php", ".cs", ".rs"],
+    ignore:     ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**"],
+  },
+
+  identity: {
+    mapFile:         process.env.IDENTITY_MAP            || "./users.json",
+    defaultUserId:   process.env.DEFAULT_USER_ID         || null,
+    defaultDevEmail: process.env.DEFAULT_DEVELOPER_EMAIL || null,
+  },
+
+  triggerMode: process.env.TRIGGER_MODE || "claudecode",
+
+  github: {
+    token:         process.env.GITHUB_TOKEN          || "",
+    webhookPort:   parseInt(process.env.GITHUB_WEBHOOK_PORT || "3456"),
+    webhookSecret: process.env.GITHUB_WEBHOOK_SECRET || "",
+  },
+
+  logLevel: process.env.LOG_LEVEL || "info",
+};
+
+export function validateConfig() {
+  const errors   = [];
+  const warnings = [];
+
+  if (!config.anthropic.apiKey)  errors.push("ANTHROPIC_API_KEY is required");
+  if (!config.kickload.apiToken) errors.push("KICKLOAD_API_TOKEN is required");
+  if (!config.email.fromAddress) errors.push("EMAIL_FROM_ADDRESS is required");
+
+  if (config.email.provider === "smtp") {
+    if (!config.email.smtp.user) errors.push("SMTP_USER is required for smtp provider");
+    if (!config.email.smtp.pass) errors.push("SMTP_PASS is required for smtp provider");
+  }
+
+  if (config.email.provider === "sendgrid" && !config.email.sendgrid.apiKey) {
+    errors.push("SENDGRID_API_KEY is required when EMAIL_PROVIDER=sendgrid");
+  }
+
+  // ngrok token is a warning, not a hard error — auto-mode handles it gracefully
+  if (!config.ngrok.authToken) {
+    warnings.push("NGROK_AUTHTOKEN not set — ngrok tunnel will not authenticate (localhost backends cannot be tested)");
+  }
+
+  if (warnings.length) {
+    warnings.forEach(w => console.warn(`  ⚠️  ${w}`));
+  }
+
+  if (errors.length) {
+    console.error("\n❌ Missing required configuration:");
+    errors.forEach(e => console.error(`   • ${e}`));
+    console.error("\n   Fix: delete .env and re-run to go through setup again, or edit .env manually.\n");
+    process.exit(1);
+  }
+}

package/email-cooldown.js

@@ -0,0 +1,23 @@
+const COOLDOWN_MS = 60_000;
+const lastSent    = new Map();
+
+export function isEmailAllowed(toEmail, identifier) {
+  const key  = `${toEmail}:${identifier}`;
+  const last = lastSent.get(key);
+  return !last || Date.now() - last >= COOLDOWN_MS;
+}
+
+export function getCooldownRemaining(toEmail, identifier) {
+  const last = lastSent.get(`${toEmail}:${identifier}`);
+  if (!last) return 0;
+  const rem = COOLDOWN_MS - (Date.now() - last);
+  return rem > 0 ? Math.ceil(rem / 1000) : 0;
+}
+
+export function recordEmailSent(toEmail, identifier) {
+  const key = `${toEmail}:${identifier}`;
+  lastSent.set(key, Date.now());
+  for (const [k, ts] of lastSent.entries()) {
+    if (Date.now() - ts > COOLDOWN_MS * 2) lastSent.delete(k);
+  }
+}