Crates Docs MCP 服务器

一个高性能的 Rust crate 文档查询 MCP 服务器，支持多种传输协议和 OAuth 认证。

目录

• 特性
• 快速开始
  • 安装
• MCP 客户端集成指南
• MCP 工具详解
• 使用示例
• 命令行使用
• 配置
• 传输协议
• 开发
• 部署
• API 端点
• 故障排除
• 许可证
• 贡献
• 致谢
• 支持

特性

• 🚀 高性能: 使用异步 Rust 和 LRU 智能缓存
• 🔧 多种传输协议: 支持 Stdio、HTTP 和 SSE
• 🔐 OAuth 认证: 支持 GitHub、Google、Keycloak 等
• 📚 完整的文档查询: 支持查找 crate、搜索 crate、查找特定项目
• 🛡️ 安全: 支持速率限制、连接池和请求验证
• 📊 监控: 内置健康检查和性能监控
• ⚙️ 可配置: 灵活的配置文件和环境变量支持

快速开始

安装

下载二进制文件

从github release中获取二进制文件

从源码构建

# 克隆仓库
git clone https://github.com/KingingWang/crates-docs.git
cd crates-docs

# 构建项目
cargo build --release

# 二进制文件位于 target/release/crates-docs

使用 Docker

# 构建 Docker 镜像
docker build -t crates-docs .

# 运行容器（默认读取容器内 /app/config.toml，并监听 0.0.0.0:8080）
docker run -p 8080:8080 crates-docs

# 使用宿主机配置文件覆盖默认配置
# 注意：容器内固定使用 /app/config.toml
# 如需自定义，请挂载到该路径
docker run -p 8080:8080 \
  -v $(pwd)/examples/config.example.toml:/app/config.toml:ro \
  crates-docs

从 crates.io 安装

cargo install crates-docs

MCP 客户端集成指南

在 Claude Desktop 中使用

编辑 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "crates-docs": {
      "command": "/path/to/crates-docs",
      "args": ["serve", "--mode", "stdio"]
    }
  }
}

在 Cursor 中使用

编辑 Cursor 配置文件 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "crates-docs": {
      "command": "/path/to/crates-docs",
      "args": ["serve", "--mode", "stdio"]
    }
  }
}

在 Windsurf 中使用

编辑 Windsurf 配置文件 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "crates-docs": {
      "command": "/path/to/crates-docs",
      "args": ["serve", "--mode", "stdio"]
    }
  }
}

在 Zed 中使用

编辑 Zed 配置文件 ~/.config/zed/settings.json：

{
  "mcp_servers": {
    "crates-docs": {
      "command": "/path/to/crates-docs",
      "args": ["serve", "--mode", "stdio"]
    }
  }
}

使用 HTTP 模式

如果需要通过网络访问，可以使用 HTTP 模式：

# 启动 HTTP 服务器
cargo run -- serve --mode http --host 0.0.0.0 --port 8080

然后在 MCP 客户端中配置：

