Crates Docs MCP 服务器

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

特性

🚀 高性能: 异步 Rust + TinyLFU/TTL 内存缓存，支持按条目 TTL，可选 Redis 扩展
📦 多架构 Docker 镜像: 支持 linux/amd64 和 linux/arm64
🔧 多种传输协议: Stdio、HTTP (Streamable HTTP)、SSE、Hybrid
📚 完整文档查询: crate 搜索、文档查找、特定项目查询
🛡️ 安全可靠: 速率限制、连接池、请求验证
📊 健康监控: 内置健康检查和性能监控
🏗️ 模块化架构: 清晰的模块划分，易于扩展和维护
🔄 HTTP 重试机制: 可配置的 HTTP 客户端重试逻辑，提高外部服务调用可靠性
📊 Prometheus 指标: 内置指标监控支持，便于运维观测
⏱️ 细粒度缓存 TTL: 为 crate 文档、项目文档、搜索结果提供独立的 TTL 配置

架构图

系统架构

graph TB
    subgraph "MCP 客户端"
        Client[Claude/Cursor/Windsurf]
    end

    subgraph "传输层"
        Stdio[Stdio 传输]
        HTTP[HTTP 传输]
        SSE[SSE 传输]
    end

    subgraph "Crates Docs MCP 服务器"
        Server[CratesDocsServer]
        Handler[CratesDocsHandler]
        Registry[ToolRegistry]

        subgraph "工具层"
            LookupCrate[lookup_crate]
            SearchCrates[search_crates]
            LookupItem[lookup_item]
            HealthCheck[health_check]
        end

        subgraph "服务层"
            DocService[DocService]
            HttpClient[HTTP Client]
        end

        subgraph "缓存层"
            MemoryCache[MemoryCache]
            RedisCache[RedisCache]
            DocCache[DocCache]
        end
    end

    subgraph "外部服务"
        DocsRs[docs.rs]
        CratesIo[crates.io]
    end

    Client --> Stdio
    Client --> HTTP
    Client --> SSE

    Stdio --> Server
    HTTP --> Server
    SSE --> Server

    Server --> Handler
    Handler --> Registry

    Registry --> LookupCrate
    Registry --> SearchCrates
    Registry --> LookupItem
    Registry --> HealthCheck

    LookupCrate --> DocService
    SearchCrates --> DocService
    LookupItem --> DocService
    HealthCheck --> HttpClient

    DocService --> HttpClient
    DocService --> DocCache

    DocCache --> MemoryCache
    DocCache --> RedisCache

    HttpClient --> DocsRs
    HttpClient --> CratesIo

数据流

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as CratesDocsServer
    participant Handler as CratesDocsHandler
    participant Tool as 工具实现
    participant Cache as DocCache
    participant External as 外部服务

    Client->>Server: MCP 请求
    Server->>Handler: 路由请求
    Handler->>Tool: 执行工具

    alt 缓存命中
        Tool->>Cache: 查询缓存
        Cache-->>Tool: 返回缓存数据
    else 缓存未命中
        Tool->>Cache: 查询缓存
        Cache-->>Tool: 未命中
        Tool->>External: HTTP 请求
        External-->>Tool: 返回数据
        Tool->>Cache: 写入缓存
    end

    Tool-->>Handler: 返回结果
    Handler-->>Server: 格式化响应
    Server-->>Client: MCP 响应

快速开始

使用 Docker（推荐）

# 从 Docker Hub 拉取镜像
docker pull kingingwang/crates-docs:latest

# 运行容器（官方镜像内置配置默认监听 0.0.0.0:8080）
docker run -d --name crates-docs -p 8080:8080 kingingwang/crates-docs:latest

# 使用自定义配置
docker run -d --name crates-docs -p 8080:8080 \
  -v $(pwd)/config.toml:/app/config.toml:ro \
  kingingwang/crates-docs:latest

Docker Compose

version: '3.8'
services:
  crates-docs:
    image: kingingwang/crates-docs:latest
    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
    restart: unless-stopped

docker compose up -d

从源码构建

git clone https://github.com/KingingWang/crates-docs.git
cd crates-docs
cargo build --release
./target/release/crates-docs serve

从 crates.io 安装

cargo install crates-docs
crates-docs serve

MCP 客户端集成

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/mcp.json：

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

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

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

Cherry Studio

打开 Cherry Studio 设置
找到 MCP 服务器 选项
点击 添加服务器
填写参数：

字段	值
名称	`crates-docs`
类型	`STDIO`
命令	`/path/to/crates-docs`
参数1	`serve`
参数2	`--mode`
参数3	`stdio`

