Rust Docs MCP Server

Rust 文档 MCP 服务

⭐ 喜欢这个项目？请在 GitHub 上为仓库 点亮星标，以示支持并获取最新动态！ ⭐

动机

现代 AI 编码助手（如 Cursor、Cline、Roo Code 等）擅长理解代码结构和语法，却常常难以掌握快速演进的库和框架的具体细节，在 Rust 这类 crate 更新频繁的生态系统中尤其如此。由于训练数据存在截止时间，它们可能不了解最新 API，从而给出错误或过时的代码建议。

此 MCP 服务通过为特定 Rust crate 提供专注且最新的知识来源，应对这一挑战。为某个 crate（例如 serde、tokio、reqwest）运行此服务的一个实例，即可为你的大模型编码助手提供一个工具（query_rust_docs），让它在编写与该 crate 相关的代码_之前_使用。

收到使用此工具的指示后，大模型可以针对该 crate 的 API 或用法提出具体问题，并直接从_当前_文档中获取答案。这能显著提高生成代码的准确性和相关性，减少手动修正的需求，并加快开发速度。

可以同时运行此服务的多个实例，让大模型助手在一次编码过程中访问多个不同 crate 的文档。

此服务会获取指定 Rust crate 的文档，为内容生成嵌入，并提供一个 MCP 工具，根据文档上下文回答有关该 crate 的问题。

功能

• 针对性文档： 每个服务实例专注于一个 Rust crate。
• 功能支持： 可指定生成文档所需的 crate 功能。
• 语义搜索： 使用 OpenAI 的 text-embedding-3-small 模型，查找与给定问题最相关的文档部分。
• 大模型摘要： 利用 OpenAI 的 gpt-4o-mini-2024-07-18 模型，仅根据检索到的文档上下文生成简洁答案。
• 缓存： 根据 crate、版本_和_请求的功能，将生成的文档内容和嵌入缓存到用户的 XDG 数据目录（~/.local/share/rustdocs-mcp-server/ 或类似目录），以加快后续启动速度。
• MCP 集成： 作为标准 MCP 服务通过 stdio 运行，并提供工具和资源。

前提条件

• OpenAI API 密钥： 用于生成嵌入和摘要回答。服务要求在 OPENAI_API_KEY 环境变量中提供此密钥。（服务还需要网络连接，以下载 crate 依赖项并调用 OpenAI API。）

安装

推荐的安装方式是从 GitHub Releases 页面 下载适用于你的操作系统的预编译二进制文件。

1. 前往 Releases 页面。
2. 下载适用于你系统的压缩包（Windows 使用 .zip，Linux/macOS 使用 .tar.gz）。
3. 解压 rustdocs_mcp_server（或 rustdocs_mcp_server.exe）二进制文件。
4. 将二进制文件放入包含在系统 PATH 环境变量中的目录（例如 /usr/local/bin、~/bin）。

从源代码构建（备选）

如果你更愿意从源代码构建，则需要安装 Rust 工具链。

1. 克隆仓库：

   git clone https://github.com/Govcraft/rust-docs-mcp-server.git
   cd rust-docs-mcp-server
   

2. 构建服务：

   cargo build --release
   

用法

新 Crate 的重要说明：

首次使用某个 Crate（或使用新版本／功能集）时，服务器需要下载文档并生成嵌入向量。此过程可能需要一些时间，尤其是对于文档量很大的 Crate，并且需要有效的互联网连接和 OpenAI API 密钥。

建议在将服务器添加到 AI 编码助手（例如 Roo Code、Cursor 等）之前，先针对任何新的 Crate 配置直接从命令行运行一次。这样可以完成初始嵌入向量的生成和缓存。看到表明服务器已就绪的启动消息（例如 “MCP Server listening on stdio”）后，即可关闭服务器（Ctrl+C）。之后的启动（包括由编码助手发起的启动）都会使用缓存数据，启动速度会快得多。

运行服务器

服务器通过命令行启动，并需要目标 Crate 的 Package ID Specification。此规范采用 Cargo 使用的格式（例如 crate_name、crate_name@version_req）。完整的规范详情请参阅 man cargo-pkgid 或 Cargo 文档。

