{"id":46841145,"url":"https://github.com/kingingwang/crates-docs","last_synced_at":"2026-05-30T08:01:12.618Z","repository":{"id":337576468,"uuid":"1154211449","full_name":"KingingWang/crates-docs","owner":"KingingWang","description":"A high-performance Rust crate documentation query MCP server supporting multiple transport protocols.","archived":false,"fork":false,"pushed_at":"2026-05-24T03:36:37.000Z","size":6950,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T05:12:43.956Z","etag":null,"topics":["ai-tools","crate","crates","crates-io","docs","documentation","mcp","mcp-server","rust","search"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KingingWang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-10T06:06:01.000Z","updated_at":"2026-05-24T03:36:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KingingWang/crates-docs","commit_stats":null,"previous_names":["kingingwang/crates-docs"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/KingingWang/crates-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingingWang%2Fcrates-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingingWang%2Fcrates-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingingWang%2Fcrates-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingingWang%2Fcrates-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KingingWang","download_url":"https://codeload.github.com/KingingWang/crates-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KingingWang%2Fcrates-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33684413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","crate","crates","crates-io","docs","documentation","mcp","mcp-server","rust","search"],"created_at":"2026-03-10T13:11:09.958Z","updated_at":"2026-05-30T08:01:12.605Z","avatar_url":"https://github.com/KingingWang.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Crates Docs MCP 服务器\n\n[![Crates.io](https://img.shields.io/crates/v/crates-docs.svg)](https://crates.io/crates/crates-docs)\n[![Documentation](https://docs.rs/crates-docs/badge.svg)](https://docs.rs/crates-docs)\n[![Docker](https://img.shields.io/docker/v/kingingwang/crates-docs/latest?label=docker)](https://hub.docker.com/r/kingingwang/crates-docs)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Build Status](https://github.com/KingingWang/crates-docs/workflows/CI/badge.svg)](https://github.com/KingingWang/crates-docs/actions)\n[![codecov](https://codecov.io/gh/kingingwang/crates-docs/branch/main/graph/badge.svg)](https://codecov.io/gh/kingingwang/crates-docs)\n[![GitHub stars](https://img.shields.io/github/stars/KingingWang/crates-docs?style=social)](https://github.com/KingingWang/crates-docs/stargazers)\n\n一个高性能的 Rust crate 文档查询 MCP 服务器，支持多种传输协议。\n\n## 特性\n\n- 🚀 **高性能**: 异步 Rust + TinyLFU/TTL 内存缓存，支持按条目 TTL，可选 Redis 扩展\n- 📦 **多架构 Docker 镜像**: 支持 `linux/amd64` 和 `linux/arm64`\n- 🔧 **多种传输协议**: Stdio、HTTP (Streamable HTTP)、SSE、Hybrid\n- 📚 **完整文档查询**: crate 搜索、文档查找、特定项目查询\n- 🛡️ **安全可靠**: 速率限制、连接池、请求验证\n- 📊 **健康监控**: 内置健康检查和性能监控\n- 🏗️ **模块化架构**: 清晰的模块划分，易于扩展和维护\n- 🔄 **HTTP 重试机制**: 可配置的 HTTP 客户端重试逻辑，提高外部服务调用可靠性\n- 📊 **Prometheus 指标**: 内置指标监控支持，便于运维观测\n- ⏱️ **细粒度缓存 TTL**: 为 crate 文档、项目文档、搜索结果提供独立的 TTL 配置\n\n## 架构图\n\n### 系统架构\n\n```mermaid\ngraph TB\n    subgraph \"MCP 客户端\"\n        Client[Claude/Cursor/Windsurf]\n    end\n\n    subgraph \"传输层\"\n        Stdio[Stdio 传输]\n        HTTP[HTTP 传输]\n        SSE[SSE 传输]\n    end\n\n    subgraph \"Crates Docs MCP 服务器\"\n        Server[CratesDocsServer]\n        Handler[CratesDocsHandler]\n        Registry[ToolRegistry]\n\n        subgraph \"工具层\"\n            LookupCrate[lookup_crate]\n            SearchCrates[search_crates]\n            LookupItem[lookup_item]\n            HealthCheck[health_check]\n        end\n\n        subgraph \"服务层\"\n            DocService[DocService]\n            HttpClient[HTTP Client]\n        end\n\n        subgraph \"缓存层\"\n            MemoryCache[MemoryCache]\n            RedisCache[RedisCache]\n            DocCache[DocCache]\n        end\n    end\n\n    subgraph \"外部服务\"\n        DocsRs[docs.rs]\n        CratesIo[crates.io]\n    end\n\n    Client --\u003e Stdio\n    Client --\u003e HTTP\n    Client --\u003e SSE\n\n    Stdio --\u003e Server\n    HTTP --\u003e Server\n    SSE --\u003e Server\n\n    Server --\u003e Handler\n    Handler --\u003e Registry\n\n    Registry --\u003e LookupCrate\n    Registry --\u003e SearchCrates\n    Registry --\u003e LookupItem\n    Registry --\u003e HealthCheck\n\n    LookupCrate --\u003e DocService\n    SearchCrates --\u003e DocService\n    LookupItem --\u003e DocService\n    HealthCheck --\u003e HttpClient\n\n    DocService --\u003e HttpClient\n    DocService --\u003e DocCache\n\n    DocCache --\u003e MemoryCache\n    DocCache --\u003e RedisCache\n\n    HttpClient --\u003e DocsRs\n    HttpClient --\u003e CratesIo\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n    participant Client as MCP 客户端\n    participant Server as CratesDocsServer\n    participant Handler as CratesDocsHandler\n    participant Tool as 工具实现\n    participant Cache as DocCache\n    participant External as 外部服务\n\n    Client-\u003e\u003eServer: MCP 请求\n    Server-\u003e\u003eHandler: 路由请求\n    Handler-\u003e\u003eTool: 执行工具\n\n    alt 缓存命中\n        Tool-\u003e\u003eCache: 查询缓存\n        Cache--\u003e\u003eTool: 返回缓存数据\n    else 缓存未命中\n        Tool-\u003e\u003eCache: 查询缓存\n        Cache--\u003e\u003eTool: 未命中\n        Tool-\u003e\u003eExternal: HTTP 请求\n        External--\u003e\u003eTool: 返回数据\n        Tool-\u003e\u003eCache: 写入缓存\n    end\n\n    Tool--\u003e\u003eHandler: 返回结果\n    Handler--\u003e\u003eServer: 格式化响应\n    Server--\u003e\u003eClient: MCP 响应\n```\n\n## 项目结构\n\n```\nsrc/\n├── lib.rs              # 库入口，导出公共 API\n├── main.rs             # 程序入口\n├── cache/              # 缓存层\n│   ├── mod.rs          # Cache trait 定义\n│   ├── memory.rs       # 内存缓存实现（TinyLFU + 按条目 TTL）\n│   └── redis.rs        # Redis 缓存实现\n├── cli/                # 命令行接口\n│   ├── mod.rs          # CLI 定义和路由\n│   ├── commands.rs     # 子命令定义\n│   ├── serve_cmd.rs    # serve 命令实现\n│   ├── test_cmd.rs     # test 命令实现\n│   ├── config_cmd.rs   # config 命令实现\n│   ├── health_cmd.rs   # health 命令实现\n│   └── version_cmd.rs  # version 命令实现\n├── config/             # 配置管理\n│   └── mod.rs          # 配置结构和加载逻辑\n├── error/              # 错误处理\n│   └── mod.rs          # 错误类型定义\n├── server/             # 服务器核心\n│   ├── mod.rs          # 服务器定义\n│   ├── auth.rs         # OAuth 认证\n│   ├── handler.rs      # MCP 请求处理\n│   └── transport.rs    # 传输层实现\n├── tools/              # MCP 工具\n│   ├── mod.rs          # 工具注册表\n│   ├── health.rs       # 健康检查工具\n│   └── docs/           # 文档查询工具\n│       ├── mod.rs      # 文档服务\n│       ├── cache.rs    # 文档缓存\n│       ├── html.rs     # HTML 处理\n│       ├── lookup_crate.rs  # crate 文档查找\n│       ├── lookup_item.rs   # 项目文档查找\n│       └── search.rs        # crate 搜索\n└── utils/              # 工具函数\n    └── mod.rs          # 通用工具\n```\n\n## 快速开始\n\n### 使用 Docker（推荐）\n\n```bash\n# 从 Docker Hub 拉取镜像\ndocker pull kingingwang/crates-docs:latest\n\n# 运行容器（官方镜像内置配置默认监听 0.0.0.0:8080）\ndocker run -d --name crates-docs -p 8080:8080 kingingwang/crates-docs:latest\n\n# 使用自定义配置\ndocker run -d --name crates-docs -p 8080:8080 \\\n  -v $(pwd)/config.toml:/app/config.toml:ro \\\n  kingingwang/crates-docs:latest\n```\n\n### Docker Compose\n\n```yaml\nversion: '3.8'\nservices:\n  crates-docs:\n    image: kingingwang/crates-docs:latest\n    ports:\n      - \"8080:8080\"\n    environment:\n      CRATES_DOCS_HOST: 0.0.0.0\n      CRATES_DOCS_PORT: 8080\n      CRATES_DOCS_TRANSPORT_MODE: hybrid\n    volumes:\n      - ./config.toml:/app/config.toml:ro\n      - ./logs:/app/logs\n    restart: unless-stopped\n```\n\n```bash\ndocker compose up -d\n```\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/KingingWang/crates-docs.git\ncd crates-docs\ncargo build --release\n./target/release/crates-docs serve\n```\n\n### 从 crates.io 安装\n\n```bash\ncargo install crates-docs\ncrates-docs serve\n```\n\n## MCP 客户端集成\n\n### Claude Desktop\n\n编辑配置文件：\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"crates-docs\": {\n      \"command\": \"/path/to/crates-docs\",\n      \"args\": [\"serve\", \"--mode\", \"stdio\"]\n    }\n  }\n}\n```\n\n### Cursor\n\n编辑 `~/.cursor/mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"crates-docs\": {\n      \"command\": \"/path/to/crates-docs\",\n      \"args\": [\"serve\", \"--mode\", \"stdio\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\n编辑 `~/.codeium/windsurf/mcp_config.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"crates-docs\": {\n      \"command\": \"/path/to/crates-docs\",\n      \"args\": [\"serve\", \"--mode\", \"stdio\"]\n    }\n  }\n}\n```\n\n### Cherry Studio\n\n1. 打开 Cherry Studio 设置\n2. 找到 `MCP 服务器` 选项\n3. 点击 `添加服务器`\n4. 填写参数：\n\n| 字段 | 值 |\n|------|------|\n| 名称 | `crates-docs` |\n| 类型 | `STDIO` |\n| 命令 | `/path/to/crates-docs` |\n| 参数1 | `serve` |\n| 参数2 | `--mode` |\n| 参数3 | `stdio` |\n\n5. 点击保存\n\n\u003e **注意**：将 `/path/to/crates-docs` 替换为实际的可执行文件路径。\n\n### HTTP 模式\n\n适合远程访问或网络服务：\n\n```bash\ncrates-docs serve --mode hybrid --host 0.0.0.0 --port 8080\n```\n\n客户端配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"crates-docs\": {\n      \"url\": \"http://your-server:8080/mcp\"\n    }\n  }\n}\n```\n\n## MCP 工具\n\n### 1. lookup_crate - 查找 Crate 文档\n\n从 docs.rs 获取完整文档。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `crate_name` | string | ✅ | Crate 名称，如 `serde`、`tokio` |\n| `version` | string | ❌ | 版本号，默认最新 |\n| `format` | string | ❌ | 输出格式：`markdown`（默认）、`text`、`html` |\n\n```json\n{ \"crate_name\": \"serde\" }\n{ \"crate_name\": \"tokio\", \"version\": \"1.35.0\" }\n```\n\n### 2. search_crates - 搜索 Crate\n\n从 crates.io 搜索 Rust crate，支持按相关性、总下载量、近期下载热度、最近更新时间和最新发布进行排序，适合做 crate 发现、选型和横向比较。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `query` | string | ✅ | 搜索关键词 |\n| `limit` | number | ❌ | 结果数量（1-100），默认 10 |\n| `sort` | string | ❌ | 排序方式，支持 `relevance`（默认）、`downloads`、`recent-downloads`、`recent-updates`、`new` |\n| `format` | string | ❌ | 输出格式：`markdown`、`text`、`json` |\n\n**排序建议**\n\n- `relevance`：优先返回与关键词最相关的结果，适合通用搜索。\n- `downloads`：按累计下载量排序，适合优先看生态里最常用、最成熟的 crate。\n- `recent-downloads`：按近期下载热度排序，适合观察最近更活跃或更受关注的项目。\n- `recent-updates`：按最近更新时间排序，适合关注仍在持续维护的 crate。\n- `new`：按发布时间排序，适合探索新发布项目。\n\n```json\n{ \"query\": \"web framework\", \"limit\": 5, \"sort\": \"downloads\" }\n{ \"query\": \"mcp\", \"sort\": \"recent-downloads\", \"format\": \"json\" }\n```\n\n### 3. lookup_item - 查找特定项目\n\n查找 crate 中的特定类型、函数或模块。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `crate_name` | string | ✅ | Crate 名称 |\n| `item_path` | string | ✅ | 项目路径，如 `serde::Serialize` |\n| `version` | string | ❌ | 版本号 |\n| `format` | string | ❌ | 输出格式 |\n\n```json\n{ \"crate_name\": \"serde\", \"item_path\": \"serde::Serialize\" }\n{ \"crate_name\": \"tokio\", \"item_path\": \"tokio::runtime::Runtime\" }\n```\n\n### 4. health_check - 健康检查\n\n检查服务器和外部服务状态。\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `check_type` | string | ❌ | `all`、`external`、`internal`、`docs_rs`、`crates_io` |\n| `verbose` | boolean | ❌ | 详细输出 |\n\n```json\n{ \"check_type\": \"all\", \"verbose\": true }\n```\n\n## 详细使用示例\n\n### Stdio 模式\n\nStdio 模式适合与本地 MCP 客户端集成：\n\n```bash\n# 启动 Stdio 服务器\ncrates-docs serve --mode stdio\n\n# 或使用默认配置（stdio 是某些客户端的默认模式）\ncrates-docs serve\n```\n\n**MCP 客户端配置示例：**\n\n```json\n{\n  \"mcpServers\": {\n    \"crates-docs\": {\n      \"command\": \"/usr/local/bin/crates-docs\",\n      \"args\": [\"serve\", \"--mode\", \"stdio\"]\n    }\n  }\n}\n```\n\n### HTTP 模式\n\nHTTP 模式适合远程访问或网络服务：\n\n```bash\n# 启动 HTTP 服务器\ncrates-docs serve --mode http --host 0.0.0.0 --port 8080\n\n# 使用自定义配置\ncrates-docs serve --config config.toml\n```\n\n**使用 curl 测试 HTTP 端点：**\n\n```bash\n# 获取服务器信息（健康检查）\ncurl http://localhost:8080/health\n\n# MCP 工具调用示例（需要 MCP 协议格式）\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"tools/list\"\n  }'\n```\n\n### SSE 模式\n\nSSE 模式支持服务器推送：\n\n```bash\n# 启动 SSE 服务器\ncrates-docs serve --mode sse --host 0.0.0.0 --port 8080\n```\n\n**SSE 客户端连接：**\n\n```bash\n# 连接到 SSE 端点\ncurl http://localhost:8080/sse\n```\n\n### 工具调用示例\n\n#### search_crates - 搜索 Crate\n\n```bash\n# 使用 CLI 测试工具\ncrates-docs test --tool search_crates --query \"serde\" --limit 5\n\n# 预期输出：\n# 搜索 \"serde\" 的结果：\n# 1. serde (v1.0.xxx) - 序列化框架\n#    下载量: xxx\n#    描述: ...\n```\n\n**MCP 调用参数：**\n\n```json\n{\n  \"name\": \"search_crates\",\n  \"arguments\": {\n    \"query\": \"web framework\",\n    \"limit\": 10,\n    \"sort\": \"downloads\",\n    \"format\": \"markdown\"\n  }\n}\n```\n\n#### lookup_crate - 查找 Crate 文档\n\n```bash\n# 使用 CLI 测试工具\ncrates-docs test --tool lookup_crate --crate-name serde\n\n# 指定版本\ncrates-docs test --tool lookup_crate --crate-name tokio --version \"1.35.0\"\n```\n\n**MCP 调用参数：**\n\n```json\n{\n  \"name\": \"lookup_crate\",\n  \"arguments\": {\n    \"crate_name\": \"serde\",\n    \"version\": \"1.0.200\",\n    \"format\": \"markdown\"\n  }\n}\n```\n\n#### lookup_item - 查找特定项目\n\n```bash\n# 使用 CLI 测试工具\ncrates-docs test --tool lookup_item --crate-name serde --item-path \"serde::Serialize\"\n```\n\n**MCP 调用参数：**\n\n```json\n{\n  \"name\": \"lookup_item\",\n  \"arguments\": {\n    \"crate_name\": \"tokio\",\n    \"item_path\": \"tokio::runtime::Runtime\",\n    \"version\": \"1.35.0\",\n    \"format\": \"markdown\"\n  }\n}\n```\n\n#### health_check - 健康检查\n\n```bash\n# 使用 CLI 执行健康检查\ncrates-docs health --check-type all --verbose\n\n# 仅检查外部服务\ncrates-docs health --check-type external\n```\n\n**MCP 调用参数：**\n\n```json\n{\n  \"name\": \"health_check\",\n  \"arguments\": {\n    \"check_type\": \"all\",\n    \"verbose\": true\n  }\n}\n```\n\n## 使用示例\n\n### 了解新 crate\n\n**用户**: \"帮我了解一下 serde\"\n\n**AI 调用**: `{ \"crate_name\": \"serde\" }`\n\n### 查找特定功能\n\n**用户**: \"tokio 怎么创建异步任务？\"\n\n**AI 调用**: `{ \"crate_name\": \"tokio\", \"item_path\": \"tokio::spawn\" }`\n\n### 搜索相关 crate\n\n**用户**: \"有什么稳定、大家都常用的 HTTP 客户端？\"\n\n**AI 调用**: `{ \"query\": \"http client\", \"limit\": 10, \"sort\": \"downloads\" }`\n\n## 命令行\n\n```bash\n# 启动服务器\ncrates-docs serve                          # 混合模式\ncrates-docs serve --mode stdio             # Stdio 模式\ncrates-docs serve --mode http --port 8080  # HTTP 模式\n\n# 生成配置\ncrates-docs config --output config.toml\ncrates-docs config --output config.toml --force\n\n# 测试工具\ncrates-docs test --tool lookup_crate --crate-name serde\ncrates-docs test --tool search_crates --query \"async\"\ncrates-docs test --tool search_crates --query \"mcp\" --sort downloads\ncrates-docs test --tool search_crates --query \"agent\" --sort recent-updates --format json\n\n# CLI 健康检查入口\ncrates-docs health\ncrates-docs health --check-type external --verbose\n\n# 版本信息\ncrates-docs version\n```\n\n\u003e 全局参数见 [`Cli`](src/cli/mod.rs:27)，常用项包括 `--config`、`--debug`、`--verbose`。\n\u003e\n\u003e [`run_health_command()`](src/cli/health_cmd.rs) 会执行真实的健康检查（内部状态 + docs.rs / crates.io 探测），与 MCP 工具 [`health_check`](src/tools/health.rs) 共用同一套检测逻辑。当整体状态不是 `healthy` 时，命令以非零退出码结束，可直接用作容器/编排器的健康探针（例如 Docker Compose 的 `healthcheck`）。\n\n## 配置\n\n### 完整配置文件示例\n\n下面是一个完整的配置文件示例，包含所有可用的配置项：\n\n```toml\n# 服务器配置\n[server]\nname = \"crates-docs\"                    # 服务器名称\nversion = \"0.1.0\"                       # 服务器版本\ndescription = \"Rust crate docs MCP server\"  # 服务器描述\nhost = \"0.0.0.0\"                        # 监听地址（0.0.0.0 允许外部访问）\nport = 8080                             # 监听端口\ntransport_mode = \"hybrid\"               # 传输模式：stdio/http/sse/hybrid\nenable_sse = true                       # 启用 SSE 支持\nenable_oauth = false                    # 启用 OAuth 认证\nmax_connections = 100                   # 最大并发连接数\nrequest_timeout_secs = 30               # 请求超时（秒）\nresponse_timeout_secs = 60              # 响应超时（秒）\nallowed_hosts = [\"localhost\", \"127.0.0.1\"]    # 允许的 Host\nallowed_origins = [\"http://localhost:*\"]      # 允许的 Origin\n\n# 缓存配置\n[cache]\ncache_type = \"memory\"                   # 缓存类型：memory 或 redis\nmemory_size = 1000                      # 内存缓存大小（条目数）\nredis_url = \"redis://localhost:6379\"    # Redis 连接 URL（使用 redis 时必需）\nkey_prefix = \"\"                         # 缓存键前缀\ndefault_ttl = 3600                      # 默认 TTL（秒）\ncrate_docs_ttl_secs = 3600              # crate 文档缓存 TTL（秒）\nitem_docs_ttl_secs = 1800               # 项目文档缓存 TTL（秒）\nsearch_results_ttl_secs = 300           # 搜索结果缓存 TTL（秒）\n\n# 日志配置\n[logging]\nlevel = \"info\"                          # 日志级别：trace/debug/info/warn/error\nfile_path = \"./logs/crates-docs.log\"    # 日志文件路径\nenable_console = true                   # 启用控制台日志\nenable_file = false                     # 启用文件日志\nmax_file_size_mb = 100                  # 单个日志文件最大大小（MB）\nmax_files = 10                          # 保留的日志文件数量\n\n# 性能配置\n[performance]\nhttp_client_pool_size = 10              # HTTP 客户端连接池大小\nhttp_client_pool_idle_timeout_secs = 90 # 连接池空闲超时（秒）\nhttp_client_connect_timeout_secs = 10   # 连接超时（秒）\nhttp_client_timeout_secs = 30           # 请求超时（秒）\nhttp_client_read_timeout_secs = 30      # 读取超时（秒）\nhttp_client_max_retries = 3             # HTTP 客户端最大重试次数\nhttp_client_retry_initial_delay_ms = 100    # 重试初始延迟（毫秒）\nhttp_client_retry_max_delay_ms = 10000      # 重试最大延迟（毫秒）\ncache_max_size = 1000                   # 最大缓存大小\ncache_default_ttl_secs = 3600           # 默认缓存 TTL（秒）\nrate_limit_per_second = 100             # 每秒请求速率限制\nconcurrent_request_limit = 50           # 并发请求限制\nenable_response_compression = true      # 启用响应压缩\nenable_metrics = true                   # 启用 Prometheus 指标\nmetrics_port = 0                        # 指标端口（0 表示使用服务器端口）\n\n# OAuth 配置（可选），推荐使用 [auth.oauth]\n[auth.oauth]\nenabled = false                         # 启用 OAuth\nclient_id = \"\"                          # OAuth 客户端 ID\nclient_secret = \"\"                      # OAuth 客户端密钥\nauthorization_endpoint = \"\"             # 授权端点 URL\ntoken_endpoint = \"\"                     # Token 端点 URL\nredirect_uri = \"\"                       # 回调 URI\nscopes = []                             # OAuth 作用域\n\n# API Key 认证配置（可选），必须使用 [auth.api_key]\n[auth.api_key]\nenabled = false                         # 启用 API Key 认证\nkeys = []                               # API Key 哈希列表（Argon2 PHC 格式），不要存明文 key\nheader_name = \"X-API-Key\"               # API Key 请求头名称\nquery_param_name = \"api_key\"            # API Key 查询参数名称\nallow_query_param = false               # 是否允许查询参数传递\nkey_prefix = \"sk\"                       # API Key 前缀（用于生成和校验结构化 key）\n```\n\n### 环境变量配置\n\n支持通过环境变量配置，适用于 Docker 部署。\n\n对于 API Key，推荐先生成一次性明文 key，再把生成出的 **hash** 放入配置或环境变量中：\n\n```bash\n# 生成新的 API Key（会输出明文 key、key_id 和 hash）\ncrates-docs generate-api-key --prefix sk\n\n# 服务器配置\nCRATES_DOCS_HOST=0.0.0.0\nCRATES_DOCS_PORT=8080\nCRATES_DOCS_TRANSPORT_MODE=hybrid\n\n# API Key 认证配置\nCRATES_DOCS_API_KEY_ENABLED=true\nCRATES_DOCS_API_KEYS='$argon2id$...generated_hash...'\nCRATES_DOCS_API_KEY_HEADER=X-API-Key\nCRATES_DOCS_API_KEY_ALLOW_QUERY=false\nCRATES_DOCS_API_KEY_PREFIX=sk\n```\n\n### Docker 部署示例\n\n```bash\n# 使用环境变量启用 API Key 认证（保存 hash，不保存明文 key）\ndocker run -d \\\n  -p 8080:8080 \\\n  -e CRATES_DOCS_API_KEY_ENABLED=true \\\n  -e CRATES_DOCS_API_KEYS='$argon2id$...generated_hash...' \\\n  -e CRATES_DOCS_API_KEY_PREFIX=sk \\\n  -e CRATES_DOCS_HOST=0.0.0.0 \\\n  kingingwang/crates-docs:latest\n```\n\n### Docker Compose 示例\n\n```yaml\nversion: '3.8'\nservices:\n  crates-docs:\n    image: kingingwang/crates-docs:latest\n    ports:\n      - \"8080:8080\"\n    environment:\n      - CRATES_DOCS_API_KEY_ENABLED=true\n      - CRATES_DOCS_API_KEYS=$argon2id$...generated_hash...\n      - CRATES_DOCS_API_KEY_PREFIX=sk\n      - CRATES_DOCS_HOST=0.0.0.0\n      - CRATES_DOCS_PORT=8080\n```\n\n### 配置项详细说明\n\n#### `[server]` 服务器配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `name` | string | `\"crates-docs\"` | 服务器名称 |\n| `host` | string | `\"127.0.0.1\"` | 监听地址，设为 `\"0.0.0.0\"` 允许外部访问 |\n| `port` | number | `8080` | 监听端口 |\n| `transport_mode` | string | `\"hybrid\"` | 传输模式：`stdio`/`http`/`sse`/`hybrid` |\n| `enable_sse` | boolean | `true` | 是否启用 SSE 支持 |\n| `max_connections` | number | `100` | 最大并发连接数 |\n| `allowed_hosts` | array | `[\"localhost\", \"127.0.0.1\"]` | 允许的 Host 列表（CORS） |\n| `allowed_origins` | array | `[\"http://localhost:*\"]` | 允许的 Origin 列表（CORS） |\n\n#### `[cache]` 缓存配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `cache_type` | string | `\"memory\"` | 缓存类型：`memory` 或 `redis` |\n| `memory_size` | number | `1000` | 内存缓存条目数 |\n| `redis_url` | string | `null` | Redis 连接 URL |\n| `key_prefix` | string | `\"\"` | 缓存键前缀 |\n| `crate_docs_ttl_secs` | number | `3600` | crate 文档缓存时间（秒） |\n| `item_docs_ttl_secs` | number | `1800` | 项目文档缓存时间（秒） |\n| `search_results_ttl_secs` | number | `300` | 搜索结果缓存时间（秒） |\n\n#### `[logging]` 日志配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `level` | string | `\"info\"` | 日志级别：`trace`/`debug`/`info`/`warn`/`error` |\n| `enable_console` | boolean | `true` | 启用控制台输出 |\n| `enable_file` | boolean | `false` | 启用文件日志 |\n| `file_path` | string | `\"./logs/crates-docs.log\"` | 日志文件路径 |\n| `max_file_size_mb` | number | `100` | 单个日志文件大小限制 |\n| `max_files` | number | `10` | 保留的日志文件数 |\n\n#### `[performance]` 性能配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `http_client_pool_size` | number | `10` | HTTP 连接池大小 |\n| `http_client_max_retries` | number | `3` | HTTP 请求最大重试次数 |\n| `rate_limit_per_second` | number | `100` | 每秒请求限制 |\n| `concurrent_request_limit` | number | `50` | 并发请求限制 |\n| `enable_response_compression` | boolean | `true` | 启用响应压缩 |\n| `enable_metrics` | boolean | `true` | 启用 Prometheus 指标 |\n\n### 环境变量配置\n\n所有配置项都可以通过环境变量覆盖，环境变量优先级最高：\n\n```bash\n# 服务器配置\nexport CRATES_DOCS_NAME=\"crates-docs\"\nexport CRATES_DOCS_HOST=\"0.0.0.0\"\nexport CRATES_DOCS_PORT=\"8080\"\nexport CRATES_DOCS_TRANSPORT_MODE=\"hybrid\"\n\n# 日志配置\nexport CRATES_DOCS_LOG_LEVEL=\"info\"\nexport CRATES_DOCS_ENABLE_CONSOLE=\"true\"\nexport CRATES_DOCS_ENABLE_FILE=\"true\"\n\n# 缓存配置\nexport CRATES_DOCS_CACHE_TYPE=\"memory\"\nexport CRATES_DOCS_CACHE_MEMORY_SIZE=\"1000\"\nexport CRATES_DOCS_CACHE_REDIS_URL=\"redis://localhost:6379\"\n\n# 性能配置\nexport CRATES_DOCS_HTTP_CLIENT_POOL_SIZE=\"10\"\nexport CRATES_DOCS_RATE_LIMIT_PER_SECOND=\"100\"\n```\n\n\u003e **注意**：环境变量会覆盖配置文件中的设置。布尔值使用 `\"true\"` 或 `\"false\"` 字符串表示。\n\u003e\n\u003e **API Key 安全建议**：\n\u003e - 使用 `crates-docs generate-api-key --prefix sk` 生成新的 key\n\u003e - 只保存生成结果中的 **hash**\n\u003e - 明文 key 只展示一次，之后请存入你的密钥管理系统\n\u003e - 不要把明文 key 直接写入 `config.toml`、Docker Compose 或环境变量示例中\n\n\u003e ⚠️ **重要安全限制**：当前版本的 API Key / OAuth 认证**尚未在 HTTP/SSE 传输层强制执行**。\n\u003e 也就是说，即使在配置中启用了认证，HTTP/SSE 端点仍然是**未鉴权**的。请勿将本服务直接暴露在不可信网络中；\n\u003e 应通过 `allowed_hosts`/`allowed_origins`、反向代理进行访问控制，或使用 stdio 模式运行。\n\u003e 服务启动时若检测到已配置但未强制执行的认证，会打印明显的告警日志。\n\n### 生成配置文件\n\n使用 CLI 生成默认配置文件：\n\n```bash\n# 生成配置文件\ncrates-docs config --output config.toml\n\n# 强制覆盖已存在的文件\ncrates-docs config --output config.toml --force\n```\n\n## 传输协议\n\n| 模式 | 适用场景 | 端点 |\n|------|---------|------|\n| `stdio` | MCP 客户端集成（推荐） | 标准输入输出 |\n| `http` | 网络服务 | `POST /mcp` |\n| `sse` | 向后兼容 | `GET /sse` |\n| `hybrid` | 网络服务（推荐） | `/mcp` + `/sse` |\n\n## MCP 端点\n\n- `POST /mcp` - MCP Streamable HTTP 端点\n- `GET /sse` - MCP SSE 端点\n\n\u003e 注意：这些是 MCP 协议端点，不是普通的 HTTP API。需要使用 MCP 客户端进行交互。\n\n## 缓存策略\n\n### 内存缓存（默认）\n\n- 当前实现位于 [`MemoryCache`](src/cache/memory.rs:37)\n- 基于 `moka::sync::Cache`，使用 TinyLFU 淘汰策略\n- 支持按条目 TTL 过期\n- 适用于单实例部署\n\n### Redis 缓存\n\n- 支持分布式部署\n- 支持持久化\n- 通过 feature flag 启用：`cache-redis`\n\n```bash\ncargo build --release --features cache-redis\n```\n\n配置示例：\n\n```toml\n[cache]\ncache_type = \"redis\"\nredis_url = \"redis://localhost:6379\"\ndefault_ttl = 3600\n```\n\n### 缓存 TTL 配置\n\n支持为不同类型的数据配置独立的 TTL：\n- `crate_docs_ttl_secs`: crate 文档缓存时间（默认 3600 秒 / 1 小时）\n- `item_docs_ttl_secs`: 项目文档缓存时间（默认 1800 秒 / 30 分钟）\n- `search_results_ttl_secs`: 搜索结果缓存时间（默认 300 秒 / 5 分钟）\n\n## 部署\n\n### Docker\n\n```bash\n# 使用预构建镜像\ndocker pull kingingwang/crates-docs:latest\ndocker run -d -p 8080:8080 kingingwang/crates-docs:latest\n\n# 或使用特定版本\ndocker pull kingingwang/crates-docs:0.3.0\n```\n\n### Systemd\n\n创建 `/etc/systemd/system/crates-docs.service`：\n\n```ini\n[Unit]\nDescription=Crates Docs MCP Server\nAfter=network.target\n\n[Service]\nType=simple\nUser=crates-docs\nWorkingDirectory=/opt/crates-docs\nExecStart=/opt/crates-docs/crates-docs serve --config /etc/crates-docs/config.toml\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl enable crates-docs\nsudo systemctl start crates-docs\n```\n\n## 开发\n\n```bash\n# 构建\ncargo build --release\n\n# 运行所有测试\ncargo test --all-features\n\n# 运行 clippy 检查\ncargo clippy --all-features --all-targets -- -D warnings\n\n# 格式化检查\ncargo fmt --check\n\n# 运行完整 CI 流程\ncargo clippy --all-features --all-targets -- -D warnings \u0026\u0026 \\\ncargo test --all-features \u0026\u0026 \\\ncargo fmt --check\n```\n\n### Feature Flags\n\n| Feature | 描述 |\n|---------|------|\n| `default` | 默认启用：`server`、`stdio`、`macros`、`cache-memory`、`logging` |\n| `server` | 启用 rust-mcp-sdk 服务端能力 |\n| `client` | 启用 rust-mcp-sdk 客户端能力 |\n| `stdio` | 启用 Stdio 传输 |\n| `hyper-server` | 启用 HTTP 服务器 |\n| `streamable-http` | 启用 Streamable HTTP |\n| `sse` | 启用 SSE 传输 |\n| `macros` | 启用 MCP 宏支持 |\n| `auth` | 启用 OAuth 认证支持 |\n| `api-key` | 启用 API Key 认证支持（默认启用） |\n| `cache-memory` | 启用内存缓存相关支持 |\n| `cache-redis` | 启用 Redis 缓存 |\n| `tls` | 启用 TLS/SSL 支持 |\n| `logging` | 启用日志相关支持 |\n\n## 故障排除\n\n### 端口被占用\n\n```bash\nlsof -i :8080\nkill -9 \u003cPID\u003e\n```\n\n### 网络问题\n\n```bash\ncurl -I https://docs.rs/\ncurl -I https://crates.io/\n```\n\n### 日志\n\n启用文件日志时，默认日志文件路径为 `./logs/crates-docs.log`。\n\n```toml\n[logging]\nlevel = \"debug\"\n```\n\n## 许可证\n\nMIT License\n\n## 贡献\n\n欢迎 Issue 和 Pull Request！\n\n1. Fork 仓库\n2. 创建分支 (`git checkout -b feature/amazing-feature`)\n3. 提交更改 (`git commit -m 'Add amazing feature'`)\n4. 推送分支 (`git push origin feature/amazing-feature`)\n5. 创建 Pull Request\n\n### 开发指南\n\n- 所有代码必须通过 `cargo clippy --all-features --all-targets -- -D warnings`\n- 所有测试必须通过 `cargo test --all-features`\n- 新功能需要添加相应的单元测试\n- 遵循现有的代码风格和文档规范\n\n## 致谢\n\n- [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) - MCP SDK\n- [docs.rs](https://docs.rs) - Rust 文档服务\n- [crates.io](https://crates.io) - Rust 包注册表\n- [lru](https://crates.io/crates/lru) - 内存缓存淘汰策略实现\n\n## API 文档\n\n### docs.rs 文档\n\n- **主文档**: [https://docs.rs/crates-docs](https://docs.rs/crates-docs)\n- **最新版本**: [https://docs.rs/crates-docs/latest](https://docs.rs/crates-docs/latest)\n\n### 主要类型使用示例\n\n#### CratesDocsServer\n\n```rust\nuse crates_docs::{AppConfig, CratesDocsServer};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // 使用默认配置\n    let config = AppConfig::default();\n    \n    // 创建服务器\n    let server = CratesDocsServer::new(config)?;\n    \n    // 运行 HTTP 服务器\n    server.run_http().await?;\n    \n    Ok(())\n}\n```\n\n#### 缓存使用\n\n```rust\nuse std::sync::Arc;\nuse crates_docs::cache::{Cache, CacheConfig, create_cache};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // 创建内存缓存\n    let config = CacheConfig::default();\n    let cache: Arc\u003cdyn Cache\u003e = Arc::from(create_cache(\u0026config)?);\n    \n    // 设置缓存值\n    cache.set(\n        \"key\".to_string(),\n        \"value\".to_string(),\n        Some(std::time::Duration::from_secs(3600))\n    ).await?;\n    \n    // 获取缓存值\n    if let Some(value) = cache.get(\"key\").await {\n        println!(\"Cached value: {}\", value);\n    }\n    \n    Ok(())\n}\n```\n\n#### 工具注册表\n\n```rust\nuse std::sync::Arc;\nuse crates_docs::tools::{ToolRegistry, create_default_registry};\nuse crates_docs::tools::docs::DocService;\nuse crates_docs::cache::memory::MemoryCache;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // 创建缓存和文档服务\n    let cache = Arc::new(MemoryCache::new(1000));\n    let doc_service = Arc::new(DocService::new(cache)?);\n    \n    // 创建默认工具注册表\n    let registry = create_default_registry(\u0026doc_service);\n    \n    // 获取所有工具\n    let tools = registry.get_tools();\n    println!(\"Registered {} tools\", tools.len());\n    \n    Ok(())\n}\n```\n\n### 模块文档\n\n- [`crates_docs::cache`](https://docs.rs/crates-docs/latest/crates_docs/cache/index.html) - 缓存模块\n- [`crates_docs::config`](https://docs.rs/crates-docs/latest/crates_docs/config/index.html) - 配置模块\n- [`crates_docs::error`](https://docs.rs/crates-docs/latest/crates_docs/error/index.html) - 错误处理\n- [`crates_docs::server`](https://docs.rs/crates-docs/latest/crates_docs/server/index.html) - 服务器模块\n- [`crates_docs::tools`](https://docs.rs/crates-docs/latest/crates_docs/tools/index.html) - MCP 工具\n- [`crates_docs::utils`](https://docs.rs/crates-docs/latest/crates_docs/utils/index.html) - 工具函数\n\n## 支持\n\n- [Issues](https://github.com/KingingWang/crates-docs/issues)\n- Email: kingingwang@foxmail.com\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=KingingWang%2Fcrates-docs\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/image?repos=KingingWang/crates-docs\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/image?repos=KingingWang/crates-docs\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/image?repos=KingingWang/crates-docs\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingingwang%2Fcrates-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingingwang%2Fcrates-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingingwang%2Fcrates-docs/lists"}