星战科技xingzhan.cloud
返回市场
MCP文档服务器

MCP文档服务器

作者：vexxvakan9 星标更新：2025-11-16
安装使用来源：spider==github.com

项目介绍

🦀 MCP Rust 文档服务器

MCP 协议 Rust 文档 TypeScript Bun License: Apache 2.0

使用 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 包的全面文档。

参数：

参数类型必填描述
crateNamestring✅Rust 包的名称
versionstring❌特定版本或语义化版本范围（例如："1.0.0"，"~4"）
targetstring❌目标平台（例如："i686-pc-windows-msvc"）
formatVersionstring❌Rustdoc JSON 格式版本

示例：

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

lookup_item_docs

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

参数：

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

示例：

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

search_crates

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

参数：

参数类型必填描述
querystring✅包名称的搜索查询（支持部分匹配）
limitnumber❌返回结果的最大数量（默认：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-ttl3600000缓存生存时间（毫秒）
MAX_CACHE_SIZE--max-cache-size100最大缓存条目数
REQUEST_TIMEOUT--request-timeout30000HTTP 请求超时（毫秒）
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-x64Linux x64/AMD64GLIBC + 字节码99MB
mcp-docsrs-linux-arm64Linux ARM64GLIBC + 字节码93MB
mcp-docsrs-linux-x64-muslLinux x64/AMD64MUSL (静态) + 字节码92MB
mcp-docsrs-linux-arm64-muslLinux ARM64MUSL (静态) + 字节码88MB
mcp-docsrs-darwin-x64macOS Intel字节码64MB
mcp-docsrs-darwin-arm64macOS Apple Silicon字节码58MB
mcp-docsrs-windows-x64.exeWindows 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 管道定义
│   └── ...                     # 各种自动化配置