也可以使用 -F 或 --features 标志指定所需的 Crate 功能，后面跟以逗号分隔的功能列表。对于需要启用特定功能才能成功运行 cargo doc 的 Crate（例如需要运行时功能的 Crate，如 async-stripe），此选项是必需的。

# Set the API key (replace with your actual key)
export OPENAI_API_KEY="sk-..."

# Example: Run server for the latest 1.x version of serde
rustdocs_mcp_server "serde@^1.0"

# Example: Run server for a specific version of reqwest
rustdocs_mcp_server "[email protected]"

# Example: Run server for the latest version of tokio
rustdocs_mcp_server tokio

# Example: Run server for async-stripe, enabling a required runtime feature
rustdocs_mcp_server "[email protected]" -F runtime-tokio-hyper-rustls

# Example: Run server for another crate with multiple features
rustdocs_mcp_server "[email protected]" --features feat1,feat2

针对特定 Crate 版本 和功能集 首次运行时，服务器将：

1. 使用 cargo doc（以及指定的功能）下载 Crate 文档。
2. 解析 HTML 文档。
3. 使用 OpenAI API 为文档内容生成嵌入向量（此过程可能需要一些时间并产生费用，不过对于大多数 Crate，费用通常只有几分之一美分；即使是拥有 5000 多个文档页面的大型 Crate（如 async-stripe），测试期间生成嵌入向量也只花费了 0.18 美元）。
4. 缓存文档内容和嵌入向量，避免再次产生费用。
5. 启动 MCP 服务。

之后针对相同 Crate 版本 和功能集 的运行将从缓存加载数据，启动速度会快得多。

MCP 交互

服务器通过标准输入／输出（stdio）使用 Model Context Protocol 进行通信。它公开以下内容：

• 工具：query_rust_docs

  • 说明： 使用语义搜索和大模型摘要，查询服务器启动时指定的 Rust Crate 文档。
  • 输入架构：

    {
      "type": "object",
      "properties": {
        "question": {
          "type": "string",
          "description": "The specific question about the crate's API or usage."
        }
      },
      "required": ["question"]
    }
    

  • 输出： 一段文本响应，包含大模型根据相关文档上下文生成的答案，前缀为 From <crate_name> docs:.
  • MCP 调用示例：

    {
      "jsonrpc": "2.0",
      "method": "callTool",
      "params": {
        "tool_name": "query_rust_docs",
        "arguments": {
          "question": "How do I make a simple GET request with reqwest?"
        }
      },
      "id": 1
    }
    

• 资源：crate://<crate_name>

  • 说明： 提供此服务器实例配置使用的 Rust Crate 名称。
  • URI： crate://<crate_name>（例如 crate://serde、crate://reqwest）
  • 内容： 包含 Crate 名称的纯文本。

• 日志： 服务器通过 logging/message 通知，将信息性日志（启动消息、查询处理步骤）发送回 MCP 客户端。

客户端配置示例（Roo Code）

你可以配置 Roo Code 等 MCP 客户端来运行此服务的多个实例，每个实例针对不同的 crate。以下是 Roo Code 的 mcp_settings.json 文件示例，为 reqwest 和 async-stripe 配置服务（注意 async-stripe 添加了 features 参数）：

