MCP Docsrs

🚀 🦀 MCP Rust Docs Server

MCP Rust Docs Server 是一个用于从 docs.rs 获取 Rust 包文档的 Model Context Protocol (MCP) 服务器，借助 rustdoc JSON API 实现快速、全面的文档检索。

特性 • 安装 • 使用方法 • 构建 • 开发 • 注意事项 • 贡献代码 • 许可证

🚀 快速开始

MCP Rust Docs Server 提供了便捷的安装和使用方式，能让你迅速开始获取 Rust 包文档。你可以根据自己的需求选择合适的安装方法，如使用 Bun 或预构建的可执行文件。

✨ 主要特性

• 🚀 快速文档获取 - 直接访问 rustdoc JSON API，全面获取包文档。
• 🔍 项级查找 - 查询包内特定的结构体、函数、特性等。
• 💾 智能缓存 - 内置基于 SQLite 后端的 LRU 缓存，实现最佳性能。
• 🎯 版本支持 - 获取特定版本或使用语义化版本范围的文档。
• 🖥️ 跨平台 - 提供适用于 Linux、macOS 和 Windows 的独立可执行文件。
• 📦 零依赖 - 单个可执行文件包含所有内容。
• 🔧 TypeScript - 使用现代 ES 模块实现完全的类型安全。
• 🗜️ 压缩支持 - 自动进行 Zstd 解压缩，实现高效数据传输。

📦 安装指南

使用 Bun

bun install
bun run build:bytecode # 或使用 bun run build:all 构建所有平台的版本

使用预构建的可执行文件

从 发布页面 下载适合你平台的最新版本：

Linux

• x64/AMD64 (GLIBC)：mcp-docsrs-linux-x64 - 适用于 Ubuntu、Debian、Fedora 等系统。
• ARM64 (GLIBC)：mcp-docsrs-linux-arm64 - 适用于 ARM64 系统，如 AWS Graviton。
• x64/AMD64 (MUSL)：mcp-docsrs-linux-x64-musl - 适用于 Alpine Linux、Docker 容器（需要 libstdc++）。
• ARM64 (MUSL)：mcp-docsrs-linux-arm64-musl - 适用于 ARM64 上的 Alpine、最小化容器（需要 libstdc++）。

macOS

• Intel：mcp-docsrs-darwin-x64 - 适用于基于 Intel 的 Mac。
• Apple Silicon：mcp-docsrs-darwin-arm64 - 适用于 M1/M2/M3 Mac。

Windows

• x64：mcp-docsrs-windows-x64.exe - 适用于 64 位 Windows。

使用 Docker

拉取并运行最新的多架构镜像（支持 x64 和 ARM64）：

# 拉取最新镜像
docker pull ghcr.io/vexxvakan/mcp-docsrs:latest

# 运行服务器
docker run --rm -i ghcr.io/vexxvakan/mcp-docsrs:latest

# 使用自定义配置运行
docker run --rm -i ghcr.io/vexxvakan/mcp-docsrs:latest \
  --cache-ttl 7200000 --max-cache-size 200

可用标签：

• latest - 最新稳定版本（多架构）
• v1.0.0 - 特定版本（多架构）
• x64 - 最新的 x64/AMD64 版本
• arm64 - 最新的 ARM64 版本

💻 使用示例

启动服务器

使用 npm 或 Bun

# 生产模式
npm start
# 或者
bun start

# 开发模式，支持热重载
npm run dev
# 或者
bun run dev

使用可执行文件

# 显示帮助信息
mcp-docsrs --help

# 使用默认设置运行
mcp-docsrs

# 使用自定义配置运行
mcp-docsrs --cache-ttl 7200000 --max-cache-size 200

🛠️ 可用工具

lookup_crate_docs

获取整个 Rust 包的完整文档。

参数：

参数	类型	是否必需	描述
crateName	字符串	✅	Rust 包的名称
version	字符串	❌	特定版本或语义化版本范围（例如："1.0.0"，"~4"）
target	字符串	❌	目标平台（例如："i686-pc-windows-msvc"）
formatVersion	字符串	❌	rustdoc JSON 格式版本

示例：

{
  "tool": "lookup_crate_docs",
  "arguments": {
    "crateName": "serde",
    "version": "latest"
  }
}

lookup_item_docs

获取包内特定项的文档。

参数：

参数	类型	是否必需	描述
crateName	字符串	✅	Rust 包的名称
itemPath	字符串	✅	项的路径（例如："struct.MyStruct"，"fn.my_function"）
version	字符串	❌	特定版本或语义化版本范围
target	字符串	❌	目标平台

示例：

{
  "tool": "lookup_item_docs",
  "arguments": {
    "crateName": "tokio",
    "itemPath": "runtime.Runtime"
  }
}

search_crates

在 crates.io 上使用模糊/部分名称匹配搜索 Rust 包。

