web-agent-bridge 1.1.2 → 2.0.0

package/wab-mcp-adapter/README.md

@@ -1,136 +0,0 @@
-# WAB-MCP Adapter
-
-**MCP adapter for Web Agent Bridge** — exposes every capability of a WAB-enabled website as a set of [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) tools so that any MCP-compatible AI agent (Claude, GPT, Gemini, open-source LLMs, etc.) can discover, read, and interact with the site through a single, standardised interface.
-
-## Quick Start
-
-```js
-const { WABMCPAdapter } = require('wab-mcp-adapter');
-
-const adapter = new WABMCPAdapter({
-  siteUrl: 'https://example.com',
-  transport: 'http',       // 'http' | 'websocket' | 'direct'
-  apiKey: 'sk-optional',   // optional API key
-});
-
-// 1. Discover site capabilities
-const doc = await adapter.discover();
-
-// 2. Get MCP tool definitions for the AI agent
-const tools = await adapter.getTools();
-
-// 3. Execute a tool call
-const result = await adapter.executeTool('wab_execute_action', {
-  name: 'signup',
-  params: { email: 'user@example.com' },
-});
-
-// 4. Clean up
-adapter.close();
-```
-
-## API Reference
-
-### `new WABMCPAdapter(options)`
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `siteUrl` | `string` | — | Target WAB site URL (required for `http` transport) |
-| `siteId` | `string` | `null` | WAB site identifier |
-| `apiKey` | `string` | `null` | API key for authenticated requests |
-| `transport` | `string` | `'http'` | Transport type: `http`, `websocket`, or `direct` |
-| `registryUrl` | `string` | `https://webagentbridge.com` | WAB fairness registry URL |
-| `page` | `object` | — | Puppeteer/Playwright page (required for `direct`) |
-| `wsUrl` | `string` | auto | WebSocket URL (required for `websocket` if no `siteUrl`) |
-| `timeout` | `number` | `15000` | Request timeout in milliseconds |
-
-### Methods
-
-| Method | Returns | Description |
-|---|---|---|
-| `discover(url?)` | `Promise<object>` | Fetch the WAB discovery document |
-| `getTools()` | `Promise<object[]>` | Return MCP tool definitions (built-in + site-specific) |
-| `executeTool(name, input)` | `Promise<object>` | Execute an MCP tool call |
-| `close()` | `void` | Release transport resources |
-
-## Built-in Tools
-
-These tools are always available, regardless of which site actions are discovered:
-
-| Tool | Description |
-|---|---|
-| `wab_discover` | Fetch the WAB discovery document from a site |
-| `wab_get_actions` | List available actions, optionally filtered by category |
-| `wab_execute_action` | Execute any WAB action by name and params |
-| `wab_read_content` | Read page element text by CSS selector |
-| `wab_get_page_info` | Return page metadata and bridge configuration |
-| `wab_fairness_search` | Search the WAB registry with fairness-weighted results |
-| `wab_authenticate` | Authenticate with the site using an API key |
-
-Site-specific actions are exposed as additional tools named `wab_<action_name>` and are generated automatically from the discovery document.
-
-## Transport Options
-
-| Transport | When to use | Requirements |
-|---|---|---|
-| **http** | Server-to-server or CLI tools calling a WAB site over REST | `siteUrl` |
-| **websocket** | Real-time bidirectional communication with low latency | `wsUrl` or `siteUrl` |
-| **direct** | In-browser automation with Puppeteer/Playwright | `page` object |
-
-## Fairness Protocol
-
-The WAB discovery registry uses a **fairness-weighted ranking** algorithm that prevents large, high-traffic sites from monopolising search results. When you call `wab_fairness_search`, the registry applies:
-
-- **Inverse-popularity weighting** — smaller sites receive a ranking boost.
-- **Recency bonus** — newly registered or recently updated sites surface sooner.
-- **Category balancing** — results are distributed across categories to avoid domination by a single vertical.
-
-This ensures a level playing field so every WAB-enabled site has equitable visibility to AI agents.
-
-## Integration with Claude / MCP
-
-Pass the tools returned by `getTools()` as the `tools` parameter when calling the Anthropic Messages API and route any `tool_use` blocks back through `executeTool`:
-
-```js
-const Anthropic = require('@anthropic-ai/sdk');
-const { WABMCPAdapter } = require('wab-mcp-adapter');
-
-const client = new Anthropic();
-const adapter = new WABMCPAdapter({ siteUrl: 'https://shop.example.com' });
-const tools = await adapter.getTools();
-
-let messages = [{ role: 'user', content: 'Find the signup form and register me.' }];
-
-while (true) {
-  const res = await client.messages.create({
-    model: 'claude-sonnet-4-20250514',
-    max_tokens: 1024,
-    tools,
-    messages,
-  });
-
-  if (res.stop_reason === 'end_turn') break;
-
-  const toolBlocks = res.content.filter((b) => b.type === 'tool_use');
-  if (!toolBlocks.length) break;
-
-  messages.push({ role: 'assistant', content: res.content });
-
-  const toolResults = [];
-  for (const block of toolBlocks) {
-    const result = await adapter.executeTool(block.name, block.input);
-    toolResults.push({
-      type: 'tool_result',
-      tool_use_id: block.id,
-      content: JSON.stringify(result.content),
-    });
-  }
-  messages.push({ role: 'user', content: toolResults });
-}
-
-adapter.close();
-```
-
-## License
-
-MIT — see [LICENSE](../LICENSE).

