@tapicker/bridge 1.0.0 → 1.1.0

package/dist/workflow-watch.js

@@ -1,18 +1,17 @@
 import { randomUUID } from 'node:crypto';
 import { WebSocket } from 'ws';
-import { DEFAULT_WORKFLOW_WATCH_WS_PATH } from './constants.js';
+import { DEFAULT_WORKFLOW_STATUS_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);
+export function workflowStatusWatchWebSocketUrl(bridgeUrl) {
+    const url = new URL(DEFAULT_WORKFLOW_STATUS_WATCH_WS_PATH, bridgeUrl);
     url.protocol = bridgeUrl.protocol === 'https:' ? 'wss:' : 'ws:';
     return url;
 }
-export function connectWorkflowWatch(url, input, token, signal) {
+export function connectWorkflowStatusWatch(url, input, token, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
-            reject(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }));
+            reject(new BridgeError('WorkflowStatusWatchCancelled', 'Workflow status watch was cancelled', { status: 499 }));
             return;
         }
         const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
@@ -56,17 +55,22 @@ export function connectWorkflowWatch(url, input, token, signal) {
             intentionalClose = true;
             cleanupAbortListener();
             if (socket.readyState === WebSocket.OPEN) {
-                socket.close(1000, 'Workflow watch closed');
+                socket.close(1000, 'Workflow status 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 }));
+                notifyClose(reason ??
+                    new BridgeError('WorkflowStatusWatchClosed', 'Workflow status watch was closed by the client', {
+                        status: 499,
+                    }));
             }
         };
         abortListener = () => {
-            const error = new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 });
+            const error = new BridgeError('WorkflowStatusWatchCancelled', 'Workflow status watch was cancelled', {
+                status: 499,
+            });
             if (!acceptedClientId) {
                 failBeforeAccept(error);
             }