参数：

参数	类型	是否必需	描述
query	字符串	✅	包名称的搜索查询（支持部分匹配）
limit	数字	❌	返回的最大结果数（默认：10）

示例：

{
  "tool": "search_crates",
  "arguments": {
    "query": "serde",
    "limit": 5
  }
}

📊 资源

服务器提供用于查询和检查缓存数据库的资源：

cache://stats

返回缓存统计信息，包括总条目数、大小和最旧条目。

示例：

{
  "totalEntries": 42,
  "totalSize": 1048576,
  "oldestEntry": "2024-01-15T10:30:00.000Z"
}

cache://entries?limit={limit}&offset={offset}

列出带有元数据的缓存条目，支持分页。

参数：

• limit - 返回的条目数（默认：100）
• offset - 跳过的条目数（默认：0）

示例：

[
  {
    "key": "serde/latest/x86_64-unknown-linux-gnu",
    "timestamp": "2024-01-15T14:20:00.000Z",
    "ttl": 3600000,
    "expiresAt": "2024-01-15T15:20:00.000Z",
    "size": 524288
  }
]

cache://query?sql={sql}

在缓存数据库上执行 SQL 查询（为安全起见，仅支持 SELECT 查询）。

示例：

cache://query?sql=SELECT key, timestamp FROM cache WHERE key LIKE '%tokio%' ORDER BY timestamp DESC

注意： URI 中的 SQL 查询应进行 URL 编码，服务器将自动解码。

cache://config

返回当前服务器配置，包括所有运行时参数。

示例响应：

{
  "cacheTtl": 7200000,
  "maxCacheSize": 200,
  "requestTimeout": 30000,
  "dbPath": "/Users/vexx/Repos/mcp-docsrs/.cache"
}

⚙️ 配置

可以使用环境变量或命令行参数配置服务器：

变量	CLI 标志	默认值	描述
CACHE_TTL	--cache-ttl	3600000	缓存的存活时间（毫秒）
MAX_CACHE_SIZE	--max-cache-size	100	缓存的最大条目数
REQUEST_TIMEOUT	--request-timeout	30000	HTTP 请求超时时间（毫秒）
DB_PATH	--db-path	:memory:	SQLite 数据库文件的路径（使用 :memory: 表示内存中）

示例：

# 使用环境变量
CACHE_TTL=7200000 MAX_CACHE_SIZE=200 npm start

# 使用命令行参数（可执行文件）
./mcp-docsrs --cache-ttl 7200000 --max-cache-size 200

# 使用持久化数据库在会话之间缓存文档
./mcp-docsrs --db-path ~/.mcp-docsrs

# 或者使用环境变量
DB_PATH=~/.mcp-docsrs npm start

🔌 MCP 配置

添加到你的 MCP 配置文件：

{
  "mcpServers": {
    "rust-docs": {
      "command": "node",
      "args": ["/path/to/mcp-docsrs/dist/index.js"]
    }
  }
}

或者使用可执行文件：

{
  "mcpServers": {
    "rust-docs": {
      "command": "/path/to/mcp-docsrs"
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "rust-docs": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/vexxvakan/mcp-docsrs:latest"]
    }
  }
}

🔧 技术细节

构建

前提条件

• Bun v1.2.14 或更高版本
• macOS、Linux 或 Windows

构建命令

# 为当前平台构建
bun run build

# 使用字节码编译构建（独立运行，需要 Bun 运行时）
bun run build:bytecode

# 为所有平台构建（7 个目标，全部使用字节码以实现快速启动）
bun run build:all

# Linux 构建（GLIBC - 标准）
bun run build:linux-x64      # Linux x64/AMD64
bun run build:linux-arm64    # Linux ARM64

# Linux 构建（MUSL - 适用于 Alpine/容器）
bun run build:linux-x64-musl    # Linux x64/AMD64 (Alpine)
bun run build:linux-arm64-musl  # Linux ARM64 (Alpine)

# macOS 构建
bun run build:darwin-x64     # macOS Intel
bun run build:darwin-arm64   # macOS Apple Silicon

# Windows 构建
bun run build:windows-x64    # Windows x64

构建输出

所有可执行文件都在 dist/ 目录中创建，并使用字节码编译以实现快速启动：

文件	平台	类型	大小
mcp-docsrs-linux-x64	Linux x64/AMD64	GLIBC + 字节码	99MB
mcp-docsrs-linux-arm64	Linux ARM64	GLIBC + 字节码	93MB
mcp-docsrs-linux-x64-musl	Linux x64/AMD64	MUSL（静态）+ 字节码	92MB
mcp-docsrs-linux-arm64-musl	Linux ARM64	MUSL（静态）+ 字节码	88MB
mcp-docsrs-darwin-x64	macOS Intel	字节码	64MB
mcp-docsrs-darwin-arm64	macOS Apple Silicon	字节码	58MB
mcp-docsrs-windows-x64.exe	Windows x64	字节码	113MB

