docs-mcp-server MCP サーバー

サードパーティのパッケージドキュメントを取得および検索するための MCP サーバー。

✨ 主な特徴

• 🌐**多用途スクレイピング:**ウェブサイト、GitHub、npm、PyPI、ローカル ファイルなどのさまざまなソースからドキュメントを取得します。
• 🧠**インテリジェント処理:**コンテンツを意味的に自動的に分割し、選択したモデル (OpenAI、Google Gemini、Azure OpenAI、AWS Bedrock、Ollama など) を使用して埋め込みを生成します。
• 💾**最適化されたストレージ:**効率的なベクター ストレージのためにsqlite-vecを備えた SQLite を活用し、堅牢なフルテキスト検索のために FTS5 を活用します。
• 🔍**強力なハイブリッド検索:**さまざまなライブラリ バージョン間でベクトル類似性と全文検索を組み合わせて、関連性の高い結果を生成します。
• ⚙️**非同期ジョブ処理:**バックグラウンド ジョブ キューと MCP/CLI ツールを使用して、スクレイピングとインデックス作成のタスクを効率的に管理します。
• 🐳シンプルなデプロイメント: Docker または npx を使用してすぐに起動して実行できます。

概要

このプロジェクトは、様々なソフトウェアライブラリおよびパッケージのドキュメントをスクレイピング、処理、インデックス作成、検索するために設計されたモデルコンテキストプロトコル（MCP）サーバーを提供します。指定されたURLからコンテンツを取得し、セマンティックスプリッティング技術を用いてコンテンツを意味のあるチャンクに分割し、OpenAIを用いてベクトル埋め込みを生成し、SQLiteデータベースにデータを保存します。このサーバーは、効率的なベクトル類似検索のためにsqlite-vec 、全文検索機能のためにFTS5を活用し、これらを組み合わせることでハイブリッドな検索結果を実現します。バージョン管理をサポートしているため、異なるライブラリバージョン（バージョン管理されていないコンテンツを含む）のドキュメントを個別に保存および検索できます。

サーバーは、次の MCP ツールを公開します。

• スクレイピング ジョブを開始します ( scrape_docs ): すぐにjobIdを返します。
• ジョブステータスの確認 ( get_job_status ): 特定のジョブの現在のステータスと進行状況を取得します。
• アクティブ/完了したジョブの一覧表示 ( list_jobs ): 最近実行中のジョブと進行中のジョブを表示します。
• ジョブのキャンセル ( cancel_job ): 実行中またはキューに入れられたジョブを停止しようとします。
• ドキュメントを検索しています ( search_docs )。
• インデックス付きライブラリの一覧表示 ( list_libraries )。
• 適切なバージョンを検索しています ( find_version )。
• インデックス付けされたドキュメントを削除しています ( remove_docs )。
• 単一の URL の取得 ( fetch_url ): URL を取得し、そのコンテンツを Markdown として返します。

構成

埋め込みモデルの動作を構成するために、次の環境変数がサポートされています。

埋め込みモデルの構成

• DOCS_MCP_EMBEDDING_MODEL :**オプション。**形式: provider:model_nameまたはmodel_name (デフォルトはtext-embedding-3-small )。サポートされているプロバイダーと必要な環境変数:
  • openai (デフォルト): OpenAIの埋め込みモデルを使用する
    • OPENAI_API_KEY :必須。OpenAI APIキー
    • OPENAI_ORG_ID :オプション。OpenAI組織ID
    • OPENAI_API_BASE :オプション。OpenAI互換API（例：Ollama、Azure OpenAI）のカスタムベースURL
  • vertex : Google Cloud Vertex AI 埋め込みを使用します
    • GOOGLE_APPLICATION_CREDENTIALS :**必須。**サービスアカウントのJSONキーファイルへのパス
  • gemini : Google Generative AI (Gemini) の埋め込みを使用します
    • GOOGLE_API_KEY :必須。Google APIキー
  • aws : AWS Bedrock 埋め込みを使用します
    • AWS_ACCESS_KEY_ID :必須。AWSアクセスキー
    • AWS_SECRET_ACCESS_KEY :必須。AWSシークレットキー
    • AWS_REGIONまたはBEDROCK_AWS_REGION :必須。Bedrockの AWS リージョン
  • microsoft : Azure OpenAI 埋め込みを使用
    • AZURE_OPENAI_API_KEY :必須。Azure OpenAI APIキー
    • AZURE_OPENAI_API_INSTANCE_NAME :必須。Azureインスタンス名
    • AZURE_OPENAI_API_DEPLOYMENT_NAME :必須。Azureデプロイメント名
    • AZURE_OPENAI_API_VERSION :必須。Azure APIバージョン

ベクトル次元