点击保存

注意：将 /path/to/crates-docs 替换为实际的可执行文件路径。

HTTP 模式

适合远程访问或网络服务：

crates-docs serve --mode hybrid --host 0.0.0.0 --port 8080

客户端配置：

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

MCP 工具

1. lookup_crate - 查找 Crate 文档

从 docs.rs 获取完整文档。

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

{ "crate_name": "serde" }
{ "crate_name": "tokio", "version": "1.35.0" }

2. search_crates - 搜索 Crate

从 crates.io 搜索 Rust crate，支持按相关性、总下载量、近期下载热度、最近更新时间和最新发布进行排序，适合做 crate 发现、选型和横向比较。

参数	类型	必需	描述
`query`	string	✅	搜索关键词
`limit`	number	❌	结果数量（1-100），默认 10
`sort`	string	❌	排序方式，支持 `relevance`（默认）、`downloads`、`recent-downloads`、`recent-updates`、`new`
`format`	string	❌	输出格式：`markdown`、`text`、`json`

排序建议

relevance：优先返回与关键词最相关的结果，适合通用搜索。
downloads：按累计下载量排序，适合优先看生态里最常用、最成熟的 crate。
recent-downloads：按近期下载热度排序，适合观察最近更活跃或更受关注的项目。
recent-updates：按最近更新时间排序，适合关注仍在持续维护的 crate。
new：按发布时间排序，适合探索新发布项目。

{ "query": "web framework", "limit": 5, "sort": "downloads" }
{ "query": "mcp", "sort": "recent-downloads", "format": "json" }

3. lookup_item - 查找特定项目

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

参数	类型	必需	描述
`crate_name`	string	✅	Crate 名称
`item_path`	string	✅	项目路径，如 `serde::Serialize`
`version`	string	❌	版本号
`format`	string	❌	输出格式

{ "crate_name": "serde", "item_path": "serde::Serialize" }
{ "crate_name": "tokio", "item_path": "tokio::runtime::Runtime" }

4. health_check - 健康检查

检查服务器和外部服务状态。

参数	类型	必需	描述
`check_type`	string	❌	`all`、`external`、`internal`、`docs_rs`、`crates_io`
`verbose`	boolean	❌	详细输出

{ "check_type": "all", "verbose": true }

详细使用示例

Stdio 模式

Stdio 模式适合与本地 MCP 客户端集成：

# 启动 Stdio 服务器
crates-docs serve --mode stdio

# 或使用默认配置（stdio 是某些客户端的默认模式）
crates-docs serve

MCP 客户端配置示例：

{
  "mcpServers": {
    "crates-docs": {
      "command": "/usr/local/bin/crates-docs",
      "args": ["serve", "--mode", "stdio"]
    }
  }
}

HTTP 模式

HTTP 模式适合远程访问或网络服务：

# 启动 HTTP 服务器
crates-docs serve --mode http --host 0.0.0.0 --port 8080

# 使用自定义配置
crates-docs serve --config config.toml

使用 curl 测试 HTTP 端点：

# 获取服务器信息（健康检查）
curl http://localhost:8080/health

# MCP 工具调用示例（需要 MCP 协议格式）
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

SSE 模式

SSE 模式支持服务器推送：

# 启动 SSE 服务器
crates-docs serve --mode sse --host 0.0.0.0 --port 8080

SSE 客户端连接：

# 连接到 SSE 端点
curl http://localhost:8080/sse

工具调用示例

search_crates - 搜索 Crate

# 使用 CLI 测试工具
crates-docs test --tool search_crates --query "serde" --limit 5

# 预期输出：
# 搜索 "serde" 的结果：
# 1. serde (v1.0.xxx) - 序列化框架
#    下载量: xxx
#    描述: ...

MCP 调用参数：

{
  "name": "search_crates",
  "arguments": {
    "query": "web framework",
    "limit": 10,
    "sort": "downloads",
    "format": "markdown"
  }
}

lookup_crate - 查找 Crate 文档

# 使用 CLI 测试工具
crates-docs test --tool lookup_crate --crate-name serde

# 指定版本
crates-docs test --tool lookup_crate --crate-name tokio --version "1.35.0"

MCP 调用参数：

{
  "name": "lookup_crate",
  "arguments": {
    "crate_name": "serde",
    "version": "1.0.200",
    "format": "markdown"
  }
}

lookup_item - 查找特定项目

