Docsearch Mcp

docsearch-mcp

ローカル優先のドキュメント検索・インデックス作成システムです。Model Context Protocol（MCP）を通じて、ローカルファイル（PDF を含む）や Confluence ページを横断する、セマンティック検索とキーワード検索を組み合わせたハイブリッド検索を提供します。Claude Code/Desktop のような AI アシスタントがドキュメント、コードベース、調査資料にアクセスするのに最適です。

✨ 機能

• 🔍 ハイブリッド検索：全文検索（FTS）とベクトル類似検索を組み合わせ、最適な結果を提供します
• 📁 複数のソース：ローカルファイル（コード、ドキュメント、PDF、オフィス文書、電子書籍、音声／動画）と Confluence スペースをインデックス化します
• 📄 PDF サポート：メタデータを保持したまま、PDF ドキュメントからテキストを抽出して検索できます
• 📝 オフィス文書：DOCX、XLSX、PPTX ファイルに加えて、OnlyOffice による変換を通じて従来形式の DOC、XLS、PPT ファイルからテキストを抽出して検索できます
• 📚 EPUB サポート：電子書籍ファイルを章単位で解析し、インデックス化します
• 🎵 音声／動画：メディアのメタデータを抽出し、オプションで Whisper API による文字起こしを行います
• 🖼️ 画像検索：AI を活用して、図、スクリーンショット、グラフの説明と検索を行います
• 🗄️ データベースの柔軟性：SQLite（ローカル優先）、PostgreSQL（スケーラブル）、VectorChord（高性能なベクトル検索）をサポートします
• 🤖 MCP 統合：Claude Code やその他の MCP 対応ツールとシームレスに統合します
• 💻 CLI ツール：複数の出力形式に対応した、独立したコマンドラインインターフェースです
• ⚡ リアルタイム更新：ファイルを監視し、自動的に再インデックス化します
• 🎯 スマートなチャンク分割：コード、ドキュメント、PDF、電子書籍、音声の文字起こしに対応した、インテリジェントなテキスト分割を行います
• 📊 複数の出力形式：形式固有のメタデータを含む、テキスト、JSON、YAML 形式で出力します
• 🔒 セキュア：API キーや機密データはご利用のマシン内に保持されます

🚀 インストールと使用方法

npm パッケージ

# Install globally
npm install -g docsearch-mcp

# Or use with npx
npx docsearch-mcp --help

Docker コンテナ

# Pull the image
docker pull ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

# Run the MCP server with proper permissions
docker run --rm -i \
  -v /path/to/your/documents:/app/documents \
  -v /path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

MCP サーバーの使用方法

MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "docsearch": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"]
    }
  }
}

ローカル開発環境のセットアップ（任意）

開発またはカスタマイズの場合：

# Clone the repository
git clone https://github.com/patrickkoss/docsearch-mcp.git
cd docsearch-mcp

# Quick setup with Make
make setup

# Or manual setup
pnpm install
cp .env.example .env
# Edit .env with your API keys and configuration

基本的な使用方法

CLI ツール

# Ingest documents
docsearch-mcp ingest files              # Index local files
docsearch-mcp ingest confluence         # Index Confluence pages
docsearch-mcp ingest all --watch        # Index all sources with file watching

# Search documents
docsearch-mcp search "your query"       # Basic search
docsearch-mcp search "typescript" -k 5 -o json  # JSON output, top 5 results
docsearch-mcp search "API docs" -s confluence   # Search only Confluence

# Get help
docsearch-mcp --help
docsearch-mcp search --help

MCP サーバー

# Run the MCP server directly
npx docsearch-mcp start

# Or if installed globally
docsearch-mcp start

Docker の使用方法

# Run with official Docker image (recommended)
docker run --rm -i \
  -v /path/to/your/documents:/app/documents \
  -v /path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

# Run CLI commands with Docker
docker run --rm -i \
  -v /path/to/your/documents:/app/documents \
  -v /path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2 \
  npx docsearch-mcp search "your query"

# Alternative: Use Docker volumes (simpler but less control)
docker run --rm \
  -v ./documents:/app/documents \
  -v docsearch-data:/app/data \
  --env-file .env \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

# For development (requires cloning repo)
docker-compose up -d docsearch-mcp

⚙️ 設定

Docker の設定

公式 Docker イメージを使用する場合は、.env ファイルを作成します：

echo "OPENAI_API_KEY=your-openai-key" > .env
echo "FILE_ROOTS=/app/documents" >> .env

Docker のデプロイに関する主な注意事項：

• ドキュメントのボリューム：ドキュメントディレクトリをコンテナ内の /app/documents にマウントします
• データの永続化：SQLite データベースを保持するには、データディレクトリを /app/data にマウントします
• ユーザー権限：マウントしたボリュームの権限に関する問題を避けるため、--user $(id -u):$(id -g) を使用します
• 環境変数：.env ファイルまたは環境変数を通じて設定を渡します
• 公式イメージ：本番環境へのデプロイには ghcr.io/patrickkoss/docsearch-mcp:v0.0.2 を使用します

