@tapicker/bridge 1.0.0

package/src/commands.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod'
+import { DEFAULT_WORKFLOW_WATCH_WS_PATH } from './constants.js'
+import { BridgeError } from './errors.js'
+import {
+  WorkflowControlInputSchema,
+  DataInputSchema,
+  WorkflowStartInputSchema,
+  WorkflowStartResultSchema,
+  WorkflowStatusDataSchema,
+  WorkflowWatchRequestSchema,
+} from './protocol/schema.js'
+import type { BridgeService } from './bridge/bridge-service.js'
+import type { WorkflowControlInput, WorkflowStartInput } from './protocol/schema.js'
+
+export type CommandContext = {
+  bridge: BridgeService
+}
+
+type CommandDefinition = {
+  description: string
+  schema: z.ZodType
+  execute: (input: unknown, context: CommandContext, clientId?: string) => Promise<unknown>
+}
+
+const CommandRequestSchema = z
+  .object({
+    clientId: z.uuid().optional(),
+    input: z.unknown(),
+  })
+  .strict()
+
+const commandDefinitions: Record<string, CommandDefinition> = {
+  'workflow.start': {
+    description: 'Start one Workflow in a selected connected Tapicker Extension',
+    schema: WorkflowStartInputSchema,
+    execute: async (input, context, clientId) => {
+      const { clientId: selectedClientId, result } = await context.bridge.sendCommandWithClientId(
+        'workflow.start',
+        input,
+        clientId,
+      )
+      if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow.start response', {
+          status: 502,
+        })
+      }
+
+      const parsed = WorkflowStartResultSchema.safeParse({ ...result, clientId: selectedClientId })
+      if (!parsed.success || parsed.data.workflowId !== (input as WorkflowStartInput).workflowId) {
+        throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow.start response', {
+          status: 502,
+          details: parsed.success
+            ? {
+                requestedWorkflowId: (input as WorkflowStartInput).workflowId,
+                returnedWorkflowId: parsed.data.workflowId,
+              }
+            : parsed.error.issues,
+        })
+      }
+
+      return parsed.data
+    },
+  },
+  'workflow.pause': {
+    description: 'Pause a running Workflow in a selected connected Tapicker Extension',
+    schema: WorkflowControlInputSchema,
+    execute: (input, context, clientId) => context.bridge.sendCommand('workflow.pause', input, clientId),
+  },
+  'workflow.resume': {
+    description: 'Resume a paused Workflow in a selected connected Tapicker Extension',
+    schema: WorkflowControlInputSchema,
+    execute: (input, context, clientId) => context.bridge.sendCommand('workflow.resume', input, clientId),
+  },
+  'workflow.stop': {
+    description: 'Stop a running Workflow in a selected connected Tapicker Extension',
+    schema: WorkflowControlInputSchema,
+    execute: (input, context, clientId) => context.bridge.sendCommand('workflow.stop', input, clientId),
+  },
+  'workflow.status': {
+    description: 'Get the current or most recently persisted Workflow status',
+    schema: WorkflowControlInputSchema,
+    execute: async (input, context, clientId) => {
+      const result = await context.bridge.sendCommand('workflow.status.get', input, clientId)
+      const parsed = WorkflowStatusDataSchema.safeParse(result)
+      if (!parsed.success || parsed.data.workflowId !== (input as WorkflowControlInput).workflowId) {
+        throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow status response', {
+          status: 502,
+          details: parsed.success ? undefined : parsed.error.issues,
+        })
+      }
+      return parsed.data
+    },
+  },
+  'data.get': {
+    description: 'Get an extracted data table by tableId; the rows count against the Extension export quota',
+    schema: DataInputSchema,
+    execute: (input, context, clientId) => context.bridge.sendCommand('data.get', input, clientId),
+  },
+  'data.delete': {
+    description: 'Delete an extracted data table by tableId',
+    schema: DataInputSchema,
+    execute: (input, context, clientId) => context.bridge.sendCommand('data.delete', input, clientId),
+  },
+}
+
+export function getCommandDefinition(name: string) {
+  return commandDefinitions[name]
+}
+
+export async function dispatchCommand(name: string, rawInput: unknown, context: CommandContext) {
+  const definition = getCommandDefinition(name)
+  if (!definition) {
+    throw new BridgeError('CommandNotFound', `Unsupported command: ${name}`, { status: 404 })
+  }
+
+  const request = CommandRequestSchema.safeParse(rawInput)
+  if (!request.success) {
+    throw new BridgeError('InvalidArguments', `Invalid command request for ${name}`, {
+      status: 400,
+      details: request.error.issues,
+    })
+  }
+
+  const parsed = definition.schema.safeParse(request.data.input)
+  if (!parsed.success) {
+    throw new BridgeError('InvalidArguments', `Invalid arguments for ${name}`, {
+      status: 400,
+      details: parsed.error.issues,
+    })
+  }
+
+  return definition.execute(parsed.data, context, request.data.clientId)
+}
+
+export function getCommandCapabilities() {
+  return [
+    ...Object.entries(commandDefinitions).map(([name, definition]) => ({
+      name,
+      description: definition.description,
+      inputSchema: z.toJSONSchema(
+        z
+          .object({
+            clientId: z.uuid().optional(),
+            input: definition.schema,
+          })
+          .strict(),
+        { io: 'input' },
+      ),
+    })),
+    {
+      name: 'workflow.watch',
+      description: 'Watch one Workflow through the workflow.watch WebSocket endpoint',
+      transport: 'websocket',
+      path: DEFAULT_WORKFLOW_WATCH_WS_PATH,
+      inputSchema: z.toJSONSchema(WorkflowWatchRequestSchema, { io: 'input' }),
+    },
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,10 @@
+export const VERSION = '1.0.0'
+export const PROTOCOL_VERSION = 1
+
+export const DEFAULT_HOST = '127.0.0.1'
+export const DEFAULT_PORT = 9520
+export const DEFAULT_PORT_MAX = 9530
+export const DEFAULT_WS_PATH = '/ws'
+export const DEFAULT_WORKFLOW_WATCH_WS_PATH = '/v1/commands/workflow.watch'
+export const DEFAULT_MCP_PATH = '/mcp'
+export const DEFAULT_REQUEST_TIMEOUT = 30_000

package/src/errors.ts

@@ -0,0 +1,72 @@
+export type BridgeErrorOptions = {
+  status?: number
+  details?: unknown
+  cause?: unknown
+}
+
+export type SerializedBridgeError = {
+  code: string
+  message: string
+  details?: unknown
+}
+
+export class BridgeError extends Error {
+  readonly code: string
+  readonly status: number
+  readonly details: unknown
+
+  constructor(code: string, message: string, options: BridgeErrorOptions = {}) {
+    super(message, { cause: options.cause })
+    this.name = 'BridgeError'
+    this.code = code
+    this.status = options.status ?? 400
+    this.details = options.details
+  }
+}
+
+export function toBridgeError(error: unknown, fallbackCode = 'InternalError', fallbackStatus = 500) {
+  if (error instanceof BridgeError) {
+    return error
+  }
+
+  if (error instanceof Error) {
+    return new BridgeError(fallbackCode, error.message, {
+      status: fallbackStatus,
+      cause: error,
+    })
+  }
+
+  return new BridgeError(fallbackCode, 'An unexpected error occurred', {
+    status: fallbackStatus,
+    details: error,
+    cause: error,
+  })
+}
+
+export function serializeBridgeError(error: unknown): SerializedBridgeError {
+  const bridgeError = toBridgeError(error)
+  const result: SerializedBridgeError = {
+    code: bridgeError.code,
+    message: bridgeError.message,
+  }
+
+  if (bridgeError.details !== undefined) {
+    result.details = bridgeError.details
+  }
+
+  return result
+}
+
+export function safeError(error: unknown) {
+  return {
+    ok: false as const,
+    error: serializeBridgeError(error),
+  }
+}
+
+export function safeSuccess<T>(data: T) {
+  return {
+    ok: true as const,
+    data,
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export { BridgeServer } from './server.js'
+export { BridgeService } from './bridge/bridge-service.js'
+export { ExtensionSession } from './bridge/extension-session.js'
+export { dispatchCommand, getCommandCapabilities, getCommandDefinition } from './commands.js'
+export { BridgeError, safeError, safeSuccess, serializeBridgeError } from './errors.js'
+export {
+  BridgeHelloDataSchema,
+  BridgePairDataSchema,
+  DataInputSchema,
+  ExtensionHelloInputSchema,
+  ExtensionPairInputSchema,
+  MessageEnvelopeSchema,
+  SafeResultSchema,
+  TabTargetSchema,
+  WorkflowControlInputSchema,
+  WorkflowLifecycleStateSchema,
+  WorkflowStatusEventSchema,
+  WorkflowStatusDataSchema,
+  WorkflowStartInputSchema,
+  WorkflowStartResultSchema,
+  WorkflowWatchRequestSchema,
+  createEnvelope,
+  parseEnvelope,
+} from './protocol/schema.js'
+export type {
+  DataInput,
+  WorkflowControlInput,
+  WorkflowStartInput,
+  WorkflowStartResult,
+  WorkflowStatusData,
+  WorkflowStatusEvent,
+  WorkflowWatchRequest,
+} from './protocol/schema.js'
+export { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js'
+export type { WorkflowWatchConnection, WorkflowWatchInput, WorkflowWatchResult } from './workflow-watch.js'

package/src/mcp.ts

@@ -0,0 +1,386 @@
+import { McpServer } from '@modelcontextprotocol/server'
+import { z } from 'zod'
+import { VERSION } from './constants.js'
+import { dispatchCommand } from './commands.js'
+import { BridgeError, safeError, safeSuccess } from './errors.js'
+import type { BridgeService } from './bridge/bridge-service.js'
+import { TabTargetSchema, WorkflowStatusEventSchema } from './protocol/schema.js'
+import type { WorkflowStatusEvent } from './protocol/schema.js'
+import { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js'
+import type { WorkflowWatchInput, WorkflowWatchResult } from './workflow-watch.js'
+
+export type TapickerMcpApi = {
+  executeCommand: (name: string, request: unknown) => Promise<unknown>
+  listExtensions: () => Promise<unknown[]>
+  watchWorkflow: (
+    input: WorkflowWatchInput,
+    onStatus: (event: WorkflowStatusEvent) => void,
+    signal?: AbortSignal,
+  ) => Promise<WorkflowWatchResult>
+}
+
+export function createBridgeMcpApi(bridge: BridgeService): TapickerMcpApi {
+  return {
+    executeCommand: (name, request) => dispatchCommand(name, request, { bridge }),
+    listExtensions: async () => bridge.getExtensionStatuses(),
+    watchWorkflow: (input, onStatus, signal) => {
+      const clientId = bridge.resolveCommandClientId('workflow.status', input.clientId)
+      return waitForWorkflowStatus({
+        clientId,
+        workflowId: input.workflowId,
+        subscribe: (handleStatus, _handleClose) => {
+          const listener = (event: WorkflowStatusEvent) => {
+            if (event.clientId === clientId && event.workflowId === input.workflowId) handleStatus(event)
+          }
+          bridge.on('workflow.status', listener)
+          return () => bridge.off('workflow.status', listener)
+        },
+        readStatus: async () => {
+          const status = await bridge.sendCommand<unknown>(
+            'workflow.status.get',
+            { workflowId: input.workflowId },
+            clientId,
+          )
+          return parseWorkflowStatusEvent(status, clientId, input.workflowId)
+        },
+        onStatus,
+        timeoutMs: input.timeoutMs,
+        signal,
+      })
+    },
+  }
+}
+
+export function createHttpMcpApi(baseUrl: string, token?: string): TapickerMcpApi {
+  const bridgeUrl = parseBridgeUrl(baseUrl)
+  const headers: Record<string, string> = {}
+  if (token) {
+    headers.Authorization = `Bearer ${token}`
+  }
+
+  const executeCommand = async (name: string, request: unknown) => {
+    const response = await fetchBridge(new URL(`/v1/commands/${encodeURIComponent(name)}`, bridgeUrl), {
+      method: 'POST',
+      headers: { ...headers, 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    })
+    const body = await readBridgeResponse(response)
+
+    if (!response.ok || !body.ok) {
+      throw new BridgeError(body.error?.code ?? 'BridgeRequestFailed', body.error?.message ?? response.statusText, {
+        status: response.status,
+        details: body.error?.details,
+      })
+    }
+
+    return body.data
+  }
+
+  return {
+    executeCommand,
+    listExtensions: async () => {
+      const response = await fetchBridge(new URL('/v1/extensions', bridgeUrl), { headers })
+      const body = await readBridgeResponse(response)
+
+      if (!response.ok || !Array.isArray(body.extensions)) {
+        throw new BridgeError(body.error?.code ?? 'BridgeRequestFailed', body.error?.message ?? response.statusText, {
+          status: response.status,
+          details: body.error?.details,
+        })
+      }
+
+      return body.extensions
+    },
+    watchWorkflow: async (input, onStatus, signal) => {
+      const connection = await connectWorkflowWatch(
+        workflowWatchWebSocketUrl(bridgeUrl),
+        { clientId: input.clientId, workflowId: input.workflowId },
+        token,
+        signal,
+      )
+      try {
+        return await waitForWorkflowStatus({
+          clientId: connection.clientId,
+          workflowId: input.workflowId,
+          subscribe: (handleStatus, handleClose) => {
+            const removeStatusListener = connection.onStatus(handleStatus)
+            const removeCloseListener = connection.onClose(handleClose)
+            return () => {
+              removeStatusListener()
+              removeCloseListener()
+            }
+          },
+          readStatus: async () => {
+            const status = await executeCommand('workflow.status', {
+              clientId: connection.clientId,
+              input: { workflowId: input.workflowId },
+            })
+            return parseWorkflowStatusEvent(status, connection.clientId, input.workflowId)
+          },
+          onStatus,
+          timeoutMs: input.timeoutMs,
+          signal,
+        })
+      } finally {
+        connection.close()
+      }
+    },
+  }
+}
+
+export function createTapickerMcpServer(api: TapickerMcpApi) {
+  const server = new McpServer({ name: 'tapicker-bridge', version: VERSION })
+
+  server.registerTool(
+    'extensions_list',
+    {
+      title: 'List connected Extensions',
+      description: 'List connected Tapicker Extensions and their clientId values for targeting Workflow commands.',
+      inputSchema: z.object({}).strict(),
+      annotations: { readOnlyHint: true },
+    },
+    async () => runTool(() => api.listExtensions()),
+  )
+
+  server.registerTool(
+    'workflow_start',
+    {
+      title: 'Start Workflow',
+      description:
+        'Start a Workflow in a connected Tapicker Extension. Returns the workflowId, full workflowName, and target clientId. If multiple Extensions are connected, provide clientId.',
+      inputSchema: z
+        .object({
+          workflowId: z.string().min(1).describe('The Workflow ID to start.'),
+          args: z.record(z.string(), z.unknown()).optional().describe('Optional Workflow input arguments.'),
+          tab: TabTargetSchema.optional().describe('Browser tab target; defaults to the active tab.'),
+          clientId: z
+            .uuid()
+            .optional()
+            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
+        })
+        .strict(),
+      annotations: { destructiveHint: true },
+    },
+    async ({ clientId, ...input }) => runTool(() => api.executeCommand('workflow.start', { clientId, input })),
+  )
+
+  for (const action of ['pause', 'resume', 'stop'] as const) {
+    server.registerTool(
+      `workflow_${action}`,
+      {
+        title: `${capitalize(action)} Workflow`,
+        description: `${capitalize(action)} a Workflow by workflowId. If multiple Extensions are connected, provide clientId.`,
+        inputSchema: z
+          .object({
+            workflowId: z.string().min(1).describe('The Workflow ID to control.'),
+            clientId: z
+              .uuid()
+              .optional()
+              .describe('Target Extension UUID; required when multiple Extensions are connected.'),
+          })
+          .strict(),
+        annotations: action === 'stop' ? { destructiveHint: true } : undefined,
+      },
+      async ({ clientId, ...input }) => runTool(() => api.executeCommand(`workflow.${action}`, { clientId, input })),
+    )
+  }
+
+  server.registerTool(
+    'workflow_status',
+    {
+      title: 'Get Workflow status',
+      description:
+        'Get the current or most recently persisted status for a Workflow. If multiple Extensions are connected, provide clientId.',
+      inputSchema: z
+        .object({
+          workflowId: z.string().min(1).describe('The Workflow ID to query.'),
+          clientId: z
+            .uuid()
+            .optional()
+            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
+        })
+        .strict(),
+      annotations: { readOnlyHint: true },
+    },
+    async ({ clientId, ...input }) => runTool(() => api.executeCommand('workflow.status', { clientId, input })),
+  )
+
+  server.registerTool(
+    'data_get',
+    {
+      title: 'Get extracted data',
+      description:
+        'Get all rows from an extracted data table by tableId. This consumes the export row quota of the connected Extension account. If multiple Extensions are connected, provide clientId.',
+      inputSchema: z
+        .object({
+          tableId: z.string().trim().min(1).max(128).describe('The data table ID copied from Tapicker Data.'),
+          clientId: z
+            .uuid()
+            .optional()
+            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
+        })
+        .strict(),
+    },
+    async ({ clientId, tableId }) => runTool(() => api.executeCommand('data.get', { clientId, input: { tableId } })),
+  )
+
+  server.registerTool(
+    'data_delete',
+    {
+      title: 'Delete extracted data',
+      description:
+        'Delete an extracted data table and remove it from Tapicker Data by tableId. If multiple Extensions are connected, provide clientId.',
+      inputSchema: z
+        .object({
+          tableId: z.string().trim().min(1).max(128).describe('The data table ID copied from Tapicker Data.'),
+          clientId: z
+            .uuid()
+            .optional()
+            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
+        })
+        .strict(),
+      annotations: { destructiveHint: true },
+    },
+    async ({ clientId, tableId }) => runTool(() => api.executeCommand('data.delete', { clientId, input: { tableId } })),
+  )
+
+  server.registerTool(
+    'workflow_watch',
+    {
+      title: 'Wait for Workflow completion',
+      description:
+        'Listen for Workflow status changes until it completes, stops, or fails. Returns the latest status when timeoutMs is reached. If multiple Extensions are connected, provide clientId.',
+      inputSchema: z
+        .object({
+          workflowId: z.string().min(1).describe('The Workflow ID to watch.'),
+          clientId: z
+            .uuid()
+            .optional()
+            .describe('Target Extension UUID; required when multiple Extensions are connected.'),
+          timeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .max(2_147_483_647)
+            .optional()
+            .describe('Optional maximum time to wait in milliseconds.'),
+        })
+        .strict(),
+      annotations: { readOnlyHint: true },
+    },
+    async ({ clientId, workflowId, timeoutMs }, context) => {
+      const progressToken = context.mcpReq._meta?.progressToken
+      let progress = 0
+      let notificationQueue = Promise.resolve()
+      return runTool(async () => {
+        const result = await api.watchWorkflow(
+          { clientId, workflowId, timeoutMs },
+          (event) => {
+            if (progressToken === undefined) return
+            progress += 1
+            notificationQueue = notificationQueue
+              .then(() =>
+                context.mcpReq.notify({
+                  method: 'notifications/progress',
+                  params: {
+                    progressToken,
+                    progress,
+                    message: `Workflow status: ${event.state}`,
+                  },
+                }),
+              )
+              .catch(() => undefined)
+          },
+          context.mcpReq.signal,
+        )
+        await notificationQueue
+        return result
+      })
+    },
+  )
+
+  return server
+}
+
+function parseWorkflowStatusEvent(value: unknown, clientId: string, workflowId: string) {
+  const parsed = WorkflowStatusEventSchema.safeParse({ ...(value as object), clientId })
+  if (!parsed.success || parsed.data.workflowId !== workflowId) {
+    throw new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid workflow status response', {
+      status: 502,
+      details: parsed.success ? undefined : parsed.error.issues,
+    })
+  }
+  return parsed.data
+}
+
+function capitalize(value: string) {
+  return `${value[0].toUpperCase()}${value.slice(1)}`
+}
+
+function parseBridgeUrl(value: string) {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch (cause) {
+    throw new BridgeError('InvalidBridgeUrl', 'Bridge URL must be a valid HTTP or HTTPS URL', { status: 400, cause })
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new BridgeError('InvalidBridgeUrl', 'Bridge URL must use HTTP or HTTPS', { status: 400 })
+  }
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new BridgeError('InvalidBridgeUrl', 'Bridge URL must contain only the HTTP(S) origin and port', {
+      status: 400,
+    })
+  }
+
+  return url
+}
+
+async function fetchBridge(url: URL, init: RequestInit) {
+  try {
+    return await fetch(url, { ...init, signal: AbortSignal.timeout(30_000) })
+  } catch (cause) {
+    throw new BridgeError('BridgeUnavailable', `Unable to reach Tapicker Bridge at ${url.origin}`, {
+      status: 503,
+      cause,
+    })
+  }
+}
+
+async function readBridgeResponse(response: Response) {
+  let body: {
+    ok?: boolean
+    data?: unknown
+    error?: { code?: string; message?: string; details?: unknown }
+    extensions?: unknown[]
+  }
+
+  try {
+    body = (await response.json()) as typeof body
+  } catch (cause) {
+    throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid JSON response', {
+      status: 502,
+      cause,
+    })
+  }
+
+  if (!body || typeof body !== 'object') {
+    throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid response', { status: 502 })
+  }
+
+  return body
+}
+
+async function runTool(operation: () => Promise<unknown>) {
+  try {
+    return {
+      content: [{ type: 'text' as const, text: JSON.stringify(safeSuccess(await operation()), null, 2) }],
+    }
+  } catch (error) {
+    return {
+      content: [{ type: 'text' as const, text: JSON.stringify(safeError(error), null, 2) }],
+      isError: true,
+    }
+  }
+}