# 使用 CLI 测试工具
crates-docs test --tool lookup_item --crate-name serde --item-path "serde::Serialize"

MCP 调用参数：

{
  "name": "lookup_item",
  "arguments": {
    "crate_name": "tokio",
    "item_path": "tokio::runtime::Runtime",
    "version": "1.35.0",
    "format": "markdown"
  }
}

health_check - 健康检查

# 使用 CLI 执行健康检查
crates-docs health --check-type all --verbose

# 仅检查外部服务
crates-docs health --check-type external

MCP 调用参数：

{
  "name": "health_check",
  "arguments": {
    "check_type": "all",
    "verbose": true
  }
}

使用示例

了解新 crate

用户: "帮我了解一下 serde"

AI 调用: { "crate_name": "serde" }

查找特定功能

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

AI 调用: { "crate_name": "tokio", "item_path": "tokio::spawn" }

搜索相关 crate

用户: "有什么稳定、大家都常用的 HTTP 客户端？"

AI 调用: { "query": "http client", "limit": 10, "sort": "downloads" }

命令行

# 启动服务器
crates-docs serve                          # 混合模式
crates-docs serve --mode stdio             # Stdio 模式
crates-docs serve --mode http --port 8080  # HTTP 模式

# 生成配置
crates-docs config --output config.toml
crates-docs config --output config.toml --force

# 测试工具
crates-docs test --tool lookup_crate --crate-name serde
crates-docs test --tool search_crates --query "async"
crates-docs test --tool search_crates --query "mcp" --sort downloads
crates-docs test --tool search_crates --query "agent" --sort recent-updates --format json

# CLI 健康检查入口
crates-docs health
crates-docs health --check-type external --verbose

# 版本信息
crates-docs version

全局参数见 Cli，常用项包括 --config、--debug、--verbose。

run_health_command() 会执行真实的健康检查（内部状态 + docs.rs / crates.io 探测），与 MCP 工具 health_check 共用同一套检测逻辑。当整体状态不是 healthy 时，命令以非零退出码结束，可直接用作容器/编排器的健康探针（例如 Docker Compose 的 healthcheck）。

配置

完整配置文件示例

下面是一个完整的配置文件示例，包含所有可用的配置项：

# 服务器配置
[server]
name = "crates-docs"                    # 服务器名称
version = "0.1.0"                       # 服务器版本
description = "Rust crate docs MCP server"  # 服务器描述
host = "0.0.0.0"                        # 监听地址（0.0.0.0 允许外部访问）
port = 8080                             # 监听端口
transport_mode = "hybrid"               # 传输模式：stdio/http/sse/hybrid
enable_sse = true                       # 启用 SSE 支持
enable_oauth = false                    # 启用 OAuth 认证
max_connections = 100                   # 最大并发连接数
request_timeout_secs = 30               # 请求超时（秒）
response_timeout_secs = 60              # 响应超时（秒）
allowed_hosts = ["localhost", "127.0.0.1"]    # 允许的 Host
allowed_origins = ["http://localhost:*"]      # 允许的 Origin

# 缓存配置
[cache]
cache_type = "memory"                   # 缓存类型：memory 或 redis
memory_size = 1000                      # 内存缓存大小（条目数）
redis_url = "redis://localhost:6379"    # Redis 连接 URL（使用 redis 时必需）
key_prefix = ""                         # 缓存键前缀
default_ttl = 3600                      # 默认 TTL（秒）
crate_docs_ttl_secs = 3600              # crate 文档缓存 TTL（秒）
item_docs_ttl_secs = 1800               # 项目文档缓存 TTL（秒）
search_results_ttl_secs = 300           # 搜索结果缓存 TTL（秒）

# 日志配置
[logging]
level = "info"                          # 日志级别：trace/debug/info/warn/error
file_path = "./logs/crates-docs.log"    # 日志文件路径
enable_console = true                   # 启用控制台日志
enable_file = false                     # 启用文件日志
max_file_size_mb = 100                  # 单个日志文件最大大小（MB）
max_files = 10                          # 保留的日志文件数量

