rust-guidelines-mcp-server

A Model Context Protocol (MCP) server for the Rust Coding Guidelines Ruleset — a custom clippy toolchain with additional coding-guideline lint rules. Enables AI assistants to run guideline checks, auto-fix warnings, explain lint rules, configure lint levels, and detect the toolchain environment.

Features

• 🔍 guidelines_check — Run cargo +guidelines_runner clippy and get structured JSON diagnostic results
• 💾 guidelines_check_save — Run cargo +guidelines_runner clippy and save results to local files (JSON + Markdown + Raw), with smart inline/summary JSON output
• 🔧 guidelines_fix — Auto-fix warnings with cargo +guidelines_runner clippy --fix
• 📖 guidelines_explain — Get detailed explanations of any clippy/guidelines lint rule
• ⚙️ guidelines_configure — Configure lint levels (allow/warn/deny/forbid) in Cargo.toml or as file attributes
• 🔎 guidelines_detect — Detect Rust toolchain environment (cargo, rustc, rustup, guidelines_runner) with install instructions
• 📄 guidelines config resource — Read project clippy configuration files
• 🛠️ troubleshooting resource — Diagnose environment issues and get fix instructions

Quick Start

Usage with npx

npx rust-guidelines-mcp-server

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rust-guidelines": {
      "command": "npx",
      "args": ["-y", "rust-guidelines-mcp-server"]
    }
  }
}

Cursor / Roo / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "rust-guidelines": {
      "command": "npx",
      "args": ["-y", "rust-guidelines-mcp-server"]
    }
  }
}

Tip: If the server cannot find your Rust toolchain or guidelines_runner, add env to the config — see Troubleshooting.

Prerequisites

• Node.js >= 18.0.0
• Rust toolchain (cargo, rustc) — Install Rust
• Coding Guidelines Ruleset — The guidelines_runner custom toolchain must be installed and linked:

# Link the guidelines_runner toolchain (adjust path to your installation)
rustup toolchain link guidelines_runner <install-dir>/tools/ruleset/runner

# Verify it works
cargo +guidelines_runner clippy --version

Default Lint Rules

Every guidelines_check, guidelines_check_save, and guidelines_fix invocation automatically enables the following 16 coding-guideline warn-level lints:

| Lint | Description | |------|-------------| | clippy::implicit_abi | Implicit ABI in extern declarations | | clippy::infinite_loop | Infinite loop detection | | clippy::unsafe_block_in_proc_macro | Unsafe blocks in proc macros | | clippy::untrusted_lib_loading | Untrusted library loading | | clippy::passing_string_to_c_functions | Passing String to C functions | | clippy::extern_without_repr | Extern types without repr attribute | | clippy::mem_unsafe_functions | Memory-unsafe function usage | | clippy::non_reentrant_functions | Non-reentrant function calls | | clippy::blocking_op_in_async | Blocking operations in async context | | clippy::fallible_memory_allocation | Fallible memory allocation | | clippy::null_ptr_dereference | Null pointer dereference | | clippy::dangling_ptr_dereference | Dangling pointer dereference | | clippy::return_stack_address | Returning stack address | | clippy::ptr_double_free | Pointer double free | | clippy::invalid_char_range | Invalid character range | | clippy::unconstrained_numeric_literal | Unconstrained numeric literal |

Users can override any of these via extra_args (e.g. ["-A", "clippy::infinite_loop"] to allow a specific lint), since later arguments take precedence in clippy.

Tools

guidelines_detect

Detect the Rust toolchain environment. Checks if cargo, rustc, rustup are installed and whether the guidelines_runner custom toolchain is properly linked, reports their versions, and provides installation/registration instructions if any tool is missing.

Parameters: None

guidelines_check

Run cargo +guidelines_runner clippy on a Rust project and return structured JSON diagnostic results. Automatically enables 16 default coding-guideline warn-level lints. Respects the project's own clippy configuration by default. Supports real-time progress reporting and cancellation.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | target | string | | Build target (e.g. --lib, --bin name) | | features | string[] | | Features to enable | | all_features | boolean | | Enable all features | | no_default_features | boolean | | Disable default features | | extra_args | string[] | | Extra arguments passed to clippy after -- (appended after default lints, later args take precedence) | | timeout | number | | Maximum timeout in seconds (default: 1800) |

Returns a JSON object:

{
  "success": true,
  "summary": { "total": 5, "errors": 1, "warnings": 4 },
  "diagnostics": [
    {
      "level": "warning",
      "code": "clippy::needless_return",
      "message": "unneeded `return` statement",
      "file": "src/main.rs",
      "line": 42,
      "column": 5,
      "rendered": "warning: unneeded `return` statement\n --> src/main.rs:42:5\n ...",
      "suggestion": { "replacement": "a + b", "applicability": "MachineApplicable" },
      "help": ["remove `return`"]
    }
  ]
}

On error: { "success": false, "error": "..." }

guidelines_check_save

Run cargo +guidelines_runner clippy and save the results to local files (guideline-output.json, guideline-output.md, guideline-output.raw.txt). If the JSON result is small (≤ max_inline_size), the full diagnostics are returned inline; otherwise only a summary with top issues and file paths are returned so the LLM can read the files later.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | output_dir | string | ✅ | Directory to save the report files (created if needed). Recommended: <project_path>/guideline-output | | target | string | | Build target (e.g. --lib, --bin name) | | features | string[] | | Features to enable | | all_features | boolean | | Enable all features | | no_default_features | boolean | | Disable default features | | extra_args | string[] | | Extra arguments passed to clippy after -- (appended after default lints) | | timeout | number | | Maximum timeout in seconds (default: 1800) | | max_inline_size | number | | Max JSON size in bytes to return inline (default: 32768 = 32KB) |

