MCP Docsrs

🚀 🦀 MCP Rust Docs Server

このサーバーは、rustdoc JSON APIを使用してdocs.rsからRustクレートのドキュメントを取得するためのModel Context Protocol (MCP) サーバーです。

主な機能 • インストール • 使用方法 • ビルド • 開発 • 注意事項 • コントリビュート • ライセンス

✨ 主な機能

• 🚀 高速なドキュメント取得 - rustdoc JSON APIに直接アクセスし、包括的なクレートドキュメントを取得します。
• 🔍 アイテムレベルの検索 - クレート内の特定の構造体、関数、トレイトなどをクエリできます。
• 💾 スマートキャッシュ - SQLiteバックエンドを持つ組み込みLRUキャッシュで、最適なパフォーマンスを実現します。
• 🎯 バージョンサポート - 特定のバージョンのドキュメントを取得するか、セマンティックバージョニングの範囲を使用できます。
• 🖥️ クロスプラットフォーム - Linux、macOS、Windows用のスタンドアロン実行ファイルが用意されています。
• 📦 依存関係ゼロ - すべてがバンドルされた単一の実行ファイルです。
• 🔧 TypeScript - 最新のESモジュールを使用した完全な型安全性があります。
• 🗜️ 圧縮サポート - 効率的なデータ転送のために、自動的にZstd解凍が行われます。

📦 インストール

Bunを使用する場合

bun install
bun run build:bytecode # またはすべてのプラットフォーム用に bun run build:all

事前ビルド済みの実行ファイルを使用する場合

Releasesページから、あなたのプラットフォーム用の最新のリリースをダウンロードします。

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クレート全体の包括的なドキュメントを取得します。

パラメーター:

例:

{
  "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
• ❌ 予期しないエラーは完全なスタックトレースを含めて赤色で表示されます。
• ℹ️ 情報ログはテストの実行を追跡するために表示されます。

これにより、次の2つを簡単に区別できます。

• エラーハンドリングを検証するテスト（予期されるエラー）
• 実際のテスト失敗（予期しないエラー）

デバッグのために完全なエラー詳細を表示するには、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年5月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 License 2.0の下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

Rustコミュニティのために❤️ で作られました。

バグ報告 • 機能リクエスト