公式 Docker イメージの使用

適切な権限を設定する推奨方法：

# Basic usage with user permissions (avoids file ownership issues)
docker run --rm -i \
  -v /absolute/path/to/documents:/app/documents \
  -v /absolute/path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.5

# For MCP server integration (background service)
docker run -d --name docsearch-mcp \
  -v /absolute/path/to/documents:/app/documents \
  -v /absolute/path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.5

Docker ボリュームを使用する代替方法：

# Using Docker volumes (simpler but less direct file access)
docker run --rm \
  -v ./documents:/app/documents \
  -v docsearch-data:/app/data \
  --env-file .env \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

Docker の権限について：

• --user $(id -u):$(id -g)：コンテナを現在のユーザー ID とグループ ID で実行し、ファイルの権限に関する問題を防ぎます
• ユーザーの動的作成：コンテナは、マウントしたボリュームの権限に一致するユーザーを自動的に作成します
• ファイル所有者の自動設定：コンテナのファイルには、適切なユーザーが自動的に所有者として設定されます
• クロスプラットフォーム互換性：さまざまなホストシステムで一貫して動作します

ローカル開発の設定

.env.example から .env ファイルを作成して、次の項目を設定します：

埋め込み（必須）

EMBEDDINGS_PROVIDER=openai
OPENAI_API_KEY=your_openai_key
OPENAI_EMBED_MODEL=text-embedding-3-small

ファイルのインデックス化