データベーススキーマは、ベクトルの埋め込みに1536次元という固定次元を使用します。次元削減をサポートする特定のプロバイダ（Geminiなど）を除き、1536次元以下のベクトルを生成するモデルのみがサポートされます。

OpenAI 互換 API (Ollama など) の場合は、エンドポイントを指すOPENAI_API_BASEを持つopenaiプロバイダーを使用します。

これらの変数は、サーバーの実行方法 (Docker、npx、またはソースから) に関係なく設定できます。

MCPサーバーの実行

docs-mcp-server を実行するには 2 つの方法があります。

オプション 1: Docker を使用する (推奨)

これはほとんどのユーザーに推奨されるアプローチです。簡単でわかりやすく、Node.js をインストールする必要もありません。

1. Docker がインストールされ、実行されていることを確認します。
2. MCP 設定を構成します。**Claude/Cline/Roo 構成例:**次の構成ブロックを MCP 設定ファイルに追加します (必要に応じてパスを調整します)。
   { "mcpServers": { "docs-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAI_API_KEY", "-v", "docs-mcp-data:/data", "ghcr.io/arabold/docs-mcp-server:latest" ], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key }, "disabled": false, "autoApprove": [] } } }
   "sk-proj-..."実際の OpenAI API キーに置き換えて、アプリケーションを再起動してください。
3. **これで完了です。**これでサーバーが AI アシスタントで利用できるようになります。

Dockerコンテナの設定:

• -i : STDIN を開いたままにします。これは、stdio 経由の MCP 通信に重要です。
• --rm : コンテナの終了時に自動的に削除します。
• -e OPENAI_API_KEY :必須。OpenAI APIキーを設定します。
• -v docs-mcp-data:/data :**永続化に必須です。**データベースを保存するためにdocs-mcp-dataという名前のDockerボリュームをマウントします。必要に応じて、特定のホストパスに置き換えることもできます（例： -v /path/on/host:/data ）。

設定環境変数（上記の「設定」を参照）は、 -eフラグを使用してコンテナに渡すことができます。例:

オプション2: npxを使用する

このアプローチは、ローカルファイルへのアクセスが必要な場合（例：ローカルファイルシステムからドキュメントのインデックス作成など）に推奨されます。これはDockerコンテナにパスをマウントすることでも実現できますが、npxを使用する方が簡単ですが、Node.jsのインストールが必要です。

1. Node.js がインストールされていることを確認します。
2. MCP 設定を構成します。**Claude/Cline/Roo 構成例:**次の構成ブロックを MCP 設定ファイルに追加します。
   { "mcpServers": { "docs-mcp-server": { "command": "npx", "args": ["-y", "--package=@arabold/docs-mcp-server", "docs-server"], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key }, "disabled": false, "autoApprove": [] } } }
   "sk-proj-..."実際の OpenAI API キーに置き換えて、アプリケーションを再起動してください。
3. **これで完了です。**これでサーバーが AI アシスタントで利用できるようになります。

CLIの使用

CLIを使用して、Dockerまたはnpx経由でドキュメントを直接管理できます。重要：同じインデックス付きドキュメントにアクセスできるようにするには、サーバーとCLIの両方で同じ方法（Dockerまたはnpx）を使用してください。

Docker CLIの使用

Docker を使用してサーバーを実行している場合は、CLI でも Docker を使用します。

サーバーと同じボリューム名（この例ではdocs-mcp-data ）を使用してください。設定環境変数（上記の「設定」を参照）は、サーバーと同様に-eフラグを使用して指定できます。

npx CLIの使用

npx を使用してサーバーを実行している場合は、CLI でも npx を使用します。

npx アプローチでは、システム上のデフォルトのデータ ディレクトリ (通常はホーム ディレクトリ内) が使用され、サーバーと CLI 間の一貫性が確保されます。

(使用可能なコマンドとオプションについては、以下の「CLI コマンド リファレンス」を参照してください。)

CLI コマンドリファレンス

docs-cliドキュメントインデックスを管理するためのコマンドを提供します。Docker ( docker run -v docs-mcp-data:/data ghcr.io/arabold/docs-mcp-server:latest docs-cli ... ) またはnpx ( npx -y --package=@arabold/docs-mcp-server docs-cli ... ) 経由でアクセスしてください。

一般的なヘルプ:

コマンド固有のヘルプ: (グローバルにインストールされていない場合は、 docs-cliをnpx...コマンドに置き換えてください)

単一の URL の取得 ( fetch-url )

単一のURLを取得し、その内容をMarkdown形式に変換します。 scrapeとは異なり、このコマンドはリンクをクロールしたり、コンテンツを保存したりしません。

オプション:

• --no-follow-redirects : HTTP リダイレクトのフォローを無効にする (デフォルト: リダイレクトをフォローする)

例:

ドキュメントのスクレイピング ( scrape )

