# Rust Doctor

> Scan, score, and fix your Rust code — clippy + cargo-audit + cargo-deny + 19 custom rules unified into one 0–100 health score. CLI · MCP server · GitHub Action.

- **Type:** MCP server
- **Install:** `agentstack add mcp-arthjean-rust-doctor`
- **Verified:** Pending review
- **Seller:** [arthjean](https://agentstack.voostack.com/s/arthjean)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [arthjean](https://github.com/arthjean)
- **Source:** https://github.com/arthjean/rust-doctor
- **Website:** https://rust-doctor.vercel.app/

## Install

```sh
agentstack add mcp-arthjean-rust-doctor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# rust-doctor

  
  
  
  
  
  
  

**The one-command health check for your Rust project.** rust-doctor scans for security, performance, correctness, architecture, and dependency issues, then folds everything into a single 0–100 score with diagnostics you can act on.

It runs `cargo clippy`, `cargo-audit`, `cargo-deny`, `cargo-geiger`, and 19 custom AST rules in one pass, and ships as a CLI, a library crate, an [MCP](https://modelcontextprotocol.io/) server, an npm package, and a GitHub Action — so it works in your terminal, your CI, and inside Claude Code, Cursor, or any MCP agent.

```console
$ rust-doctor                          # rust-doctor scanning its own codebase

   ◠ ◠    rust-doctor
    ▽     99 / 100   Great

   ████████████████████████████████████████

   Security 99 · Reliability 99 · Maintainability 100 · Performance 99 · Dependencies 99

   ✓ 0 errors   ⚠ 44 warnings   ℹ 42 infos   ·   60 files scanned in 32.9s
```

## Quickstart

No Rust toolchain required — `npx` downloads a pre-built native binary for your platform:

```bash
npx rust-doctor            # scan the current directory and print the score
```

Prefer cargo? `cargo install rust-doctor`. Want it in your AI agent? `npx rust-doctor setup`. Other formats are in [Installation](#installation).

### See it in action →

https://github.com/user-attachments/assets/6766a5d8-9a47-4eb8-892e-76c1a23eb122

## Where it fits

Rust already has excellent point tools. rust-doctor runs them together, adds rules they don't cover, and turns the result into one number you can track over time.

| You're using | It gives you | rust-doctor adds |
|---|---|---|
| `cargo clippy` | 700+ built-in lints | Category + severity mapping, 19 custom AST rules (security, async, framework, architecture), and a single 0–100 score |
| `cargo audit` / `cargo deny` | CVE and supply-chain checks | One pass that also runs clippy, geiger, and machete — skipping gracefully when a tool isn't installed |
| Separate CI steps | Each tool's own output | One command with `--json`, `--sarif`, `--diff`, `--score`, and PR comments |
| Claude Code / Cursor | Code generation | An MCP server and a slash-command skill, so the agent scans, scores, and fixes as it writes |

## Features

- **700+ clippy lints** with explicit severity overrides and category mapping
- **19 custom AST rules** via [syn](https://crates.io/crates/syn): error handling, performance, security, async, architecture, and framework anti-patterns
- **Async anti-pattern detection**: blocking calls and `block_on` inside an async context
- **Framework-aware rules**: tokio, axum, actix-web — only run when the dependency is present
- **Supply-chain auditing**: CVEs via `cargo-audit`, bans/licenses via `cargo-deny`, unsafe via `cargo-geiger`, unused deps via `cargo-machete`
- **A 0–100 health score** across five weighted dimensions, with an ASCII doctor that reacts to the result
- **MCP server**: 4 read-only tools + 2 expert audit prompts for Claude Code, Cursor, Windsurf, or any MCP client
- **Diff mode**: `--diff` scans only changed files for fast CI feedback
- **Workspace support**: scan every crate or pick specific members
- **Inline suppression**: `// rust-doctor-disable-next-line `
- **Output modes**: terminal, `--json`, `--score` (bare integer for CI), `--sarif` (GitHub code scanning)
- **`--fix`**: apply machine-applicable fixes to source files
- **Setup wizard**: `rust-doctor setup` auto-detects Claude Code, Cursor, and Windsurf and wires up MCP or installs the skill in one command
- **Distributed everywhere**: CLI binary, library crate, MCP server, npm package, and GitHub Action

## Installation

### npm / npx (recommended for MCP users)

```bash
npx rust-doctor --mcp
```

Or install globally:

```bash
npm install -g rust-doctor
```

This downloads a pre-built native binary for your platform — no Rust toolchain required.

### cargo install (from source)

```bash
cargo install rust-doctor
```

### cargo binstall (pre-built binary)

```bash
cargo binstall rust-doctor
```

### Shell installer (Linux/macOS)

```bash
curl -fsSL https://github.com/ArthurDEV44/rust-doctor/releases/latest/download/install.sh | bash
```

### PowerShell installer (Windows)

```powershell
irm https://github.com/ArthurDEV44/rust-doctor/releases/latest/download/install.ps1 | iex
```

### GitHub Releases

Download pre-built binaries from [GitHub Releases](https://github.com/ArthurDEV44/rust-doctor/releases).

Available platforms:
- `x86_64-unknown-linux-gnu`
- `aarch64-unknown-linux-gnu`
- `x86_64-apple-darwin`
- `aarch64-apple-darwin`
- `x86_64-pc-windows-msvc`

## Usage

```bash
# Scan current directory
rust-doctor

# Scan a specific directory
rust-doctor /path/to/project

# Get bare score for CI
rust-doctor --score

# JSON output
rust-doctor --json

# Scan only changed files
rust-doctor --diff

# Scan against a specific branch
rust-doctor --diff main

# Fail CI on errors
rust-doctor --fail-on error

# Scan specific workspace members
rust-doctor --project core,api

# Verbose output with file:line details
rust-doctor --verbose

# Install missing external tools (cargo-deny, cargo-audit, etc.)
rust-doctor --install-deps

# Run as MCP server
rust-doctor --mcp

# Setup wizard — configure AI agents automatically
rust-doctor setup
```

## Exit Codes

rust-doctor returns distinct exit codes so CI pipelines can tell a quality-gate
failure apart from a crash:

| Code | Meaning |
|------|---------|
| `0` | Success — scan completed and all quality gates passed |
| `1` | Setup error — MCP server, setup wizard, or `--install-deps` failed |
| `2` | Scan error — project discovery/compile failure or output rendering failed |
| `3` | Quality gate failed — score below `[score] fail_below`, or `--fail-on` threshold reached |

Gate the build on a quality failure without masking a crash:

```bash
rust-doctor --fail-on error
if [ $? -eq 3 ]; then
  echo "Quality gate failed"
  exit 1
fi
```

## AI Agent Setup (recommended)

The fastest way to integrate rust-doctor with your AI coding agent:

```bash
npx rust-doctor@latest setup
```

The wizard auto-detects installed agents (Claude Code, Cursor, Windsurf) and lets you choose:

- **CLI + Skills** (default) — installs a `SKILL.md` that teaches your agent to use the rust-doctor CLI with deep analysis capabilities
- **MCP Server** — configures the `rust-doctor --mcp` stdio server in your agent's config file

The wizard handles detection, configuration, and verification in one command. For manual setup, see the sections below.

## MCP Server

rust-doctor includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server, allowing AI coding assistants to scan and analyze Rust projects directly.

### Tools

| Tool | Description |
|------|-------------|
| `scan` | Scan a Rust project for code health issues. Returns diagnostics with a 0–100 health score. |
| `score` | Get the health score (0–100) of a Rust project as a single integer. |
| `explain_rule` | Get a detailed explanation of a rule: what it checks, why it matters, and how to fix violations. |
| `list_rules` | List all available rules with their categories and severities. |

All tools are read-only (`readOnlyHint: true`).

### Prompts

| Prompt | Description |
|--------|-------------|
| `deep-audit` | Comprehensive 6-phase expert audit: codebase exploration, static analysis, deep code review (51-item checklist), best practices research, synthesis report, and remediation choices (implement all / generate PRD / manual). |
| `health-check` | Quick scan + prioritized remediation plan (P0–P3) + fix workflow. |

### Claude Code

**Automatic setup (recommended):**

```bash
rust-doctor setup  # detects Claude Code and configures MCP or installs skill
```

**Or one-command MCP install:**

```bash
claude mcp add --transport stdio rust-doctor -- npx -y rust-doctor --mcp
```

**Or via Claude Code plugin:**

```
/plugin install rust-doctor@ArthurDEV44/rust-doctor
```

**Or add manually** to your `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "rust-doctor": {
      "command": "rust-doctor",
      "args": ["--mcp"]
    }
  }
}
```

**Or share with your team** via `.mcp.json` in your project root (committed to git):

```json
{
  "mcpServers": {
    "rust-doctor": {
      "command": "npx",
      "args": ["-y", "rust-doctor", "--mcp"]
    }
  }
}
```

### Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rust-doctor": {
      "command": "npx",
      "args": ["-y", "rust-doctor", "--mcp"]
    }
  }
}
```

### VS Code

Add to your `.vscode/settings.json`:

```json
{
  "mcp": {
    "servers": {
      "rust-doctor": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "rust-doctor", "--mcp"]
      }
    }
  }
}
```

### Windsurf

Add to your `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "rust-doctor": {
      "command": "npx",
      "args": ["-y", "rust-doctor", "--mcp"]
    }
  }
}
```

### Other MCP clients

rust-doctor uses stdio transport. Any MCP client that supports stdio can connect by running `rust-doctor --mcp`.

Built with [rmcp](https://crates.io/crates/rmcp) v1.x (official Rust MCP SDK).

## Claude Code Skill (no MCP required)

If you prefer slash commands over MCP servers, rust-doctor ships a Claude Code skill.

**Automatic install (recommended):**

```bash
rust-doctor setup  # choose "CLI + Skills", select Claude Code
```

**Or via npx:**

```bash
npx skills add https://github.com/ArthurDEV44/rust-doctor --skill rust-doctor
```

**Or copy manually:**

```bash
cp -r skills/rust-doctor/ ~/.claude/skills/rust-doctor/
```

**Usage:**

```
/rust-doctor                    # scan current project
/rust-doctor --diff             # scan changed files only
/rust-doctor --fix              # scan + apply fixes
/rust-doctor --plan             # scan + remediation plan
/rust-doctor src/               # scan a specific directory
```

The skill runs the `rust-doctor` CLI under the hood, parses the output, categorizes findings by priority, and provides actionable fix guidance with before/after code.

## GitHub Actions

```yaml
- uses: ArthurDEV44/rust-doctor@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    fail-on: warning
```

The action posts a PR comment with the health score, error/warning counts, and top diagnostics.

## Configuration

Create a `rust-doctor.toml` in your project root, or add `[package.metadata.rust-doctor]` to your `Cargo.toml`:

```toml
# rust-doctor.toml
verbose = false
fail_on = "none"