FILE_ROOTS=.
FILE_INCLUDE_GLOBS=**/*.{ts,js,py,md,txt,pdf,png,jpg,jpeg,gif,svg,webp}
FILE_EXCLUDE_GLOBS=**/node_modules/**,**/dist/**

画像検索（任意）

ENABLE_IMAGE_TO_TEXT=true
IMAGE_TO_TEXT_PROVIDER=openai
IMAGE_TO_TEXT_MODEL=gpt-4o-mini

データベースの設定

# Use SQLite (default, local-first)
DB_TYPE=sqlite
DB_PATH=./data/index.db

# OR use PostgreSQL with pgvector (for scalability)
DB_TYPE=postgresql
POSTGRES_CONNECTION_STRING=postgresql://user:password@localhost:5432/docsearch

# OR use PostgreSQL with VectorChord (high-performance vector search)
DB_TYPE=vectorchord
POSTGRES_CONNECTION_STRING=postgresql://user:password@localhost:5432/docsearch
# Optional VectorChord tuning (shown with defaults)
VECTORCHORD_RESIDUAL_QUANTIZATION=true
VECTORCHORD_LISTS=100
VECTORCHORD_SPHERICAL_CENTROIDS=true
VECTORCHORD_BUILD_THREADS=4
VECTORCHORD_PROBES=10

VectorChord は、RaBitQ 圧縮と階層的 K-means を使用する PostgreSQL 拡張機能です。pgvector の IVFFlat と比較して、より高速なインデックス作成とストレージコストの削減を実現します。pgvector と完全な互換性があり、PostgreSQL インスタンスに vchord 拡張機能をインストールする必要があります（または、tensorchord/vchord-suite Docker イメージを使用してください）。

Confluence（オプション）

CONFLUENCE_BASE_URL=https://yourcompany.atlassian.net
[email protected]
CONFLUENCE_API_TOKEN=your_confluence_token
CONFLUENCE_SPACES=SPACE1,SPACE2

# Advanced filtering (all optional)
# Filter by parent page IDs - only index pages under these parent pages
CONFLUENCE_PARENT_PAGES=12345678,87654321

# Title patterns to include (supports * wildcards)
CONFLUENCE_TITLE_INCLUDES=API*,User Guide,*Documentation*

# Title patterns to exclude (supports * wildcards)
CONFLUENCE_TITLE_EXCLUDES=Draft*,*Archive*,Test*

Confluence のフィルタリングオプション：

• 親ページによるフィルタリング：ページ ID を指定して、特定のフォルダー階層内のページのみをインデックスに登録します
• タイトルの包含パターン：一致するタイトルのページのみをインデックスに登録するパターンを定義します
• タイトルの除外パターン：一致するタイトルのページを除外するパターンを定義します
• ワイルドカードのサポート：柔軟なパターンマッチングには * を使用します（例：API* は「API」で始まるすべてのタイトルに一致します）

サポートされているファイル形式

システムはさまざまなファイル形式を自動的に検出して処理します。

• コードファイル：.ts、.js、.py、.go、.rs、.java、.cpp、.c、.rb、.php、.kt、.swift
• ドキュメント：.md、.mdx、.txt、.rst、.adoc、.yaml、.yml、.json
• PDF：.pdf ファイルは、テキスト抽出とメタデータ保持を行って自動的に解析されます
• Office ドキュメント：テキスト抽出と形式固有のメタデータに対応した .docx、.xlsx、.pptx ファイル、および OnlyOffice による変換に対応した .doc、.xls、.ppt ファイル
• 電子書籍：章を考慮した解析とメタデータ抽出に対応した .epub ファイル
• 音声：メタデータ抽出とオプションの文字起こしに対応した .mp3、.wav、.flac、.ogg、.m4a、.aac ファイル
• 動画：メタデータ抽出とオプションの文字起こしに対応した .mp4、.webm、.mkv、.avi、.mov ファイル
• 画像：AI による説明生成（オプション）に対応した .png、.jpg、.jpeg、.gif、.svg、.webp ファイル

PDF ファイルは次の方法で処理されます。

• 高度な解析によるテキスト抽出
• メタデータの保持（ページ数、ドキュメント情報）
• スマートなテキスト正規化とチャンク分割
• 破損または暗号化されたファイルのエラー処理

Office ドキュメントは次の方法で処理されます。

• DOCX：ドキュメント構造を保持しながら、mammoth によってテキストと段落を抽出します
• XLSX：シート名のプレフィックスを付けて、すべてのシートからセルのテキストを抽出します（最大 100 シート、各シート最大 10,000 行）
• PPTX：スライド番号のプレフィックスを付けて、スライドのテキストを抽出します
• 旧形式（DOC、XLS、PPT）：OnlyOffice Conversion API で新しい形式に変換した後、上記のパーサーで処理します

OnlyOffice のセットアップ（旧形式の DOC/XLS/PPT をサポートする場合）

旧形式の Office ファイルを使用するには、OnlyOffice Document Server が実行されている必要があります。

docker run -d --name onlyoffice -p 8080:80 onlyoffice/documentserver

次に、.env で設定します。

ONLYOFFICE_URL=http://localhost:8080
# ONLYOFFICE_JWT_SECRET=your-secret    # if JWT auth is enabled on your server
# ONLYOFFICE_TIMEOUT=30000             # conversion timeout in ms (default: 30000)

ONLYOFFICE_URL が設定されていない場合、旧形式の Office ファイルは取り込み時に通知なくスキップされます。

Docling のセットアップ（OCR 対応の ML ベースのドキュメント解析）

OCR、レイアウト解析、表抽出に対応した優れた PDF 解析には、ドキュメントパーサーとして Docling を使用できます：

# Run docling-serve as a Docker container
docker run -d --name docling -p 5001:5001 quay.io/docling-project/docling-serve

# For CPU-only (smaller image):
docker run -d --name docling -p 5001:5001 quay.io/docling-project/docling-serve-cpu

次に、.env で設定します：

DOCUMENT_PARSER=docling
DOCLING_URL=http://localhost:5001

Docling は、PDF、DOCX、PPTX、XLSX、HTML、画像（PNG、JPG、TIFF）、EPUB に対応しています。音声、動画、コードファイルには、この設定にかかわらず、常に組み込みパーサーが使用されます。

DOCUMENT_PARSER が設定されていない場合、または builtin に設定されている場合は、従来の軽量パーサー（pdf-parse、mammoth など）が使用されます。

EPUB ファイルは、次の方法で処理されます：

• 章ごとの HTML コンテンツ抽出とテキスト変換
• 章を考慮したチャンク分割（チャンクが章の境界をまたぐことはありません）
• メタデータの抽出（タイトル、著者、言語、章数）

音声／動画ファイルは、次の方法で処理されます：

• メタデータ抽出：music-metadata を使用して、再生時間、ビットレート、サンプルレート、コーデック、アーティスト、アルバム、タイトル、ジャンルを取得します
• オプションの文字起こし：OpenAI Whisper API（または互換エンドポイント）を使用した音声テキスト変換です。ENABLE_AUDIO_TRANSCRIPTION=true で有効にします
• タイムスタンプの保持：文字起こしのチャンクには、元ファイル内のコンテンツを特定するための時間範囲が含まれます
• ファイルサイズの上限：25MB を超えるファイルは、メタデータのみを対象にインデックスが作成されます（Whisper API の上限）
• 設定：WHISPER_API_KEY（デフォルトは OPENAI_API_KEY）、WHISPER_BASE_URL、WHISPER_MODEL（デフォルトは whisper-1）

画像ファイルでは、AI による説明の生成をオプションで利用できます：

• ビジョンモデルとの連携：OpenAI のビジョンモデル（または互換 API）を使用して、詳細な説明を生成します
• 処理の設定：環境変数 ENABLE_IMAGE_TO_TEXT で、画像からテキストへの変換を有効／無効にできます
• フォールバック対応：ビジョン処理が無効な場合、画像はファイル名でインデックス化されます
• メタデータの保持：画像の寸法、ファイルサイズ、説明のメタデータを保存します
• 検索との連携：画像の説明は、検索可能なテキストコンテンツとしてインデックス化されます

📖 使い方

CLI ツール

CLI ツールを使うと、コマンドラインから直接ドキュメントを取り込み、検索できます：

CLI コマンドとフラグ

すべての CLI フラグでは、設定の優先順位として CLI 引数 > 環境変数 > 設定ファイル が適用されます

グローバルオプション（すべてのコマンドで使用可能）

フラグ	環境変数	デフォルト	説明
-c, --config <file>	-	.env	設定ファイルのパス
--embeddings-provider <provider>	EMBEDDINGS_PROVIDER	openai	埋め込みプロバイダー（openai または tei）
--openai-api-key <key>	OPENAI_API_KEY	-	OpenAI API キー
--openai-base-url <url>	OPENAI_BASE_URL	-	OpenAI ベース URL（カスタムエンドポイント用）
--openai-embed-model <model>	OPENAI_EMBED_MODEL	text-embedding-3-small	OpenAI 埋め込みモデル
--openai-embed-dim <dimension>	OPENAI_EMBED_DIM	1536	OpenAI 埋め込みの次元数
--tei-endpoint <url>	TEI_ENDPOINT	-	Text Embeddings Inference エンドポイント
--enable-image-to-text	ENABLE_IMAGE_TO_TEXT	false	画像からテキストへの処理を有効にする
--image-to-text-provider <provider>	IMAGE_TO_TEXT_PROVIDER	openai	画像からテキストへの変換プロバイダー
--image-to-text-model <model>	IMAGE_TO_TEXT_MODEL	gpt-4o-mini	画像からテキストへの変換モデル
--confluence-base-url <url>	CONFLUENCE_BASE_URL	-	Confluence ベース URL
--confluence-email <email>	CONFLUENCE_EMAIL	-	Confluence メールアドレス
--confluence-api-token <token>	CONFLUENCE_API_TOKEN	-	Confluence API トークン
--confluence-spaces <spaces>	CONFLUENCE_SPACES	-	Confluence スペース（カンマ区切り）
--file-roots <roots>	FILE_ROOTS	.	インデックス対象のファイルルート（カンマ区切り）
--file-include-globs <globs>	FILE_INCLUDE_GLOBS	**/*.{go,ts,tsx,js,py,rs,java,md,mdx,txt,yaml,yml,json,pdf}	ファイルの対象パターン
--file-exclude-globs <globs>	FILE_EXCLUDE_GLOBS	**/{.git,node_modules,dist,build,target}/**	ファイルの除外パターン
--db-type <type>	DB_TYPE	sqlite	データベースの種類（sqlite、postgresql、または vectorchord）
--db-path <path>	DB_PATH	./data/index.db	SQLite データベースのパス
--postgres-connection-string <string>	POSTGRES_CONNECTION_STRING	-	PostgreSQL 接続文字列

Ingest コマンド

docsearch ingest [source] [options]

引数：

• source - 取り込むソース：files、confluence、または all（デフォルト：all）

オプション：

• -w, --watch - ファイルの変更を監視して再インデックスします

例：

# Basic ingestion with environment config
docsearch ingest files
docsearch ingest confluence
docsearch ingest all --watch

# Override config with CLI args
docsearch ingest files --file-roots "./src,./docs" --openai-api-key sk-xxx

# Use custom config file and database
docsearch --config prod.env --db-path /data/prod.db ingest all

# Ingest with custom file patterns
docsearch ingest files \
  --file-include-globs "**/*.{ts,md,py}" \
  --file-exclude-globs "**/node_modules/**,**/venv/**"

# Use PostgreSQL instead of SQLite
docsearch ingest all \
  --db-type postgresql \
  --postgres-connection-string "postgresql://user:pass@localhost:5432/docs"

Search コマンド

docsearch search <query> [options]

引数：

• query - 検索クエリ（必須）

オプション：

フラグ	デフォルト	説明
-k, --top-k <number>	10	返す結果の数（1～100）
-s, --source <source>	-	ソースで絞り込み：file または confluence
-r, --repo <repo>	-	リポジトリ名で絞り込み
-p, --path-prefix <prefix>	-	パスのプレフィックスで絞り込み
-m, --mode <mode>	auto	検索モード：auto、vector、または keyword
-o, --output <format>	text	出力形式：text、json、または yaml
--include-images	-	検索結果に画像を含めます
--images-only	-	画像のみを検索します

例：

# Basic search
docsearch search "typescript interface"

# Limit results and format as JSON
docsearch search "API documentation" --top-k 5 --output json

# Search only Confluence with repository filter
docsearch search "deployment guide" --source confluence --repo backend-docs

# Semantic search only with path filtering
docsearch search "authentication" --mode vector --path-prefix src/auth/

# Override database and output as YAML
docsearch --db-path /custom/index.db search "error handling" --output yaml

# Complex search with multiple filters
docsearch search "React hooks" \
  --source file \
  --repo frontend \
  --path-prefix src/components/ \
  --mode auto \
  --top-k 20 \
  --output json

# Search including images (architecture diagrams, screenshots)
docsearch search "user authentication flow" --include-images

# Search only images for diagrams and charts
docsearch search "system architecture" --images-only --output json

CLI の設定

CLI は、優先順位の高い順に複数の設定ソースに対応しています。

1. コマンドライン引数（最優先）
2. カスタム設定ファイル（--config path/to/.env）
3. .env.local ファイル
4. .env ファイル（最も優先度が低い）

CLI の出力形式

• テキスト（デフォルト）：アイコンと書式設定を使用した、人が読みやすい形式
• JSON：連携用のタイムスタンプを含む構造化データ
• YAML：設定やドキュメントに適した、すっきりとした階層形式

MCP 連携

MCP（Model Context Protocol）サーバーは、Claude Code やその他の MCP 互換ツールとシームレスに連携できます。

MCP の設定オプション

すべての設定オプションは、環境変数を介して MCP サーバーに渡されます。

必須の設定

環境変数	デフォルト	説明
EMBEDDINGS_PROVIDER	openai	埋め込みプロバイダー（openai または tei）
OPENAI_API_KEY	-	OpenAI API キー（OpenAI を使用する場合は必須）

任意の設定

環境変数	デフォルト	説明
OPENAI_BASE_URL	-	OpenAI のベース URL（カスタムエンドポイント用）
OPENAI_EMBED_MODEL	text-embedding-3-small	OpenAI の埋め込みモデル
OPENAI_EMBED_DIM	1536	OpenAI の埋め込み次元
TEI_ENDPOINT	-	Text Embeddings Inference のエンドポイント
FILE_ROOTS	.	インデックス対象のファイルルート（カンマ区切り）
FILE_INCLUDE_GLOBS	**/*.{go,ts,tsx,js,py,rs,java,md,mdx,txt,yaml,yml,json,pdf}	ファイルの対象パターン
FILE_EXCLUDE_GLOBS	**/{.git,node_modules,dist,build,target}/**	ファイルの除外パターン
CONFLUENCE_BASE_URL	-	Confluence のベース URL
CONFLUENCE_EMAIL	-	Confluence のメールアドレス
CONFLUENCE_API_TOKEN	-	Confluence の API トークン
CONFLUENCE_SPACES	-	Confluence のスペース（カンマ区切り）
DB_TYPE	sqlite	データベースの種類（sqlite、postgresql、または vectorchord）
DB_PATH	./data/index.db	SQLite データベースのパス
POSTGRES_CONNECTION_STRING	-	PostgreSQL の接続文字列

クイックセットアップ

1. パッケージをインストールします：

   npm install -g docsearch-mcp
   

2. 設定を作成します：

   # Create a .env file in your project directory
   echo "OPENAI_API_KEY=your-openai-key" > .env
   echo "FILE_ROOTS=." >> .env
   

3. Claude Code の MCP 設定に追加します：

   {
     "mcpServers": {
       "docsearch": {
         "command": "npx",
         "args": ["docsearch-mcp", "start"],
         "env": {
           "OPENAI_API_KEY": "your-openai-key",
           "EMBEDDINGS_PROVIDER": "openai",
           "FILE_ROOTS": ".,../other-project",
           "DB_PATH": "/path/to/your/index.db"
         }
       }
     }
   }
   

Docker との統合

方法 1：Docker を直接実行

{
  "mcpServers": {
    "docsearch": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/your/documents:/app/documents",
        "-v",
        "docsearch-data:/app/data",
        "--env-file",
        ".env",
        "ghcr.io/patrickkoss/docsearch-mcp:v0.0.2"
      ]
    }
  }
}

方法 2：Docker Compose を使用

docker-compose.yml ファイルを作成します：

version: '3.8'
services:
  docsearch-mcp:
    image: ghcr.io/patrickkoss/docsearch-mcp:v0.0.5
    volumes:
      - ./documents:/app/documents
      - docsearch-data:/app/data
    env_file:
      - .env
    stdin_open: true
volumes:
  docsearch-data:

次に、MCP を設定します：

{
  "mcpServers": {
    "docsearch": {
      "command": "docker",
      "args": ["exec", "-i", "docsearch-mcp", "node", "dist/src/server/mcp.js"]
    }
  }
}

MCP の高度な設定例

マルチプロジェクトのセットアップ

{
  "mcpServers": {
    "docsearch-work": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "/work/projects/frontend,/work/projects/backend",
        "FILE_INCLUDE_GLOBS": "**/*.{ts,tsx,js,py,md,yaml}",
        "DB_PATH": "/work/data/work-index.db",
        "CONFLUENCE_BASE_URL": "https://company.atlassian.net",
        "CONFLUENCE_SPACES": "DEV,API,DOCS"
      }
    },
    "docsearch-personal": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "/home/user/projects,/home/user/documents",
        "DB_PATH": "/home/user/.docsearch/personal.db",
        "EMBEDDINGS_PROVIDER": "tei",
        "TEI_ENDPOINT": "http://localhost:8080/embeddings"
      }
    }
  }
}