# 性能配置
[performance]
http_client_pool_size = 10              # HTTP 客户端连接池大小
http_client_pool_idle_timeout_secs = 90 # 连接池空闲超时（秒）
http_client_connect_timeout_secs = 10   # 连接超时（秒）
http_client_timeout_secs = 30           # 请求超时（秒）
http_client_read_timeout_secs = 30      # 读取超时（秒）
http_client_max_retries = 3             # HTTP 客户端最大重试次数
http_client_retry_initial_delay_ms = 100    # 重试初始延迟（毫秒）
http_client_retry_max_delay_ms = 10000      # 重试最大延迟（毫秒）
cache_max_size = 1000                   # 最大缓存大小
cache_default_ttl_secs = 3600           # 默认缓存 TTL（秒）
rate_limit_per_second = 100             # 每秒请求速率限制
concurrent_request_limit = 50           # 并发请求限制
enable_response_compression = true      # 启用响应压缩
enable_metrics = true                   # 启用 Prometheus 指标
metrics_port = 0                        # 指标端口（0 表示使用服务器端口）

# OAuth 配置（可选），推荐使用 [auth.oauth]
[auth.oauth]
enabled = false                         # 启用 OAuth
client_id = ""                          # OAuth 客户端 ID
client_secret = ""                      # OAuth 客户端密钥
authorization_endpoint = ""             # 授权端点 URL
token_endpoint = ""                     # Token 端点 URL
redirect_uri = ""                       # 回调 URI
scopes = []                             # OAuth 作用域

# API Key 认证配置（可选），必须使用 [auth.api_key]
[auth.api_key]
enabled = false                         # 启用 API Key 认证
keys = []                               # API Key 哈希列表（Argon2 PHC 格式），不要存明文 key
header_name = "X-API-Key"               # API Key 请求头名称
query_param_name = "api_key"            # API Key 查询参数名称
allow_query_param = false               # 是否允许查询参数传递
key_prefix = "sk"                       # API Key 前缀（用于生成和校验结构化 key）

环境变量配置

支持通过环境变量配置，适用于 Docker 部署。

对于 API Key，推荐先生成一次性明文 key，再把生成出的 hash 放入配置或环境变量中：

# 生成新的 API Key（会输出明文 key、key_id 和 hash）
crates-docs generate-api-key --prefix sk

# 服务器配置
CRATES_DOCS_HOST=0.0.0.0
CRATES_DOCS_PORT=8080
CRATES_DOCS_TRANSPORT_MODE=hybrid

# API Key 认证配置
CRATES_DOCS_API_KEY_ENABLED=true
CRATES_DOCS_API_KEYS='$argon2id$...generated_hash...'
CRATES_DOCS_API_KEY_HEADER=X-API-Key
CRATES_DOCS_API_KEY_ALLOW_QUERY=false
CRATES_DOCS_API_KEY_PREFIX=sk

Docker 部署示例

# 使用环境变量启用 API Key 认证（保存 hash，不保存明文 key）
docker run -d \
  -p 8080:8080 \
  -e CRATES_DOCS_API_KEY_ENABLED=true \
  -e CRATES_DOCS_API_KEYS='$argon2id$...generated_hash...' \
  -e CRATES_DOCS_API_KEY_PREFIX=sk \
  -e CRATES_DOCS_HOST=0.0.0.0 \
  kingingwang/crates-docs:latest

Docker Compose 示例

version: '3.8'
services:
  crates-docs:
    image: kingingwang/crates-docs:latest
    ports:
      - "8080:8080"
    environment:
      - CRATES_DOCS_API_KEY_ENABLED=true
      - CRATES_DOCS_API_KEYS=$argon2id$...generated_hash...
      - CRATES_DOCS_API_KEY_PREFIX=sk
      - CRATES_DOCS_HOST=0.0.0.0
      - CRATES_DOCS_PORT=8080

配置项详细说明

`[server]` 服务器配置

配置项	类型	默认值	说明
`name`	string	`"crates-docs"`	服务器名称
`host`	string	`"127.0.0.1"`	监听地址，设为 `"0.0.0.0"` 允许外部访问
`port`	number	`8080`	监听端口
`transport_mode`	string	`"hybrid"`	传输模式：`stdio`/`http`/`sse`/`hybrid`
`enable_sse`	boolean	`true`	是否启用 SSE 支持
`max_connections`	number	`100`	最大并发连接数
`allowed_hosts`	array	`["localhost", "127.0.0.1"]`	允许的 Host 列表（CORS）
`allowed_origins`	array	`["http://localhost:*"]`	允许的 Origin 列表（CORS）

`[cache]` 缓存配置

配置项	类型	默认值	说明
`cache_type`	string	`"memory"`	缓存类型：`memory` 或 `redis`
`memory_size`	number	`1000`	内存缓存条目数
`redis_url`	string	`null`	Redis 连接 URL
`key_prefix`	string	`""`	缓存键前缀
`crate_docs_ttl_secs`	number	`3600`	crate 文档缓存时间（秒）
`item_docs_ttl_secs`	number	`1800`	项目文档缓存时间（秒）
`search_results_ttl_secs`	number	`300`	搜索结果缓存时间（秒）

