auto-feedback 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# Feedback
+
+An MCP server that gives Claude Code eyes and hands for GUI development. When Claude builds a web app, Electron app, or Windows desktop application, Feedback launches the app, captures screenshots, interacts with the UI (click buttons, fill forms, navigate), captures errors and logs, and runs multi-step QA workflows with assertions — so Claude can iterate until the GUI actually works.
+
+## Why
+
+Claude Code currently has no way to see the visual output of GUI code it writes. This leads to blind iteration cycles where the user must describe what's wrong. Feedback closes the loop: Claude writes code, launches the app, takes a screenshot, verifies the result, and fixes issues — all autonomously.
+
+## Install
+
+```bash
+npm install -g auto-feedback
+```
+
+Then install Playwright browsers (required for web/Electron automation):
+
+```bash
+npx playwright install chromium
+```
+
+## Configure with Claude Code
+
+Add to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "feedback": {
+      "command": "auto-feedback",
+      "args": []
+    }
+  }
+}
+```
+
+Or if installed locally in a project:
+
+```json
+{
+  "mcpServers": {
+    "feedback": {
+      "command": "npx",
+      "args": ["auto-feedback"]
+    }
+  }
+}
+```
+
+Restart Claude Code after adding the configuration. You should see Feedback's 23 tools available.
+
+## What It Does
+
+### Session Management
+
+Every interaction starts with creating a session. Sessions track all resources (processes, browsers, screenshots, logs) and clean up everything when ended.
+
+### Launch Apps
+
+- **Web dev servers** — Launch `npm start`, `vite`, `webpack`, `next dev`, etc. Automatically detects when the server is ready via stdout pattern matching and TCP port polling.
+- **Electron apps** — Launch and connect Playwright for full automation.
+- **Windows .exe files** — Launch native desktop apps and track their process.
+
+### Take Screenshots
+
+- **Web/Electron** — Playwright-based screenshots with full-page or viewport modes.
+- **Desktop apps** — Native window capture by PID.
+- **Auto-capture** — Automatically captures screenshots after page navigation events.
+- **Optimized** — All screenshots resized and compressed to WebP for fast MCP transport.
+
+### Interact with UI
+
+- **Click elements** — By CSS selector, text content, role, or test ID. Returns a post-click screenshot.
+- **Type text** — Fill inputs with paste or per-keystroke typing. Auto-waits for element readiness.
+- **Navigate** — Go to URLs, browser back/forward. Updates page tracking automatically.
+- **Read state** — Get element text, visibility, enabled/disabled, attributes, bounding box.
+- **Wait for elements** — Wait for elements to become visible, hidden, attached, or detached.
+
+### Capture Errors & Logs
+
+- **Console logs** — Browser console output (log, error, warn) per session.
+- **Runtime errors** — Uncaught exceptions and page crashes.
+- **Network traffic** — HTTP requests/responses with status codes and timing.
+- **Process output** — stdout/stderr from dev servers and executables.
+
+### Run QA Workflows
+
+Execute multi-step sequences with per-step screenshots and log capture:
+
+```
+run_workflow: [
+  { action: "navigate", url: "http://localhost:3000" },
+  { action: "click", selector: "#login-button" },
+  { action: "type", selector: "#email", text: "user@example.com" },
+  { action: "type", selector: "#password", text: "password123" },
+  { action: "click", selector: "role=button[name='Sign In']" },
+  { action: "assert", selector: ".welcome-message", assertType: "text-contains", expected: "Welcome" }
+]
+```
+
+Each step captures a screenshot and log deltas. Failed steps stop the workflow with diagnostic context.
+
+### Assert UI State
+
+13 assertion types for verifying application behavior:
+
+| Assertion | What it checks |
+|-----------|---------------|
+| `exists` | Element is in the DOM |
+| `not-exists` | Element is not in the DOM |
+| `visible` | Element is visible |
+| `hidden` | Element is hidden or absent |
+| `text-equals` | Element text matches exactly |
+| `text-contains` | Element text contains substring |
+| `has-attribute` | Element has the named attribute |
+| `attribute-equals` | Attribute matches expected value |
+| `enabled` | Element is enabled |
+| `disabled` | Element is disabled |
+| `checked` | Checkbox/radio is checked |
+| `not-checked` | Checkbox/radio is not checked |
+| `value-equals` | Input value matches expected |
+
+## All 23 Tools
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 1 | `get_version` | Server version and capabilities |
+| 2 | `create_session` | Start a new testing session |
+| 3 | `list_sessions` | List active sessions |
+| 4 | `end_session` | End session and clean up resources |
+| 5 | `check_port` | Check if a port is available |
+| 6 | `launch_web_server` | Start a web dev server |
+| 7 | `launch_electron` | Launch an Electron app |
+| 8 | `launch_windows_exe` | Launch a Windows executable |
+| 9 | `stop_process` | Stop all processes in a session |
+| 10 | `screenshot_web` | Screenshot a web page by URL |
+| 11 | `screenshot_electron` | Screenshot an Electron app |
+| 12 | `screenshot_desktop` | Screenshot a desktop app window |
+| 13 | `get_screenshot` | Get latest auto-captured screenshot |
+| 14 | `click_element` | Click an element on the page |
+| 15 | `type_text` | Type into an input field |
+| 16 | `navigate` | Navigate to URL or back/forward |
+| 17 | `get_element_state` | Read element properties |
+| 18 | `wait_for_element` | Wait for element state change |
+| 19 | `get_console_logs` | Get browser console output |
+| 20 | `get_errors` | Get runtime errors and crashes |
+| 21 | `get_network_logs` | Get HTTP request/response logs |
+| 22 | `get_process_output` | Get process stdout/stderr |
+| 23 | `run_workflow` | Execute multi-step QA workflow |
+
+## Typical Flow
+
+```
+create_session
+  -> launch_web_server (npm run dev on port 3000)
+  -> screenshot_web (http://localhost:3000)
+  -> click_element (#submit-button)
+  -> type_text (#search-input, "hello world")
+  -> run_workflow (multi-step test with assertions)
+  -> get_console_logs (check for errors)
+  -> stop_process (clean up)
+  -> end_session
+```
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+- **Playwright Chromium** — installed via `npx playwright install chromium`
+- **Windows** — required for desktop app screenshots and .exe launching (web/Electron work on all platforms)
+
+## Tech Stack
+
+- TypeScript/Node.js with ESM
+- [MCP SDK](https://github.com/modelcontextprotocol/sdk) for Claude Code integration
+- [Playwright](https://playwright.dev/) for web and Electron automation
+- [Sharp](https://sharp.pixelplumbing.com/) for screenshot optimization (WebP)
+- [node-screenshots](https://github.com/nicehash/node-screenshots) for native desktop capture
+
+## License
+
+MIT

package/build/capture/console-collector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ERRX-01: Browser console log capture
+ * Attaches to Playwright page.on("console") events and stores entries
+ * in a bounded array. Uses msg.text() (never jsonValue) for reliability.
+ */
+import type { Page } from "playwright";
+import { Collector, ConsoleEntry } from "./types.js";
+/**
+ * Attach a console log collector to a Playwright page.
+ * Captures all console.log/warn/error/info/debug messages.
+ *
+ * @param page - Playwright Page to monitor
+ * @param maxEntries - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export declare function attachConsoleCollector(page: Page, maxEntries?: number): Collector<ConsoleEntry>;

package/build/capture/console-collector.js

@@ -0,0 +1,43 @@
+/**
+ * ERRX-01: Browser console log capture
+ * Attaches to Playwright page.on("console") events and stores entries
+ * in a bounded array. Uses msg.text() (never jsonValue) for reliability.
+ */
+/**
+ * Attach a console log collector to a Playwright page.
+ * Captures all console.log/warn/error/info/debug messages.
+ *
+ * @param page - Playwright Page to monitor
+ * @param maxEntries - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export function attachConsoleCollector(page, maxEntries = 1000) {
+    const entries = [];
+    const handler = (msg) => {
+        const location = msg.location();
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: msg.type(),
+            text: msg.text(),
+        };
+        // Only include location if it has a meaningful URL
+        if (location && location.url) {
+            entry.location = {
+                url: location.url,
+                lineNumber: location.lineNumber,
+                columnNumber: location.columnNumber,
+            };
+        }
+        if (entries.length >= maxEntries) {
+            entries.shift();
+        }
+        entries.push(entry);
+    };
+    page.on("console", handler);
+    return {
+        getEntries: () => [...entries],
+        detach: () => {
+            page.off("console", handler);
+        },
+    };
+}

package/build/capture/error-collector.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ERRX-02: Uncaught exception and page crash capture
+ * Attaches to Playwright page.on("pageerror") and page.on("crash") events.
+ */
+import type { Page } from "playwright";
+import { Collector, ErrorEntry } from "./types.js";
+/**
+ * Attach an error/crash collector to a Playwright page.
+ * Captures uncaught exceptions (with stack traces) and page crashes.
+ *
+ * @param page - Playwright Page to monitor
+ * @param maxEntries - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export declare function attachErrorCollector(page: Page, maxEntries?: number): Collector<ErrorEntry>;

package/build/capture/error-collector.js

@@ -0,0 +1,47 @@
+/**
+ * ERRX-02: Uncaught exception and page crash capture
+ * Attaches to Playwright page.on("pageerror") and page.on("crash") events.
+ */
+/**
+ * Attach an error/crash collector to a Playwright page.
+ * Captures uncaught exceptions (with stack traces) and page crashes.
+ *
+ * @param page - Playwright Page to monitor
+ * @param maxEntries - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export function attachErrorCollector(page, maxEntries = 100) {
+    const entries = [];
+    const errorHandler = (error) => {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            type: "uncaught-exception",
+            message: error.message,
+            stack: error.stack,
+        };
+        if (entries.length >= maxEntries) {
+            entries.shift();
+        }
+        entries.push(entry);
+    };
+    const crashHandler = () => {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            type: "page-crash",
+            message: "Page crashed (possible out of memory)",
+        };
+        if (entries.length >= maxEntries) {
+            entries.shift();
+        }
+        entries.push(entry);
+    };
+    page.on("pageerror", errorHandler);
+    page.on("crash", crashHandler);
+    return {
+        getEntries: () => [...entries],
+        detach: () => {
+            page.off("pageerror", errorHandler);
+            page.off("crash", crashHandler);
+        },
+    };
+}

package/build/capture/network-collector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ERRX-04: HTTP request/response logging
+ * Attaches to Playwright page request/response/requestfailed events.
+ * Tracks timing via Date.now() delta. Does NOT capture bodies or headers.
+ */
+import type { Page } from "playwright";
+import { Collector, NetworkEntry } from "./types.js";
+/**
+ * Attach a network request/response collector to a Playwright page.
+ * Tracks request timing, status codes, and failed requests.
+ *
+ * @param page - Playwright Page to monitor
+ * @param maxEntries - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export declare function attachNetworkCollector(page: Page, maxEntries?: number): Collector<NetworkEntry>;

package/build/capture/network-collector.js

@@ -0,0 +1,76 @@
+/**
+ * ERRX-04: HTTP request/response logging
+ * Attaches to Playwright page request/response/requestfailed events.
+ * Tracks timing via Date.now() delta. Does NOT capture bodies or headers.
+ */
+/**
+ * Attach a network request/response collector to a Playwright page.
+ * Tracks request timing, status codes, and failed requests.
+ *
+ * @param page - Playwright Page to monitor
+ * @param maxEntries - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export function attachNetworkCollector(page, maxEntries = 500) {
+    const entries = [];
+    const pendingRequests = new Map();
+    /**
+     * Composite key for matching requests to responses.
+     * Uses method + URL to handle concurrent requests to different endpoints.
+     */
+    const requestKey = (request) => `${request.method()} ${request.url()}`;
+    const requestHandler = (request) => {
+        pendingRequests.set(requestKey(request), Date.now());
+    };
+    const responseHandler = (response) => {
+        const request = response.request();
+        const key = requestKey(request);
+        const startTime = pendingRequests.get(key);
+        pendingRequests.delete(key);
+        const entry = {
+            timestamp: new Date().toISOString(),
+            method: request.method(),
+            url: request.url(),
+            resourceType: request.resourceType(),
+            status: response.status(),
+            statusText: response.statusText(),
+            durationMs: startTime !== undefined ? Date.now() - startTime : undefined,
+            fromServiceWorker: response.fromServiceWorker(),
+        };
+        if (entries.length >= maxEntries) {
+            entries.shift();
+        }
+        entries.push(entry);
+    };
+    const failedHandler = (request) => {
+        const key = requestKey(request);
+        const startTime = pendingRequests.get(key);
+        pendingRequests.delete(key);
+        const failure = request.failure();
+        const entry = {
+            timestamp: new Date().toISOString(),
+            method: request.method(),
+            url: request.url(),
+            resourceType: request.resourceType(),
+            status: 0,
+            statusText: "FAILED",
+            durationMs: startTime !== undefined ? Date.now() - startTime : undefined,
+            errorText: failure?.errorText,
+        };
+        if (entries.length >= maxEntries) {
+            entries.shift();
+        }
+        entries.push(entry);
+    };
+    page.on("request", requestHandler);
+    page.on("response", responseHandler);
+    page.on("requestfailed", failedHandler);
+    return {
+        getEntries: () => [...entries],
+        detach: () => {
+            page.off("request", requestHandler);
+            page.off("response", responseHandler);
+            page.off("requestfailed", failedHandler);
+        },
+    };
+}

package/build/capture/process-collector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ERRX-03: Process stdout/stderr buffered capture
+ * Attaches to child process output streams, splits multi-line output,
+ * and tags each line with stream source (stdout/stderr).
+ */
+import type { ChildProcess } from "child_process";
+import { Collector, ProcessOutputEntry } from "./types.js";
+/**
+ * Attach a process output collector to a child process.
+ * Captures stdout and stderr, splitting multi-line output into individual entries.
+ *
+ * @param child - Node.js ChildProcess to monitor
+ * @param maxLines - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export declare function attachProcessCollector(child: ChildProcess, maxLines?: number): Collector<ProcessOutputEntry>;

package/build/capture/process-collector.js

@@ -0,0 +1,48 @@
+/**
+ * ERRX-03: Process stdout/stderr buffered capture
+ * Attaches to child process output streams, splits multi-line output,
+ * and tags each line with stream source (stdout/stderr).
+ */
+/**
+ * Attach a process output collector to a child process.
+ * Captures stdout and stderr, splitting multi-line output into individual entries.
+ *
+ * @param child - Node.js ChildProcess to monitor
+ * @param maxLines - Maximum entries to buffer (oldest dropped when full)
+ * @returns Collector with getEntries() and detach()
+ */
+export function attachProcessCollector(child, maxLines = 5000) {
+    const entries = [];
+    const createHandler = (stream) => {
+        return (data) => {
+            const text = data.toString();
+            const lines = text.split("\n");
+            for (const line of lines) {
+                const trimmed = line.trimEnd();
+                if (trimmed.length === 0) {
+                    continue;
+                }
+                const entry = {
+                    timestamp: new Date().toISOString(),
+                    stream,
+                    text: trimmed,
+                };
+                if (entries.length >= maxLines) {
+                    entries.shift();
+                }
+                entries.push(entry);
+            }
+        };
+    };
+    const stdoutHandler = createHandler("stdout");
+    const stderrHandler = createHandler("stderr");
+    child.stdout?.on("data", stdoutHandler);
+    child.stderr?.on("data", stderrHandler);
+    return {
+        getEntries: () => [...entries],
+        detach: () => {
+            child.stdout?.off("data", stdoutHandler);
+            child.stderr?.off("data", stderrHandler);
+        },
+    };
+}

package/build/capture/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared type definitions for diagnostic capture infrastructure
+ * Used by all collector modules and SessionManager
+ */
+/**
+ * Generic collector interface — container for captured diagnostic data.
+ * Each collector attaches event listeners, stores entries in a bounded array,
+ * and provides getEntries() to read and detach() to clean up.
+ */
+export interface Collector<T> {
+    getEntries: () => T[];
+    detach: () => void;
+}
+/**
+ * ERRX-01: Console log entry
+ * Captured from Playwright page.on("console") events.
+ */
+export interface ConsoleEntry {
+    timestamp: string;
+    level: string;
+    text: string;
+    location?: {
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+    };
+}
+/**
+ * ERRX-02: Error/crash entry
+ * Captured from page.on("pageerror") and page.on("crash") events.
+ */
+export interface ErrorEntry {
+    timestamp: string;
+    type: "uncaught-exception" | "page-crash";
+    message: string;
+    stack?: string;
+}
+/**
+ * ERRX-04: Network request/response entry
+ * Captured from page.on("request"), page.on("response"), page.on("requestfailed").
+ */
+export interface NetworkEntry {
+    timestamp: string;
+    method: string;
+    url: string;
+    resourceType: string;
+    status: number;
+    statusText: string;
+    durationMs?: number;
+    errorText?: string;
+    fromServiceWorker?: boolean;
+}
+/**
+ * ERRX-03: Process output entry
+ * Captured from child process stdout/stderr streams.
+ */
+export interface ProcessOutputEntry {
+    timestamp: string;
+    stream: "stdout" | "stderr";
+    text: string;
+}

package/build/capture/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared type definitions for diagnostic capture infrastructure
+ * Used by all collector modules and SessionManager
+ */
+export {};

package/build/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Entry point for Feedback MCP server
+ * Starts server on stdio transport with graceful shutdown handling
+ */
+export {};

package/build/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Entry point for Feedback MCP server
+ * Starts server on stdio transport with graceful shutdown handling
+ */
+import { createServer } from "./server.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ShutdownManager } from "./utils/shutdown.js";
+import { SessionManager } from "./session-manager.js";
+// Create shutdown manager before any async operations
+const shutdownManager = new ShutdownManager();
+// Create session manager
+const sessionManager = new SessionManager();
+// Register signal handlers BEFORE connecting transport
+process.once("SIGINT", () => {
+    void shutdownManager.cleanup();
+});
+process.once("SIGTERM", () => {
+    void shutdownManager.cleanup();
+});
+async function main() {
+    // Create server with session manager
+    const server = createServer(sessionManager);
+    // Create stdio transport
+    const transport = new StdioServerTransport();
+    // Connect server to transport
+    await server.connect(transport);
+    // Register cleanup handlers
+    shutdownManager.register(async () => {
+        console.error("Closing server");
+    });
+    shutdownManager.register(async () => {
+        await sessionManager.destroyAll();
+    });
+    console.error("Feedback MCP Server running on stdio");
+}
+// Start server with fatal error handler
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/interaction/selectors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Selector resolution and page discovery
+ * Converts string selectors to Playwright Locators and discovers active pages
+ */
+import type { Page, Locator } from "playwright";
+import type { SessionManager } from "../session-manager.js";
+import type { PageDiscoveryResult } from "./types.js";
+/**
+ * Convert a selector string to a Playwright Locator.
+ *
+ * Supported formats:
+ * - CSS selectors: #id, .class, div > span (passed directly to Playwright)
+ * - Text: text=Click me (Playwright native)
+ * - Role: role=button[name='Submit'] (Playwright native)
+ * - XPath: xpath=//div[@id='main'] (Playwright native)
+ * - Test ID: testid=my-btn (resolved via getByTestId)
+ */
+export declare function resolveSelector(page: Page, selector: string): Locator;
+/**
+ * Find the active page for interaction in a session.
+ *
+ * - If pageIdentifier is provided, looks up that specific page
+ * - If omitted and session has exactly one page, auto-selects it
+ * - If omitted and session has 0 or >1 pages, returns actionable error
+ */
+export declare function getActivePage(sessionManager: SessionManager, sessionId: string, pageIdentifier?: string): PageDiscoveryResult;