PostgreSQL のセットアップ

{
  "mcpServers": {
    "docsearch": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "DB_TYPE": "postgresql",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/docsearch",
        "FILE_ROOTS": ".,/other/projects"
      }
    }
  }
}

VectorChord のセットアップ（高性能）

{
  "mcpServers": {
    "docsearch": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "DB_TYPE": "vectorchord",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/docsearch",
        "FILE_ROOTS": ".,/other/projects",
        "VECTORCHORD_PROBES": "20"
      }
    }
  }
}

MCP ツール

MCP サーバーは Claude Code 向けに次のツールを提供します：

doc-search

任意の出力形式を指定して、インデックス済みドキュメントを検索します。

パラメーター：

• query（文字列、必須）：検索クエリ
• topK（数値、任意）：返す結果の数（デフォルト：10、最大：100）
• source（文字列、任意）：ソースで絞り込みます（file または confluence）
• repo（文字列、任意）：リポジトリ名で絞り込みます
• pathPrefix（文字列、任意）：パスのプレフィックスで絞り込みます
• mode（文字列、任意）：検索モード（auto、vector、keyword、デフォルト：auto）
• outputFormat（文字列、任意）：出力形式（text、json、yaml、デフォルト：text）
• includeImages（ブール値、任意）：検索結果に画像を含めます
• imagesOnly（ブール値、任意）：画像のみを検索します

