@hypothesi/tauri-mcp-server 0.9.0 → 0.11.0

package/README.md

@@ -52,6 +52,18 @@ npx -y install-mcp @hypothesi/tauri-mcp-server --client claude-code
 
 Supported clients: `claude-code`, `cursor`, `windsurf`, `vscode`, `cline`, `roo-cline`, `claude`, `zed`, `goose`, `warp`, `codex`
 
+## Terminal CLI
+
+If you want to call the same tools directly from a shell, install the companion CLI package:
+
+```bash
+npm install -g @hypothesi/tauri-mcp-cli
+tauri-mcp driver-session start --port 9223
+tauri-mcp driver-session status --json
+```
+
+The CLI keeps the underlying MCP server warm in the background so stateful commands such as `driver_session` work across separate invocations.
+
 ## Multi-App Support
 
 The MCP server supports connecting to multiple Tauri apps simultaneously. Each app runs on a unique port, and the most recently connected app becomes the "default" app.

package/dist/api.d.ts

@@ -0,0 +1,2 @@
+export { TOOLS } from './tools-registry.js';
+export { createMcpServer, getCliToolDefinitions, startStdioServer } from './server.js';

package/dist/api.js

@@ -0,0 +1,2 @@
+export { TOOLS } from './tools-registry.js';
+export { createMcpServer, getCliToolDefinitions, startStdioServer } from './server.js';

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Configuration for the MCP Bridge connection.
+ *
+ * This module provides configuration options for connecting to Tauri apps,
+ * with support for environment variables and sensible defaults.
+ */
+export interface BridgeConfig {
+    host: string;
+    port: number;
+}
+/**
+ * Gets the default host for MCP Bridge connections.
+ *
+ * Resolution priority:
+ * 1. MCP_BRIDGE_HOST environment variable
+ * 2. TAURI_DEV_HOST environment variable (set by Tauri CLI for mobile dev)
+ * 3. 'localhost' (default)
+ */
+export declare function getDefaultHost(): string;
+/**
+ * Gets the default port for MCP Bridge connections.
+ *
+ * Resolution priority:
+ * 1. MCP_BRIDGE_PORT environment variable
+ * 2. 9223 (default)
+ */
+export declare function getDefaultPort(): number;
+/**
+ * Gets the full bridge configuration from environment variables.
+ */
+export declare function getConfig(): BridgeConfig;
+/**
+ * Builds a WebSocket URL from host and port.
+ */
+export declare function buildWebSocketURL(host: string, port: number): string;

package/dist/driver/app-discovery.d.ts

@@ -0,0 +1,75 @@
+/**
+ * App discovery and session management for multiple Tauri instances.
+ *
+ * This module handles discovering and connecting to multiple Tauri apps
+ * running with MCP Bridge on the same machine or remote devices using port scanning.
+ */
+import { PluginClient } from './plugin-client.js';
+export interface AppInstance {
+    host: string;
+    port: number;
+    available: boolean;
+}
+export interface SessionInfo {
+    appId: string;
+    name: string;
+    host: string;
+    port: number;
+    client?: PluginClient;
+    connected: boolean;
+}
+/**
+ * Manages discovery and connection to multiple Tauri app instances
+ */
+export declare class AppDiscovery {
+    private _activeSessions;
+    private _host;
+    private _basePort;
+    private _maxPorts;
+    constructor(host?: string, basePort?: number);
+    /**
+     * Gets the configured host.
+     */
+    get host(): string;
+    /**
+     * Sets the host for discovery.
+     */
+    setHost(host: string): void;
+    /**
+     * Discovers available Tauri app instances by scanning ports
+     */
+    discoverApps(): Promise<AppInstance[]>;
+    /**
+     * Connects to a specific app on a host and port
+     */
+    connectToPort(port: number, appName?: string, host?: string): Promise<SessionInfo>;
+    /**
+     * Gets the first available app
+     */
+    getFirstAvailableApp(): Promise<AppInstance | null>;
+    /**
+     * Disconnects from a specific session
+     */
+    disconnectSession(sessionId: string): Promise<void>;
+    /**
+     * Disconnects from all apps
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Gets the active session by ID
+     */
+    getSession(sessionId: string): SessionInfo | undefined;
+    /**
+     * Gets all active sessions
+     */
+    getAllSessions(): SessionInfo[];
+    /**
+     * Try to connect to the default port
+     */
+    connectToDefaultPort(): Promise<SessionInfo>;
+    /**
+     * Check if a port is in use (likely a Tauri app)
+     */
+    private _isPortInUse;
+}
+export declare const appDiscovery: AppDiscovery;

