Mcp Server Ragdocs

MCP-server-ragdocs

ベクトル検索を通じてドキュメントを取得・処理するためのツールを提供する MCP サーバーの実装です。これにより、AI アシスタントが関連するドキュメントのコンテキストで応答を補強できるようになります。

目次

• 使用方法
• 機能
• 設定
• デプロイ
  • ローカル開発
  • クラウドデプロイ
• Playwright 統合
• ツール
• プロジェクト構成
• Ollama 埋め込みの使用
• ライセンス
• 開発ワークフロー
• コントリビューション
• Forkception 謝辞

使用方法

RAG ドキュメントツールは、以下の用途を想定して設計されています。

• 関連するドキュメントによる AI 応答の強化
• ドキュメントを認識する AI アシスタントの構築
• 開発者向けのコンテキストを考慮したツールの作成
• セマンティックなドキュメント検索の実装
• 既存のナレッジベースの拡張

機能

• ベクトルベースのドキュメント検索と取得
• 複数のドキュメントソースのサポート
• ローカル（Ollama）または OPENAI による埋め込み生成のサポート
• セマンティック検索機能
• 自動化されたドキュメント処理
• LLM 向けのリアルタイムなコンテキスト拡張

設定

{
  "mcpServers": {
    "rag-docs": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "ollama",
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-qdrant-key" # if applicable
      }
    }
  }
}

Claude Desktop での使用

これを claude_desktop_config.json に追加します。

OpenAI 設定

{
  "mcpServers": {
    "rag-docs-openai": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-key-here",
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-qdrant-key"
      }
    }
  }
}

Ollama 設定

{
  "mcpServers": {
    "rag-docs-ollama": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "ollama",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-qdrant-key"
      }
    }
  }
}

このコードベースから Ollama を実行する

"ragdocs-mcp": {
      "command": "node",
      "args": [
        "/home/sander/code/mcp-server-ragdocs/build/index.js"
      ],
      "env": {
        "QDRANT_URL": "http://127.0.0.1:6333",
        "EMBEDDINGS_PROVIDER": "ollama",
        "OLLAMA_URL": "http://localhost:11434"
      },
      "alwaysAllow": [
        "run_queue",
        "list_queue",
        "list_sources",
        "search_documentation",
        "clear_queue",
        "remove_documentation",
        "extract_urls"
      ],
      "timeout": 3600
    }

環境変数リファレンス

変数	必要な対象	デフォルト	備考
EMBEDDINGS_PROVIDER	すべて	ollama	"openai" または "ollama"
OPENAI_API_KEY	OpenAI	-	OpenAI ダッシュボードから取得
OLLAMA_BASE_URL	Ollama	http://localhost:11434	ローカル Ollama サーバーの URL
QDRANT_URL	すべて	http://localhost:6333	Qdrant エンドポイント URL
QDRANT_API_KEY	クラウド Qdrant	-	Qdrant Cloud コンソールから取得
PLAYWRIGHT_WS_ENDPOINT	Playwright リモート	-	リモート Playwright サーバー用の WebSocket エンドポイント（例: ws://localhost:3000/）

ローカルデプロイ

リポジトリにはローカル開発用の Docker Compose 設定が含まれています。

Docker Compose のダウンロード

docker compose up -d

これにより以下が起動します。

• ポート 6333 で Qdrant ベクトルデータベース
• ポート 11434 で Ollama LLM サービス

エンドポイントへのアクセス:

• Qdrant: http://localhost:6333
• Ollama: http://localhost:11434

クラウドデプロイ

本番環境へのデプロイには:

1. ホスト型の Qdrant Cloud サービスを使用します
2. 以下の環境変数を設定します:

QDRANT_URL=your-cloud-cluster-url
QDRANT_API_KEY=your-cloud-api-key

Playwright 統合

このプロジェクトは、Playwright をローカルまたは Docker コンテナ経由で実行することをサポートしています。これにより、Playwright の依存関係を直接インストールするのが難しい環境に柔軟に対応できます。

仕組み

src/api-client.ts ファイルは、PLAYWRIGHT_WS_ENDPOINT 環境変数の有無を自動的に検出します：

• PLAYWRIGHT_WS_ENDPOINT が設定されている場合：アプリケーションは chromium.connect() を使用して、指定された WebSocket エンドポイントのリモート Playwright サーバーへの接続を試みます。これはコンテナ化された Playwright インスタンスを使用するのに最適です。
• PLAYWRIGHT_WS_ENDPOINT が設定されていない場合：アプリケーションは chromium.launch() を使用してローカルの Playwright ブラウザインスタンスを起動します。

Docker で Playwright を実行する