[ignore]
rules = ["excessive-clone", "string-from-literal"]
files = ["**/generated/**", "tests/**"]
```

CLI flags override config file values.

## Inline Suppression

```rust
// rust-doctor-disable-next-line unwrap-in-production
let value = some_option.unwrap();

let x = risky_call(); // rust-doctor-disable-line
```

## Rules

### Custom AST Rules (19 rules) — heuristic

These rules analyze the syntax tree only (via `syn`): no type resolution, no
macro expansion. They run fast and offline, but emit a **heuristic** signal, not
a type-checked verdict — calibrate confidence accordingly. Findings are tagged
`heuristic` in `--json` and SARIF output, and marked `~heuristic` in the
terminal. Rules flagged ⚠ have known structural blind spots (see below).

| Category | Rule | Severity |
|----------|------|----------|
| Error Handling | `unwrap-in-production` ⚠ | Warning |
| Error Handling | `panic-in-library` | Error |
| Error Handling | `box-dyn-error-in-public-api` | Warning |
| Error Handling | `result-unit-error` | Warning |
| Performance | `excessive-clone` | Warning |
| Performance | `string-from-literal` | Info |
| Performance | `collect-then-iterate` | Warning |
| Performance | `large-enum-variant` ⚠ | Warning |
| Performance | `unnecessary-allocation` | Warning |
| Architecture | `high-cyclomatic-complexity` | Warning |
| Security | `hardcoded-secrets` | Error |
| Security | `unsafe-block-audit` | Warning |
| Security | `sql-injection-risk` ⚠ | Error |
| Async | `blocking-in-async` ⚠ | Error |
| Async | `block-on-in-async` | Error |
| Framework | `tokio-main-missing` | Error |
| Framework | `tokio-spawn-without-move` | Error |
| Framework | `axum-handler-not-async` | Warning |
| Framework | `actix-blocking-handler` | Warning |

#### Known heuristic limitations (⚠)

Without type information these rules have documented blind spots. They're still
worth surfacing, but a finding is a prompt to look, not a confirmed defect:

- `unwrap-in-production` — matches `.unwrap()`/`.expect()` syntactically; cannot tell a provably-infallible unwrap from a risky one.
- `large-enum-variant` — counts a variant's fields, not its byte size; a few wide-type fields can outweigh many small ones.
- `blocking-in-async` — flags known blocking calls by name inside async fns; cannot follow calls into other functions or resolve aliased imports.
- `sql-injection-risk` — flags string-built queries heuristically; cannot confirm the interpolated value is actually untrusted input.

### Clippy Lints (75+ with overrides) — type-aware

rust-doctor runs `cargo clippy` with pedantic, nursery, and cargo lint groups. 75+ lints have explicit category and severity overrides across: Error Handling, Performance, Security, Correctness, Architecture, Cargo, Async, Style. Unlike the custom rules above, clippy resolves types against the compiler, so its findings are more authoritative — they are **not** tagged `heuristic`.

### External Tools (optional, auto-detected)

These tools are optional — rust-doctor gracefully skips any that are missing and shows which passes were skipped. Run `rust-doctor --install-deps` to install them all at once.

| Tool | Install | What it does |
|------|---------|-------------|
| clippy | `rustup component add clippy` | 700+ lint checks |
| cargo-deny | `cargo install cargo-deny` | Supply-chain checking (advisories, licenses, bans) |
| cargo-audit | `cargo install cargo-audit` | CVE vulnerability scanning |
| cargo-geiger | `cargo install cargo-geiger` | Unsafe code auditing across dependency tree |
| cargo-machete | `cargo install cargo-machete` | Unused dependency detection |
| cargo-semver-checks | `cargo install cargo-semver-checks` | Semver violation detection |

## Library Usage

rust-doctor is available as a library crate:

```rust
use std::path::Path;