@@ -76,7 +80,7 @@ export function connectWorkflowWatch(url, input, token, signal) {
         };
         signal?.addEventListener('abort', abortListener, { once: true });
         socket.once('open', () => {
-            socket.send(JSON.stringify(createEnvelope('workflow.watch', {
+            socket.send(JSON.stringify(createEnvelope('workflow.status.watch', {
                 clientId: input.clientId,
                 input: { workflowId: input.workflowId },
             }, { id: requestId })));
@@ -84,23 +88,23 @@ export function connectWorkflowWatch(url, input, token, signal) {
         socket.on('message', (raw) => {
             const parsedEnvelope = parseEnvelope(raw);
             if (!parsedEnvelope.success) {
-                const error = new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow watch message', {
+                const error = new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow status watch message', {
                     status: 502,
                     cause: parsedEnvelope.error,
                 });
                 if (!acceptedClientId)
                     failBeforeAccept(error);
                 else {
-                    socket.close(1007, 'Invalid Workflow watch message');
+                    socket.close(1007, 'Invalid Workflow status watch message');
                     notifyClose(error);
                 }
                 return;
             }
             const message = parsedEnvelope.data;
-            if (message.type === 'workflow.watch:res' && message.id === requestId && !acceptedClientId) {
+            if (message.type === 'workflow.status.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', {
+                    failBeforeAccept(new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow status watch response', {
                         status: 502,
                     }));
                     return;
@@ -114,7 +118,7 @@ export function connectWorkflowWatch(url, input, token, signal) {
                 }
                 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', {
+                    failBeforeAccept(new BridgeError('InvalidBridgeResponse', 'Bridge accepted a different Workflow status watch target', {
                         status: 502,
                     }));
                     return;
@@ -143,7 +147,7 @@ export function connectWorkflowWatch(url, input, token, signal) {
                 resolve(connection);
                 return;
             }
-            if (message.type !== 'workflow.status' || !acceptedClientId)
+            if (message.type !== 'workflow.status.changed' || !acceptedClientId)
                 return;
             const event = WorkflowStatusEventSchema.safeParse(message.data);
             if (!event.success)
@@ -172,7 +176,7 @@ export function connectWorkflowWatch(url, input, token, signal) {
             response.once('end', () => {
                 const body = Buffer.concat(chunks).toString('utf8');
                 let errorCode = 'BridgeRequestFailed';
-                let errorMessage = response.statusMessage || 'Bridge rejected the Workflow watch connection';
+                let errorMessage = response.statusMessage || 'Bridge rejected the Workflow status watch connection';
                 let details;
                 try {
                     const parsed = JSON.parse(body);
@@ -187,7 +191,7 @@ export function connectWorkflowWatch(url, input, token, signal) {
             });
         });
         socket.on('error', (cause) => {
-            const error = new BridgeError('BridgeUnavailable', 'Unable to connect to Tapicker Bridge Workflow watch', {
+            const error = new BridgeError('BridgeUnavailable', 'Unable to connect to Tapicker Bridge Workflow status watch', {
                 status: 503,
                 cause,
             });
@@ -199,13 +203,13 @@ export function connectWorkflowWatch(url, input, token, signal) {
         socket.once('close', (code, reason) => {
             cleanupAbortListener();
             if (!acceptedClientId) {
-                failBeforeAccept(new BridgeError('WorkflowWatchClosed', 'Bridge closed the Workflow watch connection before accepting it', {
+                failBeforeAccept(new BridgeError('WorkflowStatusWatchClosed', 'Bridge closed the Workflow status 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', {
+                notifyClose(new BridgeError('WorkflowStatusWatchClosed', 'Bridge closed the Workflow status watch connection', {
                     status: 503,
                     details: { code, reason: reason.toString() },
                 }));
@@ -227,12 +231,12 @@ export function waitForWorkflowStatus(options) {
             if (abortListener)
                 options.signal?.removeEventListener('abort', abortListener);
         };
-        const finish = (status, timedOut = false) => {
+        const finish = (status, isTimedOut = false) => {
             if (settled)
                 return;
             settled = true;
             cleanup();
-            resolve({ ...status, timedOut });
+            resolve({ ...status, isTimedOut });
         };
         const fail = (error) => {
             if (settled)
@@ -246,6 +250,8 @@ export function waitForWorkflowStatus(options) {
                 return;
             if (status.clientId !== options.clientId || status.workflowId !== options.workflowId)
                 return;
+            if (options.runAt !== undefined && status.runAt !== options.runAt)
+                return;
             if (latestStatus && sameStatus(latestStatus, status))
                 return;
             latestStatus = status;
@@ -256,11 +262,11 @@ export function waitForWorkflowStatus(options) {
                 fail(error);
                 return;
             }
-            if (terminalStates.has(status.state))
+            if (status.status === 'stopped')
                 finish(status);
         };
         if (options.signal?.aborted) {
-            fail(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }));
+            fail(new BridgeError('WorkflowStatusWatchCancelled', 'Workflow status watch was cancelled', { status: 499 }));
             return;
         }
         unsubscribe = options.subscribe(publish, fail);
@@ -269,7 +275,7 @@ export function waitForWorkflowStatus(options) {
             return;
         }
         if (options.signal) {
-            abortListener = () => fail(new BridgeError('WorkflowWatchCancelled', 'Workflow watch was cancelled', { status: 499 }));
+            abortListener = () => fail(new BridgeError('WorkflowStatusWatchCancelled', 'Workflow status watch was cancelled', { status: 499 }));
             options.signal.addEventListener('abort', abortListener, { once: true });
         }
         if (options.timeoutMs !== undefined) {
@@ -277,13 +283,13 @@ export function waitForWorkflowStatus(options) {
                 if (latestStatus)
                     finish(latestStatus, true);
                 else
-                    fail(new BridgeError('WorkflowWatchTimeout', 'Timed out before receiving Workflow status', {
+                    fail(new BridgeError('WorkflowStatusWatchTimeout', 'Timed out before receiving Workflow status', {
                         status: 504,
                         details: { timeoutMs: options.timeoutMs },
                     }));
             }, options.timeoutMs);
         }
-        void options
+        options
             .readStatus()
             .then((snapshot) => {
             if (settled)
@@ -291,7 +297,7 @@ export function waitForWorkflowStatus(options) {
             const snapshotIsAtLeastAsNew = latestStatus !== undefined && Date.parse(snapshot.updatedAt) >= Date.parse(latestStatus.updatedAt);
             if (!latestStatus ||
                 snapshotIsAtLeastAsNew ||
-                (terminalStates.has(snapshot.state) && !terminalStates.has(latestStatus.state))) {
+                (snapshot.status === 'stopped' && latestStatus.status !== 'stopped')) {
                 publish(snapshot);
             }
         })
@@ -299,6 +305,10 @@ export function waitForWorkflowStatus(options) {
     });
 }
 function sameStatus(left, right) {
-    return left.state === right.state && left.updatedAt === right.updatedAt;
+    return (left.status === right.status &&
+        left.reason === right.reason &&
+        left.runAt === right.runAt &&
+        left.stopAt === right.stopAt &&
+        left.updatedAt === right.updatedAt);
 }
 //# sourceMappingURL=workflow-watch.js.map

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@tapicker/bridge",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Tapicker local and remote command bridge",
-  "homepage": "https://www.tapicker.com/",
+  "keywords": [
+    "tapicker",
+    "web-automation",
+    "browser-automation",
+    "web-scraping",
+    "data-extraction",
+    "chrome-extension",
+    "ai-agents",
+    "mcp",
+    "mcp-server",
+    "cli"
+  ],
+  "homepage": "https://www.tapicker.com",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -19,9 +31,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "src",
-    "README.md",
-    "docs"
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -49,7 +59,7 @@
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.13",
     "prettier": "^3.6.0",
-    "typescript": "^5.9.0",
+    "typescript": "6.0.3",
     "vitest": "^4.0.0"
   }
 }

package/docs/cli.md

@@ -1,112 +0,0 @@
-# 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

@@ -1,149 +0,0 @@
-# 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

@@ -1,90 +0,0 @@
-# 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).