Docker コンテナで Playwright を実行しやすくするために、docker-compose.yml ファイルに playwright サービスが追加されました。

Docker で Playwright サーバーを起動するには：

docker-compose up playwright

このコマンドは mcr.microsoft.com/playwright:v1.53.0-noble イメージをプルし、ホストマシンのポート 3000 でアクセス可能な Playwright サーバーを起動します。

アプリケーションがこのコンテナ化された Playwright インスタンスを使用するように設定するには、次の環境変数を設定します：

PLAYWRIGHT_WS_ENDPOINT=ws://localhost:3000/

ツール

search_documentation

自然言語クエリを使用して、保存されたドキュメントを検索します。コンテキスト付きの一致する抜粋を、関連性でランク付けして返します。

入力：

• query (string)：ドキュメント内で検索するテキスト。自然言語クエリ、特定の用語、コードスニペットを使用できます。
• limit (number, optional)：返す結果の最大数（1〜20、デフォルト：5）。上限を高くするとより包括的な結果が得られますが、処理に時間がかかる場合があります。

list_sources

現在システムに保存されているすべてのドキュメントソースを一覧表示します。ソース URL、タイトル、最終更新時刻を含む、インデックス化されたすべてのドキュメントの包括的なリストを返します。検索可能なドキュメントを把握したり、特定のソースがインデックス化されているかを確認したりするために使用します。

extract_urls

指定された Web ページからすべての URL を抽出して分析します。このツールは指定された Web ページをクロールし、すべてのハイパーリンクを特定して、任意でそれらを処理キューに追加します。

入力：

• url (string)：分析する Web ページの完全な URL（プロトコルを含める必要があります。例：https://）。ページは公開アクセス可能である必要があります。
• add_to_queue (boolean, optional)：true の場合、抽出された URL を後でインデックス化するために処理キューに自動的に追加します。大規模なサイトでは過剰なキューイングを避けるため、注意して使用してください。

remove_documentation

URL によって特定のドキュメントソースをシステムから削除します。削除は永続的で、今後の検索結果に影響します。

入力：

• urls (string[])：データベースから削除する URL の配列。各 URL は、ドキュメントが追加されたときに使用された URL と完全に一致する必要があります。

list_queue

現在ドキュメント処理キューで待機しているすべての URL を一覧表示します。run_queue が呼び出されたときに処理される保留中のドキュメントソースを表示します。キューの状態を監視したり、URL が正しく追加されたかを確認したり、処理のバックログを確認したりするために使用します。

run_queue

現在ドキュメントキューにあるすべての URL を処理してインデックス化します。各 URL は順番に処理され、適切なエラー処理と再試行ロジックが適用されます。処理の進行に応じて進捗状況が提供されます。長時間実行される操作は、キューが空になるか、回復不能なエラーが発生するまで処理を続けます。

clear_queue

ドキュメント処理キューから保留中のすべての URL を削除します。新たにやり直したい場合、不要な URL を削除したい場合、保留中の処理をキャンセルしたい場合にキューをリセットするために使用します。この操作は即時かつ永続的です。後で処理したい場合は、URL を再度追加する必要があります。

プロジェクト構成

このパッケージは、コアコンポーネントと MCP プロトコルハンドラを明確に分離したモジュール式アーキテクチャに従っています。詳細な構造のドキュメントと設計上の決定については、ARCHITECTURE.md を参照してください。

Docker を使わずに Ollama 埋め込みを使用する

1. Ollama をインストールします：

curl -fsSL https://ollama.com/install.sh | sh

2. nomic-embed-text モデルをダウンロードします：

ollama pull nomic-embed-text

3. インストールを確認します：

ollama list

ライセンス

この MCP サーバーは MIT ライセンスの下でライセンスされています。これは、MIT ライセンスの諸条件に従うことを条件に、ソフトウェアを自由に使用、変更、配布できることを意味します。詳細については、プロジェクトリポジトリの LICENSE ファイルをご覧ください。

コントリビューション

コントリビューションを歓迎します！詳細なガイドラインについては CONTRIBUTING.md をご覧ください。まずは基本事項を以下に示します。

1. リポジトリをフォークする
2. 依存関係をインストールする: npm install
3. フィーチャーブランチを作成する: git checkout -b feat/your-feature
4. Conventional Commits に準拠するため、npm run commit で変更をコミットする
5. 自分のフォークにプッシュして PR を作成する

Forkception に関する謝辞

このプロジェクトは hannesrudolph/mcp-ragdocs のフォークに基づいており、さらにそれは qpd-v/mcp-ragdocs によるオリジナルの成果物からフォークされたものです。オリジナルのプロジェクトがこの実装の基盤を提供しました。