例：

Use the doc-search tool to find "TypeScript interfaces" with JSON output format, limited to 5 results from file sources only.

doc-ingest

ファイルまたはConfluenceからドキュメントを取り込みます。

パラメーター：

• source（文字列、必須）：取り込み元（files、confluence、またはall）
• watch（ブール値、任意）：ファイルの変更を監視し、再インデックスします（デフォルト：false）

例：

Use the doc-ingest tool to index all local files and Confluence pages.

doc-ingest-status

インデックス作成の統計情報とステータスを取得します。

パラメーターは不要です。

例：

Use the doc-ingest-status tool to check how many documents are currently indexed.

MCP リソース

サーバーはURIを通じてチャンクリソースも提供します。

• docchunk://{chunk_id}：IDを指定して、特定のドキュメントチャンクの全コンテンツを取得します

📚 実践例

セットアップのワークフロー例

クイックセットアップのワークフロー

# 1. Install globally
npm install -g docsearch-mcp

# 2. Configure with your API key
echo "OPENAI_API_KEY=sk-your-key-here" > .env
echo "FILE_ROOTS=.,../other-project" >> .env

# 3. Index your documents
docsearch-mcp ingest all --watch &

# 4. Test search
docsearch-mcp search "how to deploy" --output json --top-k 3