{
  "mcpServers": {
    "crates-docs": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

MCP 工具详解

1. lookup_crate - 查找 Crate 文档

从 docs.rs 获取 Rust crate 的完整文档。

参数：

参数	类型	必需	描述
crate_name	string	✅	Crate 名称，如 serde、tokio
version	string	❌	版本号，默认最新版本，如 1.0.0
format	string	❌	输出格式：markdown（默认）、text、html

示例：

// 查找最新版本
{ "crate_name": "serde" }

// 查找特定版本
{ "crate_name": "tokio", "version": "1.35.0" }

// 获取纯文本格式
{ "crate_name": "reqwest", "format": "text" }

2. search_crates - 搜索 Crate

从 crates.io 搜索 Rust crate。

参数：

参数	类型	必需	描述
query	string	✅	搜索关键词
limit	number	❌	结果数量（1-100），默认 10
format	string	❌	输出格式：markdown（默认）、text、json

示例：

// 基本搜索
{ "query": "web framework" }

// 限制结果数量
{ "query": "async runtime", "limit": 5 }

// 获取 JSON 格式
{ "query": "serialization", "format": "json" }

3. lookup_item - 查找特定项目文档

在指定 crate 中查找特定类型、函数或模块的文档。

参数：

参数	类型	必需	描述
crate_name	string	✅	Crate 名称
item_path	string	✅	项目路径，如 serde::Serialize、std::collections::HashMap
version	string	❌	版本号
format	string	❌	输出格式：markdown（默认）、text

示例：

// 查找 serde 的 Serialize trait
{ "crate_name": "serde", "item_path": "serde::Serialize" }

// 查找 tokio 的 run 函数
{ "crate_name": "tokio", "item_path": "tokio::runtime::Runtime::run" }

// 查找特定版本的 HashMap
{ "crate_name": "std", "item_path": "std::collections::HashMap", "version": "1.75.0" }

4. health_check - 健康检查

检查服务器和外部服务的健康状态。

参数：

参数	类型	必需	描述
check_type	string	❌	检查类型：all（默认）、external、internal、docs_rs、crates_io
verbose	boolean	❌	详细输出，默认 false

示例：

// 完整检查
{ "check_type": "all", "verbose": true }

// 只检查外部服务
{ "check_type": "external" }

// 只检查 docs.rs
{ "check_type": "docs_rs" }

使用示例

示例 1: 了解一个新 crate

用户: "帮我了解一下 serde 这个 crate"

AI 会使用:

{ "crate_name": "serde" }

示例 2: 查找特定功能

用户: "tokio 怎么创建一个异步任务？"

AI 会使用:

{ "crate_name": "tokio", "item_path": "tokio::spawn" }

示例 3: 搜索相关 crate

用户: "有什么好用的 HTTP 客户端库？"

AI 会使用:

{ "query": "http client", "limit": 10 }

示例 4: 比较版本差异

用户: "reqwest 0.11 和 0.12 有什么区别？"

AI 会使用:

{ "crate_name": "reqwest", "version": "0.11" }
{ "crate_name": "reqwest", "version": "0.12" }

命令行使用

启动服务器

# 使用默认配置启动服务器（混合模式：HTTP + SSE）
cargo run -- serve

# 使用 Stdio 模式（用于 MCP 客户端集成）
cargo run -- serve --mode stdio

# 使用 HTTP 模式
cargo run -- serve --mode http --host 0.0.0.0 --port 8080

# 启用调试日志
cargo run -- serve --debug

# 使用自定义配置文件
cargo run -- serve --config /path/to/config.toml

生成配置文件

# 生成默认配置文件
cargo run -- config --output config.toml

# 覆盖已存在的配置文件
cargo run -- config --output config.toml --force

测试工具

# 测试查找 crate
cargo run -- test --tool lookup_crate --crate-name serde

# 测试搜索 crate
cargo run -- test --tool search_crates --query "web framework" --limit 5

# 测试查找项目
cargo run -- test --tool lookup_item --crate-name serde --item-path "serde::Serialize"

# 测试健康检查
cargo run -- test --tool health_check

健康检查

# 执行健康检查
cargo run -- health

# 详细输出
cargo run -- health --verbose

# 检查特定服务
cargo run -- health --check-type external

注意：当前 health CLI 子命令仍是占位实现，主要用于命令结构演示；真正的健康检查能力目前在 MCP 工具 health_check 中实现。

配置

配置文件示例

创建 config.toml：

[server]
name = "crates-docs"
version = "0.2.1"
description = "高性能 Rust crate 文档查询 MCP 服务器"
host = "0.0.0.0"
port = 8080
transport_mode = "hybrid"
enable_sse = true
enable_oauth = false
max_connections = 100
request_timeout_secs = 30
response_timeout_secs = 60
allowed_hosts = ["localhost", "127.0.0.1", "0.0.0.0"]
allowed_origins = ["http://localhost:*"]

[cache]
cache_type = "memory"  # 或 "redis"
memory_size = 1000
# redis_url = "redis://localhost:6379"
default_ttl = 3600

[oauth]
enabled = false
# client_id = "your-client-id"
# client_secret = "your-client-secret"
# redirect_uri = "http://localhost:8080/oauth/callback"
# authorization_endpoint = "https://provider.com/oauth/authorize"
# token_endpoint = "https://provider.com/oauth/token"
scopes = ["openid", "profile", "email"]
provider = "Custom"

[logging]
level = "info"
file_path = "./logs/crates-docs.log"
enable_console = true
enable_file = true
max_file_size_mb = 100
max_files = 10

[performance]
http_client_pool_size = 10
cache_max_size = 1000
cache_default_ttl_secs = 3600
rate_limit_per_second = 100
concurrent_request_limit = 50
enable_response_compression = true

环境变量

所有配置都可以通过环境变量覆盖：

export CRATES_DOCS_HOST="0.0.0.0"
export CRATES_DOCS_PORT="8080"
export CRATES_DOCS_TRANSPORT_MODE="http"
export CRATES_DOCS_LOG_LEVEL="debug"

传输协议

Stdio 模式（推荐用于 MCP 客户端）

最简单、最安全的模式，适合与 MCP 客户端（Claude Desktop、Cursor 等）集成：

cargo run -- serve --mode stdio

HTTP 模式（Streamable HTTP）

适合网络服务和需要远程访问的场景：

cargo run -- serve --mode http --host 0.0.0.0 --port 8080

SSE 模式（Server-Sent Events）

用于向后兼容，推荐使用 Hybrid 模式：

cargo run -- serve --mode sse --host 0.0.0.0 --port 8080

混合模式（推荐用于网络服务）

同时支持 HTTP 和 SSE，最灵活的模式：

cargo run -- serve --mode hybrid --host 0.0.0.0 --port 8080

开发

构建

# 开发构建
cargo build

# 发布构建
cargo build --release

# 检查代码
cargo check
cargo clippy
cargo fmt

测试

# 运行单元测试
cargo test

# 运行集成测试
cargo test --test integration_tests

# 运行特定测试
cargo test test_lookup_crate

# 运行所有特性测试
cargo test --all-features

代码质量

# 代码格式化
cargo fmt

# 代码检查
cargo clippy -- -D warnings

# 安全检查
cargo audit

部署

系统服务（Systemd）

创建 /etc/systemd/system/crates-docs.service：

[Unit]
Description=Crates Docs MCP Server
After=network.target

[Service]
Type=simple
User=crates-docs
WorkingDirectory=/opt/crates-docs
ExecStart=/opt/crates-docs/target/release/crates-docs serve --config /etc/crates-docs/config.toml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Docker Compose

version: '3.8'
services:
  crates-docs:
    build: .
    ports:
      - "8080:8080"
    environment:
      CRATES_DOCS_HOST: 0.0.0.0
      CRATES_DOCS_PORT: 8080
      CRATES_DOCS_TRANSPORT_MODE: hybrid
    volumes:
      - ./config.toml:/app/config.toml:ro
      - ./logs:/app/logs
      - ./data:/app/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

启动服务：

docker compose up -d

API 端点

健康检查

当前 README 中曾使用 GET /health 作为示意，但从现有代码看，项目已明确实现并可确认的网络端点主要是 MCP 传输端点，而不是独立的 HTTP 健康检查路由。也就是说：

• CLI 健康检查命令见 health_command()
• MCP 工具健康检查实现见 health_check
• HTTP/SSE 服务端点由传输层启动，见 run_http_server()、run_sse_server()、run_hybrid_server()

因此，这里更准确的 API 描述应聚焦 MCP 端点：

MCP 端点

• POST /mcp - MCP Streamable HTTP 端点
• GET /sse - MCP SSE 端点

故障排除

常见问题

1. 端口被占用

# 检查端口占用
sudo lsof -i :8080

# 杀死占用进程
sudo kill -9 <PID>

2. 内存不足

调整配置文件中的缓存大小：

[cache]
memory_size = 500

3. 网络问题

# 检查网络连接
curl -I https://docs.rs/
curl -I https://crates.io/api/v1/crates?q=test&per_page=1

日志

日志文件位于 ./logs/crates-docs.log，可以通过配置调整日志级别：

[logging]
level = "debug"  # trace, debug, info, warn, error

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

致谢

• rust-mcp-sdk - MCP SDK
• docs.rs - Rust 文档服务
• crates.io - Rust 包注册表

支持

如有问题，请：

1. 查看 Issues
2. 查看 文档
3. 发送邮件到 kingingwang@foxmail.com