package/dist/driver/element-picker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Element picker module for MCP Server Tauri.
+ *
+ * Provides two tools:
+ * - selectElement: Agent-initiated picker overlay (user clicks element)
+ * - getPointedElement: Retrieve element user pointed at via Alt+Shift+Click
+ */
+import { z } from 'zod';
+import type { ToolContent } from '../tools-registry.js';
+export declare const SelectElementSchema: z.ZodObject<{
+    windowId: z.ZodOptional<z.ZodString>;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+} & {
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    windowId?: string | undefined;
+    appIdentifier?: string | number | undefined;
+}, {
+    windowId?: string | undefined;
+    appIdentifier?: string | number | undefined;
+    timeout?: number | undefined;
+}>;
+export declare const GetPointedElementSchema: z.ZodObject<{
+    windowId: z.ZodOptional<z.ZodString>;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    windowId?: string | undefined;
+    appIdentifier?: string | number | undefined;
+}, {
+    windowId?: string | undefined;
+    appIdentifier?: string | number | undefined;
+}>;
+export declare function selectElement(options: {
+    timeout?: number;
+    windowId?: string;
+    appIdentifier?: string | number;
+}): Promise<ToolContent[]>;
+export declare function getPointedElement(options: {
+    windowId?: string;
+    appIdentifier?: string | number;
+}): Promise<ToolContent[]>;

package/dist/driver/element-picker.js

