MCP 服务器

search-docs

Enables AI agents to search local Markdown documents using natural language, with automatic indexing and section-level retrieval.

README

🐕️ 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で：

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

→ 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で：

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

→ 詳しい手順

その他の使い方

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): プログラマティックな利用