@hypothesi/tauri-mcp-server 0.9.0 → 0.10.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/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;
+}

package/dist/driver/script-manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Script Manager - Manages persistent script injection across page navigations.
+ *
+ * This module provides functions to register, remove, and manage scripts that
+ * should be automatically re-injected when pages load or navigate.
+ *
+ * @internal This module is for internal use only and is not exposed as MCP tools.
+ */
+/**
+ * Type of script to inject.
+ */
+export type ScriptType = 'inline' | 'url';
+/**
+ * A script entry in the registry.
+ */
+export interface ScriptEntry {
+    /** Unique identifier for this script. */
+    id: string;
+    /** Type of script (inline code or external URL). */
+    type: ScriptType;
+    /** The script content (JavaScript code) or URL. */
+    content: string;
+}
+/**
+ * Response from script registration.
+ */
+interface RegisterScriptResponse {
+    registered: boolean;
+    scriptId: string;
+}
+/**
+ * Response from script removal.
+ */
+interface RemoveScriptResponse {
+    removed: boolean;
+    scriptId: string;
+}
+/**
+ * Response from clearing scripts.
+ */
+interface ClearScriptsResponse {
+    cleared: number;
+}
+/**
+ * Response from getting scripts.
+ */
+interface GetScriptsResponse {
+    scripts: ScriptEntry[];
+}
+/**
+ * Registers a script to be injected into the webview.
+ *
+ * The script will be immediately injected if the page is loaded, and will be
+ * automatically re-injected on subsequent page loads/navigations.
+ *
+ * @param id - Unique identifier for the script
+ * @param type - Type of script ('inline' for code, 'url' for external script)
+ * @param content - The script content (JavaScript code) or URL
+ * @param windowLabel - Optional window label to target
+ * @returns Promise resolving to registration result
+ */
+export declare function registerScript(id: string, type: ScriptType, content: string, windowLabel?: string): Promise<RegisterScriptResponse>;
+/**
+ * Removes a script from the registry and DOM.
+ *
+ * @param id - The script ID to remove
+ * @param windowLabel - Optional window label to target
+ * @returns Promise resolving to removal result
+ */
+export declare function removeScript(id: string, windowLabel?: string): Promise<RemoveScriptResponse>;
+/**
+ * Clears all registered scripts from the registry and DOM.
+ *
+ * @param windowLabel - Optional window label to target
+ * @returns Promise resolving to the number of scripts cleared
+ */
+export declare function clearScripts(windowLabel?: string): Promise<ClearScriptsResponse>;
+/**
+ * Gets all registered scripts.
+ *
+ * @returns Promise resolving to the list of registered scripts
+ */
+export declare function getScripts(): Promise<GetScriptsResponse>;
+/**
+ * Checks if a script with the given ID is registered.
+ *
+ * @param id - The script ID to check
+ * @returns Promise resolving to true if the script is registered
+ */
+export declare function isScriptRegistered(id: string): Promise<boolean>;
+export {};

package/dist/driver/scripts/aria-api-loader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * aria-api library loader
+ *
+ * Bundles aria-api for browser injection. Provides comprehensive W3C-compliant
+ * accessibility computation including:
+ * - WAI-ARIA 1.3 role computation
+ * - HTML-AAM 1.0 implicit role mappings
+ * - Accessible Name and Description Computation 1.2
+ * - aria-owns relationship handling
+ */
+/** Script ID used for the aria-api library in the script registry. */
+export declare const ARIA_API_SCRIPT_ID = "__mcp_aria_api__";
+/**
+ * Get the aria-api library source code.
+ * Loaded lazily and cached.
+ */
+export declare function getAriaApiSource(): string;