# 5. Test MCP server
npx docsearch-mcp start

本番環境向けDockerのワークフロー

# 1. Setup production environment
echo "OPENAI_API_KEY=sk-your-key" > .env
echo "FILE_ROOTS=/app/documents" >> .env
# Add other configuration as needed

# 2. Create documents directory
mkdir -p documents
cp -r /path/to/your/docs/* documents/

# 3. Run the official Docker image
docker run -d \
  --name docsearch-mcp \
  -v $(pwd)/documents:/app/documents \
  -v docsearch-data:/app/data \
  --env-file .env \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.5

# 4. Index documents
docker exec docsearch-mcp npx docsearch-mcp ingest all

# 5. Test search
docker exec docsearch-mcp npx docsearch-mcp search "authentication" -o json

よくあるユースケース

コードドキュメントの検索

TypeScript/Reactプロジェクトのセットアップ：

# CLI configuration
docsearch-mcp ingest files \
  --file-roots "./src,./docs,./README.md" \
  --file-include-globs "**/*.{ts,tsx,md,yaml,json}" \
  --file-exclude-globs "**/node_modules/**,**/dist/**,**/.git/**"

# Search for React patterns
docsearch-mcp search "useEffect hook patterns" --source file --top-k 10
docsearch-mcp search "TypeScript interface" --mode vector --output json

MCPの設定：

{
  "mcpServers": {
    "project-docs": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "./src,./docs,./README.md",
        "FILE_INCLUDE_GLOBS": "**/*.{ts,tsx,md,yaml,json}",
        "FILE_EXCLUDE_GLOBS": "**/node_modules/**,**/dist/**",
        "DB_PATH": "./project-search.db"
      }
    }
  }
}

複数リポジトリのセットアップ

チームのドキュメントハブ：

