rust-analyzer-mcp 0.4.0

# rust-analyzer MCP Server

This is a Model Context Protocol (MCP) server that provides integration with rust-analyzer, allowing
AI assistants to analyze Rust code, get hover information, find definitions, references, and more.
Written in Rust for optimal performance and native integration.

## Prerequisites

1. **rust-analyzer**: Make sure rust-analyzer is installed and available in your PATH
   ```bash
   # Install via rustup (recommended)
   rustup component add rust-analyzer
   
   # Or install directly
   cargo install rust-analyzer
   
   # Verify installation
   rust-analyzer --version
   ```

2. **Rust**: Version 1.70 or higher with Cargo
3. **A Rust project**: The server works best with a valid Rust workspace (containing `Cargo.toml`)

## Why Rust?

This Rust implementation offers several advantages over alternative implementations:

- **Performance**: Native Rust binary with minimal overhead
- **Memory Safety**: No runtime errors from memory issues
- **Ecosystem Integration**: Perfect fit for Rust development workflows
- **Small Binary Size**: Optimized release builds with LTO
- **Concurrent Safety**: Tokio async runtime handles multiple requests efficiently
- **Native LSP Handling**: Direct integration with rust-analyzer's protocol

## Installation

### From crates.io (Recommended)

Install directly from crates.io:
```bash
cargo install rust-analyzer-mcp
```

The binary will be installed to your Cargo bin directory (usually `~/.cargo/bin/rust-analyzer-mcp`).

### From Source

1. Clone the repository:
   ```bash
   git clone https://github.com/zeenix/rust-analyzer-mcp.git
   cd rust-analyzer-mcp
   ```

2. Build the project:
   ```bash
   cargo build --release
   ```

3. The binary will be available at `target/release/rust-analyzer-mcp`

## Configuration

### Claude Code Configuration

Add an MCP server configuration to one of these locations:

**Option 1: Project-specific** (`.mcp.json` in your Rust project root):
```json
{
  "mcpServers": {
    "rust-analyzer": {
      "command": "rust-analyzer-mcp"
    }
  }
}
```

**Option 2: User-wide** (`~/.claude.json` or `~/.claude/settings.json`):
```json
{
  "mcpServers": {
    "rust-analyzer": {
      "command": "rust-analyzer-mcp"
    }
  }
}
```

**Note:** If you installed from crates.io, the command will be in your PATH. If you built from
source, use the full path to the binary. You can also configure servers using Claude Code's CLI
wizard too.

### Claude Desktop Configuration

