<p align="center"> <img src="./rust.png" alt="Rust logo" width="180" /> </p>

rust-debug-mcp

A Model Context Protocol (MCP) server for debugging and operating Rust Tauri applications over WebSocket.

Table of Contents

• Overview
• Features
• Installation
• Usage
• Tools API
• Examples
• Development
• Contributing
• License

Overview

rust-debug-mcp bridges MCP clients and Tauri debug backends. It provides a single tool (tauri_debug_command) that routes commands to specialized handlers for app lifecycle operations, core debugging, metrics/task inspection, frontend actions, and UI automation.

It supports multiple target apps through configs/apps.json, including capability checks per app before command execution.

Features

Core Functionality

• Multi-app registry support with per-app command capability gating
• App lifecycle management (start_app, kill_app)
• Core debug command forwarding through a typed WebSocket bridge
• Response verbosity control (concise and detailed)

Debugging & Inspection

• Task/session/metrics commands for Commander-style backends
• Frontend broadcast support for app-side actions
• UI automation commands (click, fill, select, type, press_key, snapshots, screenshots, wait/hover/scroll, console logs)

Reliability

• Connection status checks and reconnect behavior in bridge manager
• Request timeout handling for bridge calls
• Ordered handler routing with clean command-to-handler resolution

Installation

Quick Setup

# Clone repository
git clone https://github.com/ruizrica/rust-debug-mcp.git

# Enter project
cd rust-debug-mcp

# Install dependencies
npm install

# Build
npm run build

Installing in an MCP Client

Add to your MCP config (example):

{
  "mcpServers": {
    "tauri-debug": {
      "command": "node",
      "args": ["/absolute/path/to/rust-debug-mcp/dist/server.js"],
      "env": {
        "LOG_LEVEL": "info",
        "TAURI_WS_URL": "ws://localhost:9002",
        "COMMANDER_WS_URL": "ws://localhost:9002"
      }
    }
  }
}

For deeper setup and troubleshooting, see docs/RUNBOOK.md.

Usage

Starting the Server

npm run dev
# or
npm start

The server communicates over stdio and is intended to be launched by an MCP client.

Multi-App Configuration

configs/apps.json controls default app, app endpoints, and command capability sets:

{
  "default": "commander",
  "apps": {
    "commander": {
      "name": "Commander",
      "wsUrl": "ws://localhost:9002",
      "commands": ["all"]
    },
    "photon": {
      "name": "Photon CLI",
      "wsUrl": "ws://localhost:9847",
      "commands": ["core", "ui_automation"]
    }
  }
}

Tools API

The server exposes one MCP tool:

Tool	Description
tauri_debug_command	Execute a debug command against a selected app (command, optional params, optional app, optional response_format)

Command Categories

• App lifecycle: start_app, kill_app
• Core: test_connection, get_debug_mode, set_debug_mode, get_app_dir, get_logs, get_system_metrics, test_command, simple_test
• Task/session/metrics: get_session_metrics, get_task_metrics, get_all_tasks, get_task, get_tasks_by_status, get_task_groups, list_windows
• Frontend action: broadcast_to_frontend
• UI automation: click, fill, select, type, press_key, get_snapshot, take_screenshot, wait_for, hover, scroll, get_console_logs

For full payload details, see docs/COMMAND_REFERENCE.md.

Examples

Minimal Command

{
  "command": "test_connection"
}

Targeting a Specific App

{
  "command": "get_debug_mode",
  "app": "commander"
}

UI Interaction

{
  "command": "click",
  "app": "photon",
  "params": {
    "uid": "e5"
  }
}

Development

Project Structure

rust-debug-mcp/
├── src/
│   ├── server.ts             # MCP server entry point
│   ├── bridge-manager.ts     # WebSocket bridge and manager
│   ├── app-registry.ts       # Multi-app registry and capability checks
│   ├── handlers/             # Command handlers and router
│   ├── response-formatter.ts # Concise/detailed output formatter
│   └── types.ts              # Type definitions
├── configs/
│   └── apps.json
├── docs/
├── tests/
├── package.json
└── tsconfig.json

Build

npm run build

Typecheck

npm run typecheck

Testing

npm test
npm run test:unit
npm run test:integration

Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch
3. Make and test your changes
4. Open a pull request

License

MIT

---

Built with TypeScript, Rust, Tauri, and MCP.