Rust Docs MCP Server

1# Rust Docs MCP Server
2 
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4 
5⭐ **Like this project? Please
6[star the repository](https://github.com/Govcraft/rust-docs-mcp-server) on
7GitHub to show your support and stay updated!** ⭐
8 
9## Motivation
10 
11Modern AI-powered coding assistants (like Cursor, Cline, Roo Code, etc.) excel
12at understanding code structure and syntax but often struggle with the specifics
13of rapidly evolving libraries and frameworks, especially in ecosystems like Rust
14where crates are updated frequently. Their training data cutoff means they may
15lack knowledge of the latest APIs, leading to incorrect or outdated code
16suggestions.
17 
18This MCP server addresses this challenge by providing a focused, up-to-date
19knowledge source for a specific Rust crate. By running an instance of this
20server for a crate (e.g., `serde`, `tokio`, `reqwest`), you give your LLM coding
21assistant a tool (`query_rust_docs`) it can use _before_ writing code related to
22that crate.
23 
24When instructed to use this tool, the LLM can ask specific questions about the
25crate's API or usage and receive answers derived directly from the _current_
26documentation. This significantly improves the accuracy and relevance of the
27generated code, reducing the need for manual correction and speeding up
28development.
29 
30Multiple instances of this server can be run concurrently, allowing the LLM
31assistant to access documentation for several different crates during a coding
32session.
33 
34This server fetches the documentation for a specified Rust crate, generates
35embeddings for the content, and provides an MCP tool to answer questions about
36the crate based on the documentation context.
37 
38## Features
39 
40- **Targeted Documentation:** Focuses on a single Rust crate per server
41  instance.
42- **Feature Support:** Allows specifying required crate features for
43  documentation generation.
44- **Semantic Search:** Uses OpenAI's `text-embedding-3-small` model to find the
45  most relevant documentation sections for a given question.
46- **LLM Summarization:** Leverages OpenAI's `gpt-4o-mini-2024-07-18` model to
47  generate concise answers based _only_ on the retrieved documentation context.
48- **Caching:** Caches generated documentation content and embeddings in the
49  user's XDG data directory (`~/.local/share/rustdocs-mcp-server/` or similar)
50  based on crate, version, _and_ requested features to speed up subsequent
51  launches.
52- **MCP Integration:** Runs as a standard MCP server over stdio, exposing tools
53  and resources.
54 
55## Prerequisites
56 
57- **OpenAI API Key:** Needed for generating embeddings and summarizing answers.
58  The server expects this key to be available in the `OPENAI_API_KEY`
59  environment variable. (The server also requires network access to download
60  crate dependencies and interact with the OpenAI API).
61 
62## Installation
63 
64The recommended way to install is to download the pre-compiled binary for your
65operating system from the
66[GitHub Releases page](https://github.com/Govcraft/rust-docs-mcp-server/releases).
67 
681. Go to the
69   [Releases page](https://github.com/Govcraft/rust-docs-mcp-server/releases).
702. Download the appropriate archive (`.zip` for Windows, `.tar.gz` for
71   Linux/macOS) for your system.
723. Extract the `rustdocs_mcp_server` (or `rustdocs_mcp_server.exe`) binary.
734. Place the binary in a directory included in your system's `PATH` environment
74   variable (e.g., `/usr/local/bin`, `~/bin`).
75 
76### Building from Source (Alternative)
77 
78If you prefer to build from source, you will need the
79[Rust Toolchain](https://rustup.rs/) installed.
80 
811. **Clone the repository:**
82   ```bash
83   git clone https://github.com/Govcraft/rust-docs-mcp-server.git
84   cd rust-docs-mcp-server
85   ```
862. **Build the server:**
87   ```bash
88   cargo build --release
89   ```
90 
91## Usage
92 
93**Important Note for New Crates:**
94 
95When using the server with a crate for the first time (or with a new version/feature set), it needs to download the documentation and generate embeddings. This process can take some time, especially for crates with extensive documentation, and requires an active internet connection and OpenAI API key.
96 
97It is recommended to run the server once directly from your command line for any new crate configuration *before* adding it to your AI coding assistant (like Roo Code, Cursor, etc.). This allows the initial embedding generation and caching to complete. Once you see the server startup messages indicating it's ready (e.g., "MCP Server listening on stdio"), you can shut it down (Ctrl+C). Subsequent launches, including those initiated by your coding assistant, will use the cached data and start much faster.
98 
99 
100### Running the Server
101 
102The server is launched from the command line and requires the **Package ID
103Specification** for the target crate. This specification follows the format used
104by Cargo (e.g., `crate_name`, `crate_name@version_req`). For the full
105specification details, see `man cargo-pkgid` or the
106[Cargo documentation](https://doc.rust-lang.org/cargo/reference/pkgid-spec.html).
107 
108Optionally, you can specify required crate features using the `-F` or
109`--features` flag, followed by a comma-separated list of features. This is
110necessary for crates that require specific features to be enabled for
111`cargo doc` to succeed (e.g., crates requiring a runtime feature like
112`async-stripe`).
113 
114```bash
115# Set the API key (replace with your actual key)
116export OPENAI_API_KEY="sk-..."
117 
118# Example: Run server for the latest 1.x version of serde
119rustdocs_mcp_server "serde@^1.0"
120 
121# Example: Run server for a specific version of reqwest
122rustdocs_mcp_server "reqwest@0.12.0"
123 
124# Example: Run server for the latest version of tokio
125rustdocs_mcp_server tokio
126 
127# Example: Run server for async-stripe, enabling a required runtime feature
128rustdocs_mcp_server "async-stripe@0.40" -F runtime-tokio-hyper-rustls
129 
130# Example: Run server for another crate with multiple features
131rustdocs_mcp_server "some-crate@1.2" --features feat1,feat2
132```
133 
134On the first run for a specific crate version _and feature set_, the server
135will:
136 
1371. Download the crate documentation using `cargo doc` (with specified features).
1382. Parse the HTML documentation.
1393. Generate embeddings for the documentation content using the OpenAI API (this
140   may take some time and incur costs, though typically only fractions of a US
141   penny for most crates; even a large crate like `async-stripe` with over 5000
142   documentation pages cost only $0.18 USD for embedding generation during
143   testing).
1444. Cache the documentation content and embeddings so that the cost isn't
145   incurred again.
1465. Start the MCP server.
147 
148Subsequent runs for the same crate version _and feature set_ will load the data
149from the cache, making startup much faster.
150 
151### MCP Interaction
152 
153The server communicates using the Model Context Protocol over standard
154input/output (stdio). It exposes the following:
155 
156- **Tool: `query_rust_docs`**
157  - **Description:** Query documentation for the specific Rust crate the server
158    was started for, using semantic search and LLM summarization.
159  - **Input Schema:**
160    ```json
161    {
162      "type": "object",
163      "properties": {
164        "question": {
165          "type": "string",
166          "description": "The specific question about the crate's API or usage."
167        }
168      },
169      "required": ["question"]
170    }
171    ```
172  - **Output:** A text response containing the answer generated by the LLM based
173    on the relevant documentation context, prefixed with
174    `From <crate_name> docs:`.
175  - **Example MCP Call:**
176    ```json
177    {
178      "jsonrpc": "2.0",
179      "method": "callTool",
180      "params": {
181        "tool_name": "query_rust_docs",
182        "arguments": {
183          "question": "How do I make a simple GET request with reqwest?"
184        }
185      },
186      "id": 1
187    }
188    ```
189 
190- **Resource: `crate://<crate_name>`**
191  - **Description:** Provides the name of the Rust crate this server instance is
192    configured for.
193  - **URI:** `crate://<crate_name>` (e.g., `crate://serde`, `crate://reqwest`)
194  - **Content:** Plain text containing the crate name.
195 
196- **Logging:** The server sends informational logs (startup messages, query
197  processing steps) back to the MCP client via `logging/message` notifications.
198 
199### Example Client Configuration (Roo Code)
200 
201You can configure MCP clients like Roo Code to run multiple instances of this
202server, each targeting a different crate. Here's an example snippet for Roo
203Code's `mcp_settings.json` file, configuring servers for `reqwest` and
204`async-stripe` (note the added features argument for `async-stripe`):
205 
206```json
207{
208  "mcpServers": {
209    "rust-docs-reqwest": {
210      "command": "/path/to/your/rustdocs_mcp_server",
211      "args": [
212        "reqwest@0.12"
213      ],
214      "env": {
215        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
216      },
217      "disabled": false,
218      "alwaysAllow": []
219    },
220    "rust-docs-async-stripe": {
221      "command": "rustdocs_mcp_server",
222      "args": [
223        "async-stripe@0.40",
224        "-F",
225        " runtime-tokio-hyper-rustls"
226      ],
227      "env": {
228        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
229      },
230      "disabled": false,
231      "alwaysAllow": []
232    }
233  }
234}
235```
236 
237**Note:**
238 
239- Replace `/path/to/your/rustdocs_mcp_server` with the actual path to the
240  compiled binary on your system if it isn't in your PATH.
241- Replace `YOUR_OPENAI_API_KEY_HERE` with your actual OpenAI API key.
242- The keys (`rust-docs-reqwest`, `rust-docs-async-stripe`) are arbitrary names
243  you choose to identify the server instances within Roo Code.
244 
245### Example Client Configuration (Claude Desktop)
246 
247For Claude Desktop users, you can configure the server in the MCP settings.
248Here's an example configuring servers for `serde` and `async-stripe`:
249 
250```json
251{
252  "mcpServers": {
253    "rust-docs-serde": {
254      "command": "/path/to/your/rustdocs_mcp_server",
255      "args": [
256        "serde@^1.0"
257      ]
258    },
259    "rust-docs-async-stripe-rt": {
260      "command": "rustdocs_mcp_server",
261      "args": [
262        "async-stripe@0.40",
263        "-F",
264        "runtime-tokio-hyper-rustls"
265      ]
266    }
267  }
268}
269```
270 
271**Note:**
272 
273- Ensure `rustdocs_mcp_server` is in your system's PATH or provide the full path
274  (e.g., `/path/to/your/rustdocs_mcp_server`).
275- The keys (`rust-docs-serde`, `rust-docs-async-stripe-rt`) are arbitrary names
276  you choose to identify the server instances.
277- Remember to set the `OPENAI_API_KEY` environment variable where Claude Desktop
278  can access it (this might be system-wide or via how you launch Claude
279  Desktop). Claude Desktop's MCP configuration might not directly support
280  setting environment variables per-server like Roo Code.
281- The example shows how to add the `-F` argument for crates like `async-stripe`
282  that require specific features.
283 
284### Caching
285 
286- **Location:** Cached documentation and embeddings are stored in the XDG data
287  directory, typically under
288  `~/.local/share/rustdocs-mcp-server/<crate_name>/<sanitized_version_req>/<features_hash>/embeddings.bin`.
289  The `sanitized_version_req` is derived from the version requirement, and
290  `features_hash` is a hash representing the specific combination of features
291  requested at startup. This ensures different feature sets are cached
292  separately.
293- **Format:** Data is cached using `bincode` serialization.
294- **Regeneration:** If the cache file is missing, corrupted, or cannot be
295  decoded, the server will automatically regenerate the documentation and
296  embeddings.
297 
298## How it Works
299 
3001. **Initialization:** Parses the crate specification and optional features from
301   the command line using `clap`.
3022. **Cache Check:** Looks for a pre-existing cache file for the specific crate,
303   version requirement, and feature set.
3043. **Documentation Generation (if cache miss):**
305   - Creates a temporary Rust project depending only on the target crate,
306     enabling the specified features in its `Cargo.toml`.
307   - Runs `cargo doc` using the `cargo` library API to generate HTML
308     documentation in the temporary directory.
309   - Dynamically locates the correct output directory within `target/doc` by
310     searching for the subdirectory containing `index.html`.
3114. **Content Extraction (if cache miss):**
312   - Walks the generated HTML files within the located documentation directory.
313   - Uses the `scraper` crate to parse each HTML file and extract text content
314     from the main content area (`<section id="main-content">`).
3155. **Embedding Generation (if cache miss):**
316   - Uses the `async-openai` crate and `tiktoken-rs` to generate embeddings for
317     each extracted document chunk using the `text-embedding-3-small` model.
318   - Calculates the estimated cost based on the number of tokens processed.
3196. **Caching (if cache miss):** Saves the extracted document content and their
320   corresponding embeddings to the cache file (path includes features hash)
321   using `bincode`.
3227. **Server Startup:** Initializes the `RustDocsServer` with the
323   loaded/generated documents and embeddings.
3248. **MCP Serving:** Starts the MCP server using `rmcp` over stdio.
3259. **Query Handling (`query_rust_docs` tool):**
326   - Generates an embedding for the user's question.
327   - Calculates the cosine similarity between the question embedding and all
328     cached document embeddings.
329   - Identifies the document chunk with the highest similarity.
330   - Sends the user's question and the content of the best-matching document
331     chunk to the `gpt-4o-mini-2024-07-18` model via the OpenAI API.
332   - The LLM is prompted to answer the question based _only_ on the provided
333     context.
334   - Returns the LLM's response to the MCP client.
335 
336## License
337 
338This project is licensed under the MIT License.
339 
340Copyright (c) 2025 Govcraft
341 
342## Sponsor
343 
344Govcraft is a one-person shop—no corporate backing, no investors, just me building useful tools. If this project helps you, [sponsoring](https://github.com/sponsors/Govcraft) keeps the work going.
345 
346[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-%E2%9D%A4-%23db61a2?logo=GitHub)](https://github.com/sponsors/Govcraft)
347