@tapicker/bridge 1.0.0

package/dist/workflow-watch.js

@@ -0,0 +1,304 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocket } from 'ws';
+import { DEFAULT_WORKFLOW_WATCH_WS_PATH } from './constants.js';
+import { BridgeError } from './errors.js';
+import { SafeResultSchema, WorkflowStatusEventSchema, createEnvelope, parseEnvelope } from './protocol/schema.js';
+const terminalStates = new Set(['completed', 'stopped', 'failed']);
+export function workflowWatchWebSocketUrl(bridgeUrl) {
+    const url = new URL(DEFAULT_WORKFLOW_WATCH_WS_PATH, bridgeUrl);
+    url.protocol = bridgeUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url;
+}
+export function connectWorkflowWatch(url, input, token, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }));
+            return;
+        }
+        const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
+        const socket = new WebSocket(url, headers ? { headers } : undefined);
+        const requestId = randomUUID();
+        const statusListeners = new Set();
+        const closeListeners = new Set();
+        const pendingStatusEvents = [];
+        let acceptedClientId;
+        let settled = false;
+        let intentionalClose = false;
+        let closedError;
+        let abortListener;
+        const cleanupAbortListener = () => {
+            if (abortListener)
+                signal?.removeEventListener('abort', abortListener);
+            abortListener = undefined;
+        };
+        const failBeforeAccept = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanupAbortListener();
+            socket.terminate();
+            reject(error);
+        };
+        const notifyClose = (error) => {
+            closedError = error;
+            cleanupAbortListener();
+            for (const listener of closeListeners) {
+                try {
+                    listener(error);
+                }
+                catch {
+                    // A consumer callback must not escape the WebSocket event handler.
+                }
+            }
+            closeListeners.clear();
+        };
+        const close = (reason) => {
+            intentionalClose = true;
+            cleanupAbortListener();
+            if (socket.readyState === WebSocket.OPEN) {
+                socket.close(1000, 'Workflow watch closed');
+            }
+            else if (socket.readyState === WebSocket.CONNECTING) {
+                socket.terminate();
+            }
+            if (acceptedClientId) {
+                notifyClose(reason ?? new BridgeError('WorkflowWatchClosed', 'Workflow watch was closed by the client', { status: 499 }));
+            }
+        };
+        abortListener = () => {
+            const error = new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 });
+            if (!acceptedClientId) {
+                failBeforeAccept(error);
+            }
+            else {
+                close(error);
+            }
+        };
+        signal?.addEventListener('abort', abortListener, { once: true });
+        socket.once('open', () => {
+            socket.send(JSON.stringify(createEnvelope('workflow.watch', {
+                clientId: input.clientId,
+                input: { workflowId: input.workflowId },
+            }, { id: requestId })));
+        });
+        socket.on('message', (raw) => {
+            const parsedEnvelope = parseEnvelope(raw);
+            if (!parsedEnvelope.success) {
+                const error = new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow watch message', {
+                    status: 502,
+                    cause: parsedEnvelope.error,
+                });
+                if (!acceptedClientId)
+                    failBeforeAccept(error);
+                else {
+                    socket.close(1007, 'Invalid Workflow watch message');
+                    notifyClose(error);
+                }
+                return;
+            }
+            const message = parsedEnvelope.data;
+            if (message.type === 'workflow.watch:res' && message.id === requestId && !acceptedClientId) {
+                const result = SafeResultSchema.safeParse(message.data);
+                if (!result.success) {
+                    failBeforeAccept(new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow watch response', {
+                        status: 502,
+                    }));
+                    return;
+                }
+                if (!result.data.ok) {
+                    failBeforeAccept(new BridgeError(result.data.error.code, result.data.error.message, {
+                        status: 409,
+                        details: result.data.error.details,
+                    }));
+                    return;
+                }
+                const accepted = WorkflowStatusEventSchema.pick({ clientId: true, workflowId: true }).safeParse(result.data.data);
+                if (!accepted.success || accepted.data.workflowId !== input.workflowId) {
+                    failBeforeAccept(new BridgeError('InvalidBridgeResponse', 'Bridge accepted a different Workflow watch target', {
+                        status: 502,
+                    }));
+                    return;
+                }
+                acceptedClientId = accepted.data.clientId;
+                settled = true;
+                const connection = {
+                    clientId: accepted.data.clientId,
+                    workflowId: accepted.data.workflowId,
+                    onStatus(listener) {
+                        statusListeners.add(listener);
+                        for (const event of pendingStatusEvents.splice(0))
+                            listener(event);
+                        return () => statusListeners.delete(listener);
+                    },
+                    onClose(listener) {
+                        if (closedError) {
+                            listener(closedError);
+                            return () => undefined;
+                        }
+                        closeListeners.add(listener);
+                        return () => closeListeners.delete(listener);
+                    },
+                    close,
+                };
+                resolve(connection);
+                return;
+            }
+            if (message.type !== 'workflow.status' || !acceptedClientId)
+                return;
+            const event = WorkflowStatusEventSchema.safeParse(message.data);
+            if (!event.success)
+                return;
+            if (event.data.clientId !== acceptedClientId || event.data.workflowId !== input.workflowId)
+                return;
+            if (statusListeners.size === 0) {
+                if (pendingStatusEvents.length >= 128)
+                    pendingStatusEvents.shift();
+                pendingStatusEvents.push(event.data);
+            }
+            else {
+                for (const listener of statusListeners) {
+                    try {
+                        listener(event.data);
+                    }
+                    catch {
+                        // A consumer callback must not escape the WebSocket event handler.
+                    }
+                }
+            }
+        });
+        socket.once('unexpected-response', (_request, response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+            response.once('end', () => {
+                const body = Buffer.concat(chunks).toString('utf8');
+                let errorCode = 'BridgeRequestFailed';
+                let errorMessage = response.statusMessage || 'Bridge rejected the Workflow watch connection';
+                let details;
+                try {
+                    const parsed = JSON.parse(body);
+                    errorCode = parsed.error?.code || errorCode;
+                    errorMessage = parsed.error?.message || errorMessage;
+                    details = parsed.error?.details;
+                }
+                catch {
+                    // Keep the HTTP status text when the response is not Bridge JSON.
+                }
+                failBeforeAccept(new BridgeError(errorCode, errorMessage, { status: response.statusCode || 503, details }));
+            });
+        });
+        socket.on('error', (cause) => {
+            const error = new BridgeError('BridgeUnavailable', 'Unable to connect to Tapicker Bridge Workflow watch', {
+                status: 503,
+                cause,
+            });
+            if (!acceptedClientId)
+                failBeforeAccept(error);
+            else
+                notifyClose(error);
+        });
+        socket.once('close', (code, reason) => {
+            cleanupAbortListener();
+            if (!acceptedClientId) {
+                failBeforeAccept(new BridgeError('WorkflowWatchClosed', 'Bridge closed the Workflow watch connection before accepting it', {
+                    status: 503,
+                    details: { code, reason: reason.toString() },
+                }));
+            }
+            else if (!intentionalClose) {
+                notifyClose(new BridgeError('WorkflowWatchClosed', 'Bridge closed the Workflow watch connection', {
+                    status: 503,
+                    details: { code, reason: reason.toString() },
+                }));
+            }
+        });
+    });
+}
+export function waitForWorkflowStatus(options) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let latestStatus;
+        let timer;
+        let unsubscribe = () => { };
+        let abortListener;
+        const cleanup = () => {
+            unsubscribe();
+            if (timer)
+                clearTimeout(timer);
+            if (abortListener)
+                options.signal?.removeEventListener('abort', abortListener);
+        };
+        const finish = (status, timedOut = false) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve({ ...status, timedOut });
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const publish = (status) => {
+            if (settled)
+                return;
+            if (status.clientId !== options.clientId || status.workflowId !== options.workflowId)
+                return;
+            if (latestStatus && sameStatus(latestStatus, status))
+                return;
+            latestStatus = status;
+            try {
+                options.onStatus?.(status);
+            }
+            catch (error) {
+                fail(error);
+                return;
+            }
+            if (terminalStates.has(status.state))
+                finish(status);
+        };
+        if (options.signal?.aborted) {
+            fail(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }));
+            return;
+        }
+        unsubscribe = options.subscribe(publish, fail);
+        if (settled) {
+            unsubscribe();
+            return;
+        }
+        if (options.signal) {
+            abortListener = () => fail(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }));
+            options.signal.addEventListener('abort', abortListener, { once: true });
+        }
+        if (options.timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+                if (latestStatus)
+                    finish(latestStatus, true);
+                else
+                    fail(new BridgeError('WorkflowWatchTimeout', 'Timed out before receiving Workflow status', {
+                        status: 504,
+                        details: { timeoutMs: options.timeoutMs },
+                    }));
+            }, options.timeoutMs);
+        }
+        void options
+            .readStatus()
+            .then((snapshot) => {
+            if (settled)
+                return;
+            const snapshotIsAtLeastAsNew = latestStatus !== undefined && Date.parse(snapshot.updatedAt) >= Date.parse(latestStatus.updatedAt);
+            if (!latestStatus ||
+                snapshotIsAtLeastAsNew ||
+                (terminalStates.has(snapshot.state) && !terminalStates.has(latestStatus.state))) {
+                publish(snapshot);
+            }
+        })
+            .catch(fail);
+    });
+}
+function sameStatus(left, right) {
+    return left.state === right.state && left.updatedAt === right.updatedAt;
+}
+//# sourceMappingURL=workflow-watch.js.map

