Rust Documentation MCP Server

Supercharge your AI Editor with Rust Superpowers. 🚀

The rustools-mcp server bridges the gap between Large Language Models (LLMs) like Trae, Cursor, or Claude and the Rust ecosystem. It provides real-time access to docs.rs, crates.io, and the Rust Book, enabling your AI assistant to fetch accurate documentation, explain complex concepts, and fix compiler errors with context-aware intelligence.

✨ Key Features

📦 Context Bundles: Get a complete crate overview (README + Modules + Features) in a single tool call.
🔍 Smart Discovery: Find crates by name or search for functions by signature (e.g., fn(u32) -> String).
🧠 Error Intelligence: Explain compiler errors (E0382) with official explanations from the Rust Error Index.
📖 Deep Code Access: Read raw source code when documentation is insufficient.
⚡ Offline-First Speed: Persistent caching ensures instant responses for frequently used docs.
🔬 Macro Vision: Expand macros to see the actual code generated by the compiler.

📦 Installation

Option 1: Build from Source (Recommended)

Clone the repository:

git clone https://github.com/zakarialabib/rustools-mcp.git
cd rustools-mcp

Build the release binary:
```
cargo build --release
```

Option 2: Run Directly

You can also point your MCP client directly to cargo run if you have Rust installed.

🔌 Configuration

Trae / Cursor (Stdio Mode)

Stdio mode is strictly recommended to avoid CORS and network issues with local editors.

Add this to your mcp_config.json:

{
  "mcpServers": {
    "rust-docs": {
      "command": "cargo",
      "args": [
        "run",
        "--release",
        "--manifest-path",
        "C:/absolute/path/to/rustools-mcp/Cargo.toml",
        "--",
        "stdio"
      ]
    }
  }
}

Note: Replace C:/absolute/path/to/... with the actual absolute path to the project.

HTTP / SSE Mode (Advanced)

For remote setups or clients supporting Server-Sent Events (SSE):

Start the server:

cargo run --release -- http --address 127.0.0.1:8080

Configure MCP:

{
  "mcpServers": {
    "rust-docs": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

🧭 User Guide: The Cognitive Workflow

To get the best results, we recommend a 3-step "Holy Trinity" workflow. Teach your AI to follow this pattern:

1. DISCOVERY (The "What")

Goal: Identify the right tool or crate.

Unknown Crate? → find_crates("keywords")
Unknown Concept? → get_language_concept("concept") (e.g., "pinning", "async")
Unknown Type Shape? → find_by_signature("crate", "fn(A) -> B")

2. ANALYSIS (The "Context")

Goal: Load the map before starting the journey.

New Crate Encountered? → MUST CALL get_context_bundle("crate").
- Why? This is a "Cognitive Bundle" containing README + Modules + Features. It prevents 3 separate round-trips.
Need Implementation Details? → find_trait_implementors("crate", "Trait").
- Why? Helps you answer "What can I pass to this function?"
Check Dependencies? → get_crate_dependencies("crate").

3. VALIDATION (The "How")

Goal: Verify assumptions with ground truth.

Writing Code? → get_symbol_docs("crate", "path::to::Item").
Debugging Logic? → read_source_file("crate", "path/to/impl.rs").
Fixing Errors? → explain_error_code("E0xxx").

Resource Selection Matrix

⚡ Pro Tips for Efficiency

No Guessing: Never guess if a type implements a trait. Use find_trait_implementors.
Compilation Failures: If code fails with "module not found", run analyze_feature_flags. It's usually a missing feature in Cargo.toml.
Implementation > Docs: If docs are generic, read the source (read_source_file) to understand the actual behavior.
Path Precision: Always use fully qualified paths (std::vec::Vec) in get_symbol_docs.

🛠️ Available Tools

🏗️ Developer Architecture

This section details the internal logic for contributors and curious developers.

System Architecture

The project is a Model Context Protocol (MCP) server implemented in Rust, designed to bridge LLMs with the Rust ecosystem.

graph TD
    User[LLM / Client] <-->|JSON-RPC (Stdio/SSE)| Server[Server Layer]
    Server -->|Dispatches| Handler[Tool Handler (mcp.rs)]
    
    subgraph Core Logic
        Handler -->|1. Check| Cache[InMemoryCache (cache.rs)]
        Handler -->|2. Miss| Fetcher[DocFetcher (mcp.rs)]
        Fetcher -->|3. Request| Parser[DocsParser (docs_parser.rs)]
    end
    
    subgraph Data Sources
        Parser <-->|HTTP| DocsRS[docs.rs]
        Parser <-->|HTTP| CratesIO[crates.io]
        Parser <-->|HTTP| RustBook[doc.rust-lang.org]
    end
    
    Cache -->|Persist| Disk[.cache/ directory]
    Parser -->|Return| Markdown[Optimized Markdown]

Key Components

Server Layer (src/server.rs):
- Uses rmcp crate for protocol handling.
- Supports Stdio (default) and SSE transports.
- Spawns a background task for the Web UI dashboard (port 3000).
Tool Handler (src/mcp.rs):
- The "Brain" of the server.
- Maps MCP tool calls to internal functions.
- Implements "Cognitive Triggers" (Discovery -> Analysis -> Validation).
Docs Parser (src/docs_parser.rs):
- The "Engine".
- Manages HTTP sessions and parses HTML using scraper.
- Converts HTML to LLM-friendly Markdown using html2md.
Caching (src/cache.rs):
- Thread-safe InMemoryCache with disk persistence.
- Automatically saves/loads from .cache/ directory.

Observability & Debugging

Logs: requests.log contains JSON-line formatted logs of every tool call.
Console: Uses tracing for standard error output.
Verification: Run cargo run --bin verify_mcp to validate all tools.

Test Command:

cargo run --release -- test --tool find_crates --query "async"

❓ Troubleshooting

MCP Servers