特定のライブラリの指定された URL からドキュメントをスクレイピングしてインデックスを作成します。

オプション:

• -v, --version <string> : スクレイピングされたドキュメントに関連付ける特定のバージョン。
  • 完全バージョン ( 1.2.3 )、プレリリース バージョン ( 1.2.3-beta.1 )、または部分バージョン ( 1 、 1.2から1.0.0 、 1.2.0に拡張) を受け入れます。
  • 省略した場合、ドキュメントはバージョン管理されていないものとしてインデックス付けされます。
• -p, --max-pages <number> : スクレイピングする最大ページ数 (デフォルト: 1000)。
• -d, --max-depth <number> : 最大ナビゲーション深度 (デフォルト: 3)。
• -c, --max-concurrency <number> : 最大同時リクエスト数 (デフォルト: 3)。
• --ignore-errors : スクレイピング中のエラーを無視します (デフォルト: true)。

例:

ドキュメントの検索 ( search )

ライブラリのインデックス付きドキュメントを検索し、オプションでバージョン別にフィルタリングします。

オプション:

• -v, --version <string> : 検索対象となるバージョンまたは範囲。
  • 正確なバージョン ( 18.0.0 )、部分的なバージョン ( 18 )、または範囲 ( 18.x ) をサポートします。
  • 省略した場合は、利用可能な最新のインデックス バージョンを検索します。
  • 特定のバージョン/範囲が一致しない場合は、ターゲットよりも古い最新のインデックス バージョンにフォールバックします。
  • バージョン管理されていないドキュメントのみを検索するには、空の文字列を明示的に渡します: --version "" 。(注: --versionを省略すると、最新のバージョンが検索されますが、他のバージョンが存在しない場合はバージョン管理されていない可能性があります)。
• -l, --limit <number> : 結果の最大数 (デフォルト: 5)。
• -e, --exact-match : 指定されたバージョンと正確に一致するもののみを一致させます (フォールバックと範囲一致を無効にします) (デフォルト: false)。

例:

利用可能なバージョンの検索 ( find-version )

ターゲットに基づいてライブラリに最適なバージョンのインデックスをチェックし、バージョン管理されていないドキュメントが存在するかどうかを示します。

オプション:

• -v, --version <string> : 対象のバージョンまたは範囲。省略した場合は、利用可能な最新バージョンを検索します。

例:

ライブラリの一覧表示 ( list )

ストア内で現在インデックス付けされているすべてのライブラリを一覧表示します。

ドキュメントの削除 ( remove )

特定のライブラリとバージョンのインデックス付きドキュメントを削除します。

オプション:

• -v, --version <string> : 削除する特定のバージョン。省略した場合は、ライブラリのバージョン管理されていないドキュメントが削除されます。

例:

バージョン処理の概要

• **スクレイピング:**特定の有効なバージョン（ XYZ 、 XYZ-pre 、 XY 、 X ）またはバージョンなし（バージョン管理されていないドキュメントの場合）が必要です。範囲（ Xx ）はスクレイピングでは無効です。
• **検索/発見:**特定のバージョン、部分バージョン、または範囲（ XYZ 、 XY 、 X 、 Xx ）を指定できます。ターゲットが一致しない場合は、最新の古いバージョンにフォールバックします。バージョンを省略すると、利用可能な最新バージョンがターゲットになります。-- --version ""を明示的に指定して検索すると、バージョン管理されていないドキュメントがターゲットになります。
• バージョン管理されてい**ないドキュメント:**ライブラリには、特定のバージョンを指定せずにドキュメントが保存されている場合があります（スクレイピング時に--version省略することで）。これらのドキュメントは--version ""明示的に使用して検索できます。find find-versionコマンドは、semver に一致するものに加えて、バージョン管理されていないドキュメントが存在するかどうかも報告します。

開発と高度なセットアップ

このセクションでは、開発目的でソースコードから直接サーバー/CLIを実行する方法について説明します。現在、主な使用方法は「方法2」で説明したように、パブリックDockerイメージを使用することです。

ソースから実行（開発）

これにより、分離された環境が提供され、HTTP エンドポイントを介してサーバーが公開されます。

1. リポジトリをクローンします。
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. **.envファイルを作成します。**例をコピーし、OpenAI キーを追加します (以下の「環境設定」を参照)。
   cp .env.example .env # Edit .env and add your OPENAI_API_KEY
3. Docker イメージをビルドします。
   docker build -t docs-mcp-server .