package/docs/cli.md

@@ -0,0 +1,112 @@
+# CLI Reference
+
+The examples below assume the package is installed globally and the `tapicker` command is available in `PATH`. Start with the [Getting Started guide](https://www.tapicker.com/docs/bridge-getting-started). Run `tapicker --help` or `tapicker <command> --help` for concise command help.
+
+## Start and Manage Bridge
+
+```bash
+tapicker bridge start [options]
+tapicker bridge stop [--data-dir <path>]
+tapicker bridge code [--refresh] [--data-dir <path>]
+tapicker bridge extensions [--data-dir <path>]
+```
+
+| Command                 | Purpose                                                                                         |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `bridge start`          | Run in the foreground; press `Ctrl+C` to stop. Prints the listening addresses and pairing code. |
+| `bridge start --daemon` | Run in the background.                                                                          |
+| `bridge stop`           | Stop a background Bridge.                                                                       |
+| `bridge code`           | Display the current four-digit pairing code.                                                    |
+| `bridge code --refresh` | Rotate the pairing code and unlock pairing after rate limiting.                                 |
+| `bridge extensions`     | List connected Extension clients, including clients that have not finished pairing.             |
+
+### `bridge start` Options
+
+| Option                                   | Default                                 | Description                                                             |
+| ---------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
+| `--host <host>`                          | `127.0.0.1`                             | Bind address. Non-loopback binding requires a Token and TLS.            |
+| `--port <port>`                          | First available port from `9520`–`9530` | Set a fixed listening port.                                             |
+| `--token <token>`                        | `TAPICKER_BRIDGE_TOKEN` or none         | Bearer Token for protected HTTP, MCP, and status subscription requests. |
+| `--cors-origin <origins>`                | `*`                                     | Comma-separated allowlist of HTTP origins.                              |
+| `--tls-key <path>` / `--tls-cert <path>` | None                                    | TLS private key and certificate; provide both for remote binding.       |
+| `--data-dir <path>`                      | `TAPICKER_DATA_DIR` or `~/.tapicker`    | Directory for pairing credentials and daemon files.                     |
+| `--daemon`                               | Off                                     | Run in the background.                                                  |
+
+If you use a custom `--data-dir`, pass the same directory to `stop`, `code`, and `extensions`.
+
+## Control a Workflow
+
+```bash
+tapicker workflow start <workflowId> [options]
+tapicker workflow pause <workflowId> [options]
+tapicker workflow resume <workflowId> [options]
+tapicker workflow stop <workflowId> [options]
+tapicker workflow status <workflowId> [options]
+tapicker workflow watch <workflowId> [options]
+```
+
+Start with an input object and stream status updates:
+
+```bash
+tapicker workflow start jr657xeb --args '{"keyword":"Tapicker"}' --watch
+```
+
+Other tab targets are `new` and `id:<positive-tabId>`:
+
+```bash
+tapicker workflow start jr657xeb --tab new
+tapicker workflow start jr657xeb --tab id:123
+```
+
+`--args` must be a JSON object. The default is `{}`. `--tab` defaults to `active`.
+
+| Option                     | Default                                         | Description                                                                  |
+| -------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| `--host <host>`            | `127.0.0.1`                                     | Bridge host.                                                                 |
+| `--port <port>`            | `9520`                                          | Bridge port. Pass the actual port if Bridge selected another one.            |
+| `--token <token>`          | None                                            | Bridge Bearer Token.                                                         |
+| `--client-id <uuid>`       | Auto-select when exactly one Extension is ready | Select an Extension when multiple are ready.                                 |
+| `--https`                  | Off                                             | Use HTTPS and WSS instead of HTTP and WS.                                    |
+| `--args <json>`            | `{}`                                            | Workflow input object; `start` only.                                         |
+| `--tab <target>`           | `active`                                        | `active`, `new`, or `id:<positive-tabId>`; `start` only.                     |
+| `--watch`                  | Off                                             | After starting, stream updates until a terminal state; `start` only.         |
+| `--timeout <milliseconds>` | No limit                                        | Limit how long `watch` or `start --watch` waits. Does not stop the Workflow. |
+
+`start --watch` establishes the watch before starting the Workflow to avoid missing initial status changes. `workflow watch` listens to a Workflow that is already running; it does not start or control it. A watch timeout or `Ctrl+C` ends only the listener, not the Workflow. Output is newline-delimited JSON.
+
+The start response includes `workflowId`, the full `workflowName`, and the selected `clientId`. A Workflow supports one active instance at a time in its Extension.
+
+## Select an Extension
+
+List clients first:
+
+```bash
+tapicker bridge extensions
+```
+
+Pass `--client-id <uuid>` to target one ready Extension. You can omit it only when exactly one ready Extension is connected. Pending pairing connections are not command targets. Bridge never broadcasts a command to every Extension.
+
+## Read or Delete Extracted Data
+
+```bash
+tapicker data get <tableId> [options]
+tapicker data delete <tableId> [options]
+```
+
+Get all rows from a data table:
+
+```bash
+tapicker data get 4a1b2c3d
+```
+
+`tableId` is copied from the Extension’s Data list or detail page. `data get` returns `tableId`, `tableName`, the row count, and all rows. The row count consumes the connected Extension account’s export quota; if quota is insufficient or unavailable, the command fails without returning the data. `data delete` removes the table from Tapicker Data.
+
+Data commands accept `--host`, `--port`, `--token`, `--client-id`, and `--https`.
+
+## Connect an MCP Client over stdio
+
+```bash
+tapicker mcp [--url <http(s)://host:port>] [--token <token>]
+```
+
+This starts an MCP stdio adapter that connects to an already-running Bridge over HTTP. It does not start another Bridge server. The default URL is `http://127.0.0.1:9520`; set `TAPICKER_BRIDGE_URL` and `TAPICKER_BRIDGE_TOKEN` in the MCP client environment when needed. See the [MCP guide](mcp.md) for client configuration examples.

package/docs/http-api.md

@@ -0,0 +1,149 @@
+# HTTP API Reference
+
+Bridge serves HTTP, WebSocket, and MCP from one port. The default local base URL is `http://127.0.0.1:9520`. At startup, Bridge tries ports `9520`–`9530` and prints the actual address. Use that address in every client.
+
+For installation and setup, see the [Getting Started guide](https://www.tapicker.com/docs/bridge-getting-started). For a short integration walkthrough, see [Connect an AI Agent](https://www.tapicker.com/docs/bridge-ai-agents).
+
+## Endpoints
+
+| Method / transport  | Path                          | Token required when configured? | Purpose                                                |
+| ------------------- | ----------------------------- | ------------------------------- | ------------------------------------------------------ |
+| `GET`               | `/v1/health`                  | No                              | Check Bridge health.                                   |
+| `GET`               | `/v1/discovery`               | No                              | Read Bridge metadata and the Extension WebSocket path. |
+| `GET`               | `/v1/capabilities`            | No                              | Discover commands and their input schemas.             |
+| `GET`               | `/v1/extensions`              | Yes                             | List connected Extension clients.                      |
+| `POST`              | `/v1/commands/{command}`      | Yes                             | Call a Workflow or data command.                       |
+| WebSocket           | `/v1/commands/workflow.watch` | Yes                             | Subscribe to one Workflow’s status events.             |
+| Streamable HTTP MCP | `/mcp`                        | Yes                             | Connect a remote MCP client.                           |
+| WebSocket           | `/ws`                         | Pairing credential              | Extension pairing and internal command transport.      |
+
+When Bridge is started with a Token, protected requests must include:
+
+```http
+Authorization: Bearer YOUR_TOKEN
+```
+
+`/ws` is for Tapicker Extension connections, not external Agent commands. It uses the pairing code and saved Extension credential, not the HTTP Bearer Token.
+
+## CORS and Local Security
+
+HTTP and `/mcp` allow all web origins by default (`--cors-origin *`) and support browser `OPTIONS` preflight requests. Use one comma-separated allowlist to restrict origins:
+
+```bash
+tapicker bridge start --cors-origin https://agent.example.com,https://app.example.com
+```
+
+CORS is not authentication. The default local Bridge has no Bearer Token, so a web page may be able to call its local HTTP API. Keep Bridge bound to `127.0.0.1`, and set an origin allowlist when browser access should be limited. WebSocket connections do not use CORS.
+
+## Discover Bridge and Extensions
+
+```bash
+curl http://127.0.0.1:9520/v1/health
+curl http://127.0.0.1:9520/v1/discovery
+curl http://127.0.0.1:9520/v1/capabilities
+curl http://127.0.0.1:9520/v1/extensions
+```
+
+`/v1/health` reports Bridge health, not Extension readiness. `/v1/extensions` returns connected clients, for example:
+
+```json
+{
+  "extensions": [
+    {
+      "clientId": "56a450e6-41f1-448e-9ea7-a2d958cbda37",
+      "clientName": "MacOS.Chrome.152.a1b2",
+      "connected": true,
+      "ready": true,
+      "pairingRequired": false,
+      "capabilities": ["workflow.start", "workflow.pause"]
+    }
+  ]
+}
+```
+
+Only `ready: true` clients can receive commands. The list does not expose pairing codes or saved credentials. Add the Bearer header to `/v1/extensions` when a Token is configured.
+
+`/v1/capabilities` lists supported commands, descriptions, JSON input schemas, and the WebSocket path for `workflow.watch`.
+
+## Call a Command
+
+All HTTP command requests use this shape:
+
+```json
+{
+  "clientId": "optional-extension-uuid",
+  "input": {
+    "workflowId": "jr657xeb"
+  }
+}
+```
+
+`clientId` is optional only when exactly one ready Extension is connected. If multiple are ready, specify one; Bridge returns `409 ClientIdRequired` rather than broadcasting the command. Pending pairing connections are not eligible targets.
+
+| Command           | `input`                                                                                              |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `workflow.start`  | `workflowId`; optional `args` object (default `{}`); optional `tab` (default `{ "mode": "active" }`) |
+| `workflow.pause`  | `workflowId`                                                                                         |
+| `workflow.resume` | `workflowId`                                                                                         |
+| `workflow.stop`   | `workflowId`                                                                                         |
+| `workflow.status` | `workflowId`                                                                                         |
+| `data.get`        | `tableId`                                                                                            |
+| `data.delete`     | `tableId`                                                                                            |
+
+`tab` can be `{ "mode": "active" }`, `{ "mode": "new" }`, or `{ "mode": "id", "tabId": 123 }`.
+
+Start a Workflow:
+
+```bash
+curl -X POST http://127.0.0.1:9520/v1/commands/workflow.start \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"workflowId":"jr657xeb","args":{"keyword":"Tapicker"},"tab":{"mode":"active"}}}'
+```
+
+If a Token is configured, add `-H 'Authorization: Bearer YOUR_TOKEN'`.
+
+Pause, resume, stop, and status use the same request format. For example:
+
+```bash
+curl -X POST http://127.0.0.1:9520/v1/commands/workflow.pause \
+  -H 'Content-Type: application/json' \
+  -d '{"clientId":"56a450e6-41f1-448e-9ea7-a2d958cbda37","input":{"workflowId":"jr657xeb"}}'
+```
+
+A successful start response includes the selected `clientId`, `workflowId`, full `workflowName`, and an accepted state. Other successful responses use `{ "ok": true, "data": ... }`. Errors use `{ "ok": false, "error": { "code", "message", "details?" } }`.
+
+## Read or Delete a Data Table
+
+Use the `tableId` copied from the Extension’s Data list or detail page:
+
+```bash
+curl -X POST http://127.0.0.1:9520/v1/commands/data.get \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"tableId":"4a1b2c3d"}}'
+```
+
+`data.get` returns `tableId`, `tableName`, `count`, and all `rows`. The row count consumes the connected Extension account’s export quota. If the quota is insufficient or unavailable, Bridge returns an error without the data.
+
+Delete a table with `POST /v1/commands/data.delete` and the same `input` shape. It removes the table from Tapicker Data; verify the `tableId` before deleting. The success response contains `tableId` and `tableName`.
+
+## Get Workflow Status
+
+`workflow.status` returns one snapshot with `workflowId`, `state`, and ISO-formatted `updatedAt`. States include `running`, `paused`, `stopping`, `completed`, `stopped`, and `failed`.
+
+For ongoing updates, subscribe to the WebSocket endpoint `/v1/commands/workflow.watch` instead of repeatedly calling `workflow.status`. After reconnecting, call `workflow.status` once to get the latest snapshot. See [Workflow Status WebSocket](workflow-watch.md).
+
+The `workflow.watch` path requires a WebSocket upgrade; a regular HTTP request returns `405 WebSocketRequired`.
+
+## Common Errors
+
+| HTTP status | Example codes                                                                 | Meaning                                                |
+| ----------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `400`       | `InvalidArguments`, `InvalidJson`                                             | The request body or command input is invalid.          |
+| `401`       | `Unauthorized`                                                                | A required Bearer Token is missing or invalid.         |
+| `404`       | `NotFound`, `CommandNotFound`                                                 | The endpoint or command does not exist.                |
+| `409`       | `ClientIdRequired`, `ExtensionNotConnected`, `ExtensionCapabilityUnavailable` | Select a ready Extension or check its availability.    |
+| `502`       | `ExportQuotaExceeded`                                                         | Reading the table exceeded the account’s export quota. |
+| `503`       | `ExtensionUnavailable`                                                        | No paired, ready Extension is connected.               |
+| `504`       | `ExtensionRequestTimeout`                                                     | The Extension did not respond in time.                 |
+
+Use the returned `error.code` and `error.message` as the source of truth for a specific failure.

package/docs/mcp.md

@@ -0,0 +1,90 @@
+# MCP Guide
+
+Tapicker Bridge exposes Workflow and data commands as MCP tools. The Bridge must already be running, and the target Tapicker Extension must be paired and ready.
+
+For a first-time setup, follow the [Getting Started guide](https://www.tapicker.com/docs/bridge-getting-started). For an overview of the user flow, see [Connect an AI Agent](https://www.tapicker.com/docs/bridge-ai-agents).
+
+## Choose a Transport
+
+| Transport       | How the agent connects                                               | Best for                                               |
+| --------------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
+| stdio           | The agent starts `tapicker mcp`, which connects to Bridge over HTTP. | An agent running on the same computer as Bridge.       |
+| Streamable HTTP | The agent connects directly to `https://<host>:<port>/mcp`.          | A remote Bridge and an agent that supports remote MCP. |
+
+Both transports expose the same tools. The stdio adapter does not start a Bridge server.
+
+## Local MCP over stdio
+
+Start Bridge separately, then add an MCP server entry to your agent configuration:
+
+```json
+{
+  "mcpServers": {
+    "tapicker": {
+      "command": "tapicker",
+      "args": ["mcp"],
+      "env": {
+        "TAPICKER_BRIDGE_URL": "http://127.0.0.1:9520"
+      }
+    }
+  }
+}
+```
+
+Restart or reload the agent after changing its configuration. The CLI defaults to `http://127.0.0.1:9520`; if Bridge selected another port, update `TAPICKER_BRIDGE_URL` to the actual HTTP address printed at startup.
+
+When the Bridge uses a Token, add `TAPICKER_BRIDGE_TOKEN` to the MCP server environment. Prefer environment variables or your agent’s secret store over putting a Token in a shared config file.
+
+If the agent cannot find `tapicker`, set `command` to the absolute path of the installed executable. When running from a source checkout, use `node` as the command and the absolute path to `dist/cli.js` followed by `mcp` as the arguments.
+
+You can also launch the adapter manually:
+
+```bash
+tapicker mcp --url http://127.0.0.1:9520
+```
+
+## Remote MCP over Streamable HTTP
+
+The MCP endpoint uses the same port as HTTP and WebSocket:
+
+```text
+https://bridge.example.com:9520/mcp
+```
+
+Configure the agent’s remote MCP connection with this URL. If Bridge uses a Token, configure this request header:
+
+```http
+Authorization: Bearer YOUR_TOKEN
+```
+
+Remote deployments require TLS and a Bearer Token. See [Pairing, Configuration, and Security](operations.md).
+
+## Available Tools
+
+| Tool              | Parameters                                       | Purpose                                                       |
+| ----------------- | ------------------------------------------------ | ------------------------------------------------------------- |
+| `extensions_list` | None                                             | List Extension clients and find a target `clientId`.          |
+| `workflow_start`  | `workflowId`, optional `args`, `tab`, `clientId` | Start a Workflow. Returns when the start request is accepted. |
+| `workflow_pause`  | `workflowId`, optional `clientId`                | Pause an active Workflow.                                     |
+| `workflow_resume` | `workflowId`, optional `clientId`                | Resume a paused Workflow.                                     |
+| `workflow_stop`   | `workflowId`, optional `clientId`                | Stop an active Workflow.                                      |
+| `workflow_status` | `workflowId`, optional `clientId`                | Get one current or most recently persisted status snapshot.   |
+| `workflow_watch`  | `workflowId`, optional `clientId`, `timeoutMs`   | Wait for status updates until a terminal state or timeout.    |
+| `data_get`        | `tableId`, optional `clientId`                   | Read all rows from a data table; consumes export quota.       |
+| `data_delete`     | `tableId`, optional `clientId`                   | Delete a data table from Tapicker Data.                       |
+
+`workflow_start.tab` accepts `{ "mode": "active" }`, `{ "mode": "new" }`, or `{ "mode": "id", "tabId": 123 }`; it defaults to the active tab. `args` must be an object.
+
+`data_get` returns `tableId`, `tableName`, and all rows. The row count consumes the connected Extension account’s export quota; when the quota is insufficient or unavailable, the operation fails without returning data. `data_delete` removes the table, so verify the `tableId` first.
+
+## Select an Extension
+
+If exactly one ready Extension is connected, `clientId` can be omitted. If multiple are ready, call `extensions_list` and pass the chosen `clientId` to the command. Pending pairing connections may appear in the list but are not command targets. Bridge sends each command to one Extension; it does not broadcast.
+
+## Watch a Long-Running Workflow
+
+`workflow_start` returns after the Extension accepts the start request. Then call `workflow_watch` to wait for updates without repeatedly calling `workflow_status`. Its terminal states are `completed`, `stopped`, and `failed`.
+
+When supported by the MCP client, Bridge also reports intermediate status updates as progress. A `timeoutMs` expiration returns the latest known status with `timedOut: true`. Cancelling the watch stops waiting only; it does not stop the Workflow. Use `workflow_status` when you need a single snapshot.
+
+The equivalent HTTP/WebSocket protocol is documented in [Workflow Status WebSocket](workflow-watch.md).