package/wab-mcp-adapter/index.js

@@ -1,555 +0,0 @@
-/**
- * WAB-MCP Adapter
- *
- * Converts Web Agent Bridge (WAB) capabilities into Model Context Protocol
- * (MCP) tools so any MCP-compatible AI agent can interact with WAB-enabled
- * websites through a uniform tool interface.
- *
- * @module wab-mcp-adapter
- */
-
-'use strict';
-
-const DISCOVERY_PATHS = ['/agent-bridge.json', '/.well-known/wab.json'];
-const DEFAULT_REGISTRY = 'https://webagentbridge.com';
-const DEFAULT_TIMEOUT_MS = 15_000;
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Minimal fetch wrapper with timeout and error normalisation.
- * Uses the global `fetch` available in Node 18+.
- *
- * @param {string}  url
- * @param {object}  [opts]         - Standard fetch options
- * @param {number}  [timeoutMs]    - Per-request timeout
- * @returns {Promise<object>}      - Parsed JSON body
- */
-async function jsonFetch(url, opts = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-
-  try {
-    const res = await fetch(url, { ...opts, signal: controller.signal });
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      throw new Error(`HTTP ${res.status} from ${url}: ${body}`);
-    }
-    return await res.json();
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/** Build a fully-qualified URL, tolerating trailing slashes. */
-function resolveUrl(base, path) {
-  return new URL(path, base.replace(/\/+$/, '') + '/').href;
-}
-
-/**
- * Convert a single WAB action descriptor into an MCP tool definition.
- *
- * @param {object} action
- * @returns {object} MCP tool
- */
-function actionToTool(action) {
-  const properties = {};
-  const required = [];
-
-  const fields = action.params || action.fields || [];
-  for (const f of fields) {
-    properties[f.name] = {
-      type: f.type || 'string',
-      description: f.description || f.label || f.name,
-    };
-    if (f.required) required.push(f.name);
-  }
-
-  return {
-    name: `wab_${action.name}`,
-    description: action.description || `Execute WAB action "${action.name}"`,
-    input_schema: {
-      type: 'object',
-      properties,
-      ...(required.length ? { required } : {}),
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Built-in tool definitions (always available regardless of site)
-// ---------------------------------------------------------------------------
-
-const BUILTIN_TOOLS = [
-  {
-    name: 'wab_discover',
-    description: 'Discover a WAB-enabled site — returns the full discovery document including metadata, supported actions and fairness policy.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        url: { type: 'string', description: 'Site URL to discover (defaults to the configured siteUrl)' },
-      },
-    },
-  },
-  {
-    name: 'wab_get_actions',
-    description: 'List all actions exposed by the connected WAB site, optionally filtered by category.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        category: { type: 'string', description: 'Optional category filter' },
-      },
-    },
-  },
-  {
-    name: 'wab_execute_action',
-    description: 'Execute any WAB action by name with the supplied parameters.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        name:   { type: 'string', description: 'Action name to execute' },
-        params: { type: 'object', description: 'Key/value parameters for the action' },
-      },
-      required: ['name'],
-    },
-  },
-  {
-    name: 'wab_read_content',
-    description: 'Read the text content of a page element identified by a CSS selector.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        selector: { type: 'string', description: 'CSS selector of the target element' },
-      },
-      required: ['selector'],
-    },
-  },
-  {
-    name: 'wab_get_page_info',
-    description: 'Return page metadata including title, URL, bridge version and active configuration.',
-    input_schema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'wab_fairness_search',
-    description: 'Search the WAB discovery registry for sites matching a query, ranked using the fairness protocol to surface smaller sites equitably.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        query:    { type: 'string', description: 'Search query' },
-        category: { type: 'string', description: 'Optional category filter' },
-        limit:    { type: 'number', description: 'Maximum results (default 10)' },
-      },
-      required: ['query'],
-    },
-  },
-  {
-    name: 'wab_authenticate',
-    description: 'Authenticate with the WAB site using an API key and optional agent metadata.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        apiKey: { type: 'string', description: 'API key for authentication' },
-        meta:   { type: 'object', description: 'Optional agent metadata (name, version, etc.)' },
-      },
-      required: ['apiKey'],
-    },
-  },
-];
-
-// ---------------------------------------------------------------------------
-// Transport layer
-// ---------------------------------------------------------------------------
-
-class HTTPTransport {
-  /** @param {string} baseUrl  @param {object} headers */
-  constructor(baseUrl, headers = {}) {
-    this.baseUrl = baseUrl;
-    this.headers = headers;
-  }
-
-  async request(path, body) {
-    const url = resolveUrl(this.baseUrl, path);
-    const opts = body
-      ? { method: 'POST', headers: { 'Content-Type': 'application/json', ...this.headers }, body: JSON.stringify(body) }
-      : { method: 'GET', headers: this.headers };
-    return jsonFetch(url, opts);
-  }
-}
-
-class WebSocketTransport {
-  /** @param {string} wsUrl  @param {object} headers */
-  constructor(wsUrl, headers = {}) {
-    this.wsUrl = wsUrl;
-    this.headers = headers;
-    this._ws = null;
-    this._id = 0;
-    this._pending = new Map();
-  }
-
-  async connect() {
-    if (this._ws && this._ws.readyState === 1) return;
-
-    const WebSocket = (await import('ws')).default;
-    return new Promise((resolve, reject) => {
-      this._ws = new WebSocket(this.wsUrl, { headers: this.headers });
-      this._ws.on('open', resolve);
-      this._ws.on('error', reject);
-      this._ws.on('message', (raw) => {
-        try {
-          const msg = JSON.parse(raw);
-          const cb = this._pending.get(msg.id);
-          if (cb) { this._pending.delete(msg.id); cb(msg); }
-        } catch { /* ignore malformed frames */ }
-      });
-    });
-  }
-
-  async request(_path, body) {
-    await this.connect();
-    const id = ++this._id;
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => { this._pending.delete(id); reject(new Error('WebSocket request timed out')); }, DEFAULT_TIMEOUT_MS);
-      this._pending.set(id, (msg) => { clearTimeout(timer); msg.error ? reject(new Error(msg.error)) : resolve(msg.result ?? msg); });
-      this._ws.send(JSON.stringify({ id, ...body }));
-    });
-  }
-
-  close() {
-    if (this._ws) { this._ws.close(); this._ws = null; }
-  }
-}
-
-class DirectTransport {
-  /**
-   * @param {object} page - Puppeteer / Playwright page handle
-   */
-  constructor(page) {
-    this.page = page;
-  }
-
-  async request(_path, body) {
-    if (!body) {
-      return this.page.evaluate(() => window.AICommands.getPageInfo());
-    }
-    const { name, data } = body;
-    if (name) {
-      return this.page.evaluate((n, d) => window.AICommands.execute(n, d), name, data ?? {});
-    }
-    return this.page.evaluate((b) => window.AICommands.execute(b.method, b.params || {}), body);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// WABMCPAdapter
-// ---------------------------------------------------------------------------
-
-/**
- * Main adapter class that connects to a WAB-enabled website and exposes its
- * capabilities as MCP tools consumable by any MCP-compatible AI agent.
- *
- * @example
- * const adapter = new WABMCPAdapter({ siteUrl: 'https://example.com' });
- * const tools = await adapter.getTools();
- * const result = await adapter.executeTool('wab_discover', {});
- */
-class WABMCPAdapter {
-  /**
-   * @param {object}  options
-   * @param {string}  [options.siteUrl]        - Target WAB site URL
-   * @param {string}  [options.siteId]         - WAB site identifier
-   * @param {string}  [options.apiKey]         - API key for authenticated requests
-   * @param {string}  [options.transport='http'] - 'http' | 'websocket' | 'direct'
-   * @param {string}  [options.registryUrl]    - Custom WAB registry URL
-   * @param {object}  [options.page]           - Page handle (required for 'direct' transport)
-   * @param {string}  [options.wsUrl]          - WebSocket URL (required for 'websocket' transport)
-   * @param {number}  [options.timeout]        - Request timeout in ms
-   */
-  constructor(options = {}) {
-    this.siteUrl     = options.siteUrl;
-    this.siteId      = options.siteId || null;
-    this.apiKey      = options.apiKey || null;
-    this.registryUrl = options.registryUrl || DEFAULT_REGISTRY;
-    this.timeout     = options.timeout || DEFAULT_TIMEOUT_MS;
-
-    this._discovery   = null;
-    this._siteActions = [];
-    this._sessionToken = null;
-
-    const headers = {};
-    if (this.apiKey) headers['x-api-key'] = this.apiKey;
-
-    const transport = (options.transport || 'http').toLowerCase();
-    if (transport === 'websocket') {
-      const wsUrl = options.wsUrl || (this.siteUrl ? this.siteUrl.replace(/^http/, 'ws') + '/ws' : null);
-      if (!wsUrl) throw new Error('wsUrl or siteUrl is required for websocket transport');
-      this._transport = new WebSocketTransport(wsUrl, headers);
-    } else if (transport === 'direct') {
-      if (!options.page) throw new Error('page option is required for direct transport');
-      this._transport = new DirectTransport(options.page);
-    } else {
-      if (!this.siteUrl) throw new Error('siteUrl is required for http transport');
-      this._transport = new HTTPTransport(this.siteUrl, headers);
-    }
-  }
-
-  // -----------------------------------------------------------------------
-  // Discovery
-  // -----------------------------------------------------------------------
-
-  /**
-   * Fetch the WAB discovery document from the site, trying multiple
-   * well-known paths in order.
-   *
-   * @param {string} [url] - Override URL to discover
-   * @returns {Promise<object>}
-   */
-  async discover(url) {
-    const base = url || this.siteUrl;
-    if (!base) throw new Error('No siteUrl configured and no url argument supplied');
-
-    let lastError;
-    for (const path of DISCOVERY_PATHS) {
-      try {
-        this._discovery = await jsonFetch(resolveUrl(base, path), {}, this.timeout);
-        this._extractActions(this._discovery);
-        return this._discovery;
-      } catch (err) {
-        lastError = err;
-      }
-    }
-
-    if (this.siteId) {
-      try {
-        this._discovery = await jsonFetch(
-          resolveUrl(base, `/api/discovery/${this.siteId}`), {}, this.timeout
-        );
-        this._extractActions(this._discovery);
-        return this._discovery;
-      } catch (err) { lastError = err; }
-    }
-
-    try {
-      this._discovery = await jsonFetch(
-        resolveUrl(base, '/api/wab/discover'), {}, this.timeout
-      );
-      if (this._discovery.result) this._discovery = this._discovery.result;
-      this._extractActions(this._discovery);
-      return this._discovery;
-    } catch (err) { lastError = err; }
-
-    throw new Error(`WAB discovery failed for ${base}: ${lastError?.message}`);
-  }
-
-  /** @private */
-  _extractActions(doc) {
-    const actions = doc.actions || doc.capabilities?.commands || doc.capabilities?.actions || [];
-    this._siteActions = Array.isArray(actions) ? actions.map(a => {
-      if (typeof a === 'string') return { name: a, description: `Permission: ${a}`, trigger: 'api' };
-      return a;
-    }) : [];
-  }
-
-  // -----------------------------------------------------------------------
-  // MCP tool interface
-  // -----------------------------------------------------------------------
-
-  /**
-   * Return the full set of MCP tool definitions — built-ins plus any
-   * site-specific action tools discovered from the WAB document.
-   *
-   * @returns {Promise<object[]>}
-   */
-  async getTools() {
-    if (!this._discovery && this.siteUrl) {
-      try { await this.discover(); } catch { /* built-ins still available */ }
-    }
-
-    const siteTools = this._siteActions.map(actionToTool);
-    return [...BUILTIN_TOOLS, ...siteTools];
-  }
-
-  /**
-   * Execute a single MCP tool call.
-   *
-   * @param {string} toolName  - MCP tool name (e.g. 'wab_discover')
-   * @param {object} input     - Tool input parameters
-   * @returns {Promise<object>}
-   */
-  async executeTool(toolName, input = {}) {
-    try {
-      const result = await this._dispatch(toolName, input);
-      return { type: 'tool_result', tool_use_id: toolName, content: result };
-    } catch (err) {
-      return { type: 'tool_result', tool_use_id: toolName, is_error: true, content: { error: err.message } };
-    }
-  }
-
-  /** @private Route a tool call to the appropriate handler. */
-  async _dispatch(name, input) {
-    switch (name) {
-      case 'wab_discover':
-        return this.discover(input.url);
-
-      case 'wab_get_actions':
-        return this._getActions(input.category);
-
-      case 'wab_execute_action':
-        return this._executeAction(input.name, input.params);
-
-      case 'wab_read_content':
-        return this._readContent(input.selector);
-
-      case 'wab_get_page_info':
-        return this._getPageInfo();
-
-      case 'wab_fairness_search':
-        return this._fairnessSearch(input.query, input.category, input.limit);
-
-      case 'wab_authenticate':
-        return this._authenticate(input.apiKey, input.meta);
-
-      default:
-        // Site-specific dynamic tools: strip `wab_` prefix and execute
-        if (name.startsWith('wab_')) {
-          const actionName = name.slice(4);
-          return this._executeAction(actionName, input);
-        }
-        throw new Error(`Unknown tool: ${name}`);
-    }
-  }
-
-  // -----------------------------------------------------------------------
-  // Core operations
-  // -----------------------------------------------------------------------
-
-  /** @private */
-  async _getActions(category) {
-    if (!this._discovery) await this.discover();
-    let actions = this._siteActions;
-    if (category) {
-      actions = actions.filter((a) => a.category === category);
-    }
-    return { actions };
-  }
-
-  /** @private */
-  async _executeAction(name, params) {
-    if (!name) throw new Error('Action name is required');
-
-    const headers = this._authHeaders();
-    if (this._transport instanceof HTTPTransport) {
-      const url = resolveUrl(this.siteUrl, `/api/wab/actions/${encodeURIComponent(name)}`);
-      return jsonFetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', ...headers },
-        body: JSON.stringify({ params: params || {} }),
-      }, this.timeout).then(r => r.result || r);
-    }
-
-    return this._transport.request(`/api/wab/actions/${name}`, { name, data: params || {} });
-  }
-
-  /** @private */
-  async _readContent(selector) {
-    if (!selector) throw new Error('CSS selector is required');
-
-    if (this._transport instanceof HTTPTransport) {
-      const url = resolveUrl(this.siteUrl, '/api/wab/read');
-      return jsonFetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', ...this._authHeaders() },
-        body: JSON.stringify({ selector }),
-      }, this.timeout).then(r => r.result || r);
-    }
-
-    return this._transport.request('/api/wab/read', { selector });
-  }
-
-  /** @private */
-  async _getPageInfo() {
-    if (this._transport instanceof HTTPTransport) {
-      const siteParam = this.siteId ? `?siteId=${this.siteId}` : '';
-      return jsonFetch(
-        resolveUrl(this.siteUrl, `/api/wab/page-info${siteParam}`),
-        { headers: this._authHeaders() }, this.timeout
-      ).then(r => r.result || r);
-    }
-    return this._transport.request('/api/wab/page-info');
-  }
-
-  // -----------------------------------------------------------------------
-  // Fairness registry
-  // -----------------------------------------------------------------------
-
-  /**
-   * Search the WAB discovery registry with fairness-weighted ranking so
-   * smaller and newer sites get equitable visibility alongside large ones.
-   *
-   * @param {string}  query
-   * @param {string}  [category]
-   * @param {number}  [limit=10]
-   * @returns {Promise<object>}
-   */
-  async _fairnessSearch(query, category, limit = 10) {
-    const params = new URLSearchParams({ q: query || '', limit: String(limit) });
-    if (category) params.set('category', category);
-
-    const base = this.siteUrl || this.registryUrl;
-    const result = await jsonFetch(`${base.replace(/\/+$/, '')}/api/wab/search?${params}`, {}, this.timeout);
-    return result.result || result;
-  }
-
-  // -----------------------------------------------------------------------
-  // Authentication
-  // -----------------------------------------------------------------------
-
-  /** @private */
-  async _authenticate(apiKey, meta) {
-    if (!apiKey) throw new Error('apiKey is required');
-
-    const payload = {
-      apiKey,
-      ...(this.siteId ? { siteId: this.siteId } : {}),
-      ...(meta ? { meta } : {})
-    };
-
-    if (this._transport instanceof HTTPTransport) {
-      const result = await jsonFetch(resolveUrl(this.siteUrl, '/api/wab/authenticate'), {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload),
-      }, this.timeout);
-      const data = result.result || result;
-      if (data.token) this._sessionToken = data.token;
-      return data;
-    }
-
-    const result = await this._transport.request('/api/wab/authenticate', payload);
-    const data = result.result || result;
-    if (data.token) this._sessionToken = data.token;
-    return data;
-  }
-
-  /** @private Build auth headers from session token and/or API key. */
-  _authHeaders() {
-    const h = {};
-    if (this._sessionToken) h['Authorization'] = `Bearer ${this._sessionToken}`;
-    if (this.apiKey) h['x-api-key'] = this.apiKey;
-    return h;
-  }
-
-  // -----------------------------------------------------------------------
-  // Lifecycle
-  // -----------------------------------------------------------------------
-
-  /** Clean up resources (e.g. open WebSocket connections). */
-  close() {
-    if (typeof this._transport.close === 'function') {
-      this._transport.close();
-    }
-  }
-}
-
-module.exports = { WABMCPAdapter, actionToTool, BUILTIN_TOOLS };