{
  "mcpServers": {
    "team-knowledge": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "/team/frontend,/team/backend,/team/mobile,/team/docs",
        "CONFLUENCE_BASE_URL": "https://company.atlassian.net",
        "CONFLUENCE_SPACES": "TEAM,API,ARCH,DEPLOY",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-token",
        "DB_TYPE": "postgresql",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost/team_docs"
      }
    }
  }
}

個人の調査環境のセットアップ：

# Index academic papers and personal notes
docsearch-mcp ingest files \
  --file-roots "/home/user/papers,/home/user/notes,/home/user/projects" \
  --file-include-globs "**/*.{pdf,md,txt,py,ipynb}" \
  --embeddings-provider tei \
  --tei-endpoint "http://localhost:8080/embeddings"

# Search across all personal knowledge
docsearch-mcp search "machine learning optimization" --mode auto --top-k 15

# Search for diagrams and technical images
docsearch-mcp search "neural network architecture" --include-images --top-k 10
docsearch-mcp search "flowchart" --images-only --output json

PDF中心のワークフロー

# Setup for research document collection
docsearch-mcp ingest files \
  --file-roots "/research/papers,/research/reports" \
  --file-include-globs "**/*.{pdf,docx,md,txt}" \
  --openai-embed-model "text-embedding-3-large" \
  --openai-embed-dim 3072

# Search through research papers
docsearch-mcp search "neural network architectures" \
  --mode vector \
  --top-k 20 \
  --output yaml

高度な検索の例

複雑なフィルタリング

# Search only TypeScript files in components directory
docsearch-mcp search "button component" \
  --source file \
  --path-prefix src/components/ \
  --mode auto

# Find Confluence deployment docs from specific space
docsearch-mcp search "kubernetes deployment" \
  --source confluence \
  --repo DEVOPS \
  --mode keyword

# Semantic search across all sources with high precision
docsearch-mcp search "error handling patterns" \
  --mode vector \
  --top-k 50 \
  --output json | jq '.results[] | select(.score > 0.8)'

# Search for architecture diagrams and flowcharts
docsearch-mcp search "system design diagram" \
  --images-only \
  --mode vector \
  --output json

# Include images when searching for UI/UX content
docsearch-mcp search "user interface design" \
  --include-images \
  --path-prefix docs/ \
  --top-k 20

出力形式の例

テキスト出力（人間が読みやすい形式）：

docsearch-mcp search "authentication middleware" --output text

JSON出力（スクリプト向け）：

# Get results for further processing
RESULTS=$(docsearch-mcp search "API rate limiting" --output json)
echo "$RESULTS" | jq '.results[].path' | head -5

YAML出力（ドキュメント向け）：

# Generate documentation from search results
docsearch-mcp search "configuration options" --output yaml > config-docs.yml

トラブルシューティングの例

検索品質のデバッグ

# Compare search modes
docsearch-mcp search "async function" --mode keyword --top-k 5
docsearch-mcp search "async function" --mode vector --top-k 5
docsearch-mcp search "async function" --mode auto --top-k 5

# Check what's indexed
docsearch-mcp ingest-status

パフォーマンスの最適化

# Use smaller embedding model for speed
docsearch-mcp ingest all \
  --openai-embed-model "text-embedding-3-small" \
  --openai-embed-dim 1536

# Use local TEI for privacy/speed
docker run -d --name tei -p 8080:80 \
  ghcr.io/huggingface/text-embeddings-inference:cpu-1.2 \
  --model-id sentence-transformers/all-MiniLM-L6-v2

docsearch-mcp ingest all \
  --embeddings-provider tei \
  --tei-endpoint http://localhost:8080/embeddings

統合の例

CI/CDパイプラインとの統合

# .github/workflows/docs-index.yml
name: Update Documentation Index
on:
  push:
    paths: ['docs/**', 'src/**/*.md', 'README.md']

jobs:
  update-index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - name: Install dependencies
        run: npm install -g pnpm && pnpm install
      - name: Build docsearch
        run: pnpm build
      - name: Update search index
        run: |
          pnpm start:cli ingest files \
            --file-roots "." \
            --openai-api-key "${{ secrets.OPENAI_API_KEY }}" \
            --db-path "./search-index.db"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

スクリプトとの統合

#!/bin/bash
# update-docs.sh - Automated documentation indexing

# Check if API key is set
if [ -z "$OPENAI_API_KEY" ]; then
    echo "Please set OPENAI_API_KEY environment variable"
    exit 1
fi

# Index all project documentation
echo "Indexing project documentation..."
docsearch-mcp ingest files \
    --file-roots "./src,./docs,./examples" \
    --file-include-globs "**/*.{ts,js,md,yaml,json}" \
    --db-path "./project-index.db"

# Generate search summary
echo "Search index updated. Statistics:"
docsearch-mcp ingest-status --output json | jq '.documents'

検索モード

