cbrowser 5.0.2 → 5.2.0

package/dist/mcp-server.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CBrowser MCP Server
+ *
+ * Exposes CBrowser browser automation tools via Model Context Protocol.
+ * Run with: cbrowser mcp-server
+ * Or: npx cbrowser mcp-server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startMcpServer = startMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const browser_js_1 = require("./browser.js");
+// Shared browser instance
+let browser = null;
+async function getBrowser() {
+    if (!browser) {
+        browser = new browser_js_1.CBrowser({
+            headless: true,
+            persistent: true,
+        });
+    }
+    return browser;
+}
+async function startMcpServer() {
+    const server = new mcp_js_1.McpServer({
+        name: "cbrowser",
+        version: "5.0.0",
+    });
+    // =========================================================================
+    // Navigation Tools
+    // =========================================================================
+    server.tool("navigate", "Navigate to a URL and take a screenshot", {
+        url: zod_1.z.string().url().describe("The URL to navigate to"),
+    }, async ({ url }) => {
+        const b = await getBrowser();
+        const result = await b.navigate(url);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        url: result.url,
+                        title: result.title,
+                        loadTime: result.loadTime,
+                        screenshot: result.screenshot,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // =========================================================================
+    // Interaction Tools
+    // =========================================================================
+    server.tool("click", "Click an element on the page using text, selector, or description", {
+        selector: zod_1.z.string().describe("Element to click (text content, CSS selector, or description)"),
+        force: zod_1.z.boolean().optional().describe("Bypass safety checks for destructive actions"),
+    }, async ({ selector, force }) => {
+        const b = await getBrowser();
+        const result = await b.click(selector, { force });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: result.success,
+                        message: result.message,
+                        screenshot: result.screenshot,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("smart_click", "Click with auto-retry and self-healing selectors", {
+        selector: zod_1.z.string().describe("Element to click"),
+        maxRetries: zod_1.z.number().optional().default(3).describe("Maximum retry attempts"),
+    }, async ({ selector, maxRetries }) => {
+        const b = await getBrowser();
+        const result = await b.smartClick(selector, { maxRetries });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: result.success,
+                        attempts: result.attempts.length,
+                        finalSelector: result.finalSelector,
+                        message: result.message,
+                        aiSuggestion: result.aiSuggestion,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("fill", "Fill a form field with text", {
+        selector: zod_1.z.string().describe("Input field to fill (name, placeholder, label, or selector)"),
+        value: zod_1.z.string().describe("Value to enter"),
+    }, async ({ selector, value }) => {
+        const b = await getBrowser();
+        const result = await b.fill(selector, value);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: result.success,
+                        message: result.message,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // =========================================================================
+    // Extraction Tools
+    // =========================================================================
+    server.tool("screenshot", "Take a screenshot of the current page", {
+        path: zod_1.z.string().optional().describe("Optional path to save the screenshot"),
+    }, async ({ path }) => {
+        const b = await getBrowser();
+        const file = await b.screenshot(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ screenshot: file }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("extract", "Extract data from the page", {
+        what: zod_1.z.enum(["links", "headings", "forms", "images", "text"]).describe("What to extract"),
+    }, async ({ what }) => {
+        const b = await getBrowser();
+        const result = await b.extract(what);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result.data, null, 2),
+                },
+            ],
+        };
+    });
+    // =========================================================================
+    // Assertion Tools
+    // =========================================================================
+    server.tool("assert", "Assert a condition using natural language", {
+        assertion: zod_1.z.string().describe("Natural language assertion like \"page contains 'Welcome'\" or \"title is 'Home'\""),
+    }, async ({ assertion }) => {
+        const b = await getBrowser();
+        const result = await b.assert(assertion);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        passed: result.passed,
+                        message: result.message,
+                        actual: result.actual,
+                        expected: result.expected,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // =========================================================================
+    // Analysis Tools
+    // =========================================================================
+    server.tool("analyze_page", "Analyze page structure for forms, buttons, links", {}, async () => {
+        const b = await getBrowser();
+        const analysis = await b.analyzePage();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        title: analysis.title,
+                        forms: analysis.forms.length,
+                        buttons: analysis.buttons.length,
+                        links: analysis.links.length,
+                        hasLogin: analysis.hasLogin,
+                        hasSearch: analysis.hasSearch,
+                        hasNavigation: analysis.hasNavigation,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("generate_tests", "Generate test scenarios for a page", {
+        url: zod_1.z.string().url().optional().describe("URL to analyze (uses current page if not provided)"),
+    }, async ({ url }) => {
+        const b = await getBrowser();
+        const result = await b.generateTests(url);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        testsGenerated: result.tests.length,
+                        tests: result.tests.map(t => ({
+                            name: t.name,
+                            description: t.description,
+                            steps: t.steps.length,
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // =========================================================================
+    // Session Tools
+    // =========================================================================
+    server.tool("save_session", "Save browser session (cookies, storage) for later use", {
+        name: zod_1.z.string().describe("Name for the saved session"),
+    }, async ({ name }) => {
+        const b = await getBrowser();
+        await b.saveSession(name);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: true, sessionName: name }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("load_session", "Load a previously saved session", {
+        name: zod_1.z.string().describe("Name of the session to load"),
+    }, async ({ name }) => {
+        const b = await getBrowser();
+        const loaded = await b.loadSession(name);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: loaded, sessionName: name }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("list_sessions", "List all saved sessions", {}, async () => {
+        const b = await getBrowser();
+        const sessions = await b.listSessions();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(sessions, null, 2),
+                },
+            ],
+        };
+    });
+    // =========================================================================
+    // Self-Healing Tools
+    // =========================================================================
+    server.tool("heal_stats", "Get self-healing selector cache statistics", {}, async () => {
+        const b = await getBrowser();
+        const stats = b.getSelectorCacheStats();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(stats, null, 2),
+                },
+            ],
+        };
+    });
+    // Connect via stdio transport
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // Handle shutdown
+    process.on("SIGINT", async () => {
+        if (browser) {
+            await browser.close();
+        }
+        process.exit(0);
+    });
+}
+// Run if called directly
+if (process.argv[1]?.endsWith("mcp-server.js") || process.argv[1]?.endsWith("mcp-server.ts")) {
+    startMcpServer().catch(console.error);
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/docs/INSTALL.md

@@ -57,7 +57,7 @@ CBROWSER_DATA_DIR="./data" npx cbrowser navigate "https://example.com"
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CBROWSER_DATA_DIR` | `~/.cbrowser` | Data storage directory |
-| `CBROWSER_HEADLESS` | `false` | Run headless by default |
+| `CBROWSER_HEADLESS` | `true` | Run headless by default (set to `false` for GUI) |
 | `CBROWSER_TIMEOUT` | `30000` | Default timeout (ms) |
 | `CBROWSER_VIEWPORT_WIDTH` | `1280` | Default viewport width |
 | `CBROWSER_VIEWPORT_HEIGHT` | `800` | Default viewport height |

package/examples/basic-usage.ts

@@ -2,9 +2,11 @@
  * CBrowser Basic Usage Examples
  *
  * Run with: npx ts-node examples/basic-usage.ts
+ * Or: bun run examples/basic-usage.ts
  */
 
-import { CBrowser } from "../src/index.js";
+import { CBrowser } from "cbrowser";
+// For local development: import { CBrowser } from "../src/index.js";
 
 async function basicNavigation() {
   console.log("=== Basic Navigation ===\n");

package/examples/smart-automation.ts

@@ -0,0 +1,184 @@
+/**
+ * CBrowser v5.0.0 Smart Automation Examples
+ *
+ * Demonstrates:
+ * - Smart click with auto-retry
+ * - Natural language assertions
+ * - Self-healing selector cache
+ * - AI test generation
+ *
+ * Run with: npx ts-node examples/smart-automation.ts
+ */
+
+import { CBrowser } from "../src/index.js";
+
+async function smartClickExample() {
+  console.log("=== Smart Click with Auto-Retry ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    await browser.navigate("https://example.com");
+
+    // Smart click automatically:
+    // 1. Checks self-healing cache for known working selectors
+    // 2. Tries the original selector
+    // 3. Generates alternatives (text variants, ARIA roles, attributes)
+    // 4. Retries with each alternative
+    // 5. Caches the working selector for future use
+    const result = await browser.smartClick("More information...", {
+      maxRetries: 3,
+    });
+
+    console.log(`Success: ${result.success}`);
+    console.log(`Attempts: ${result.attempts.length}`);
+    console.log(`Final selector: ${result.finalSelector}`);
+
+    if (result.aiSuggestion) {
+      console.log(`AI suggestion: ${result.aiSuggestion}`);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function assertionsExample() {
+  console.log("\n=== Natural Language Assertions ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    await browser.navigate("https://example.com");
+
+    // Title assertions
+    const titleResult = await browser.assert("title contains 'Example'");
+    console.log(`Title assertion: ${titleResult.passed ? "PASS" : "FAIL"}`);
+    console.log(`  Message: ${titleResult.message}`);
+
+    // URL assertions
+    const urlResult = await browser.assert("url contains 'example.com'");
+    console.log(`URL assertion: ${urlResult.passed ? "PASS" : "FAIL"}`);
+    console.log(`  Message: ${urlResult.message}`);
+
+    // Content assertions
+    const contentResult = await browser.assert(
+      "page contains 'illustrative examples'"
+    );
+    console.log(`Content assertion: ${contentResult.passed ? "PASS" : "FAIL"}`);
+    console.log(`  Message: ${contentResult.message}`);
+
+    // Element count assertions
+    const linkResult = await browser.assert("1 links");
+    console.log(`Link count assertion: ${linkResult.passed ? "PASS" : "FAIL"}`);
+    console.log(`  Actual: ${linkResult.actual}, Expected: ${linkResult.expected}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+async function selfHealingExample() {
+  console.log("\n=== Self-Healing Selector Cache ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Get cache statistics
+    const stats = browser.getSelectorCacheStats();
+    console.log(`Cache entries: ${stats.totalEntries}`);
+    console.log(`Total successes: ${stats.totalSuccesses}`);
+    console.log(`Total failures: ${stats.totalFailures}`);
+
+    if (stats.topDomains.length > 0) {
+      console.log("\nTop domains:");
+      for (const { domain, count } of stats.topDomains) {
+        console.log(`  ${domain}: ${count} cached selectors`);
+      }
+    }
+
+    // The cache is stored in ~/.cbrowser/selector-cache.json
+    // Each entry maps: domain + originalSelector -> workingSelector
+    // When a selector fails, CBrowser checks the cache first
+    // If found, it uses the cached working selector
+    // If not found, it tries alternatives and caches the one that works
+  } finally {
+    await browser.close();
+  }
+}
+
+async function testGenerationExample() {
+  console.log("\n=== AI Test Generation ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Generate tests for a page
+    const result = await browser.generateTests("https://example.com");
+
+    console.log(`Page analyzed: ${result.url}`);
+    console.log(`Tests generated: ${result.tests.length}\n`);
+
+    // Show generated test scenarios
+    for (const test of result.tests) {
+      console.log(`Test: ${test.name}`);
+      console.log(`  Description: ${test.description}`);
+      console.log(`  Steps: ${test.steps.length}`);
+      console.log(`  Assertions: ${test.assertions.join(", ")}`);
+      console.log();
+    }
+
+    // Generated Playwright code
+    console.log("=== Generated Playwright Code ===");
+    console.log(result.playwrightCode.slice(0, 500) + "...\n");
+
+    // Generated CBrowser script
+    console.log("=== Generated CBrowser Script ===");
+    console.log(result.cbrowserScript.slice(0, 500) + "...\n");
+  } finally {
+    await browser.close();
+  }
+}
+
+async function pageAnalysisExample() {
+  console.log("\n=== Page Analysis ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    await browser.navigate("https://example.com");
+
+    const analysis = await browser.analyzePage();
+
+    console.log(`Title: ${analysis.title}`);
+    console.log(`URL: ${analysis.url}`);
+    console.log(`Forms: ${analysis.forms.length}`);
+    console.log(`Buttons: ${analysis.buttons.length}`);
+    console.log(`Links: ${analysis.links.length}`);
+    console.log(`Inputs: ${analysis.inputs.length}`);
+    console.log(`Has login form: ${analysis.hasLogin}`);
+    console.log(`Has search: ${analysis.hasSearch}`);
+    console.log(`Has navigation: ${analysis.hasNavigation}`);
+
+    // Detailed form analysis
+    if (analysis.forms.length > 0) {
+      console.log("\nForm details:");
+      for (const form of analysis.forms) {
+        console.log(`  Selector: ${form.selector}`);
+        console.log(`  Fields: ${form.fields.length}`);
+        console.log(`  Is login: ${form.isLoginForm}`);
+        console.log(`  Is search: ${form.isSearchForm}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  await smartClickExample();
+  await assertionsExample();
+  await selfHealingExample();
+  await testGenerationExample();
+  await pageAnalysisExample();
+}
+
+main().catch(console.error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cbrowser",
-  "version": "5.0.2",
-  "description": "AI-powered browser automation with constitutional safety, personas, session persistence, and autonomous journeys",
+  "version": "5.2.0",
+  "description": "AI-powered browser automation with self-healing selectors, natural language assertions, test generation, MCP server, constitutional safety, and autonomous journeys",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -32,30 +32,38 @@
     "core-web-vitals",
     "har-export",
     "network-mocking",
-    "video-recording"
+    "video-recording",
+    "self-healing-selectors",
+    "smart-retry",
+    "natural-language-assertions",
+    "test-generation",
+    "mcp-server",
+    "claude-integration"
   ],
-  "author": "Your Name",
+  "author": "Wyld Digital",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yourusername/cbrowser.git"
+    "url": "git+https://github.com/wyld-digital/cbrowser.git"
   },
   "bugs": {
-    "url": "https://github.com/yourusername/cbrowser/issues"
+    "url": "https://github.com/wyld-digital/cbrowser/issues"
   },
-  "homepage": "https://github.com/yourusername/cbrowser#readme",
+  "homepage": "https://github.com/wyld-digital/cbrowser#readme",
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "playwright": "^1.40.0"
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "playwright": "^1.40.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
-    "typescript": "^5.3.0",
-    "eslint": "^8.55.0",
     "@typescript-eslint/eslint-plugin": "^6.13.0",
-    "@typescript-eslint/parser": "^6.13.0"
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.55.0",
+    "typescript": "^5.3.0"
   },
   "files": [
     "dist/",