4. Docker コンテナを実行します。
   # Option 1: Using a named volume (recommended) # Docker automatically creates the volume 'docs-mcp-data' if it doesn't exist on first run. docker run -i --env-file .env -v docs-mcp-data:/data --name docs-mcp-server docs-mcp-server # Option 2: Mapping to a host directory # docker run -i --env-file .env -v /path/on/your/host:/data --name docs-mcp-server docs-mcp-server
   • -i : STDIN が接続されていない場合でも開いたままにします。これは、stdio 経由でサーバーとやり取りする際に非常に重要です。
   • --env-file .env : ローカルの.envファイルから環境変数 ( OPENAI_API_KEYなど) を読み込みます。
   • -v docs-mcp-data:/dataまたは-v /path/on/your/host:/data :**永続化に不可欠です。**これは、Docker の名前付きボリューム（Docker は必要に応じてdocs-mcp-dataを自動的に作成します）またはホストディレクトリをコンテナ内の/data``/dataにマウントします。/data ディレクトリは、サーバーがdocuments.dbファイルを保存する場所です（Dockerfile のDOCS_MCP_STORE_PATHで設定）。これにより、コンテナが停止または削除された場合でも、インデックス化されたドキュメントが永続化されます。
   • --name docs-mcp-server : コンテナに便利な名前を割り当てます。

   コンテナ内のサーバーは Node.js を使用して直接実行され、 stdioを介して通信するようになりました。

この方法は、プロジェクトに貢献したり、未公開バージョンを実行したりする場合に役立ちます。

1. リポジトリをクローンします。
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. 依存関係をインストールします:
   npm install
3. **プロジェクトをビルドします。**これにより、TypeScript がdist/ディレクトリ内の JavaScript にコンパイルされます。
   npm run build
4. **環境設定：**以下の「環境設定」の説明に従って、 .envファイルを作成して設定します。これはOPENAI_API_KEY提供するために不可欠です。
5. 走る：
   • サーバー（開発モード）： npm run dev:server （ビルド、監視、再起動）
   • サーバー（本番モード）： npm run start （ビルド済みのコードを実行）
   • CLI: npm run cli -- <command> [options]またはnode dist/cli.js <command> [options]

環境設定（Source/Docker用）

**注:**この.envファイルの設定は、主にサーバーをソースから実行するかDockerメソッドを使用する場合に必要ですnpx統合メソッドを使用する場合は、 OPENAI_API_KEY MCP構成ファイルに直接設定されます。

1. .env.exampleに基づいて.envファイルを作成します。
   cp .env.example .env
2. .env内の OpenAI API キーを更新します。
   # Required: Your OpenAI API key for generating embeddings. OPENAI_API_KEY=your-api-key-here # Optional: Your OpenAI Organization ID (handled automatically by LangChain if set) OPENAI_ORG_ID= # Optional: Custom base URL for OpenAI API (e.g., for Azure OpenAI or compatible APIs) OPENAI_API_BASE= # Optional: Embedding model name (defaults to "text-embedding-3-small") # Examples: text-embedding-3-large, text-embedding-ada-002 DOCS_MCP_EMBEDDING_MODEL= # Optional: Specify a custom directory to store the SQLite database file (documents.db). # If set, this path takes precedence over the default locations. # Default behavior (if unset): # 1. Uses './.store/' in the project root if it exists (legacy). # 2. Falls back to OS-specific data directory (e.g., ~/Library/Application Support/docs-mcp-server on macOS). # DOCS_MCP_STORE_PATH=/path/to/your/desired/storage/directory

デバッグ（ソースから）

MCPサーバーはNode.js経由で直接実行する場合、stdio経由で通信するため、デバッグが困難になる可能性があります。ビルド後にパッケージスクリプトとして提供されるMCP Inspectorの使用をお勧めします。

インスペクターは、ブラウザでデバッグ ツールにアクセスするための URL を提供します。

リリース

このプロジェクトでは、セマンティック リリースとConventional Commitsを使用してリリース プロセスを自動化します。

仕組み:

1. コミット メッセージ: mainブランチにマージされるすべてのコミットは、Conventional Commits 仕様に従う必要があります。
2. **手動トリガー:**新しいリリースを作成する準備ができたら、[アクション] タブから「リリース」GitHub Actions ワークフローを手動でトリガーできます。
3. **semantic-releaseアクション:**バージョンを決定し、 CHANGELOG.mdとpackage.jsonを更新し、コミットし、タグ付けし、npm に公開し、GitHub リリースを作成します。

必要なこと:

• Conventional Commits を使用します。
• 変更をmainにマージします。
• 準備ができたら、GitHub の [アクション] タブから手動でリリースをトリガーします。

**自動化の処理:**変更ログ、バージョンアップ、タグ、npm 公開、GitHub リリース。

建築

プロジェクトのアーキテクチャと設計原則の詳細については、 ARCHITECTURE.md を参照してください。

注目すべきは、このプロジェクトのコードの大部分が、まさにこの MCP サーバーの機能を活用して、AI アシスタント Cline によって生成されたことです。