// Discover the project (finds Cargo.toml, loads config)
let (dir, info, config) = rust_doctor::discovery::bootstrap_project(
    Path::new("/path/to/project"), false,
)?;

// Resolve config with defaults
let resolved = rust_doctor::config::resolve_config_defaults(config.as_ref());

// Run the scan
let result = rust_doctor::scan::scan_project(&info, &resolved, false, &[], true)?;
println!("Score: {}/100 ({})", result.score, result.score_label);
```

Full API docs are on [docs.rs/rust-doctor](https://docs.rs/rust-doctor).

## Score Calculation

**Read the 0–100 score as a compass, not a thermometer.** It points you toward
the weakest dimension; it isn't a precision measurement. The per-dimension
scores (shown in the terminal box and in `--json`) carry the real signal — they
tell you *where* to act.

### How it's computed

The score is a weighted average across 5 dimensions:

| Dimension | Weight | Covers |
|-----------|--------|--------|
| Security | ×2.0 | Security rules (hardcoded secrets, unsafe, SQL injection) |
| Reliability | ×1.5 | Correctness, error handling, async, framework |
| Maintainability | ×1.0 | Architecture, style |
| Performance | ×1.0 | Performance |
| Dependencies | ×1.0 | Cargo, dependencies, advisory findings (RUSTSEC / cargo-deny) |

Each dimension starts at 100 and loses points per **unique rule** violated,
weighted by severity:

`dimension = 100 − (unique_error_rules × 1.5) − (unique_warning_rules × 0.75) − (unique_info_rules × 0.25)`

The dimension is clamped to `[0, 100]`, and the overall score is the weighted
average of the five, also clamped to `[0, 100]`.

The score counts unique rules, not occur

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [arthjean](https://github.com/arthjean)
- **Source:** [arthjean/rust-doctor](https://github.com/arthjean/rust-doctor)
- **License:** Apache-2.0
- **Homepage:** https://rust-doctor.vercel.app/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-arthjean-rust-doctor
- Seller: https://agentstack.voostack.com/s/arthjean
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.