• Auto（デフォルト）：キーワード検索とセマンティック検索のハイブリッド
• Keyword：全文検索のみ
• Vector：セマンティック検索のみ

Makeコマンド

利用可能なコマンドをすべて確認するには、make helpを実行します。

# Development Commands
make install                    # Install dependencies
make dev                        # Start development server for MCP
make dev-ingest                 # Start development ingestion
make setup                      # Setup project for development

# Build Commands
make build                      # Build the project
make clean                      # Clean all generated files

# Quality Assurance
make lint                       # Run linter
make lint-fix                   # Run linter with auto-fix
make format                     # Format code with Prettier
make typecheck                  # Run TypeScript type checking
make test                       # Run tests
make test-run                   # Run tests once
make test-unit                  # Run unit tests only
make test-integration           # Run integration tests (requires Docker)
make check-all                  # Run all quality checks

# Production Commands
make start                      # Start production MCP server
make start-ingest               # Start production ingestion

# Data Management
make ingest-files               # Ingest local files
make ingest-confluence          # Ingest Confluence pages
make watch                      # Watch for file changes and re-index
make clean-data                 # Clean data directory

NPMスクリプト（代替手段）

# CLI Tool
pnpm dev:cli                    # CLI development mode
pnpm start:cli                  # CLI production mode (after build)

# Ingestion (legacy scripts)
pnpm dev:ingest files           # Index local files
pnpm dev:ingest confluence      # Index Confluence pages
pnpm dev:ingest watch           # Watch for file changes

# MCP Server
pnpm dev:mcp                    # Development server
pnpm start:mcp                  # Production server

# Quality
pnpm lint                       # Run linter
pnpm test                       # Run tests
pnpm test:unit                  # Run unit tests only
pnpm test:integration           # Run integration tests (requires Docker)
pnpm build                      # Build project

🏗️ アーキテクチャ

このシステムは、クリーンなポートとアダプター（ヘキサゴナル）アーキテクチャを採用しています。

┌─────────────────┐    ┌─────────────────┐
│   Local Files   │    │   Confluence    │
└─────────┬───────┘    └─────────┬───────┘
          │                      │
          ▼                      ▼
    ┌─────────────────────────────────┐
    │        Ingestion Engine         │
    │   • Content extraction         │
    │   • Smart chunking             │
    │   • Embedding generation       │
    └─────────────┬───────────────────┘
                  │
                  ▼
    ┌─────────────────────────────────┐
    │      Database Layer             │
    │   SQLite (sqlite-vec) OR        │
    │   PostgreSQL (pgvector) OR      │
    │   PostgreSQL (VectorChord)      │
    │   • Document metadata          │
    │   • Text chunks                │
    │   • Vector embeddings          │
    │   • Full-text search index     │
    └─────────────┬───────────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
┌─────────────────┐  ┌─────────────────┐
│   CLI Tool      │  │   MCP Server    │
│ • Text output   │  │ • Tool calls    │
│ • JSON output   │  │ • Resources     │
│ • YAML output   │  │ • Claude integration │
│ • Config mgmt   │  │ • Ingestion tools     │
└─────────────────┘  └─────────────────┘

主なコンポーネント

• ドメイン層：中核となるインターフェースとビジネスロジック
• アダプター：設定、データベース、出力形式の処理
• CLI：複数の出力形式に対応したコマンドラインインターフェース
• MCP サーバー：Claude CodeとのModel Context Protocol統合

🤝 コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

開発ワークフロー

1. プロジェクトをフォークします

2. フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）

3. 開発環境をセットアップします。

   make setup
   

4. 変更を加え、品質を確認します。

   make check-all          # Run linter, typecheck, and tests
   make format             # Format your code
   

5. 変更をコミットします（git commit -m 'Add some AmazingFeature'）

6. ブランチにプッシュします（git push origin feature/AmazingFeature）

7. プルリクエストを作成します

🚀 デプロイ（VM上のPostgres / VectorChord）

SQLiteはローカル開発でのデフォルトであり、追加のインフラストラクチャは不要です。本番VMでPostgresまたはVectorChordを実行する場合は、deploy/ansible/のAnsibleプレイブックを使用してください。

次の処理を行います。

• Dockerのインストール
• TLS（テスト環境では自己署名証明書、本番環境ではLet's Encrypt）
• CIDRを設定可能なUFWファイアウォール
• ansible-vaultによる認証情報の管理
• 夜間のpg_dumpバックアップと、オプションでのS3へのアップロード
• デプロイ後にデータベースへ接続できることを確認するMoleculeテスト

運用手順の詳細については、**deploy/ansible/README.md**を参照してください。

📝 ライセンス

このプロジェクトはApache License Version 2の下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• 統合標準を提供するModel Context Protocol
• ベクトル検索機能を提供するsqlite-vec
• 高性能なPostgreSQLベクトル検索を提供するVectorChord
• AIを活用した開発体験を提供するClaude Code