<div align="center">

# 🦁 LeoPulse Studio MCP

**Next-Generation High-Throughput Desktop Load Testing & Real-User Traffic Simulation Platform powered by the Model Context Protocol (MCP)**

[![Electron](https://img.shields.io/badge/Electron-33.0.0-47848F?style=for-the-badge&logo=electron&logoColor=white)](https://www.electronjs.org/)
[![React](https://img.shields.io/badge/React-18.3.0-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6.0-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Vite](https://img.shields.io/badge/Vite-5.4.0-646CFF?style=for-the-badge&logo=vite&logoColor=white)](https://vitejs.dev/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3.4.14-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white)](https://tailwindcss.com/)
[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.32.1-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

<p align="center">
  An open-source, high-performance desktop platform engineered for software architects, DevOps engineers, and autonomous AI agents to simulate massive real-user web traffic, evaluate server breaking points, and conduct executive capacity audits.
</p>

[Architecture](#-system-architecture) • [Key Features](#-comprehensive-feature-deep-dive) • [Model Context Protocol](#-model-context-protocol-mcp--alexa-integration) • [Quick Start](#-quick-start--cli-reference) • [Safety Notice](#-ethical-use--safety-disclaimer)

</div>

---

## 🏛️ System Architecture

LeoPulse Studio enforces an isolated multi-process architecture that decouples user interface rendering from high-concurrency network operations. Real load generation executes inside a dedicated Node.js Worker Thread utilizing `undici.Pool` with zero-storage stream draining to count and discard payload bytes at wire speed without memory bloat.

In parallel, an official **Model Context Protocol (MCP)** server runs over standard I/O (stdio) to allow **Amazon Alexa+** skills, Claude Desktop, and autonomous AI agents to orchestrate load testing workflows hands-free.

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              RENDERER PROCESS (Chromium)                               │
│       React 18  •  TypeScript  •  Tailwind CSS Bento Grid  •  Dual-Axis Recharts       │
│                                                                                        │
│   ┌───────────────────────────┐   ┌──────────────────────────┐   ┌─────────────────┐   │
│   │   New Campaign Setup      │   │   Live Dashboard & Logs  │   │ Executive Audit │   │
│   │   (Raycast Hero + Preset) │   │   (80px Telemetry Strip) │   │ (EN / AR BiDi)  │   │
│   └─────────────┬─────────────┘   └────────────┬─────────────┘   └────────┬────────┘   │
│                 │                              │                          │            │
│                 └──────────────────────────────┼──────────────────────────┘            │
│                                                │                                       │
│                               ┌────────────────▼────────────────┐                      │
│                               │  Floating Alexa+ Copilot Drawer │                      │
│                               │  (Ctrl+K Slide-Over / MCP Card) │                      │
│                               └────────────────┬────────────────┘                      │
└────────────────────────────────────────────────┼───────────────────────────────────────┘
                                                 │
                                   typed IPC via contextBridge
                            (src/main/preload.ts: secure bridge)
                                                 │
┌────────────────────────────────────────────────▼───────────────────────────────────────┐
│                                MAIN PROCESS (Node.js)                                  │
│         BrowserWindow Manager  •  Zero-Bloat Window Framing  •  Worker Thread Host     │
└───────────────────────┬────────────────────────────────────────┬───────────────────────┘
                        │ parentPort.postMessage()               │ child_process / stdio
                        │                                        │
┌───────────────────────▼────────────────────────┐ ┌─────────────▼───────────────────────┐
│         ENGINE WORKER THREAD (Node.js)         │ │   MODEL CONTEXT PROTOCOL (MCP)      │
│      (src/main/engine/engine.worker.ts)        │ │        (src/mcp/server.ts)          │
│                                                │ │                                     │
│  ┌──────────────────┐   ┌───────────────────┐  │ │  Official @modelcontextprotocol/sdk │
│  │ Undici Pool &    │   │ Multi-Tier Smart  │  │ │  StdioServerTransport (JSON-RPC)    │
│  │ ProxyAgent       │◄─►│ Circuit Breaker   │  │ │                                     │
│  └────────┬─────────┘   └─────────┬─────────┘  │ │  [start_load_test]                  │
│           │                       │            │ │  [get_live_telemetry]               │
│           ▼                       ▼            │ │  [stop_load_test]                   │
│  ┌──────────────────┐   ┌───────────────────┐  │ │  [get_executive_audit]              │
│  │ Null-Sink Zero-  │   │ Reservoir Sampler │  │ │                                     │
│  │ Stream Draining  │   │ P50/P95/P99 Tails │  │ │  ◄── Amazon Alexa+ & AI Agents      │
│  └──────────────────┘   └───────────────────┘  │ └─────────────────────────────────────┘
└───────────────────────┬────────────────────────┘
                        │ HTTP/1.1 Egress (0ms Gap)
                        ▼
             Target Web Application / API Gateway
```

---

## ⚡ Comprehensive Feature Deep-Dive

### 1. 🚀 High-Throughput Multi-Path Engine
- **Closed-Loop Concurrency**: Virtual users continuously fire requests in tight zero-gap loops. As soon as a response finishes draining, the virtual user triggers the next request, driving target servers to authentic peak throughput.
- **Step-Up Ramp-Up Scheduling**: Incremental ramp-up mode introduces virtual users in controlled stages (e.g., +20 VUs every 10 seconds), pinpointing the exact inflection threshold where latency begins degrading.
- **Internal Link Crawler**: Discovers and distributes requests across up to 50 internal same-origin URLs to simulate realistic user browsing paths rather than flooding a single static endpoint.
- **2026 User-Agent Pool**: Dynamically rotates randomized, realistic desktop (70%) and mobile (30%) user-agent signatures.

### 2. 🧠 Zero-Storage Stream Draining (0 Byte Memory Bloat)
- Standard HTTP clients store response chunks in memory buffers, leading to memory exhaustion and Garbage Collector (GC) latency spikes when handling gigabytes of response data.
- LeoPulse Studio pipes all incoming HTTP response streams into custom Node.js `Writable` null sinks. Chunks increment cumulative byte counters and are immediately freed from RAM, preserving flat <80 MB host memory usage even across millions of completed requests.

### 3. 🛡️ Multi-Tier Smart Circuit Breaker
Automated real-time safety watchdog protecting infrastructure from cascading outages:
- **Tier 1 (Critical Origin Outage)**: Trips if connection refusal (`ECONNREFUSED`), origin downtime (Cloudflare `521`/`523`), or DNS/SSL failures exceed 80% over 5 seconds.
- **Tier 2 (Stress Collapse)**: Trips if 5xx server errors (`500`, `502`, `503`, `504`) or socket timeouts exceed 50% over 10 seconds. Records and logs the exact **Breaking Point Capacity** (in VUs and RPS).
- **Tier 3 (Rate-Limit / WAF)**: Detects Cloudflare, AWS WAF, or gateway throttling (`429`, `403` exceeding 60% over 10s) and ceases probing.
- **Safe Route Errors**: Client-side 404/400 errors are logged for diagnostic inspection but never trip the safety circuit breaker.

### 4. 🔌 Official Model Context Protocol (MCP) Server
- Self-hosted stdio server runtime implementing the open Model Context Protocol standard (`@modelcontextprotocol/sdk`).
- Exposes 4 fully-typed, Zod-validated tools for **Amazon Alexa+** skills and autonomous AI orchestrators:
  - `start_load_test`: Starts closed-loop or ramp-up load tests with target URL, concurrency, duration, and proxy parameters.
  - `get_live_telemetry`: Fetches real-time snapshots including RPS throughput, active VUs, P50/P95/P99 latencies, and data transfer.
  - `stop_load_test`: Gracefully halts active campaigns and destroys connection pools.
  - `get_executive_audit`: Queries capacity status verdicts, SLA compliance, and remediation guidance in English or Arabic.

### 5. ✨ Integrated Alexa+ Copilot Drawer
- Slide-over floating assistant drawer anchored to the bottom right (`Ctrl+K` or floating FAB trigger).
- Formulates and executes natural language commands (e.g., *"Run 50-VU Load Test on https://example.com for 60s"*, *"What is our live telemetry?"*, *"Generate executive audit"*).
- Visual MCP Tool Invocation Cards display tool names, structured JSON input parameters, and engine return payloads in real time.

### 6. 🌐 Enterprise Bento Hairline UI
- Modern developer tool standard inspired by Linear, Raycast, and Datadog.
- Strict 1px hairline borders (`border-zinc-200 dark:border-zinc-800`), refined corner radius (`rounded-md` / `rounded-lg`), and high-density numeric readouts with monospace tabular figures (`font-mono tabular-nums`).
- Fully verified **WCAG AAA** contrast across both Light Mode and Dark Mode.
- Native Electron framing: eliminated Windows legacy menu bar bloat (`autoHideMenuBar: true`, `Menu.setApplicationMenu(null)`).

### 7. 📊 Bilingual Executive Audits & Corporate PDF Export
- Generates publication-ready executive capacity audits evaluating throughput resilience against a 200ms SLA target.
- **Dual-Engine PDF Export**:
  - **English Mode**: High-resolution vector tables generated via `jspdf-autotable` with embedded Recharts telemetry graphs.
  - **Arabic Mode**: Authentic right-to-left (BiDi) typography powered by high-DPI canvas capturing (`html2canvas`) and native `Tajawal`/`Cairo` font ligatures, eliminating character disconnection or text reversal.
- Instant CSV export for downstream analysis in Grafana, Excel, or Datadog.

---

## 🔌 Model Context Protocol (MCP) & Alexa+ Integration

LeoPulse Studio turns local capacity testing into an autonomous service that any MCP-compatible AI agent or voice assistant can execute.

### 🛠️ Exposed MCP Tools

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `start_load_test` | `targetUrl` (string, req), `concurrency` (10-1000), `durationSec` (number), `mode` (`closed-loop` / `ramp-up`), `crawlInternal` (boolean), `proxy` (optional) | Programmatically launches a load test campaign with zero-storage stream draining and armed multi-tier circuit breaker. |
| `get_live_telemetry` | *None* | Fetches a real-time telemetry snapshot (current RPS throughput, active VUs, P50/P95/P99 latency, success rate, and data transfer). |
| `stop_load_test` | *None* | Gracefully terminates active load test campaigns and destroys underlying connection pools. |
| `get_executive_audit` | `language` (`en` / `ar`, default `en`) | Retrieves the executive capacity verdict (Resilient / Degraded / Critical), SLA compliance analysis, and actionable engineering recommendations in English or Arabic. |

### 🎙️ Alexa+ Voice Interaction Example
> **DevOps Engineer**: *"Alexa, tell LeoPulse Studio to run a closed-loop stress test on our checkout API with 200 virtual users."*  
> **Alexa+ (via MCP)**: *"Load test started against https://api.store.internal with 200 concurrent virtual users. Zero-storage stream draining and multi-tier circuit breakers are armed."*  
>  
> **DevOps Engineer**: *"Alexa, ask LeoPulse Studio for the executive capacity audit in Arabic."*  
> **Alexa+ (via MCP)**: *"النتيجة التنفيذية: الخادم مستقر وعالي المرونة بنسبة نجاح 99.4% وتأخير P95 يبلغ 42 مللي ثانية. معايير اتفاقية مستوى الخدمة مستوفاة بالكامل."*

---

## 🚀 Quick Start & CLI Reference

### 📋 Prerequisites
- **Node.js**: `v18.0.0` or higher (Node.js 20+ LTS recommended)
- **npm**: `v9.0.0` or higher
- **OS**: Windows 10/11, macOS 12+, or modern Linux distributions

### 📦 Installation
```bash
# Clone the repository
git clone https://github.com/leopulse-studio/leopulse-studio.git
cd leopulse-studio

# Install dependencies
npm install
```

### 💻 Running the Application

```bash
# 1. Run in development mode (with Vite HMR + Electron)
npm run dev

# 2. Run the headless Model Context Protocol (MCP) server for Alexa+ & AI Agents
npm run mcp

# 3. Type-check TypeScript codebase (0 compiler errors)
npm run typecheck

# 4. Compile production bundles (Main, Renderer, Preload, Engine Worker)
npm run build

# 5. Launch the compiled desktop application
npm start
```

---

## 📁 Project Directory Structure

```
leopulse-studio/
├── .gitignore                     # Git ignore rules for build artifacts & logs
├── LICENSE                        # MIT License terms
├── README.md                      # Comprehensive project documentation
├── DEVPOST_SUBMISSION.md          # Official Devpost submission deliverables
├── package.json                   # Dependencies, scripts, and build metadata
├── tsconfig.json                  # TypeScript config (Renderer & MCP)
├── tsconfig.main.json             # TypeScript config (Main process & Engine Worker)
├── vite.config.ts                 # Vite bundler configuration
├── tailwind.config.js             # Tailwind CSS tokens (Bento hairline styling)
├── postcss.config.js              # PostCSS configuration
├── build/                         # Production application icons (.ico, .png)
├── src/
│   ├── main/
│   │   ├── index.ts               # Electron Main process lifecycle & IPC bridges
│   │   ├── preload.ts             # Secure contextBridge API definition
│   │   └── engine/
│   │       ├── engine.worker.ts   # Core worker thread: Undici pool, stream draining
│   │       ├── circuitBreaker.ts  # Multi-tier automated circuit breaker logic
│   │       ├── metricsAggregator.ts# Rolling window RPS & reservoir quantile sampling
│   │       └── crawler.ts         # Internal link crawler for authentic multi-page load
│   ├── mcp/
│   │   └── server.ts              # Model Context Protocol (MCP) server for Alexa+ & AI Agents
│   ├── shared/
│   │   ├── types.ts               # Shared TypeScript interfaces (IPC, Metrics, Config)
│   │   ├── errorCatalog.ts        # Comprehensive HTTP & transport error definitions
│   │   ├── i18n.ts                # Bilingual translation dictionary (English & Arabic)
│   │   └── userAgents.ts          # Realistic 2026 desktop and mobile User-Agent pool
│   └── renderer/
│       ├── index.html             # HTML entry point with web fonts & theme bootstrap
│       ├── main.tsx               # React DOM bootstrap
│       ├── App.tsx                # App routing & provider wrapping
│       ├── hooks/
│       │   ├── useTheme.ts        # Dark / Light theme manager with localStorage sync
│       │   ├── useI18n.ts         # Active language and BiDi direction manager
│       │   └── useEngineMetrics.ts# Real-time IPC telemetry subscriber hook
│       ├── components/
│       │   ├── copilot/
│       │   │   └── FloatingCopilotDrawer.tsx # Floating Alexa+ Copilot (MCP) slide-over
│       │   ├── layout/            # Sidebar, Header, and AppLayout shell
│       │   ├── error/             # ErrorHoverCard interactive tooltips
│       │   └── ui/                # Tailwind merge and utility primitives
│       └── pages/
│           ├── NewCampaign.tsx    # Raycast hero bar, 65% config grid, 35% receipt sheet
│           ├── LiveDashboard.tsx  # 80px metric strip, dual Y-axis chart, log workstation
│           ├── Reports.tsx        # Executive audit reports and PDF export engine
│           └── LegalDisclaimer.tsx# Authorized use notice & compliance terms
```

---

## 🔒 Security & Isolation Standard

LeoPulse Studio is built upon strict security constraints:

| Security Property | Value | Rationale |
|:---|:---|:---|
| `contextIsolation` | `true` | Prevents renderer scripts from accessing Electron/Node internals. |
| `nodeIntegration` | `false` | Disables Node.js runtime primitives inside the Chromium DOM window. |
| `sandbox` | `false` | Permits typed `preload.ts` context bridge without permission restrictions. |
| `webSecurity` | `true` | Enforces standard browser security policies and origin isolation. |
| Navigation Guard | `Denied` | Intercepts `window.open` and routes external links to system browser. |
| Zero Telemetry | `100% Local` | Operates completely offline with zero data collection or tracking. |

---

## ⚖️ Ethical Use & Safety Disclaimer

> [!IMPORTANT]
> **LeoPulse Studio is intended exclusively for authorized capacity planning, performance benchmarking, and reliability testing on servers, applications, and networks that you own, operate, or have explicit written authorization to test.**

- **Strictly Authorized Testing**: Running load tests, denial of service (DoS/DDoS) tests, or stressing third-party infrastructures without explicit consent is illegal under international cybercrime legislation, including the **Computer Fraud and Abuse Act (CFAA)** in the United States, the **Computer Misuse Act** in the United Kingdom, the **EU NIS2 Directive**, and equivalent global statutes.
- **Automatic Watchdog Protection**: The load engine includes a hardware-level and network-level multi-tier circuit breaker designed to halt traffic immediately if origin instability or rate-limiting thresholds are reached.
- **Privacy Assurance**: LeoPulse Studio does not collect, record, or transmit test targets, credentials, or benchmarking telemetry to any external service. All computations and connection pools execute locally on your device.

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

Copyright (c) 2026 **LeoPulse Studio Contributors**.