@hypothesi/tauri-plugin-mcp-bridge 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2025-11-26
+
+_No changes to this package._
+
+## [0.1.1] - 2025-11-26
+
+### Fixed
+- Improve `execute_js` error handling with better JSON parse error logging
+- Add `__TAURI__` availability check before emitting script results
+- Catch unhandled promise rejections in executed scripts
+- Double-wrap script execution to catch both parse and runtime errors
+
+### Added
+- Initial release of tauri-plugin-mcp-bridge
+- IPC monitoring capabilities
+- Window information retrieval
+- Backend state inspection
+- Custom event emission
+- WebSocket server for real-time event streaming

package/LICENSE

@@ -0,0 +1,39 @@
+MIT License
+
+Copyright (c) 2025 Fireside Development, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Apache License, Version 2.0
+
+Copyright (c) 2025 Fireside Development, LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,260 @@
+# Tauri MCP Bridge Plugin
+
+[![Crates.io](https://img.shields.io/crates/v/tauri-plugin-mcp-bridge.svg)](https://crates.io/crates/tauri-plugin-mcp-bridge)
+[![Documentation](https://docs.rs/tauri-plugin-mcp-bridge/badge.svg)](https://docs.rs/tauri-plugin-mcp-bridge)
+[![License](https://img.shields.io/crates/l/tauri-plugin-mcp-bridge.svg)](https://github.com/hypothesi/mcp-server-tauri)
+
+A Tauri plugin that bridges the Model Context Protocol (MCP) with Tauri applications, enabling deep inspection and interaction with Tauri's IPC layer, backend state, and window management.
+
+## Overview
+
+The MCP Bridge plugin extends MCP servers with direct access to Tauri internals. It provides real-time IPC monitoring, window state inspection, backend state access, and event emission capabilities.
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+tauri-plugin-mcp-bridge = "0.1"
+```
+
+## Usage
+
+Register the plugin in your Tauri application:
+
+```rust
+use tauri_plugin_mcp_bridge;
+
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_mcp_bridge::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+### Custom Configuration
+
+By default, the plugin binds to `0.0.0.0` (all interfaces) to support remote device development. For localhost-only access:
+
+```rust
+use tauri_plugin_mcp_bridge::Builder;
+
+fn main() {
+    tauri::Builder::default()
+        .plugin(Builder::new().bind_address("127.0.0.1").build())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+## Features
+
+### 1. IPC Monitoring
+
+Monitor all Tauri IPC calls in real-time with timing and argument capture:
+
+```typescript
+// Start monitoring
+await invoke('plugin:mcp-bridge|start_ipc_monitor');
+
+// Execute some commands to generate IPC traffic
+await invoke('greet', { name: 'World' });
+
+// Get captured events
+const events = await invoke('plugin:mcp-bridge|get_ipc_events');
+```
+
+### 2. Window Information
+
+Get detailed window state:
+
+```typescript
+const windowInfo = await invoke('plugin:mcp-bridge|get_window_info');
+// Returns: { width, height, x, y, title, focused, visible }
+```
+
+### 3. Backend State
+
+Inspect application backend state:
+
+```typescript
+const state = await invoke('plugin:mcp-bridge|get_backend_state');
+// Returns: { app: { name, identifier, version }, tauri: { version },
+//            environment: { debug, os, arch, family }, windows: [...], timestamp }
+```
+
+### 4. Event Emission
+
+Trigger custom events for testing:
+
+```typescript
+await invoke('plugin:mcp-bridge|emit_event', {
+  eventName: 'custom-event',
+  payload: { data: 'test' }
+});
+```
+
+## MCP Server Integration
+
+This plugin is part of the larger MCP Server for Tauri, which provides **23 total MCP tools** for comprehensive Tauri development and testing. The plugin specifically enables the following tools:
+
+### Project Management Tools (4)
+
+1. **tauri_run_command** - Run any Tauri CLI command with full flexibility
+2. **tauri_read_config** - Read Tauri configuration files (including platform-specific configs)
+3. **tauri_write_config** - Write to Tauri configuration files with validation
+4. **tauri_get_docs** - Get Tauri documentation (LLM Cheat Sheet) for the detected project version
+
+### Mobile Development Tools (2)
+
+1. **tauri_list_devices** - List connected Android devices and iOS simulators
+2. **tauri_launch_emulator** - Launch an Android AVD or iOS Simulator
+
+### UI Automation & WebView Tools (11)
+
+Tools for UI automation and webview interaction via the plugin's WebSocket connection:
+
+1. **tauri_driver_session** - Manage automation session (start or stop)
+2. **tauri_webview_find_element** - Find an element in the webview
+3. **tauri_driver_get_console_logs** - Get console logs from the webview
+4. **tauri_read_platform_logs** - Read platform logs (Android logcat, iOS device logs, system logs)
+5. **tauri_webview_interact** - Perform gestures (click, double-click, long-press, swipe, scroll)
+6. **tauri_webview_screenshot** - Take screenshots of the entire webview
+7. **tauri_webview_keyboard** - Type text or simulate keyboard events with optional modifiers
+8. **tauri_webview_wait_for** - Wait for element selectors, text content, or IPC events
+9. **tauri_webview_get_styles** - Get computed CSS styles for element(s)
+10. **tauri_webview_execute_js** - Execute arbitrary JavaScript code in the webview context
+11. **tauri_webview_focus_element** - Focus on a specific element in the webview
+
+### IPC & Plugin Tools (6)
+
+Tools that directly use the MCP Bridge plugin's Rust backend:
+
+1. **tauri_plugin_execute_ipc** - Execute any Tauri IPC command with the MCP bridge plugin
+2. **tauri_plugin_get_window_info** - Get detailed information about the current window
+3. **tauri_plugin_ipc_monitor** - Manage IPC monitoring (start or stop)
+4. **tauri_plugin_ipc_get_events** - Retrieve all captured IPC events with optional filtering
+5. **tauri_plugin_emit_event** - Emit custom Tauri events for testing event handlers
+6. **tauri_plugin_get_backend_state** - Get backend application state and metadata
+
+## Architecture
+
+```text
+MCP Server (Node.js)
+    │
+    ├── Native IPC (via plugin) ────> Tauri App Webview (DOM/UI)
+    │                                       │
+    └── Plugin Client ──────────────────────┼──> Plugin Commands
+         (WebSocket port 9223)              │
+                                            │
+                                      mcp-bridge Plugin
+                                      (Rust Backend)
+```
+
+## WebSocket Communication
+
+The plugin runs a WebSocket server on port 9223 (or next available in range 9223-9322) for real-time communication with the MCP server.
+
+### Remote Device Development
+
+By default, the WebSocket server binds to `0.0.0.0` (all network interfaces), enabling connections from:
+
+- **iOS devices** on the same network
+- **Android devices** on the same network or via `adb reverse`
+- **Emulators/Simulators** via localhost
+
+#### Connecting from MCP Server
+
+The MCP server supports connecting to remote Tauri apps via the `tauri_driver_session` tool:
+
+```typescript
+// Connect to a Tauri app on a remote device
+tauri_driver_session({ action: 'start', host: '192.168.1.100' })
+
+// Or use environment variables:
+// MCP_BRIDGE_HOST=192.168.1.100 npx mcp-server-tauri
+// TAURI_DEV_HOST=192.168.1.100 npx mcp-server-tauri (same as Tauri CLI uses)
+```
+
+#### Connection Strategy
+
+The MCP server uses a fallback strategy:
+1. Try `localhost:{port}` first (most reliable for simulators/emulators/desktop)
+2. If localhost fails and a remote host is configured, try `{host}:{port}`
+3. Auto-discover apps on localhost if specific connection fails
+
+## Development
+
+### Building the Plugin
+
+From the plugin directory:
+
+```bash
+cd packages/tauri-plugin-mcp-bridge
+cargo build
+```
+
+Or from the workspace root:
+
+```bash
+npm run build:plugin
+```
+
+### Documentation
+
+View the comprehensive Rust API documentation:
+
+```bash
+npm run docs:rust
+```
+
+Or directly:
+
+```bash
+cd packages/tauri-plugin-mcp-bridge
+cargo doc --open --no-deps
+```
+
+### Testing
+
+Run the MCP server tests which include plugin integration tests:
+
+```bash
+npm test
+```
+
+## Permissions
+
+The plugin requires the following permissions to be configured in your Tauri capabilities:
+
+- `execute_command`
+- `get_window_info`
+- `get_backend_state`
+- `emit_event`
+- `start_ipc_monitor`
+- `stop_ipc_monitor`
+- `get_ipc_events`
+
+These are typically auto-configured when using the plugin.
+
+## API Documentation
+
+For detailed API documentation, including:
+
+- Complete function signatures and parameters
+- Rust examples for backend integration
+- TypeScript examples for frontend usage
+- Architecture and design details
+
+Visit the [docs.rs documentation](https://docs.rs/tauri-plugin-mcp-bridge) or build locally with `npm run docs:rust`.
+
+## License
+
+This project is licensed under either of:
+
+- MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+
+at your option.

package/dist-js/index.d.ts

@@ -0,0 +1,50 @@
+export interface WindowInfo {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    title: string;
+    focused: boolean;
+    visible: boolean;
+}
+export interface BackendState {
+    status: string;
+    windows: number;
+}
+export interface IPCEvent {
+    timestamp: number;
+    command: string;
+    args: unknown;
+    result?: unknown;
+    error?: string;
+    duration_ms?: number;
+}
+/**
+ * Execute an arbitrary Tauri command
+ */
+export declare function executeCommand(command: string, args?: unknown): Promise<unknown>;
+/**
+ * Get information about the current window
+ */
+export declare function getWindowInfo(): Promise<WindowInfo>;
+/**
+ * Get backend application state
+ */
+export declare function getBackendState(): Promise<BackendState>;
+/**
+ * Emit a custom event for testing
+ */
+export declare function emitEvent(eventName: string, payload?: unknown): Promise<string>;
+/**
+ * Start IPC monitoring - captures all invoke() calls
+ */
+export declare function startIPCMonitor(): Promise<string>;
+/**
+ * Stop IPC monitoring
+ */
+export declare function stopIPCMonitor(): Promise<string>;
+/**
+ * Get all captured IPC events
+ */
+export declare function getIPCEvents(): Promise<IPCEvent[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist-js/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../guest-js/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAEtF;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,CAEzD;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAE7D;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAErF;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAEvD;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAExD"}

package/dist-js/index.js

@@ -0,0 +1,43 @@
+import { invoke } from '@tauri-apps/api/core';
+/**
+ * Execute an arbitrary Tauri command
+ */
+export async function executeCommand(command, args) {
+    return await invoke('plugin:mcp-bridge|execute_command', { command, args });
+}
+/**
+ * Get information about the current window
+ */
+export async function getWindowInfo() {
+    return await invoke('plugin:mcp-bridge|get_window_info');
+}
+/**
+ * Get backend application state
+ */
+export async function getBackendState() {
+    return await invoke('plugin:mcp-bridge|get_backend_state');
+}
+/**
+ * Emit a custom event for testing
+ */
+export async function emitEvent(eventName, payload) {
+    return await invoke('plugin:mcp-bridge|emit_event', { eventName, payload });
+}
+/**
+ * Start IPC monitoring - captures all invoke() calls
+ */
+export async function startIPCMonitor() {
+    return await invoke('plugin:mcp-bridge|start_ipc_monitor');
+}
+/**
+ * Stop IPC monitoring
+ */
+export async function stopIPCMonitor() {
+    return await invoke('plugin:mcp-bridge|stop_ipc_monitor');
+}
+/**
+ * Get all captured IPC events
+ */
+export async function getIPCEvents() {
+    return await invoke('plugin:mcp-bridge|get_ipc_events');
+}

package/guest-js/index.ts

@@ -0,0 +1,74 @@
+import { invoke } from '@tauri-apps/api/core';
+
+export interface WindowInfo {
+   width: number;
+   height: number;
+   x: number;
+   y: number;
+   title: string;
+   focused: boolean;
+   visible: boolean;
+}
+
+export interface BackendState {
+   status: string;
+   windows: number;
+}
+
+export interface IPCEvent {
+   timestamp: number;
+   command: string;
+   args: unknown;
+   result?: unknown;
+   error?: string;
+   duration_ms?: number;
+}
+
+/**
+ * Execute an arbitrary Tauri command
+ */
+export async function executeCommand(command: string, args?: unknown): Promise<unknown> {
+   return await invoke('plugin:mcp-bridge|execute_command', { command, args });
+}
+
+/**
+ * Get information about the current window
+ */
+export async function getWindowInfo(): Promise<WindowInfo> {
+   return await invoke('plugin:mcp-bridge|get_window_info');
+}
+
+/**
+ * Get backend application state
+ */
+export async function getBackendState(): Promise<BackendState> {
+   return await invoke('plugin:mcp-bridge|get_backend_state');
+}
+
+/**
+ * Emit a custom event for testing
+ */
+export async function emitEvent(eventName: string, payload?: unknown): Promise<string> {
+   return await invoke('plugin:mcp-bridge|emit_event', { eventName, payload });
+}
+
+/**
+ * Start IPC monitoring - captures all invoke() calls
+ */
+export async function startIPCMonitor(): Promise<string> {
+   return await invoke('plugin:mcp-bridge|start_ipc_monitor');
+}
+
+/**
+ * Stop IPC monitoring
+ */
+export async function stopIPCMonitor(): Promise<string> {
+   return await invoke('plugin:mcp-bridge|stop_ipc_monitor');
+}
+
+/**
+ * Get all captured IPC events
+ */
+export async function getIPCEvents(): Promise<IPCEvent[]> {
+   return await invoke('plugin:mcp-bridge|get_ipc_events');
+}

package/guest-js/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@tauri-plugin/mcp-bridge",
+  "version": "0.1.2",
+  "description": "Guest bindings for MCP Bridge Tauri plugin",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts"
+}

package/guest-js/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2021",
+    "lib": ["ES2021"],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "../dist-js",
+    "rootDir": ".",
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+   "name": "@hypothesi/tauri-plugin-mcp-bridge",
+   "version": "0.1.2",
+   "description": "JavaScript bindings for @hypothesi/tauri-plugin-mcp-bridge - MCP Bridge plugin for Tauri",
+   "type": "module",
+   "main": "./dist-js/index.js",
+   "types": "./dist-js/index.d.ts",
+   "exports": {
+      ".": {
+         "import": "./dist-js/index.js",
+         "types": "./dist-js/index.d.ts"
+      }
+   },
+   "scripts": {
+      "build": "tsc --project guest-js/tsconfig.json",
+      "prepublishOnly": "npm run build"
+   },
+   "files": [
+      "dist-js",
+      "guest-js",
+      "README.md",
+      "CHANGELOG.md",
+      "LICENSE",
+      "package.json"
+   ],
+   "repository": {
+      "type": "git",
+      "url": "https://github.com/hypothesi/mcp-server-tauri.git",
+      "directory": "packages/tauri-plugin-mcp-bridge"
+   },
+   "author": "hypothesi",
+   "license": "MIT",
+   "keywords": [
+      "tauri",
+      "tauri-plugin",
+      "mcp",
+      "ipc",
+      "monitoring"
+   ],
+   "dependencies": {
+      "@tauri-apps/api": "^2.0.0"
+   },
+   "devDependencies": {
+      "typescript": "^5.6.3"
+   },
+   "publishConfig": {
+      "access": "public"
+   }
+}