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 社區用心打造 ❤️

報告錯誤 • 請求特性