`[logging]` 日志配置

配置项	类型	默认值	说明
`level`	string	`"info"`	日志级别：`trace`/`debug`/`info`/`warn`/`error`
`enable_console`	boolean	`true`	启用控制台输出
`enable_file`	boolean	`false`	启用文件日志
`file_path`	string	`"./logs/crates-docs.log"`	日志文件路径
`max_file_size_mb`	number	`100`	单个日志文件大小限制
`max_files`	number	`10`	保留的日志文件数

`[performance]` 性能配置

配置项	类型	默认值	说明
`http_client_pool_size`	number	`10`	HTTP 连接池大小
`http_client_max_retries`	number	`3`	HTTP 请求最大重试次数
`rate_limit_per_second`	number	`100`	每秒请求限制
`concurrent_request_limit`	number	`50`	并发请求限制
`enable_response_compression`	boolean	`true`	启用响应压缩
`enable_metrics`	boolean	`true`	启用 Prometheus 指标

环境变量配置

所有配置项都可以通过环境变量覆盖，环境变量优先级最高：

# 服务器配置
export CRATES_DOCS_NAME="crates-docs"
export CRATES_DOCS_HOST="0.0.0.0"
export CRATES_DOCS_PORT="8080"
export CRATES_DOCS_TRANSPORT_MODE="hybrid"

# 日志配置
export CRATES_DOCS_LOG_LEVEL="info"
export CRATES_DOCS_ENABLE_CONSOLE="true"
export CRATES_DOCS_ENABLE_FILE="true"

# 缓存配置
export CRATES_DOCS_CACHE_TYPE="memory"
export CRATES_DOCS_CACHE_MEMORY_SIZE="1000"
export CRATES_DOCS_CACHE_REDIS_URL="redis://localhost:6379"

# 性能配置
export CRATES_DOCS_HTTP_CLIENT_POOL_SIZE="10"
export CRATES_DOCS_RATE_LIMIT_PER_SECOND="100"

注意：环境变量会覆盖配置文件中的设置。布尔值使用 "true" 或 "false" 字符串表示。

API Key 安全建议：

使用 crates-docs generate-api-key --prefix sk 生成新的 key

只保存生成结果中的 hash

明文 key 只展示一次，之后请存入你的密钥管理系统

不要把明文 key 直接写入 config.toml、Docker Compose 或环境变量示例中

⚠️ 重要安全限制：当前版本的 API Key / OAuth 认证尚未在 HTTP/SSE 传输层强制执行。也就是说，即使在配置中启用了认证，HTTP/SSE 端点仍然是未鉴权的。请勿将本服务直接暴露在不可信网络中；应通过 allowed_hosts/allowed_origins、反向代理进行访问控制，或使用 stdio 模式运行。服务启动时若检测到已配置但未强制执行的认证，会打印明显的告警日志。

生成配置文件

使用 CLI 生成默认配置文件：

# 生成配置文件
crates-docs config --output config.toml

# 强制覆盖已存在的文件
crates-docs config --output config.toml --force

传输协议

模式	适用场景	端点
`stdio`	MCP 客户端集成（推荐）	标准输入输出
`http`	网络服务	`POST /mcp`
`sse`	向后兼容	`GET /sse`
`hybrid`	网络服务（推荐）	`/mcp` + `/sse`

MCP 端点

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

注意：这些是 MCP 协议端点，不是普通的 HTTP API。需要使用 MCP 客户端进行交互。

API Key 认证使用指南

API Key 认证用于保护 HTTP/SSE/Hybrid 模式下的 MCP 端点，防止未授权访问。启用后，所有 MCP 请求必须携带有效的 API Key，/health 端点始终开放以便监控。

完整流程概览

1. 生成 API Key  →  得到明文 key（客户端用）和 hash（服务端存）
2. 配置服务端    →  将 hash 写入 config.toml 或环境变量
3. 启动服务      →  crates-docs serve --config config.toml
4. 客户端携带 key →  Authorization: Bearer <明文 key>

第一步：生成 API Key

crates-docs generate-api-key

输出示例：

Generated API key successfully.

Plain-text key (show once and store securely):
sk-live-<your-api-key-here>

Key ID:
<key-id>

Store this hash in configuration or secret storage:
$argon2id$v=19$m=47104,t=1,p=1$<salt>$<hash>

⚠️ 重要：

