@search-docs/mcp-server

Claude Codeから直接search-docsを利用するためのMCP Serverです。

概要

このMCP Serverは、Claude Codeとsearch-docsサーバを接続し、会話から直接ドキュメント検索を実行できるようにします。

提供機能

動的ツール登録

MCP Serverはシステム状態に応じて利用可能なツールを動的に変更します。

システム状態とツールの対応:

| 状態 | init | get_system_status | search | get_document | get_outline | index_status | add_related_project | list_related_projects | |------|------|-------------------|--------|--------------|-------------|--------------|---------------------|----------------------| | NOT_CONFIGURED（未設定） | ✓ | ✓ | - | - | - | - | - | - | | CONFIGURED_SERVER_DOWN（設定済み、サーバ停止） | ✓ | ✓ | ✓* | ✓* | ✓* | ✓* | ✓ | ✓ | | RUNNING（稼働中） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

*: サーバ停止時も自動起動するため利用可能

注意:

• init実行後、全てのツールが利用可能になります
• ただし、Claude Codeは現在MCP通知に未対応のため、ツールリスト更新には再接続が必要です
• CONFIGURED_SERVER_DOWN時は、ツール呼び出しで自動的にサーバが起動されます（server_start/server_stopツールは廃止）

ツール一覧

1. init

設定ファイルを初期化します。

利用可能条件: 常時

パラメータ:

• port (number, オプション): サーバポート番号（省略時はランダムなポート番号が割り当てられます）
• force (boolean, オプション): 既存設定を上書き（デフォルト: false）

2. get_system_status

システムの状態を取得します。設定ファイルの有無、サーバの起動状態、インデックス情報を確認できます。

利用可能条件: 常時

パラメータ: なし

3. search

文書を検索します。クエリに基づいてVector検索を実行し、関連する文書セクションを返します。

利用可能条件: サーバ稼働中（RUNNING）

パラメータ:

• query (string, 必須): 検索クエリ
• project (string, オプション): 検索対象のプロジェクト名。未指定の場合はメインプロジェクトを検索します
• depth (number, オプション): 最大深度（0-3）。0=文書全体のみ、1=章まで、2=節まで、3=項まで。省略時は全階層を検索
• limit (number, オプション): 結果数制限（デフォルト: 10）
• includeCleanOnly (boolean, オプション): 最新の文書内容のみを検索対象とする（デフォルト: false）
• includePaths (array of string, オプション): 包含するドキュメントパス（前方一致）。例: ["docs/", "README.md"]
• excludePaths (array of string, オプション): 除外するドキュメントパス（前方一致）。例: ["docs/internal/", "temp/"]
• previewLines (number, オプション): プレビュー行数（デフォルト: 5）

4. get_document

文書の内容を取得します。パス指定で文書全体、またはセクションIDで特定セクションを取得できます。

利用可能条件: サーバ稼働中（RUNNING）

パラメータ:

• path (string, オプション): 文書パス（sectionIdを指定しない場合は必須）
• sectionId (string, オプション): セクションID（検索結果から取得、pathを指定しない場合は必須）
• project (string, オプション): 取得対象のプロジェクト名

注意: pathとsectionIdのどちらか一方は必須です。

5. get_outline

文書の構造（アウトライン）を取得します。セクション番号、見出し、行数、トークン数、セクションIDを一覧表示します。

利用可能条件: サーバ稼働中（RUNNING）

パラメータ:

• path (string, オプション): 文書パス（sectionIdを指定しない場合は必須）
• sectionId (string, オプション): セクションID（指定した場合、そのセクション配下のみ表示）
• project (string, オプション): 取得対象のプロジェクト名

注意: pathとsectionIdのどちらか一方は必須です。

6. index_status

インデックスの状態を確認します。総文書数、セクション数、Dirtyセクション数などを表示します。

利用可能条件: サーバ稼働中（RUNNING）

パラメータ: なし

7. add_related_project

関連プロジェクトを追加します。複数プロジェクト横断検索を可能にします。

利用可能条件: 設定済み（CONFIGURED_SERVER_DOWN または RUNNING）

パラメータ:

• name (string, 必須): プロジェクト名
• path (string, 必須): プロジェクトのパス

8. list_related_projects

登録済み関連プロジェクトの一覧を取得します。

利用可能条件: 設定済み（CONFIGURED_SERVER_DOWN または RUNNING）

パラメータ: なし

セットアップ

Docker版（推奨）

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

docker mcp run 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

npx版のセットアップ手順

サーバ自動起動機能

MCP Serverは必要に応じて自動的にsearch-docsサーバを起動します。

動作:

1. CONFIGURED_SERVER_DOWN状態で検索ツール（search, get_document等）を呼び出す
2. 自動的にサーバを起動
3. サーバが起動したら接続を確立し、リクエストを処理

これにより、手動でサーバを起動する必要がなくなりました。server_start/server_stopツールは廃止されました。

前提条件

ビルド済みであること

pnpm build

Claude Code統合

Claude Codeの設定ファイル（claude_desktop_config.jsonまたはcline_mcp_settings.json）に以下を追加：

{
  "mcpServers": {
    "search-docs": {
      "command": "node",
      "args": [
        "/absolute/path/to/search-docs/packages/mcp-server/dist/server.js",
        "--project-dir",
        "${workspaceFolder}"
      ]
    }
  }
}

注意: /absolute/path/to/search-docs/ は実際のパスに置き換えてください。

開発

ビルド

pnpm build

開発モード（watch）

pnpm dev

テスト起動

node dist/server.js --project-dir /path/to/your/project

トラブルシューティング

サーバに接続できない

エラー: Failed to connect to search-docs server

通常は不要: MCP Serverはサーバを自動起動します。

手動で確認する場合:

1. サーバが起動しているか確認

   node packages/cli/dist/index.js server status

2. 必要に応じてサーバを起動

   node packages/cli/dist/index.js server start

設定ファイルが見つからない

MCP Serverはプロジェクトディレクトリの .search-docs.json を読み込みます。

ファイルが存在しない場合はデフォルト設定（localhost:24280）を使用します。

関連パッケージ

• @search-docs/client: JSON-RPCクライアント
• @search-docs/server: 検索サーバ
• @search-docs/cli: CLIツール