Add this to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "rust-analyzer": {
      "command": "rust-analyzer-mcp"
    }
  }
}
```

**Note:** If installed from crates.io, the command will be in your PATH. For Claude Desktop, you
may want to specify a `cwd` parameter if you want to analyze a specific project by default.

### Cargo features

By default rust-analyzer analyses and checks your crate with whatever features its manifest makes
default, so code behind a feature gate looks unresolved and its errors go unreported. Pass the
features to use on the command line:

```bash
rust-analyzer-mcp --all-features /path/to/project
rust-analyzer-mcp --features serde,tokio /path/to/project
rust-analyzer-mcp --no-default-features --features serde /path/to/project
```

In a workspace, a feature may need naming with the package it belongs to, exactly as cargo wants
it: `--features my-crate/serde`.

Which features to use is a choice worth making per project rather than everywhere: `--all-features`
enables even the features a crate never expects to see enabled together, which for some projects
means analysis that fails or takes far longer than it needs to. Options go in `args` alongside the
command:

```json
{
  "mcpServers": {
    "rust-analyzer": {
      "command": "rust-analyzer-mcp",
      "args": ["--features", "serde,tokio"]
    }
  }
}
```

Anything else rust-analyzer can be configured with is available through `--config`, which takes any
[rust-analyzer setting](https://rust-analyzer.github.io/book/configuration.html) without the
`rust-analyzer.` prefix. The value is read as JSON, or taken for a string if it is not JSON:

```bash
rust-analyzer-mcp --config check.command=clippy --config 'check.extraArgs=["--tests"]' .
```

### Other MCP Clients

For other MCP clients, run the server with:
```bash
./target/release/rust-analyzer-mcp
```

Or during development:
```bash
cargo run
```

The server communicates via stdio and follows the MCP protocol.

## Available Tools

Every `file_path` argument below may be given relative to the workspace root, as an absolute path,
or as a `file:` URI.

### Working Features ✅

#### `rust_analyzer_symbols`
Get all symbols (functions, structs, enums, etc.) in a file.

**Parameters:**
- `file_path`: Path to the Rust file

#### `rust_analyzer_definition`
Find the definition of a symbol at a specific position.

**Parameters:**
- `file_path`: Path to the Rust file
- `line`: Line number (0-based)  
- `character`: Character position (0-based)

#### `rust_analyzer_references`
Find all references to a symbol at a specific position.

**Parameters:**
- `file_path`: Path to the Rust file
- `line`: Line number (0-based)
- `character`: Character position (0-based)

#### `rust_analyzer_hover`
Get hover information (documentation, type info) for a symbol at a specific position.

**Parameters:**
- `file_path`: Path to the Rust file (relative to workspace)
- `line`: Line number (0-based)
- `character`: Character position (0-based)

#### `rust_analyzer_completion`
Get code completion suggestions at a specific position.

**Parameters:**
- `file_path`: Path to the Rust file
- `line`: Line number (0-based)
- `character`: Character position (0-based)

#### `rust_analyzer_format`
Format a Rust file using rust-analyzer's formatter. Returns an array of text edits to apply.

**Parameters:**
- `file_path`: Path to the Rust file

Returns an empty array if the file is already formatted, or an array of edits with ranges and new
text to apply.

#### `rust_analyzer_code_actions`
Get available code actions (quick fixes, refactorings) for a range.

**Parameters:**
- `file_path`: Path to the Rust file
- `line`: Start line number (0-based)
- `character`: Start character position (0-based)
- `end_line`: End line number (0-based)
- `end_character`: End character position (0-based)

**Note:** Code actions availability depends on:
- rust-analyzer being fully indexed
- Having actual code issues or refactoring opportunities in the selected range
- May return empty array if no actions are applicable

#### `rust_analyzer_diagnostics`
Get diagnostics (errors, warnings, hints) for a specific file.

**Parameters:**
- `file_path`: Path to the Rust file

Runs a fresh `cargo check` and waits for it to finish, so the result describes the file as it is on
disk rather than as it was when first looked at. If the check does not finish in time, the result
says so in a `note` field and asking again picks up the rest.

Returns diagnostics with severity levels (error, warning, hint, information), messages, and location
ranges. Includes a summary count of diagnostics by severity.

#### `rust_analyzer_workspace_diagnostics`
Get all diagnostics across the entire workspace.

**Parameters:** None

Returns aggregated diagnostics for all files in the workspace with file paths, severity levels,
messages, and a summary of total counts by severity.

#### `rust_analyzer_rename`
Rename the symbol at a position, everywhere it is used in the workspace.

**Parameters:**
- `file_path`: Path to the Rust file
- `line`: Line number (0-based)
- `character`: Character position (0-based)
- `new_name`: The new name

Changes no files. It returns the edits to apply, each with the byte range it covers and the text it
replaces, listed last-first within each file so they can be applied one after another without
adjusting for the ones already made. It fails rather than answering while rust-analyzer is still
loading the workspace, since a rename worked out before then could miss references. Renaming a module also renames its file, which is reported
under `file_operations`; the untouched LSP `WorkspaceEdit` is included as `workspace_edit`.

### `rust_analyzer_set_workspace`
Change the workspace root directory.

**Parameters:**
- `workspace_path`: Path to the new workspace root

## Usage Examples

Here are some example prompts you can use with Claude when this MCP server is configured:

1. **Code Analysis:**
   ```
   Can you analyze the main function in src/main.rs and tell me what it does? 
   Use the rust analyzer tools to get hover information and symbols.
   ```

2. **Finding Definitions:**
   ```
   I'm looking at a function call on line 25 of src/lib.rs at character position 10. 
   Can you find its definition using rust-analyzer?
   ```

3. **Code Completion:**
   ```
   I'm writing code at line 15, character 8 in src/main.rs. 
   What completion suggestions are available?
   ```

4. **Refactoring Help:**
   ```
   What code actions are available for the code between line 10-15 in src/utils.rs?
   ```

5. **Error Checking:**
   ```
   Can you get the diagnostics for src/main.rs and tell me about any errors or warnings?
   ```

6. **Workspace Analysis:**
   ```
   Show me all the diagnostics across the entire workspace using rust-analyzer.
   ```

## Project Structure

```
rust-analyzer-mcp-server/
├── src/
│   └── main.rs       # Main MCP server implementation
├── Cargo.toml        # Rust dependencies and metadata
└── README.md         # This file
```

## Development

To run in development mode:
```bash
cargo run
```

To build for release:
```bash
cargo build --release
```

To run tests:
```bash
cargo test
```

To check code without building:
```bash
cargo check
```

For verbose logging during development:
```bash
RUST_LOG=debug cargo run
```

To run with release optimizations in dev:
```bash
cargo run --release
```

## Troubleshooting

### rust-analyzer not found
- Ensure rust-analyzer is in your PATH: `which rust-analyzer`
- Try reinstalling: `rustup component add rust-analyzer`

### Connection errors
- Make sure you're running the server in a valid Rust workspace (with Cargo.toml)
- Check that the file paths are correct and relative to the workspace root

### Permission issues
- Make sure the server has read access to your Rust files
- Check that rust-analyzer has permission to analyze your project

### LSP communication issues
- The server handles LSP protocol automatically
- Check console output for any rust-analyzer errors (use `RUST_LOG=debug` for verbose logging)
- Ensure your Rust project compiles successfully

### Build issues
- Make sure you have Rust 1.70+ installed: `rustc --version`
- Try `cargo clean` and rebuild if you encounter dependency issues

### Performance
- rust-analyzer may take time to initially index large projects
- Subsequent requests should be much faster
- Consider excluding large target/ directories if needed

## Contributing

This is a foundation implementation that covers the most common rust-analyzer features. Contributions are welcome for:

- Additional LSP methods (workspace symbols, call hierarchy, etc.)
- Better error handling and diagnostics  
- Configuration options (via CLI args or config files)
- Performance optimizations and async improvements
- Integration tests and benchmarks
- Better LSP message parsing and error recovery
- Support for additional rust-analyzer features

### Development Guidelines

- Use `cargo fmt` for consistent formatting
- Run `cargo clippy` for linting
- Add tests for new functionality  
- Update documentation for new tools
- Follow Rust async best practices with Tokio

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.