明文 key（sk-live-...）只显示一次，请立即保存到密钥管理器中，服务端无法从 hash 反推出明文
hash（$argon2id$...）写入服务端配置，用于验证客户端发来的 key
两者不可互换：客户端用明文，服务端存 hash

也可以指定自定义前缀：

crates-docs generate-api-key --prefix myapp

第二步：配置服务端

方式 A：配置文件（推荐）

创建或编辑 config.toml，将生成的 hash 放入 keys 列表：

[auth.api_key]
enabled = true
keys = ["$argon2id$v=19$m=47104,t=1,p=1$<salt>$<hash>"]
header_name = "X-API-Key"
query_param_name = "api_key"
allow_query_param = false
key_prefix = "sk"

支持多个 key（例如为不同客户端分配不同 key）：

[auth.api_key]
enabled = true
keys = [
  "$argon2id$v=19$m=47104,t=1,p=1$hash1...",
  "$argon2id$v=19$m=47104,t=1,p=1$hash2...",
]
key_prefix = "sk"

方式 B：环境变量

export CRATES_DOCS_API_KEY_ENABLED=true
export CRATES_DOCS_API_KEYS='$argon2id$v=19$m=47104,t=1,p=1$<salt>$<hash>'
export CRATES_DOCS_API_KEY_PREFIX=sk

方式 C：CLI 标志

crates-docs serve --enable-api-key

注意：CLI 标志仅启用认证开关，key 列表仍需通过配置文件或环境变量提供。

第三步：启动服务

# 使用配置文件
crates-docs serve --config config.toml --mode hybrid --host 0.0.0.0 --port 8080

# 或使用环境变量
export CRATES_DOCS_API_KEY_ENABLED=true
export CRATES_DOCS_API_KEYS='$argon2id$...'
crates-docs serve --mode hybrid

启动后日志中会显示 API Key 认证已启用。

第四步：客户端使用 API Key

curl 测试

# 使用 Bearer token（直连服务端必须用此方式）
curl -H "Authorization: Bearer sk-live-<your-api-key-here>" \
  -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 未携带 key 的请求会返回 401
curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → 401 Unauthorized

# /health 端点无需认证
curl http://127.0.0.1:8080/health

Claude Desktop 配置

{
  "mcpServers": {
    "crates-docs": {
      "url": "http://your-server:8080/mcp",
      "headers": {
        "Authorization": "Bearer sk-live-<your-api-key-here>"
      }
    }
  }
}

Cursor 配置

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "crates-docs": {
      "url": "http://your-server:8080/mcp",
      "headers": {
        "Authorization": "Bearer sk-live-<your-api-key-here>"
      }
    }
  }
}

其他 MCP 客户端

任何支持自定义 HTTP header 的 MCP 客户端，添加以下 header 即可：

Authorization: Bearer <你的明文 key>

管理操作

查看已注册的 API Key

crates-docs list-api-keys

吊销 API Key

# 通过 Key ID 吊销
crates-docs revoke-api-key --key-id <key_id>

# 吊销后需重启服务生效

添加新 Key

运行 crates-docs generate-api-key 生成新 key
将新 hash 追加到 config.toml 的 keys 列表中
重启服务

常见问题

Q: 为什么不能用 X-API-Key header 直连服务端？

A: 进程内的 MCP 中间件只识别 Authorization: Bearer 头。X-API-Key header 需要配合反向代理使用——代理将 X-API-Key: <k> 改写为 Authorization: Bearer <k> 后转发给后端。详见下方"认证与加密传输"章节。

Q: 可以通过 URL 查询参数传递 key 吗？

A: 配置 allow_query_param = true 后，反向代理可以支持 ?api_key=<key> 方式。但直连服务端仍只接受 Bearer token。出于安全考虑，不建议在 URL 中传递 key（会出现在日志和浏览器历史中）。

Q: 忘记了明文 key 怎么办？

A: 明文 key 只在生成时显示一次，无法从 hash 反推。如果丢失，需要生成新 key 并替换配置中的 hash。

Q: 多个客户端可以共用同一个 key 吗？

A: 可以，但建议为不同客户端分配不同 key，便于独立吊销。

认证与加密传输（TLS）

在 HTTP/SSE/Hybrid 服务器模式下，访问控制分为两层，可按需组合：

能力	由谁提供	说明
认证（只有持有密钥者可连接）	进程内置（默认编译进二进制）	校验 `Authorization: Bearer <key>`，密钥以 Argon2 哈希存储、常量时间比对
加密（被监听也无法解密）	前置反向代理（Caddy/nginx）	终止 TLS，并把 `X-API-Key: <k>` 改写为 `Authorization: Bearer <k>`