@@ -99,13 +99,13 @@ async function cleanupPickerHighlights(windowId, appIdentifier) {
  * Capture a screenshot of a specific element using html2canvas.
  * Returns the base64 data URL of the cropped element image, or null on failure.
  */
-async function captureElementScreenshot(cssSelector, windowId) {
+async function captureElementScreenshot(cssSelector, windowId, appIdentifier) {
     // Ensure html2canvas is loaded in the webview
     try {
-        const isRegistered = await isScriptRegistered(HTML2CANVAS_SCRIPT_ID);
+        const isRegistered = await isScriptRegistered(HTML2CANVAS_SCRIPT_ID, appIdentifier);
         if (!isRegistered) {
             const source = getHtml2CanvasSource();
-            await registerScript(HTML2CANVAS_SCRIPT_ID, 'inline', source);
+            await registerScript(HTML2CANVAS_SCRIPT_ID, 'inline', source, windowId, appIdentifier);
         }
     }
     catch {
@@ -149,7 +149,7 @@ async function captureElementScreenshot(cssSelector, windowId) {
       return dataUrl;
    `;
     try {
-        const dataUrl = await executeAsyncInWebview(captureScript, windowId, 10000);
+        const dataUrl = await executeAsyncInWebview(captureScript, windowId, 10000, appIdentifier);
         if (!dataUrl || !dataUrl.startsWith('data:image/')) {
             return null;
         }
@@ -221,7 +221,7 @@ export async function selectElement(options) {
     // Add formatted metadata
     content.push({ type: 'text', text: formatElementMetadata(element) });
     // Capture element-only screenshot (no picker overlays visible)
-    const screenshot = await captureElementScreenshot(element.cssSelector, windowId);
+    const screenshot = await captureElementScreenshot(element.cssSelector, windowId, appIdentifier);
     if (screenshot) {
         content.push(screenshot);
     }
@@ -261,7 +261,7 @@ export async function getPointedElement(options) {
     // Add formatted metadata
     content.push({ type: 'text', text: formatElementMetadata(element) });
     // Capture element-only screenshot (no overlays)
-    const screenshot = await captureElementScreenshot(element.cssSelector, windowId);
+    const screenshot = await captureElementScreenshot(element.cssSelector, windowId, appIdentifier);
     if (screenshot) {
         content.push(screenshot);
     }

package/dist/driver/plugin-client.d.ts

@@ -0,0 +1,100 @@
+import { EventEmitter } from 'events';
+interface PluginCommand {
+    id?: string;
+    command: string;
+    args?: unknown;
+}
+export interface PluginResponse {
+    id?: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    windowContext?: {
+        windowLabel: string;
+        totalWindows: number;
+        warning?: string;
+    };
+}
+/**
+ * Client to communicate with the MCP Bridge plugin's WebSocket server
+ */
+export declare class PluginClient extends EventEmitter {
+    private _ws;
+    private _url;
+    private _host;
+    private _port;
+    private _reconnectAttempts;
+    private _shouldReconnect;
+    private _reconnectDelay;
+    private _pendingRequests;
+    /**
+     * Constructor for PluginClient
+     * @param host Host address of the WebSocket server
+     * @param port Port number of the WebSocket server
+     */
+    constructor(host: string, port: number);
+    /**
+     * Creates a PluginClient with default configuration from environment.
+     */
+    static create_default(): PluginClient;
+    /**
+     * Gets the host this client is configured to connect to.
+     */
+    get host(): string;
+    /**
+     * Gets the port this client is configured to connect to.
+     */
+    get port(): number;
+    /**
+     * Connect to the plugin's WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the plugin
+     */
+    disconnect(): void;
+    /**
+     * Send a command to the plugin and wait for response.
+     *
+     * Automatically retries on transient "not found" errors (e.g. window not
+     * yet registered after WebSocket connect) with exponential backoff.
+     */
+    sendCommand(command: PluginCommand, timeoutMs?: number): Promise<PluginResponse>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+}
+/**
+ * Gets the existing singleton PluginClient without creating or modifying it.
+ * Use this for status checks where you don't want to affect the current connection.
+ *
+ * @returns The existing PluginClient or null if none exists
+ */
+export declare function getExistingPluginClient(): PluginClient | null;
+/**
+ * Gets or creates a singleton PluginClient.
+ *
+ * If host/port are provided and differ from the existing client's configuration,
+ * the existing client is disconnected and a new one is created. This ensures
+ * that session start with a specific port always uses that port.
+ *
+ * @param host Optional host override
+ * @param port Optional port override
+ */
+export declare function getPluginClient(host?: string, port?: number): PluginClient;
+/**
+ * Resets the singleton client (useful for reconnecting with different config).
+ */
+export declare function resetPluginClient(): void;
+export declare function connectPlugin(host?: string, port?: number): Promise<void>;
+/**
+ * Ensures a session is active and connects to the plugin using session config.
+ * This should be used by all tools that require a connected Tauri app.
+ *
+ * @param appIdentifier - Optional app identifier to target specific app
+ * @throws Error if no session is active
+ */
+export declare function ensureSessionAndConnect(appIdentifier?: string | number): Promise<PluginClient>;
+export declare function disconnectPlugin(): Promise<void>;
+export {};

package/dist/driver/plugin-commands.d.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+export declare const ExecuteIPCCommandSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodUnknown>;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    appIdentifier?: string | number | undefined;
+    args?: unknown;
+}, {
+    command: string;
+    appIdentifier?: string | number | undefined;
+    args?: unknown;
+}>;
+export declare function executeIPCCommand(options: {
+    command: string;
+    args?: unknown;
+    appIdentifier?: string | number;
+}): Promise<string>;
+export declare const ManageIPCMonitoringSchema: z.ZodObject<{
+    action: z.ZodEnum<["start", "stop"]>;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    action: "start" | "stop";
+    appIdentifier?: string | number | undefined;
+}, {
+    action: "start" | "stop";
+    appIdentifier?: string | number | undefined;
+}>;
+export declare const StartIPCMonitoringSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const StopIPCMonitoringSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare function manageIPCMonitoring(action: 'start' | 'stop', appIdentifier?: string | number): Promise<string>;
+export declare function startIPCMonitoring(appIdentifier?: string | number): Promise<string>;
+export declare function stopIPCMonitoring(appIdentifier?: string | number): Promise<string>;
+export declare const GetIPCEventsSchema: z.ZodObject<{
+    filter: z.ZodOptional<z.ZodString>;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    filter?: string | undefined;
+    appIdentifier?: string | number | undefined;
+}, {
+    filter?: string | undefined;
+    appIdentifier?: string | number | undefined;
+}>;
+export declare function getIPCEvents(filter?: string, appIdentifier?: string | number): Promise<string>;
+export declare const EmitTestEventSchema: z.ZodObject<{
+    eventName: z.ZodString;
+    payload: z.ZodUnknown;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    eventName: string;
+    appIdentifier?: string | number | undefined;
+    payload?: unknown;
+}, {
+    eventName: string;
+    appIdentifier?: string | number | undefined;
+    payload?: unknown;
+}>;
+export declare function emitTestEvent(eventName: string, payload: unknown, appIdentifier?: string | number): Promise<string>;
+export declare const GetWindowInfoSchema: z.ZodObject<{
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    appIdentifier?: string | number | undefined;
+}, {
+    appIdentifier?: string | number | undefined;
+}>;
+export declare function getWindowInfo(appIdentifier?: string | number): Promise<string>;
+export declare const GetBackendStateSchema: z.ZodObject<{
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    appIdentifier?: string | number | undefined;
+}, {
+    appIdentifier?: string | number | undefined;
+}>;
+/**
+ * Get backend state from the connected Tauri app.
+ *
+ * This function can work in two modes:
+ * 1. Normal mode: Requires an active session (for MCP tool calls)
+ * 2. Setup mode: Uses existing connected client (for session setup)
+ *
+ * @param useExistingClient If true, uses the existing connected client without
+ *        session validation. Used during session setup before currentSession is set.
+ */
+export declare function getBackendState(options?: {
+    useExistingClient?: boolean;
+    appIdentifier?: string | number;
+}): Promise<string>;
+export declare const ListWindowsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+/**
+ * Lists all open webview windows in the Tauri application.
+ */
+export declare function listWindows(appIdentifier?: string | number): Promise<string>;
+export declare const ResizeWindowSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    windowId: z.ZodOptional<z.ZodString>;
+    logical: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    width: number;
+    height: number;
+    logical: boolean;
+    windowId?: string | undefined;
+}, {
+    width: number;
+    height: number;
+    windowId?: string | undefined;
+    logical?: boolean | undefined;
+}>;
+/**
+ * Resizes a window to the specified dimensions.
+ *
+ * @param options - Resize options including width, height, and optional windowId
+ * @returns JSON string with the result of the resize operation
+ */
+export declare function resizeWindow(options: {
+    width: number;
+    height: number;
+    windowId?: string;
+    logical?: boolean;
+    appIdentifier?: string | number;
+}): Promise<string>;
+export declare const ManageWindowSchema: z.ZodObject<{
+    action: z.ZodEnum<["list", "info", "resize"]>;
+    windowId: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    logical: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    appIdentifier: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    action: "list" | "info" | "resize";
+    logical: boolean;
+    windowId?: string | undefined;
+    appIdentifier?: string | number | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+}, {
+    action: "list" | "info" | "resize";
+    windowId?: string | undefined;
+    appIdentifier?: string | number | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    logical?: boolean | undefined;
+}>;
+/**
+ * Unified window management function.
+ *
+ * Actions:
+ * - `list`: List all open webview windows with their labels, titles, URLs, and state
+ * - `info`: Get detailed info for a window (size, position, title, focus, visibility)
+ * - `resize`: Resize a window to specified dimensions
+ *
+ * @param options - Action and parameters
+ * @returns JSON string with the result
+ */
+export declare function manageWindow(options: {
+    action: 'list' | 'info' | 'resize';
+    windowId?: string;
+    width?: number;
+    height?: number;
+    logical?: boolean;
+    appIdentifier?: string | number;
+}): Promise<string>;

package/dist/driver/protocol.d.ts

@@ -0,0 +1,128 @@
+/**
+ * WebSocket protocol types for communication between MCP server and Tauri plugin
+ *
+ * This file defines the message format for the WebSocket-based communication
+ * between the Node.js MCP server and the Rust Tauri plugin.
+ */
+/** Commands that can be sent to the Tauri plugin */
+export type PluginCommandType = 'execute_command' | 'get_window_info' | 'get_backend_state' | 'emit_event' | 'start_ipc_monitor' | 'stop_ipc_monitor' | 'get_ipc_events' | 'execute_js' | 'capture_native_screenshot';
+/** Request message sent from MCP server to Tauri plugin */
+export interface PluginRequest {
+    id: string;
+    command: PluginCommandType;
+    args?: unknown;
+}
+/** Response message sent from Tauri plugin to MCP server */
+export interface PluginResponse {
+    id: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+/** Event broadcast from Tauri plugin (not in response to a request) */
+export interface PluginEvent {
+    type: 'ipc_event' | 'console_log' | 'error' | 'element_picked' | 'element_pointed';
+    payload: unknown;
+    timestamp?: string;
+}
+/** Structured info about a parent element in the DOM ancestry */
+export interface ParentElementInfo {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    boundingRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Metadata collected about a picked/pointed DOM element */
+export interface ElementMetadata {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    attributes: Record<string, string>;
+    textContent: string;
+    boundingRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    cssSelector: string;
+    xpath: string;
+    computedStyles: Record<string, string>;
+    parentChain: ParentElementInfo[];
+    timestamp: number;
+}
+/** Broadcast message for element picker events */
+export interface ElementPickerBroadcast {
+    type: 'element_picked' | 'element_pointed';
+    payload: {
+        pickerId?: string;
+        element?: ElementMetadata;
+        cancelled?: boolean;
+    };
+}
+/** IPC event captured by the monitor */
+export interface IPCEvent {
+    command: string;
+    args?: unknown;
+    response?: unknown;
+    duration?: number;
+    timestamp: string;
+}
+/** Window information returned by get_window_info */
+export interface WindowInfo {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    title: string;
+    focused: boolean;
+    visible: boolean;
+}
+/** Backend state returned by get_backend_state */
+export interface BackendState {
+    app: {
+        name: string;
+        identifier: string;
+        version: string;
+    };
+    tauri: {
+        version: string;
+    };
+    environment: {
+        debug: boolean;
+        os: string;
+        arch: string;
+        family: string;
+    };
+    windows: Array<{
+        label: string;
+        title: string;
+        focused: boolean;
+        visible: boolean;
+    }>;
+    window_count: number;
+    timestamp: number;
+}
+/** Console log entry */
+export interface ConsoleLogEntry {
+    level: 'log' | 'info' | 'warn' | 'error' | 'debug';
+    message: string;
+    timestamp: string;
+    source?: string;
+}
+/** Screenshot result */
+export interface ScreenshotResult {
+    data: string;
+    format: 'png' | 'jpeg';
+    width?: number;
+    height?: number;
+}