@jobshimo/browser-link 0.0.1

package/dist/tools/browser-definitions.js

@@ -0,0 +1,127 @@
+/**
+ * MCP tool definitions for the browser-bridge family. Kept separate from
+ * the runtime dispatcher so the JSON schemas stay reviewable in one place
+ * and the dispatch logic stays small.
+ */
+export const BROWSER_TOOL_DEFINITIONS = [
+    {
+        name: 'browser.list_tabs',
+        description: 'List Chrome tabs currently connected to browser-link. A tab is connected only after the user clicks Conectar in the extension popup. Returns tab_id, url and title for each.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'browser.ping',
+        description: 'Verify the bridge to a tab. Returns its current title and url.',
+        inputSchema: {
+            type: 'object',
+            properties: { tab_id: { type: 'string' } },
+            required: ['tab_id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.navigate',
+        description: 'Navigate the connected tab to a URL. By default waits for the load event.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                url: { type: 'string', description: 'Full URL including protocol.' },
+                wait_for_load: { type: 'boolean', default: true },
+            },
+            required: ['tab_id', 'url'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.snapshot',
+        description: 'Snapshot of the tab: title, url, visible text (truncated) and a list of interactive elements (buttons, links, inputs, selects, textareas) with a CSS selector and labels. Use this to understand page state before clicking or typing.',
+        inputSchema: {
+            type: 'object',
+            properties: { tab_id: { type: 'string' } },
+            required: ['tab_id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.console',
+        description: 'Return recent console messages (log, info, warn, error) from the connected tab since it was attached. Rolling buffer (last 200).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                level: { type: 'string', enum: ['log', 'info', 'warn', 'error', 'debug'] },
+            },
+            required: ['tab_id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.network',
+        description: 'Return recent network requests from the connected tab (rolling buffer, last 200). Includes request_id, method, url, status, mime, size, timing. Use browser.network_body to fetch the body of a specific request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                url_filter: { type: 'string', description: 'Optional substring to filter request URLs.' },
+            },
+            required: ['tab_id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.network_body',
+        description: 'Fetch the response body of a single network request by request_id (from browser.network).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                request_id: { type: 'string' },
+            },
+            required: ['tab_id', 'request_id'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.click',
+        description: 'Click an element by CSS selector in the connected tab. The selector usually comes from browser.snapshot.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                selector: { type: 'string' },
+            },
+            required: ['tab_id', 'selector'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.type',
+        description: 'Focus an input by CSS selector and type text into it. If clear=true, clears the current value first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                selector: { type: 'string' },
+                text: { type: 'string' },
+                clear: { type: 'boolean', default: false },
+            },
+            required: ['tab_id', 'selector', 'text'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'browser.evaluate',
+        description: 'Run a JavaScript expression in the page context and return its result. Use an IIFE with return if you need multi-step logic.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tab_id: { type: 'string' },
+                expression: { type: 'string' },
+            },
+            required: ['tab_id', 'expression'],
+            additionalProperties: false,
+        },
+    },
+];
+//# sourceMappingURL=browser-definitions.js.map

package/dist/tools/browser-definitions.js.map

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

package/dist/tools/browser-dispatch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dispatcher for browser.* tools. Mirrors the shape of the map dispatcher
+ * (`handleMapTool` / `isMapTool`) so both families look the same from
+ * runServer().
+ *
+ * The handlers do not own state: they receive a `BrowserToolDeps` object
+ * with the live tab map and the call function. This makes the dispatcher
+ * unit-testable with a fake `callBrowserTool`.
+ */
+export interface TabSnapshot {
+    tab_id: string;
+    url: string;
+    title: string;
+}
+export interface BrowserToolDeps {
+    listTabs(): TabSnapshot[];
+    callBrowserTool(tabId: string, tool: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+}
+export declare function isBrowserTool(name: string): boolean;
+export declare function handleBrowserTool(name: string, args: unknown, deps: BrowserToolDeps): Promise<unknown>;

package/dist/tools/browser-dispatch.js

@@ -0,0 +1,75 @@
+/**
+ * Dispatcher for browser.* tools. Mirrors the shape of the map dispatcher
+ * (`handleMapTool` / `isMapTool`) so both families look the same from
+ * runServer().
+ *
+ * The handlers do not own state: they receive a `BrowserToolDeps` object
+ * with the live tab map and the call function. This makes the dispatcher
+ * unit-testable with a fake `callBrowserTool`.
+ */
+import { requireTabId } from './responses.js';
+export function isBrowserTool(name) {
+    return name === 'browser.list_tabs' || BROWSER_TOOL_HANDLERS.has(name);
+}
+const NAVIGATE_TIMEOUT_MS = 30_000;
+const BROWSER_TOOL_HANDLERS = new Map([
+    ['browser.list_tabs', (_args, deps) => deps.listTabs()],
+    ['browser.ping', (args, deps) => deps.callBrowserTool(requireTabId(args), 'ping', {})],
+    [
+        'browser.navigate',
+        (args, deps) => {
+            const { url, wait_for_load = true } = args;
+            return deps.callBrowserTool(requireTabId(args), 'navigate', { url, wait_for_load }, NAVIGATE_TIMEOUT_MS);
+        },
+    ],
+    ['browser.snapshot', (args, deps) => deps.callBrowserTool(requireTabId(args), 'snapshot', {})],
+    [
+        'browser.console',
+        (args, deps) => {
+            const { level } = args ?? {};
+            return deps.callBrowserTool(requireTabId(args), 'console', { level });
+        },
+    ],
+    [
+        'browser.network',
+        (args, deps) => {
+            const { url_filter } = args ?? {};
+            return deps.callBrowserTool(requireTabId(args), 'network', { url_filter });
+        },
+    ],
+    [
+        'browser.network_body',
+        (args, deps) => {
+            const { request_id } = args;
+            return deps.callBrowserTool(requireTabId(args), 'network_body', { request_id });
+        },
+    ],
+    [
+        'browser.click',
+        (args, deps) => {
+            const { selector } = args;
+            return deps.callBrowserTool(requireTabId(args), 'click', { selector });
+        },
+    ],
+    [
+        'browser.type',
+        (args, deps) => {
+            const { selector, text, clear = false, } = args;
+            return deps.callBrowserTool(requireTabId(args), 'type', { selector, text, clear });
+        },
+    ],
+    [
+        'browser.evaluate',
+        (args, deps) => {
+            const { expression } = args;
+            return deps.callBrowserTool(requireTabId(args), 'evaluate', { expression });
+        },
+    ],
+]);
+export async function handleBrowserTool(name, args, deps) {
+    const handler = BROWSER_TOOL_HANDLERS.get(name);
+    if (!handler)
+        throw new Error(`Unknown browser tool: ${name}`);
+    return handler(args, deps);
+}
+//# sourceMappingURL=browser-dispatch.js.map

package/dist/tools/browser-dispatch.js.map

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

package/dist/tools/responses.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP tool-response helpers shared between the browser bridge and the map.
+ * Lifted out of runServer() so they can be unit-tested in isolation.
+ */
+/** Shape we emit for an MCP tool result. Index signature is intentional:
+ * newer @modelcontextprotocol/sdk schemas extend ServerResult with optional
+ * fields we do not populate (e.g. task), and we want the structural type
+ * to remain compatible without us having to track every SDK addition. */
+export interface ToolResponse {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: true;
+    [extra: string]: unknown;
+}
+export declare function toolResponse(data: unknown): ToolResponse;
+export declare function toolError(message: string): ToolResponse;
+export declare function requireTabId(args: unknown): string;

package/dist/tools/responses.js

@@ -0,0 +1,27 @@
+/**
+ * MCP tool-response helpers shared between the browser bridge and the map.
+ * Lifted out of runServer() so they can be unit-tested in isolation.
+ */
+export function toolResponse(data) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: typeof data === 'string' ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function toolError(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+export function requireTabId(args) {
+    const id = args?.tab_id;
+    if (!id)
+        throw new Error('tab_id required');
+    return id;
+}
+//# sourceMappingURL=responses.js.map

package/dist/tools/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../src/tools/responses.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;aACtE;SACF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;QACtD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,MAAM,EAAE,GAAI,IAAwC,EAAE,MAAM,CAAC;IAC7D,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAC5C,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/tools/server-instructions.d.ts

@@ -0,0 +1,3 @@
+/** Usage protocol pushed to the MCP client on `initialize`. Plain string,
+ * intentionally kept short. Edit here when the protocol changes. */
+export declare const SERVER_INSTRUCTIONS = "browser-link bridges Claude Code to the Chrome tabs the user has\nexplicitly connected through the companion extension, and ships a\npersistent UI map backed by a local SQLite DB. The data dir resolves\nper-OS via env-paths ($XDG_DATA_HOME/browser-link on Linux,\n~/Library/Application Support/browser-link on macOS, %APPDATA%/browser-link\non Windows). Override with $BROWSER_LINK_DATA_DIR. The map is private\nand per-machine; never persisted in any repo.\n\n## When operating on a tab\n\n1. Before doing anything on a tab whose URL you don't already know,\n   call `browser.map.recall` with { origin } (and optionally url) to load\n   selectors, flows and gotchas previously learned for that app.\n2. If recall returns entries with `failed_at` more recent than\n   `verified_at`, treat them as suspect: re-verify (snapshot / evaluate)\n   before reusing, or replace them.\n3. After every interaction that used a map entry, call\n   `browser.map.record_use` with { entry_id, ok }. ok=true updates\n   verified_at; ok=false updates failed_at. Keep the map honest.\n4. After a non-trivial flow that worked end-to-end, persist it with\n   `browser.map.save`. Three `kind` values:\n   - selector: { selector, evidence? } \u2014 a CSS selector tied to a purpose.\n   - flow: { steps: [...] } \u2014 an ordered list of actions to reach an outcome.\n   - gotcha: { body } \u2014 free-form note about something non-obvious.\n   Use `url_pattern` = pathname (exact). Promote to glob only if you have\n   evidence of a parametric route. Provide `purpose` as a stable, reusable\n   label (\"open task detail dialog\", not \"open IB0311 detail\").\n5. Never save selectors or flows you have not just successfully executed.\n6. Never store domain data (IDs, user names, dates, etc.). The map captures\n   UI structure only.\n\n## Identifying the app\n\n- `origin` = scheme://host:port of the tab.\n- `app_key` distinguishes apps that share an origin over time. On first\n  save you may omit it; it will be derived from the page title (slugified).\n  Use `browser.map.rename_app` if that initial guess is poor.\n\n## When something is wrong\n\n- A selector from recall fails \u2192 record_use({ok:false}), learn the new\n  one, save it (upsert on purpose).\n- A whole app got refactored \u2192 `browser.map.forget` the app_id and let\n  the map repopulate as you learn the new structure.\n\nThe map is a cache of navigation, not a substitute for `browser.snapshot`.\nThe live snapshot is always the source of truth.";

package/dist/tools/server-instructions.js

@@ -0,0 +1,50 @@
+/** Usage protocol pushed to the MCP client on `initialize`. Plain string,
+ * intentionally kept short. Edit here when the protocol changes. */
+export const SERVER_INSTRUCTIONS = `browser-link bridges Claude Code to the Chrome tabs the user has
+explicitly connected through the companion extension, and ships a
+persistent UI map backed by a local SQLite DB. The data dir resolves
+per-OS via env-paths (\$XDG_DATA_HOME/browser-link on Linux,
+~/Library/Application Support/browser-link on macOS, %APPDATA%/browser-link
+on Windows). Override with \$BROWSER_LINK_DATA_DIR. The map is private
+and per-machine; never persisted in any repo.
+
+## When operating on a tab
+
+1. Before doing anything on a tab whose URL you don't already know,
+   call \`browser.map.recall\` with { origin } (and optionally url) to load
+   selectors, flows and gotchas previously learned for that app.
+2. If recall returns entries with \`failed_at\` more recent than
+   \`verified_at\`, treat them as suspect: re-verify (snapshot / evaluate)
+   before reusing, or replace them.
+3. After every interaction that used a map entry, call
+   \`browser.map.record_use\` with { entry_id, ok }. ok=true updates
+   verified_at; ok=false updates failed_at. Keep the map honest.
+4. After a non-trivial flow that worked end-to-end, persist it with
+   \`browser.map.save\`. Three \`kind\` values:
+   - selector: { selector, evidence? } — a CSS selector tied to a purpose.
+   - flow: { steps: [...] } — an ordered list of actions to reach an outcome.
+   - gotcha: { body } — free-form note about something non-obvious.
+   Use \`url_pattern\` = pathname (exact). Promote to glob only if you have
+   evidence of a parametric route. Provide \`purpose\` as a stable, reusable
+   label ("open task detail dialog", not "open IB0311 detail").
+5. Never save selectors or flows you have not just successfully executed.
+6. Never store domain data (IDs, user names, dates, etc.). The map captures
+   UI structure only.
+
+## Identifying the app
+
+- \`origin\` = scheme://host:port of the tab.
+- \`app_key\` distinguishes apps that share an origin over time. On first
+  save you may omit it; it will be derived from the page title (slugified).
+  Use \`browser.map.rename_app\` if that initial guess is poor.
+
+## When something is wrong
+
+- A selector from recall fails → record_use({ok:false}), learn the new
+  one, save it (upsert on purpose).
+- A whole app got refactored → \`browser.map.forget\` the app_id and let
+  the map repopulate as you learn the new structure.
+
+The map is a cache of navigation, not a substitute for \`browser.snapshot\`.
+The live snapshot is always the source of truth.`;
+//# sourceMappingURL=server-instructions.js.map

package/dist/tools/server-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/tools/server-instructions.ts"],"names":[],"mappings":"AAAA;oEACoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iDA8Cc,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,6 @@
+/** Shape of an MCP tool definition for our ListToolsRequestSchema response. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}

package/dist/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}

package/dist/utils/open-url.d.ts

@@ -0,0 +1,4 @@
+/** Open the given URL in the user's default browser, cross-platform.
+ * Best-effort: returns true if the spawn succeeded, false if no opener
+ * is available. We never wait for the browser process. */
+export declare function openUrl(url: string): boolean;

package/dist/utils/open-url.js

@@ -0,0 +1,37 @@
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+/** Open the given URL in the user's default browser, cross-platform.
+ * Best-effort: returns true if the spawn succeeded, false if no opener
+ * is available. We never wait for the browser process. */
+export function openUrl(url) {
+    const os = platform();
+    const opts = { detached: true, stdio: 'ignore' };
+    let cmd;
+    let args;
+    if (os === 'darwin') {
+        cmd = 'open';
+        args = [url];
+    }
+    else if (os === 'win32') {
+        // `start` is a shell builtin on Windows, so we go through cmd.
+        // The empty string ('') is the window title argument that `start` expects
+        // when the URL itself contains characters cmd would otherwise misinterpret.
+        cmd = 'cmd';
+        args = ['/c', 'start', '""', url];
+    }
+    else {
+        // Linux / BSDs: rely on freedesktop's xdg-open. Most desktop installs
+        // ship it; if not, the caller falls back to printing the URL.
+        cmd = 'xdg-open';
+        args = [url];
+    }
+    try {
+        const child = spawn(cmd, args, opts);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=open-url.js.map

package/dist/utils/open-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-url.js","sourceRoot":"","sources":["../../src/utils/open-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;0DAE0D;AAC1D,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC;IACtB,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAiB,EAAE,CAAC;IAE1D,IAAI,GAAW,CAAC;IAChB,IAAI,IAAc,CAAC;IACnB,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,GAAG,GAAG,MAAM,CAAC;QACb,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;SAAM,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QAC1B,+DAA+D;QAC/D,0EAA0E;QAC1E,4EAA4E;QAC5E,GAAG,GAAG,KAAK,CAAC;QACZ,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;SAAM,CAAC;QACN,sEAAsE;QACtE,8DAA8D;QAC9D,GAAG,GAAG,UAAU,CAAC;QACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACrC,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jobshimo/browser-link",
+  "version": "0.0.1",
+  "description": "MCP server that bridges Claude (and other MCP clients) to a Chrome tab, with a persistent UI map of selectors, flows and gotchas across sessions.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "chrome",
+    "browser-automation",
+    "ai-tools"
+  ],
+  "homepage": "https://github.com/jobshimo/browser-link#readme",
+  "bugs": {
+    "url": "https://github.com/jobshimo/browser-link/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jobshimo/browser-link.git",
+    "directory": "packages/server"
+  },
+  "license": "MIT",
+  "author": "Martín Miguel Bernal",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "browser-link": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli.ts",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build && node ./scripts/prepare-publish.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.5.0",
+    "env-paths": "^3.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.1.4"
+  }
+}