进程内置认证（Bearer）

auth 已包含在 default features 中，因此标准 cargo build / cargo install 即具备认证能力。是否真正启用是运行时开关，无需重新编译：

打开/关闭由 auth.api_key.enabled 控制（配置文件、--enable-api-key CLI 标志或 CRATES_DOCS_API_KEY_ENABLED 环境变量），改动后重启生效。
启用后，每个 MCP 请求都必须携带 Authorization: Bearer <key>，否则返回 401； /health 始终开放，便于监控。
密钥用 crates-docs generate-api-key 生成：配置里保存 hash，把明文 key 发给客户端。吊销密钥 = 从 keys 移除并重启。

# 启用后，直连服务端必须使用 Bearer 头：
curl -H "Authorization: Bearer <明文 key>" -X POST http://127.0.0.1:8080/mcp

为什么是 Bearer 而不是 X-API-Key？ 进程内的 MCP 中间件只识别 Authorization: Bearer 头，无法读取 X-API-Key 或查询参数。header_name、 allow_query_param 等配置项仅对前置反向代理有意义（见下）。

加密传输与 `X-API-Key`（反向代理）

进程本身只说明文 HTTP，没有 TLS。若服务要对外暴露、需要加密，或希望继续使用 X-API-Key 头，请在前面加一层反向代理：它终止 TLS（HTTPS），把 X-API-Key: <k> 改写为 Authorization: Bearer <k>，再转发到仅监听 127.0.0.1 的后端——后端依旧做密码学校验，构成纵深防御。

客户端 --HTTPS, X-API-Key--> 反向代理 --HTTP, Authorization: Bearer--> 127.0.0.1:8080

开箱即用的配置（含 Caddy 与 nginx，以及完整步骤）见 docs/reverse-proxy/。使用反向代理时，请把后端绑定到回环地址（server.host = "127.0.0.1"），避免客户端绕过 TLS 直连后端。

缓存策略

内存缓存（默认）

当前实现位于 MemoryCache
基于 moka::sync::Cache，使用 TinyLFU 淘汰策略
支持按条目 TTL 过期
适用于单实例部署

Redis 缓存

支持分布式部署
支持持久化
通过 feature flag 启用：cache-redis

cargo build --release --features cache-redis

配置示例：

[cache]
cache_type = "redis"
redis_url = "redis://localhost:6379"
default_ttl = 3600

缓存 TTL 配置

支持为不同类型的数据配置独立的 TTL：

crate_docs_ttl_secs: crate 文档缓存时间（默认 3600 秒 / 1 小时）
item_docs_ttl_secs: 项目文档缓存时间（默认 1800 秒 / 30 分钟）
search_results_ttl_secs: 搜索结果缓存时间（默认 300 秒 / 5 分钟）

部署

Docker

# 使用预构建镜像
docker pull kingingwang/crates-docs:latest
docker run -d -p 8080:8080 kingingwang/crates-docs:latest

# 或使用特定版本
docker pull kingingwang/crates-docs:0.3.0

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/crates-docs serve --config /etc/crates-docs/config.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable crates-docs
sudo systemctl start crates-docs

开发

# 构建
cargo build --release

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

# 运行 clippy 检查
cargo clippy --all-features --all-targets -- -D warnings

# 格式化检查
cargo fmt --check

# 运行完整 CI 流程
cargo clippy --all-features --all-targets -- -D warnings && \
cargo test --all-features && \
cargo fmt --check

Feature Flags

Feature	描述
`default`	默认启用：`server`、`stdio`、`macros`、`cache-memory`、`logging`
`server`	启用 rust-mcp-sdk 服务端能力
`client`	启用 rust-mcp-sdk 客户端能力
`stdio`	启用 Stdio 传输
`hyper-server`	启用 HTTP 服务器
`streamable-http`	启用 Streamable HTTP
`sse`	启用 SSE 传输
`macros`	启用 MCP 宏支持
`auth`	启用 OAuth 认证支持
`api-key`	启用 API Key 认证支持（默认启用）
`cache-memory`	启用内存缓存相关支持
`cache-redis`	启用 Redis 缓存
`tls`	启用 TLS/SSL 支持
`logging`	启用日志相关支持

故障排除

端口被占用

lsof -i :8080
kill -9 <PID>

网络问题

curl -I https://docs.rs/
curl -I https://crates.io/

日志