开发

开发工作流

# 安装依赖
bun install

# 在开发模式下运行
bun run dev

# 运行测试
bun test

# 代码检查
bun run lint

# 类型检查
bun run typecheck

# 检查构建大小（更新 README 表格）
bun run check:sizes  # 构建后运行

测试

项目包含对所有主要组件的全面测试：

# 运行所有测试
bun test

# 在监视模式下运行测试
bun test --watch

# 运行特定测试文件
bun test cache.test.ts

# 运行带有完整错误日志的测试（包括预期错误）
LOG_EXPECTED_ERRORS=true bun test

测试输出

测试默认配置为提供清晰的输出：

• ✅ 预期错误（如 404 测试中的 CrateNotFoundError）显示为绿色对勾：✓ Expected CrateNotFoundError thrown
• ❌ 意外错误以红色显示完整堆栈跟踪
• ℹ️ 信息日志显示以跟踪测试执行

这使得区分以下情况变得容易：

• 验证错误处理的测试（预期错误）
• 实际测试失败（意外错误）

要查看完整的错误详细信息以进行调试，请设置 LOG_EXPECTED_ERRORS=true。

项目结构

mcp-docsrs/
├── src/                        # 源代码
│   ├── cli.ts                  # CLI 入口点，带有参数解析
│   ├── index.ts                # MCP 服务器入口点
│   ├── server.ts               # MCP 服务器实现，带有工具/资源处理程序
│   ├── cache.ts                # 带有 SQLite 持久化的 LRU 缓存
│   ├── docs-fetcher.ts         # docs.rs JSON API 的 HTTP 客户端
│   ├── rustdoc-parser.ts       # rustdoc JSON 格式的解析器
│   ├── errors.ts               # 自定义错误类型和错误处理
│   ├── types.ts                # TypeScript 类型和 Zod 模式
│   └── tools/                  # MCP 工具实现
│       ├── index.ts            # 工具导出和注册
│       ├── lookup-crate.ts     # 获取完整的包文档
│       ├── lookup-item.ts      # 获取特定项的文档
│       └── search-crates.ts    # 在 crates.io 上搜索包
├── test/                       # 测试文件
│   ├── cache.test.ts           # 缓存功能测试
│   ├── cache-status.test.ts    # 缓存状态和指标测试
│   ├── docs-fetcher.test.ts    # API 客户端测试
│   ├── integration.test.ts     # 端到端集成测试
│   ├── persistent-cache.test.ts # SQLite 缓存持久化测试
│   ├── rustdoc-parser.test.ts  # JSON 解析器测试
│   └── search-crates.test.ts   # 包搜索测试
├── scripts/                    # 开发和测试脚本
│   ├── test-crates-search.ts   # 手动包搜索测试
│   ├── test-mcp.ts             # MCP 服务器测试
│   ├── test-persistent-cache.ts # 缓存持久化测试
│   ├── test-resources.ts       # 资源端点测试
│   └── test-zstd.ts            # Zstandard 压缩测试
├── plans/                      # 项目规划文档
│   └── feature-recommendations.md # 未来功能想法
├── dist/                       # 构建输出（平台可执行文件）
├── .github/                    # GitHub Actions 工作流
│   ├── workflows/              # CI/CD 管道定义
│   └── ...                     # 各种自动化配置
├── CLAUDE.md                   # AI 助手说明
├── README.md                   # 项目文档
├── LICENSE                     # Apache 2.0 许可证
├── package.json                # 项目依赖和脚本
├── tsconfig.json               # TypeScript 配置
├── biome.json                  # 代码格式化/检查配置
└── bun.lock                    # Bun 包锁定文件

📝 注意事项

⚠️ 重要提示

• 📅 docs.rs 上的 rustdoc JSON 功能于 2025-05-23 开始，因此该日期之前的版本没有 JSON 文档。
• ⚠️ MUSL 构建限制：由于 已知的 Bun 问题，MUSL 构建不是完全静态的，运行时需要 libstdc++。对于 Docker/Alpine 部署，请使用 apk add libstdc++ 安装。

💡 使用建议

• 🔄 服务器会自动处理重定向和格式版本兼容性。
• ⚡ 缓存响应可显著提高重复查询的性能。
• 📦 预构建的可执行文件包含所有依赖项，无需运行时安装。

🤝 贡献代码

欢迎贡献代码！请随时提交拉取请求。

1. 分叉仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

🙏 致谢

• docs.rs 提供 Rust 文档 API
• Model Context Protocol 提供 MCP 规范
• Rust 社区提供优秀的文档标准

📄 许可证

本项目采用 Apache 许可证 2.0 版 - 有关详细信息，请参阅 LICENSE 文件。

---

为 Rust 社区精心打造 ❤️

报告问题 • 请求功能