{
  "mcpServers": {
    "rust-docs-reqwest": {
      "command": "/path/to/your/rustdocs_mcp_server",
      "args": [
        "[email protected]"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
      },
      "disabled": false,
      "alwaysAllow": []
    },
    "rust-docs-async-stripe": {
      "command": "rustdocs_mcp_server",
      "args": [
        "[email protected]",
        "-F",
        " runtime-tokio-hyper-rustls"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

注意：

• 如果编译后的二进制文件不在 PATH 中，请将 /path/to/your/rustdocs_mcp_server 替换为系统中的实际路径。
• 将 YOUR_OPENAI_API_KEY_HERE 替换为你的实际 OpenAI API 密钥。
• 这些键（rust-docs-reqwest、rust-docs-async-stripe）是你自行选择的任意名称，用于在 Roo Code 中标识服务实例。

客户端配置示例（Claude Desktop）

Claude Desktop 用户可以在 MCP 设置中配置此服务。以下示例为 serde 和 async-stripe 配置服务：

{
  "mcpServers": {
    "rust-docs-serde": {
      "command": "/path/to/your/rustdocs_mcp_server",
      "args": [
        "serde@^1.0"
      ]
    },
    "rust-docs-async-stripe-rt": {
      "command": "rustdocs_mcp_server",
      "args": [
        "[email protected]",
        "-F",
        "runtime-tokio-hyper-rustls"
      ]
    }
  }
}

注意：

• 确保 rustdocs_mcp_server 位于系统的 PATH 中，或提供完整路径（例如，/path/to/your/rustdocs_mcp_server）。
• 这些键（rust-docs-serde、rust-docs-async-stripe-rt）是你自行选择的任意名称，用于标识服务实例。
• 请记得在 Claude Desktop 可访问的位置设置 OPENAI_API_KEY 环境变量（可以是系统级设置，也可以通过启动 Claude Desktop 的方式设置）。Claude Desktop 的 MCP 配置可能不直接支持像 Roo Code 那样按服务设置环境变量。
• 示例展示了如何为 async-stripe 等需要特定 features 的 crate 添加 -F 参数。

缓存

• **位置：**缓存的文档和嵌入数据存储在 XDG 数据目录中，通常位于 ~/.local/share/rustdocs-mcp-server/<crate_name>/<sanitized_version_req>/<features_hash>/embeddings.bin。 sanitized_version_req 根据版本要求生成，而 features_hash 是一个哈希值，用于表示启动时请求的特定 features 组合。这可确保不同的 features 集分别缓存。
• **格式：**使用 bincode 序列化缓存数据。
• **重新生成：**如果缓存文件缺失、损坏或无法解码，服务将自动重新生成文档和嵌入数据。

工作原理

1. 初始化： 使用 clap 从命令行解析 crate 规格和可选功能。
2. 缓存检查： 查找针对特定 crate、版本要求和功能集的现有缓存文件。
3. 生成文档（缓存未命中时）：
   • 创建一个仅依赖目标 crate 的临时 Rust 项目，并在其 Cargo.toml 中启用指定功能。
   • 使用 cargo 库 API 运行 cargo doc，在临时目录中生成 HTML 文档。
   • 通过在 target/doc 中搜索包含 index.html 的子目录，动态定位正确的输出目录。
4. 提取内容（缓存未命中时）：
   • 遍历已定位文档目录中的生成 HTML 文件。
   • 使用 scraper crate 解析每个 HTML 文件，并从主要内容区域（<section id="main-content">）提取文本内容。
5. 生成嵌入（缓存未命中时）：
   • 使用 async-openai crate 和 tiktoken-rs，通过 text-embedding-3-small 模型为每个提取出的文档块生成嵌入。
   • 根据处理的令牌数量计算预估费用。
6. 缓存（缓存未命中时）： 使用 bincode 将提取的文档内容及其对应的嵌入保存到缓存文件中（路径包含功能哈希值）。
7. 启动服务： 使用已加载或生成的文档及嵌入初始化 RustDocsServer。
8. 提供 MCP 服务： 使用 rmcp 通过标准输入输出启动 MCP 服务。
9. 处理查询（query_rust_docs 工具）：
   • 为用户的问题生成嵌入。
   • 计算问题嵌入与所有缓存文档嵌入之间的余弦相似度。
   • 找出相似度最高的文档块。
   • 通过 OpenAI API 将用户的问题和匹配度最高的文档块内容发送给 gpt-4o-mini-2024-07-18 模型。
   • 提示大模型仅根据提供的上下文回答问题。
   • 将大模型的回复返回给 MCP 客户端。

许可证

本项目采用 MIT 许可证。

版权所有 (c) 2025 Govcraft

赞助

Govcraft 是一个由我一人经营的小项目，没有公司支持，也没有投资者，只有我在打造实用工具。如果这个项目对你有所帮助，赞助即可支持项目持续进行。