Content
<p align="center">
<img src="./rust.png" alt="Rust logo" width="180" />
</p>
# rust-debug-mcp
[](https://www.typescriptlang.org/)
[](https://www.rust-lang.org/)
[](https://tauri.app/)
[](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
[](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.
