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

# rust-debug-mcp

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Rust](https://img.shields.io/badge/Rust-000000?style=for-the-badge&logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![Tauri](https://img.shields.io/badge/Tauri-24C8DB?style=for-the-badge&logo=tauri&logoColor=white)](https://tauri.app/)
[![WebSocket](https://img.shields.io/badge/WebSocket-010101?style=for-the-badge&logo=websocket&logoColor=white)](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
[![Model Context Protocol](https://img.shields.io/badge/MCP-6236FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNMTggMThhMSAxIDAgMCAxLTEgMUg3YTEgMSAwIDAgMS0xLTFWNmExIDEgMCAwIDEgMS0xaDEwYTEgMSAwIDAgMSAxIDF2MTJ6Ij48L3BhdGg+PHBhdGggZD0iTTEyIDZ2MTIiPjwvcGF0aD48cGF0aCBkPSJNNiA5aDEyIj48L3BhdGg+PHBhdGggZD0iTTYgMTVoMTIiPjwvcGF0aD48L3N2Zz4=&logoColor=white)](https://modelcontextprotocol.ai/)

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

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Tools API](#tools-api)
- [Examples](#examples)
- [Development](#development)
- [Contributing](#contributing)
- [License](#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

```bash
# 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):

```json
{
  "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

```bash
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:

```json
{
  "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

```json
{
  "command": "test_connection"
}
```

### Targeting a Specific App

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

### UI Interaction

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

## Development

### Project Structure

```text
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

```bash
npm run build
```

### Typecheck

```bash
npm run typecheck
```

### Testing

```bash
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.