启用文件日志时，默认日志文件路径为 ./logs/crates-docs.log。

[logging]
level = "debug"

许可证

MIT License

贡献

欢迎 Issue 和 Pull Request！

Fork 仓库
创建分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送分支 (git push origin feature/amazing-feature)
创建 Pull Request

开发指南

所有代码必须通过 cargo clippy --all-features --all-targets -- -D warnings
所有测试必须通过 cargo test --all-features
新功能需要添加相应的单元测试
遵循现有的代码风格和文档规范

致谢

rust-mcp-sdk - MCP SDK
docs.rs - Rust 文档服务
crates.io - Rust 包注册表
lru - 内存缓存淘汰策略实现

API 文档

docs.rs 文档

主文档: https://docs.rs/crates-docs
最新版本: https://docs.rs/crates-docs/latest

主要类型使用示例

CratesDocsServer

use crates_docs::{AppConfig, CratesDocsServer};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 使用默认配置
    let config = AppConfig::default();
    
    // 创建服务器
    let server = CratesDocsServer::new(config)?;
    
    // 运行 HTTP 服务器
    server.run_http().await?;
    
    Ok(())
}

缓存使用

use std::sync::Arc;
use crates_docs::cache::{Cache, CacheConfig, create_cache};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建内存缓存
    let config = CacheConfig::default();
    let cache: Arc<dyn Cache> = Arc::from(create_cache(&config)?);
    
    // 设置缓存值
    cache.set(
        "key".to_string(),
        "value".to_string(),
        Some(std::time::Duration::from_secs(3600))
    ).await?;
    
    // 获取缓存值
    if let Some(value) = cache.get("key").await {
        println!("Cached value: {}", value);
    }
    
    Ok(())
}

工具注册表

use std::sync::Arc;
use crates_docs::tools::{ToolRegistry, create_default_registry};
use crates_docs::tools::docs::DocService;
use crates_docs::cache::memory::MemoryCache;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建缓存和文档服务
    let cache = Arc::new(MemoryCache::new(1000));
    let doc_service = Arc::new(DocService::new(cache)?);
    
    // 创建默认工具注册表
    let registry = create_default_registry(&doc_service);
    
    // 获取所有工具
    let tools = registry.get_tools();
    println!("Registered {} tools", tools.len());
    
    Ok(())
}

模块文档

crates_docs::cache - 缓存模块
crates_docs::config - 配置模块
crates_docs::error - 错误处理
crates_docs::server - 服务器模块
crates_docs::tools - MCP 工具
crates_docs::utils - 工具函数

支持

Issues
Email: kingingwang@foxmail.com

crates-docs 1.0.0

Crates Docs MCP 服务器

特性

架构图

系统架构

数据流

快速开始

使用 Docker（推荐）

Docker Compose

从源码构建

从 crates.io 安装

MCP 客户端集成

Claude Desktop

Cursor

Windsurf

Cherry Studio

HTTP 模式

MCP 工具

1. lookup_crate - 查找 Crate 文档

2. search_crates - 搜索 Crate

3. lookup_item - 查找特定项目

4. health_check - 健康检查

详细使用示例

Stdio 模式

HTTP 模式

SSE 模式

工具调用示例

search_crates - 搜索 Crate

lookup_crate - 查找 Crate 文档

lookup_item - 查找特定项目

health_check - 健康检查

使用示例

了解新 crate

查找特定功能

搜索相关 crate

命令行

配置

完整配置文件示例

环境变量配置

Docker 部署示例

Docker Compose 示例

配置项详细说明

[server] 服务器配置

[cache] 缓存配置

[logging] 日志配置

[performance] 性能配置

环境变量配置

生成配置文件

传输协议

MCP 端点

API Key 认证使用指南

完整流程概览

第一步：生成 API Key

第二步：配置服务端

方式 A：配置文件（推荐）

方式 B：环境变量

方式 C：CLI 标志

第三步：启动服务

第四步：客户端使用 API Key

curl 测试

Claude Desktop 配置

Cursor 配置

其他 MCP 客户端

管理操作

查看已注册的 API Key

吊销 API Key

添加新 Key

常见问题

认证与加密传输（TLS）

进程内置认证（Bearer）

加密传输与 X-API-Key（反向代理）

缓存策略

内存缓存（默认）

Redis 缓存

缓存 TTL 配置

部署

Docker

Systemd

开发

Feature Flags

`[server]` 服务器配置

`[cache]` 缓存配置

`[logging]` 日志配置

`[performance]` 性能配置

加密传输与 `X-API-Key`（反向代理）