Returns a JSON object. When data is small enough:

{
  "success": true,
  "summary": { "total": 5, "errors": 1, "warnings": 4 },
  "files": {
    "json": "/path/to/guideline-output.json",
    "markdown": "/path/to/guideline-output.md",
    "raw": "/path/to/guideline-output.raw.txt"
  },
  "diagnostics": [ ... ]
}

When data exceeds max_inline_size:

{
  "success": true,
  "summary": { "total": 150, "errors": 3, "warnings": 147 },
  "files": { "json": "...", "markdown": "...", "raw": "..." },
  "truncated": true,
  "truncation_reason": "Full JSON is 128.0KB, exceeds inline limit of 32.0KB. Read the JSON file for complete diagnostics: ...",
  "top_issues_by_code": [
    { "code": "clippy::needless_return", "count": 45 }
  ],
  "top_issues_by_file": [
    { "file": "src/main.rs", "count": 50 }
  ]
}

guidelines_fix

Auto-fix warnings using cargo +guidelines_runner clippy --fix. Automatically enables 16 default coding-guideline warn-level lints. Respects the project's own clippy configuration by default. Supports real-time progress reporting and cancellation.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | allow_dirty | boolean | | Allow fixing in dirty working directory | | allow_staged | boolean | | Allow fixing with staged changes | | allow_no_vcs | boolean | | Allow fixing even if no VCS (git) is detected | | target | string | | Build target | | features | string[] | | Features to enable | | extra_args | string[] | | Extra arguments passed to clippy after -- (appended after default lints) | | timeout | number | | Maximum timeout in seconds (default: 1800) |

guidelines_explain

Explain a specific clippy/guidelines lint rule with examples, using the guidelines_runner toolchain.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lint_name | string | ✅ | Lint name (e.g. needless_return or clippy::needless_return) |

guidelines_configure

Configure clippy lint levels for a project.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | action | enum | ✅ | allow, warn, deny, or forbid | | lints | string[] | ✅ | List of lint names to configure | | scope | enum | | project (Cargo.toml) or file (attributes) |

Resources

guidelines://config/{project_path}

Read the clippy configuration for a Rust project, including:

• clippy.toml / .clippy.toml contents
• Cargo.toml [lints.clippy] section

guidelines://troubleshooting

Diagnose environment issues (missing CARGO_HOME, RUSTUP_HOME, guidelines_runner toolchain, PATH problems) and get step-by-step fix instructions for different MCP clients.

Troubleshooting

If the MCP server cannot find your Rust toolchain or the guidelines_runner toolchain (e.g. cargo not found or guidelines_runner toolchain not found), the most common causes are:

1. The MCP client process does not inherit your shell environment variables
2. The guidelines_runner toolchain is not linked via rustup toolchain link

Fix 1: Link the guidelines_runner toolchain

# Adjust the path to your coding-guidelines-ruleset installation
rustup toolchain link guidelines_runner <install-dir>/tools/ruleset/runner

# Verify it works
cargo +guidelines_runner clippy --version

Fix 2: Add environment variables to your MCP client config

{
  "mcpServers": {
    "rust-guidelines": {
      "command": "npx",
      "args": ["-y", "rust-guidelines-mcp-server"],
      "env": {
        "CARGO_HOME": "/path/to/your/.cargo",
        "RUSTUP_HOME": "/path/to/your/.rustup"
      }
    }
  }
}

Windows example:

"env": {
  "CARGO_HOME": "C:\\Users\\YourName\\.cargo",
  "RUSTUP_HOME": "C:\\Users\\YourName\\.rustup"
}

macOS/Linux example (default paths):

"env": {
  "CARGO_HOME": "/home/username/.cargo",
  "RUSTUP_HOME": "/home/username/.rustup"
}

You can also use the guidelines_detect tool or read the guidelines://troubleshooting resource for detailed diagnostics.

Project Structure

rust-guidelines-mcp-server/
├── src/
│   ├── index.ts                # Entry point, MCP Server setup & tool/resource registration
│   ├── tools/
│   │   ├── clippy-check.ts     # guidelines_check tool
│   │   ├── clippy-check-save.ts# guidelines_check_save tool
│   │   ├── clippy-fix.ts       # guidelines_fix tool
│   │   ├── clippy-explain.ts   # guidelines_explain tool
│   │   ├── clippy-configure.ts # guidelines_configure tool
│   │   └── clippy-detect.ts    # guidelines_detect tool
│   ├── resources/
│   │   ├── clippy-config.ts    # guidelines config resource
│   │   └── troubleshooting.ts  # troubleshooting resource
│   └── utils/
│       ├── cargo-runner.ts     # Cargo/command execution with +toolchain support
│       ├── cargo-progress.ts   # Cargo build progress tracking
│       ├── default-lints.ts    # Default coding-guideline lint rules (16 lints)
│       ├── diagnostics.ts      # Clippy JSON output parsing
│       ├── detect.ts           # Toolchain environment detection
│       ├── progress.ts         # MCP progress reporting utilities
│       ├── report-writer.ts    # Report file writer (JSON/Markdown/raw)
│       └── validate.ts         # Project path validation
├── package.json
├── tsconfig.json
└── README.md

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run directly
npm start

# Run tests
npm test

# Inspect with MCP Inspector
npm run inspect

License

MIT