# Install core + adapters
pnpm add @browserkit-dev/core @browserkit-dev/adapter-hackernews @browserkit-dev/adapter-linkedin

# Log in once per authenticated site (opens a browser window)
browserkit login linkedin

# Start the daemon
browserkit start --config browserkit.config.js

{
  "mcpServers": {
    "browserkit-hackernews": { "url": "http://localhost:3847/mcp" },
    "browserkit-linkedin":   { "url": "http://localhost:3848/mcp" }
  }
}

AI Agent (Cursor / Claude / custom)
         ↓ HTTP MCP
browserkit daemon
  ├── hackernews  :3847  headless Chromium  (public, no auth needed)
  ├── linkedin    :3848  headless Chrome    (authenticated, uses real Chrome)
  └── ...

// browserkit.config.js
export default {
  host: "127.0.0.1",        // bind address (non-localhost requires bearerToken)
  basePort: 3847,           // first adapter auto-assigns from here
  bearerToken: process.env.BROWSERKIT_TOKEN,  // optional auth

  adapters: {
    // key = npm package name (no naming convention required)
    "@browserkit-dev/adapter-hackernews": {
      port: 3847,
    },
    "@browserkit-dev/adapter-linkedin": {
      port: 3848,
      channel: "chrome",    // use real Chrome — avoids bot detection on login
    },
    "@someone/my-custom-adapter": {
      port: 3849,
      debugPort: 4849,      // optional: enables raw Playwright access via CDP
      authStrategy: "persistent",   // "persistent" | "storage-state" | "cdp-attach" | "extension"
      rateLimit: { minDelayMs: 3000 },
    },
  },
};

browserkit start [--adapter <pkg>] [--port <n>] [--config <path>]
browserkit login <site>           # one-time login (opens browser)
browserkit status                 # show running adapters
browserkit config cursor          # generate Cursor MCP settings JSON
browserkit create-adapter <name>  # scaffold a new adapter package

headless  →  fully invisible, automation runs normally (default)
watch     →  browser becomes visible, automation continues (optional slowMoMs)
paused    →  browser visible, tool calls queue — user has manual control

AI Agent (Cursor / Claude)
    ↓ HTTP MCP
browserkit daemon
    ├── hackernews  :3847  headless Patchright  (default — no login needed)
    └── linkedin    :3848  your Chrome          (extension mode — inherits your session)
                              └── Playwriter relay → Chrome extension → authenticated tab

pnpm add playwriter

// browserkit.config.js
export default {
  adapters: {
    "@browserkit-dev/adapter-linkedin": {
      authStrategy: "extension",  // use Chrome extension backend
      // extensionPort: 19988,    // optional — Playwriter's default
    },
    "@browserkit-dev/adapter-hackernews": {
      // defaults to "persistent" — headless Patchright as normal
    },
  },
};

browserkit start

// Script written by Claude Code, executed via shell
const { chromium } = require('playwright');

// Attach to the running session — already logged in, no auth needed
const browser = await chromium.connectOverCDP("http://127.0.0.1:4848");
const context = browser.contexts()[0];
const page = context.pages()[0];

// Full Playwright API — write any automation
await page.goto("https://my-site.com/data");
const results = await page.$$eval(".row", (els) => els.map((el) => el.textContent?.trim()));
console.log(JSON.stringify(results));

await browser.disconnect(); // disconnect only — session stays alive

npx @browserkit-dev/core create-adapter my-site
cd adapter-my-site
pnpm install

import { defineAdapter } from "@browserkit-dev/core";
import { z } from "zod";
import type { Page } from "playwright";

export default defineAdapter({
  // ── Required ────────────────────────────────────────────────────────────
  site: "my-site",                          // unique ID, becomes the MCP server name
  domain: "my-site.com",                    // used for profile scoping
  loginUrl: "https://my-site.com/login",    // where to navigate for login flow

  async isLoggedIn(page: Page): Promise<boolean> {
    // Return true when the page shows an authenticated state.
    // Called before every tool call. If it returns false, browserkit
    // triggers the human handoff flow (opens browser, waits for login).
    // For public sites (no auth), always return true.
    return page.getByRole("navigation", { name: "user menu" }).isVisible({ timeout: 3000 });
  },

  tools: () => [ /* see below */ ],

  // ── Optional ────────────────────────────────────────────────────────────
  rateLimit: { minDelayMs: 2000 },          // min delay between consecutive tool calls

  selectors: {                              // exported CSS selectors for health_check reporting
    mainContent: ".main-content",           // health_check validates these on the live page
    loginButton: "button[data-testid=login]",
  },
});

tools: () => [
  {
    name: "get_data",
    description: "Get data from my-site",

    // Zod schema — validated before handler is called
    inputSchema: z.object({
      query: z.string().describe("Search query"),
      limit: z.number().int().min(1).max(50).default(10),
    }),

    // handler receives: the live authenticated Page + validated input
    async handler(page: Page, input: unknown) {
      const { query, limit } = mySchema.parse(input); // use schema.parse for type safety

      await page.goto(`https://my-site.com/search?q=${encodeURIComponent(query)}`);
      await page.waitForSelector(".result", { timeout: 10_000 });

      const results = await page.evaluate(({ sel, n }) => {
        return Array.from(document.querySelectorAll(sel))
          .slice(0, n)
          .map((el) => el.textContent?.trim() ?? "");
      }, { sel: ".result", n: limit });

      // Return value must have this shape:
      return {
        content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
        // isError: true  — set this if the tool failed but you want to return a message
      };
    },
  },
],

// tests/mcp-protocol.test.ts
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import myAdapter from "../src/index.js";
import { createTestAdapterServer, createTestMcpClient } from "@browserkit-dev/core/testing";

let server, client;

beforeAll(async () => {
  server = await createTestAdapterServer(myAdapter);
  client = await createTestMcpClient(server.url);
}, 30_000);

afterAll(async () => {
  await client.close();
  await server.stop();
});

it("get_data returns results", async () => {
  const result = await client.callTool("get_data", { query: "test" });
  expect(result.isError).toBeFalsy();
  const data = JSON.parse(result.content[0].text);
  expect(Array.isArray(data)).toBe(true);
});

pnpm build
npm publish --access public