MCP Docsrs

🚀 🦀 MCP Rust Docs Server

MCP Rust Docs Server 是一个基于 Model Context Protocol（MCP）的服务器，用于借助 rustdoc JSON API 从 docs.rs 获取 Rust 包文档，能够为开发者提供高效、便捷的文档查询服务。

🚀 快速开始

启动服务器

使用 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

✨ 主要特性

• 🚀 快速文档获取：直接访问 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 构建。

💻 使用示例

🛠️ 可用工具

lookup_crate_docs

获取整个 Rust 包的完整文档。 参数：

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

lookup_item_docs

获取包内特定项的文档。 参数：

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

search_crates

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

{
  "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"
}

⚙️ 配置

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

# 使用环境变量
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/ 目录中创建，并使用字节码编译以实现快速启动：

👨‍💻 开发

开发工作流

# 安装依赖
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++ 安装 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 社区用心打造 ❤️

报告错误 • 请求特性