🦀 MCP Rust 文档服务器

使用 rustdoc JSON API 从 docs.rs 获取 Rust 包文档 的 模型上下文协议 (MCP) 服务器

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

✨ 特性

<a id="features"></a>

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

📦 安装

<a id="installation"></a>

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

🚀 使用

<a id="usage"></a>

启动服务器

使用 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	string	✅	Rust 包的名称
version	string	❌	特定版本或语义化版本范围（例如："1.0.0"，"~4"）
target	string	❌	目标平台（例如："i686-pc-windows-msvc"）
formatVersion	string	❌	Rustdoc JSON 格式版本

示例：

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

lookup_item_docs

获取包内特定项目的文档。

参数：

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

示例：

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

search_crates

在 crates.io 上搜索 Rust 包，支持模糊/部分名称匹配。

参数：

参数	类型	必填	描述
query	string	✅	包名称的搜索查询（支持部分匹配）
limit	number	❌	返回结果的最大数量（默认：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"]
    }
  }
}

<a id="building"></a>

🏗️ 构建

<a id="building"></a>

先决条件

• 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

<a id="development"></a>

👨‍💻 开发

<a id="development"></a>

开发工作流

# 安装依赖
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 管道定义
│   └── ...                     # 各种自动化配置