🐕️ search-docs

ローカル文書をAIエージェントが検索できるようにする

プロジェクトのドキュメント、設計書、調査メモ。大量の文書から必要な情報を見つけるのは大変です。

search-docsは、Markdown文書をVector検索可能にし、Claude CodeなどのAIエージェントが自然言語で検索できるようにします。

コンセプト

• ローカルファースト: すべてのデータはローカルに保存、プライバシー重視
• エージェント統合: Claude Codeから自然言語で検索
• 自動更新: ファイル変更を自動検知、常に最新の情報を検索可能
• セクション分割: 文書全体だけでなく、関連する章節を精度高く発見

仕組み

search-docsは、シンプルな3層構造で動作します：

Markdown文書
    ↓ (見出しで分割)
Sections (depth 0-3)
    ↓ (Vector化)
LanceDB Index
    ↓ (自然言語で検索)
AIエージェント / CLI / API

Document: プロジェクトの.mdファイル Section: 見出しごとに分割された意味のある単位 Vector Index: 日本語最適化モデル（Ruri）でVector化 Server: プロジェクトごとに起動、変更を自動検知

詳細: システムアーキテクチャ

30秒で始める（Claude Code）

Docker版（推奨）

ランタイム依存（Node.js, Python, uv）を排除し、セキュアな境界で実行できます。

.claude/settings.json または .mcp.json に以下を追加:

{
  "mcpServers": {
    "search-docs": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", ".:/workspace:ro",
        "-v", "./.search-docs:/workspace/.search-docs",
        "otolab/search-docs-mcp:latest",
        "--project-dir", "/workspace"
      ]
    }
  }
}

ボリュームマウント:

• .:/workspace:ro — プロジェクトのドキュメントを読み取り専用でマウント
• ./.search-docs:/workspace/.search-docs — インデックスデータの永続化（読み書き）

その後、Claude Codeで：

1. 「search-docsのセットアップをお願い」と依頼
2. MCPを再接続（reconnect）
3. 「このプロジェクトのアーキテクチャについて教えて」と依頼

→ Docker構成ガイド

npm/npx版（Docker環境がない場合）

Docker環境がない場合の代替手段です。uv（Pythonパッケージマネージャ）が必要です。

# macOS (Homebrew)
brew install uv

# macOS/Linux (公式インストーラ)
curl -LsSf https://astral.sh/uv/install.sh | sh

claude mcp add npx -- -y @search-docs/mcp-server

その後、Claude Codeで：

1. 「search-docsのセットアップをお願い」と依頼
2. MCPを再接続（reconnect）
3. 「このプロジェクトのアーキテクチャについて教えて」と依頼

→ 詳しい手順

その他の使い方

CLIツールとして使う

# グローバルインストール
npm install -g @search-docs/cli

# またはnpxで直接実行（インストール不要）
npx @search-docs/cli server start
npx @search-docs/cli search "検索クエリ"

→ ユーザーガイド

プログラムから使う

TypeScript/JavaScript APIとしても利用できます。

import { SearchClient } from '@search-docs/client';

const client = new SearchClient({ port: 24280 });
const results = await client.search('検索クエリ');

→ クライアントライブラリ

主な特徴

セクション分割検索

文書全体だけでなく、H1〜H4の見出し単位で検索。関連する章節をピンポイントで発見できます。

リアルタイム更新

ファイル変更を自動検知、バックグラウンドで再インデックス。常に最新の情報を検索できます。

プロジェクト独立

プロジェクトごとに独立したサーバとインデックス。複数プロジェクトを同時に使用できます。

日本語最適化

日本語に最適化された埋め込みモデル（Ruri）を使用。日本語文書の検索精度が高くなっています。

アーキテクチャ概要

search-docsはin-process構成（MCPサーバ） と クライアント・サーバ構成（HTTPサーバ） の2つのモードで動作します：

MCPサーバモード（Claude Code統合）

• MCP Server (@search-docs/mcp-server): SearchDocsServerをin-processで直接保持
  • HTTPデーモン不要、高速起動
  • SearchDocsServer（read-only）
  • WatcherProcess（write、heartbeat調停）
  • DBEngine（Python/LanceDB/Ruri）
  • EmbeddingServerProcess（自動検出・起動）

HTTPサーバモード（外部クライアント向け）

• Server (@search-docs/server): server start コマンドで起動
  • JSON-RPC API提供
  • CLI Tool、Client Libraryから利用
• CLI Tool (@search-docs/cli): コマンドライン
• Client Library (@search-docs/client): プログラマティックな利用

共通インターフェイス

• SearchDocsService: MCPサーバとHTTPクライアントの共通インターフェイス
  • SearchDocsServer（in-process実装）
  • SearchDocsClient（HTTP実装）

詳細: システムアーキテクチャ | データモデル

ドキュメント

📚 使い始める

• クイックスタート - 5分で体験
• ユーザーガイド - 本格的に使う
• CLIリファレンス - 全コマンドの詳細

🔧 詳しく知る

• システムアーキテクチャ - 技術スタックと実装
• データモデル - データ構造の設計
• アーキテクチャ決定記録 - 設計判断の記録

🤝 統合する

• Claude Code統合 - MCP Serverとして使う
• クライアントライブラリ - APIリファレンス

→ 全ドキュメント一覧

ライセンス

このプロジェクトはプライベートプロジェクトです。

関連プロジェクト

• sebas-chan: DBエンジンのアーキテクチャ参照元