Docdex

🚀 Docdex

Docdexは、軽量なローカルドキュメンテーションインデクサー兼検索デーモンです。プロジェクトごとに動作し、マークダウンやテキストドキュメントのディスク上のインデックスを維持し、HTTPまたはCLIを介して上位k件のスニペットを提供します。外部サービスやアップロードは必要ありません。

🚀 クイックスタート

# インストール (npm)
npm i -g docdex
# または一度だけ使用
npx docdex --version

# リポジトリ/ワークスペースの完全インデックス
docdexd index --repo /path/to/repo

# ライブファイル監視を伴うHTTP APIの起動 (セキュアモードでは認証トークンが必要)
docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --auth-token <token>
# ローカルでトークンなしで使用する場合は、--secure-mode=falseを追加
# docdexd serve --repo /path/to/repo --host 127.0.0.1 --port 46137 --log info --secure-mode=false

# CLIを介した即時検索 (JSON)
docdexd query --repo /path/to/repo --query "otp flow" --limit 5

✨ 主な機能

• リポジトリごとのローカルでのMarkdown/テキストファイルのインデックス作成（tantivyベース；ネットワーク呼び出しなし）。
• HTTP API (/search, /snippet, /healthz) とCLI (query, ingest, self-check) が同じインデックスを共有。
• サービス提供中のライブファイル監視によるインクリメンタルな更新。
• セキュリティ設定：TLS（手動証明書またはCertbot）、デフォルトで認証トークンが必要（--secure-mode=falseで無効化）、デフォルトでループバックのみ許可リスト、デフォルトのレート制限、リクエストサイズ制限、厳格な状態ディレクトリのパーミッション、監査ログ、chroot/特権剥奪/ネットワーク共有解除（Unix）。
• コーディングアシスタントに適した出力：要約、スニペット、およびドキュメントメタデータ。
• AI対応：GET /ai-help はエージェント用のJSONプレイブック（エンドポイント、CLIコマンド、制限、ベストプラクティス）を返します。

📦 インストール

npmを通じたインストール

• Node.js >= 18が必要です。
• インストール: npm i -g docdex（または npx docdex --version を実行して確認）。
• コマンド: docdex（別名 docdexd）は、GitHubリリースから適切なバイナリをダウンロードします。
• サポート対象: macOS (arm64, x64)、Linux glibc (arm64, x64)、Linux musl (arm64, x64)、Windows (x64, arm64)；インストーラは適切なプラットフォームのリリースアセットを取得します。
• フォークから公開する場合、インストール前に DOCDEX_DOWNLOAD_REPO=<owner/repo> を設定すると、ダウンローダはあなたのリリースアセットを取得します。
• 配布: バイナリはGitHub Releasesに保存されます（小さなnpmパッケージ）；インストール後に docdexd-<platform>.tar.gz をnpmバージョンに合わせて取得します。
• 公開にはnpm Trusted Publishing (OIDC) を使用します — NPMトークンは不要です；.github/workflows/release.yml を参照してください。

📚 ドキュメント

何をするのか

• リポジトリ内のMarkdown/テキストドキュメントをインデックス化し、ローカルに保存します（デフォルトでは <repo>/.docdex/index の下にtantivyベースのインデックスがあります）。
• 同じインデックスをHTTP (/search, /snippet, /healthz) およびCLI (query, ingest, self-check) を介して提供するため、自動化と対話的な使用で同じデータセットを共有できます。
• サービス提供中にファイルを監視し、変更をインクリメンタルに取り込みます。
• 強化されたデフォルト設定：ループバックバインディング、非ループバックでのTLS強制、デフォルトで認証トークンが必要（--secure-mode=falseで無効化）、セキュアモードではループバックのみ許可リストとデフォルトのレート制限（60 req/min）、監査ログが有効、および厳格な状態ディレクトリのパーミッション。

どのように動作するのか

1. docdexd index はリポジトリのディスク上のインデックスを構築します（存在する場合はレガシーの .gpt-creator/docdex/index を再利用します）。
2. docdexd serve はそのインデックスを読み込み、インクリメンタルな更新のためのファイルウォッチャーを起動し、HTTP APIを公開します。
3. HTTPクライアントまたはCLI (docdexd query) は同じインデックスから読み取ります；ingest は完全な再インデックス化なしで単一のファイルを更新できます。
4. オプションのTLS/認証/レート制限設定により、リモートアクセスをセキュアにします；監査ログによりアクセスアクションを記録できます。

使い方のチートシート

• インデックスの構築: docdexd index --repo <path>（--exclude-* を追加してパスをスキップ）。
• ウォッチャー付きでサービスを起動: docdexd serve --repo <path> --host 127.0.0.1 --port 46137 --log warn --auth-token <token>（セキュアモードではデフォルトでループバックのみ許可リストとレート制限が適用されます；リモートで使用する場合は --allow-ip/--secure-mode=false/--rate-limit-per-min を必要に応じて追加）。
• セキュアなサービスの提供: --auth-token <token> を追加（デフォルトで必要）；--tls-cert/--tls-key または --certbot-domain <domain> でTLSを使用。
• 単一ファイルの取り込み: docdexd ingest --repo <path> --file docs/new.md（除外設定を尊重）。
• CLIを介したクエリ: docdexd query --repo <path> --query "term" --limit 4。
• Gitのクリーンアップ: .docdex/（特に .docdex/index/）をリポジトリの .gitignore に追加して、インデックスアーティファクトがコミットされないようにします。
• ヘルスチェック: curl http://127.0.0.1:46137/healthz。
• 要約のみの検索レスポンス: curl "http://127.0.0.1:46137/search?q=foo&snippets=false"；上位のヒットに対してのみスニペットを取得します。
• トークン予算: curl "http://127.0.0.1:46137/search?q=foo&max_tokens=800" で、あなたのプロンプト予算を超えるヒットを除外します；snippets=false と組み合わせてから、保持する1 - 2個のスニペットを取得します。
• テキストのみのスニペット: /snippet/:doc_id に text_only=true を追加するか、serve を --strip-snippet-html で起動します（または --disable-snippet-text でメタデータのみを返す）。
• リクエストをコンパクトに保つ: デフォルトで max_query_bytes=4096 および max_request_bytes=16384 が適用されます；クエリを短く保ち、--max-limit を低く保つ（デフォルト8）ことで、過大なレスポンスを避けます。
• プロンプトのクリーンアップ: エージェントのプロンプトでは、空白を正規化し、rel_path、summary、およびトリミングされた snippet のみを含めます（score/token_estimate/doc_id を省略）。
• ノイズを早期に削除する: --exclude-dir および --exclude-prefix を使用して、ベンダー/ビルド/キャッシュ/シークレットをインデックスから除外し、スニペットを関連性の高いものに保ちます。
• エージェントのための静かなログ記録: レスポンスを他の場所でマーシャリングする場合は、docdexd serve --log warn --access-log=false を実行してログのオーバーヘッドを削減します。
• クライアント側でのヒットのキャッシュ: doc_id ↔ rel_path ↔ summary を保存して、繰り返しのスニペット呼び出しを避けます；新しいdoc_idに対してのみスニペットを取得します。
• エージェントのヘルプ: curl http://127.0.0.1:46137/ai-help（設定されている場合は認証が必要；--auth-token を設定した場合は Authorization: Bearer <token> を含める）。レスポンスには短いMCP登録レシピが含まれています。

バージョニング

• タグ付きリリース (vX.Y.Z) によるセマンティックバージョニング。Rustクレートとnpmパッケージは同じバージョンを共有します。
• コンベンショナルコミットにより、Release Pleaseを介してリリースノートが生成されます；これにより、Cargo.toml と npm/package.json を更新し、チャンジログを更新し、マージ時にタグ/リリースを作成するリリースPRが開かれます。
• 統合する際はリリースされたバージョンを指定する（例：スクリプトやDockerfileで）ことで、アップグレードが明示的かつ可逆的になります。
• ソースからビルドする場合、バージョンはこのリポジトリの Cargo.toml から取得されます；npmラッパーは一致するバージョンを使用してバイナリを取得します。

パスとデフォルト値

• 状態/インデックスディレクトリ: <repo>/.docdex/index（存在しないがレガシーの <repo>/.gpt-creator/docdex/index が存在する場合、Docdexはそれを再利用し、警告を表示します）。ディレクトリはデフォルトで 0700 のパーミッションで作成されます。
• HTTP API: サービス起動時のデフォルトは 127.0.0.1:46137 です。
• Docdexのデータとログはリポジトリ内に留まり、外部サービスは使用しません。

設定オプション

• --repo <path>: インデックス化するワークスペースのルート（デフォルトは .）。
• --state-dir <path> / DOCDEX_STATE_DIR: インデックスの保存パスを上書き（相対パスは repo の下で解決されます）。
• --exclude-prefix a,b,c / DOCDEX_EXCLUDE_PREFIXES: スキップする追加の相対プレフィックス。
• --exclude-dir a,b,c / DOCDEX_EXCLUDE_DIRS: ツリー内のどこでもスキップする追加のディレクトリ名。
• --auth-token <token> / DOCDEX_AUTH_TOKEN: セキュアモードで必要なベアラートークン（デフォルト）；--secure-mode=false で起動する場合のみ省略可能。
• --secure-mode <true|false> / DOCDEX_SECURE_MODE: デフォルトは true；有効にすると、認証トークンが必要で、デフォルトでループバックのみ許可リスト、およびデフォルトのレート制限（60 req/min）が適用されます。
• --allow-ip a,b,c / DOCDEX_ALLOW_IPS: HTTP APIにアクセスできるオプションのカンマ区切りのIP/CIDR（デフォルト: セキュアモードではループバックのみ；セキュアモードが無効な場合はすべて許可）。
• --tls-cert / DOCDEX_TLS_CERT および --tls-key / DOCDEX_TLS_KEY: 提供された証明書/キーでHTTPSを提供します。TLSが強制されている場合、非ループバックのバインディングは明示的にオプトアウトしない限りHTTPSを使用する必要があります。
• --certbot-domain <domain> / DOCDEX_CERTBOT_DOMAIN: TLSを /etc/letsencrypt/live/<domain>/{fullchain.pem,privkey.pem}（Certbot）に向けます。手動の --tls-* と競合します。
• --certbot-live-dir <path> / DOCDEX_CERTBOT_LIVE_DIR: fullchain.pem と privkey.pem を含む特定のCertbotライブディレクトリを使用します。
• --require-tls <true|false> / DOCDEX_REQUIRE_TLS: デフォルトは true。非ループバックのバインディングでTLSを強制します；信頼できるプロキシでTLSがすでに終了している場合は false に設定します。
• --insecure / DOCDEX_INSECURE_HTTP=true: TLSが強制されている場合でも、非ループバックのバインディングでプレーンHTTPを許可します（信頼できるプロキシの背後でのみ使用）。
• --max-limit <n> / DOCDEX_MAX_LIMIT: HTTPの limit を最大 n に制限します（デフォルト: 8）。
• --max-query-bytes <n> / DOCDEX_MAX_QUERY_BYTES: クエリ文字列が n バイトを超えるリクエストを拒否します（デフォルト: 4096）。
• --max-request-bytes <n> / DOCDEX_MAX_REQUEST_BYTES: Content-Lengthまたはサイズヒントが n バイトを超えるリクエストを拒否します（デフォルト: 16384）。
• --rate-limit-per-min <n> / DOCDEX_RATE_LIMIT_PER_MIN: 1分あたりのIPごとのリクエスト予算（セキュアモードで未設定/0の場合のデフォルトは60；セキュアモードがオフの場合、0で無効化）。
• --rate-limit-burst <n> / DOCDEX_RATE_LIMIT_BURST: レート制限器のオプションのバースト容量（0の場合は1分あたりの制限がデフォルト）。
• --audit-log-path <path> / DOCDEX_AUDIT_LOG_PATH: 監査ログのJSONLをこのパスに書き込みます（デフォルト: <state-dir>/audit.log）。
• --audit-max-bytes <n> / DOCDEX_AUDIT_MAX_BYTES: このバイト数を超えたら監査ログをローテートします（デフォルト: 5_000_000）。
• --audit-max-files <n> / DOCDEX_AUDIT_MAX_FILES: ローテートされた監査ファイルを最大でこの数だけ保持します（デフォルト: 5）。
• --audit-disable / DOCDEX_AUDIT_DISABLE=true: 監査ログを完全に無効にします。
• --strip-snippet-html / DOCDEX_STRIP_SNIPPET_HTML=true: レスポンスから snippet.html を省略して、テキストのみのスニペットを強制します（HTMLは存在する場合はデフォルトでサニタイズされます）。
• --disable-snippet-text / DOCDEX_DISABLE_SNIPPET_TEXT=true: レスポンスからスニペットのテキスト/HTMLを完全に省略します（ドキュメントメタデータのみが返されます）。
• --access-log <true|false> / DOCDEX_ACCESS_LOG: クエリ値がレダクトされた最小限の構造化アクセスログを出力します（デフォルト: true）。
• --run-as-uid / DOCDEX_RUN_AS_UID, --run-as-gid / DOCDEX_RUN_AS_GID: （Unix）起動準備後に特権を指定されたUID/GIDに剥奪します。
• --chroot <path> / DOCDEX_CHROOT: （Unix）サービスを開始する前に path にchrootします；リポジトリ/状態パスはそのジェイル内に存在する必要があります。
• --unshare-net / DOCDEX_UNSHARE_NET=true: （Linuxのみ）サービスを開始する前にネットワーク名前空間を共有解除します（CAP_SYS_ADMIN/rootが必要）；他のプラットフォームでは無効。
• ログ記録: serve で --log <level>（デフォルトは info）、または RUST_LOG=docdexd=debug スタイルのフィルター。
• セキュアモードのデフォルト: --secure-mode=true（デフォルト）の場合、docdexは認証トークンを必要とし、上書きされない限りループバックIPのみを許可し、60 req/minのレート制限を適用します。ローカル開発でオプトアウトするには --secure-mode=false を設定し、必要に応じて --allow-ip/レート制限を調整します。

インデックス化ルール (詳細は index/mod.rs を参照)

• ファイルタイプ: .md, .markdown, .mdx, .txt（DEFAULT_EXTENSIONS を拡張してさらに追加）。
• スキップされるディレクトリ: エコシステム全体の幅広いVCS/ビルド/キャッシュ/ベンダーフォルダ（例：.git, .hg, .svn, node_modules, .pnpm-store, .yarn*, .nx, .rollup-cache, .webpack-cache, .tsbuildinfo, .next, .nuxt, .svelte-kit, .mypy_cache, .ruff_cache, .venv, target, go-build, .gradle, .mvn, pods, .dart_tool, .android, .serverless, .vercel, .netlify, _build, _opam, .stack-work, elm-stuff, library, intermediate, .godot など；完全なリストは DEFAULT_EXCLUDED_DIR_NAMES を参照）。
• スキップされる相対プレフィックス: logs/, .docdex/, .docdex/logs/, .docdex/tmp/, .gpt-creator/logs/, .gpt-creator/tmp/, .mastercoda/logs/, .mastercoda/tmp/, docker/.data/, docker-data/, .docker/。
• スニペットのサイズ: 要約は約360文字（最大4セグメント）；スニペットは約420文字。

HTTP API

• GET /healthz — ok を返します；このエンドポイントは認証不要で、レート制限されません（IP許可リストは依然として適用されます）。
• GET /search?q=<text>&limit=<n>&snippets=<bool>&max_tokens=<u64> — ドキュメントID、相対パス、要約、スニペット、スコア、トークン推定値を含む { hits: [...] } を返します。snippets=false を設定すると要約のみのレスポンスが返されます；max_tokens を設定すると、あなたの予算を超えるヒットを除外します。
• GET /snippet/:doc_id?window=<lines>&q=<query>&text_only=<bool>&max_tokens=<u64> — オプションのハイライト付きスニペットを含む { doc, snippet } を返します；クエリのハイライトが空の場合はプレビューにフォールバックします（デフォルトのウィンドウ: 40行）。text_only=true を設定するとHTMLを除外してペイロードを縮小します；max_tokens を設定すると、ドキュメントがあなたの予算を超える場合はスニペットを省略します。
• GET /ai-help — エージェント用のJSONプレイブック（エンドポイント、CLIコマンド、制限、ベストプラクティス）を返します。
• GET /metrics — レート制限/認証/エラーメトリクスのPrometheusスタイルのカウンターを返します。
• --auth-token が設定されている場合、HTTP呼び出し（/ai-help を含む）には Authorization: Bearer <token> を含めてください。

CLIコマンド

• serve --repo <path> [--host 127.0.0.1] [--port 46137] [--log info] — ライブファイル監視によるインクリメンタルな更新を伴うHTTP APIを起動します。
• index --repo <path> — インデックス全体を再構築します。
• ingest --repo <path> --file <file> — 単一のファイルを再インデックス化します。
• query --repo <path> --query "<text>" [--limit 8] — 検索を実行し、JSON形式のヒットを出力します。
• self-check --repo <path> --terms "foo,bar" [--limit 5] — アクセスを有効にする前にインデックスを機密キーワードでスキャンします（見つかった場合は非ゼロの終了コードで失敗します；サンプルヒットとさらに存在するかどうかを報告します）。デフォルトでは組み込みのトークン/パスワードパターンが含まれています；提供されたキーワードのみを使用する場合は --include-default-patterns=false で無効化します。

ヘルプとコマンドの探索

• すべてのコマンド/フラグを表示: docdexd --help。
• すべてのサブコマンドのヘルプを表示: docdexd help-all。
• serve オプション（TLS、認証、レート制限、ウォッチャー）を表示: docdexd serve --help。
• インデックス化オプションを表示: docdexd index --help（除外パス、カスタム状態ディレクトリ）。
• 即時クエリを表示: docdexd query --help。
• 自己チェックスキャナーのオプションを表示: docdexd self-check --help。
• エージェントのヘルプエンドポイント: curl http://127.0.0.1:46137/ai-help（--auth-token が設定されている場合は Authorization: Bearer <token> を含める）。レスポンスにはエンドポイント、制限、およびベストプラクティスのJSONリストが含まれています。
• MCPのヘルプ/登録: docdexd mcp --help でMCPフラグを表示します；docdexd mcp --repo <repo> --log warn を使用してクライアントに登録します。Codexの設定例:

  {
    "mcpServers": {
      "docdex": {
        "command": "docdexd",
        "args": ["mcp", "--repo", ".", "--log", "warn", "--max-results", "8"],
        "env": {}
      }
    }
  }
  

• MCPのクイック追加コマンド（人気のエージェント）:
  • Docdexヘルパー: docdex mcp-add --repo /path/to/repo --log warn --max-results 8 でサポートされるエージェントを自動検出します；--all を追加すると、すべての既知のクライアントを試し、UIのみのクライアントについては手動手順を表示します、または --remove でアンインストールします。
  • Codex CLI: codex mcp add docdex -- docdexd mcp --repo /path/to/repo --log warn --max-results 8。
  • 汎用JSON設定（Cursor、Continue、Windsurf、Cline、Claude Desktop devtools）: 上記の mcpServers.docdex ブロックをMCP設定ファイルに追加します（パスはクライアントによって異なります；ほとんどのクライアントは表示されている command/args スキーマを受け入れます）。
  • 手動/stdioのみのクライアント: 自分で docdexd mcp --repo /path/to/repo --log warn --max-results 8 を起動し、クライアントをそのコマンド/バイナリに向けます。
• 公開されているツール（CallToolResultのコンテンツ: result.content[0].textにJSONが含まれています）:
  • docdex_search — 引数: { "query": "<text>", "limit": <int optional>, "project_root": "<path optional>" }。返り値: { "results": [...], "repo_root": "...", "state_dir": "...", "limit": <int>, "project_root": "...", "meta": {...} }。
  • docdex_index — 引数: { "paths": ["relative/or/absolute"], "project_root": "<path optional>" }。paths が空の場合はすべてを再インデックス化します；それ以外の場合は指定されたファイルを取り込みます。
  • docdex_files — 引数: { "limit": <int optional, default 200, max 1000>, "offset": <int optional, default 0>, "project_root": "<path optional>" }。返り値: { "results": [{ "doc_id", "rel_path", "summary", "token_estimate" }], "total", "limit", "offset", "repo_root", "project_root" }。
  • docdex_open — 引数: { "path": "<relative file>", "start_line": <int optional>, "end_line": <int optional>, "project_root": "<path optional>" }。返り値: { "path", "start_line", "end_line", "total_lines", "content", "repo_root", "project_root" }（リポジトリ外のパスや大きなファイルは拒否されます）。
  • docdex_stats — 引数: { "project_root": "<path optional>" }。返り値: { "num_docs", "state_dir", "index_size_bytes", "segments", "avg_bytes_per_doc", "generated_at_epoch_ms", "last_updated_epoch_ms", "repo_root", "project_root" }。
• 呼び出し例:
  • 初期化: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
  • ワークスペースルートを指定した初期化: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"workspace_root":"/path/to/repo"}}（サーバーのリポジトリと一致する必要があります；後続の呼び出しのデフォルトのproject_rootを設定します）
  • ツールの一覧を表示: {"jsonrpc":"2.0","id":2,"method":"tools/list"}
  • 再インデックス化: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docdex_index","arguments":{"paths":[]}}}
  • 検索: {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"docdex_search","arguments":{"query":"payment auth flow","limit":3,"project_root":"/repo"}}}
  • ファイルの一覧を表示: {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"docdex_files","arguments":{"limit":10,"offset":0}}}
  • ファイルを開く: {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"docdex_open","arguments":{"path":"docs/readme.md","start_line":1,"end_line":20}}}
  • 統計情報を表示: {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"docdex_stats","arguments":{}}}
• エラー: 無効なJSON → コード -32700；サポートされていない/欠落している jsonrpc → -32600；不明なツール/メソッド → -32601；無効なパラメータ（空のクエリ、不正な引数、project_rootの不一致） → -32602；内部エラーには error.data に reason 文字列が含まれています。
• エージェントのガイダンス: コーディング前に簡潔なクエリで docdex_search を呼び出します；数件のヒットのみを取得します；結果が古くなっているように見える場合は docdex_index を呼び出します；あなたのスタックがMCPに対応していない場合はHTTP/CLIを引き続き使用します。
• ヘルプ: docdexd mcp --help でMCPのフラグとデフォルト値を表示します；docdexd help-all にはツールと使用方法を列挙したMCPセクションが含まれています。

トラブルシューティング

• 古いインデックス: docdexd index --repo <path> を再実行します。
• ポートの競合: --host/--port を変更します。

セキュリティに関する考慮事項

• デフォルトのバインドは 127.0.0.1 です；信頼できるリバースプロキシ/ファイアウォールの背後にいない限り、このままにしておいてください。信頼できないネットワークで --host 0.0.0.0 を避けてください。
• デフォルトでは、非ループバックのバインディングにはTLSが必要です；信頼できるプロキシでトラフィックがすでに終了している場合は、--require-tls=false または --insecure でオプトアウトしてください。
• 外部に公開する場合は、リバースプロキシを前に配置し、TLSを終了し、認証（基本認証/OAuth/mTLS）とIP/VPN許可リストを要求します。例（nginx）:

  server {
    listen 443 ssl;
    server_name docdex.example.com;
    ssl_certificate /path/fullchain.pem;
    ssl_certificate_key /path/privkey.pem;
    auth_basic "Protected";
    auth_basic_user_file /etc/nginx/.htpasswd; # またはOAuth/mTLSをフックする
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    location / {
      proxy_pass http://127.0.0.1:46137;
      proxy_set_header Host $host;
    }
  }
  

• コーパスを絞り込む: 精選されたステージングディレクトリを使用するか、--exclude-dir / --exclude-prefix を使用してインデックス化前にシークレット/プライベートパスを除外します；ウォッチャーは repo 内のスコープ内のファイル変更を取り込みます。
• ログに注意する: スニペット/パスが機密情報である場合は、本番環境で詳細なログ記録を避けてください；リバースプロキシのアクセスログにもクエリ用語とパスが記録される可能性があります。
• 最小限の特権: docdexを低特権のユーザー/コンテナで実行し、状態ディレクトリを制限付きのパーミッションのパスに配置します。
• 公開前に検証する: docdexd query で機密キーワードを検索し、ヒットがないことを確認します；必要に応じてインデックスを暗号化されたディスクに保存します。
• オプションの強化: HTTP API（またはプロキシ）で認証トークンを要求します；ローカルホストでない場合はTLSを強制します（デフォルト）、または信頼できるプロキシの背後でのみ --require-tls=false/--insecure で明示的にオプトアウトします；レート制限（--rate-limit-per-min）を有効にし、limit/リクエストサイズ（--max-limit, --max-query-bytes, --max-request-bytes）を制限します；スニペットのHTMLを埋め込む場合はエスケープ/サニタイズするか、--disable-snippet-text でスニペットを完全に無効にします；状態ディレクトリはデフォルトで 0700 で作成されます — 特権のないユーザーの下に置き、必要に応じて --run-as-uid/--run-as-gid, --chroot, またはコンテナ化します；アクセスログを最小限/レダクトし（--access-log）、サービスを公開する前に機密用語の self-check を実行します；静止データの機密性のために、状態ディレクトリを暗号化されたストレージに配置するか、ホストレベルのディスク暗号化を使用します。

LLMツールとの統合

Docdexはツールに依存しません。エージェント/コード生成ツールのための簡単なレシピ:

• リポジトリごとに一度起動: docdexd index --repo <repo> 次に docdexd serve --repo <repo> --host 127.0.0.1 --port 46137 --log warn（またはサービスを起動せずに直接CLIを使用）。
• 環境変数で設定: DOCDEX_STATE_DIR（インデックスの場所）、DOCDEX_EXCLUDE_PREFIXES、DOCDEX_EXCLUDE_DIRS、RUST_LOG=docdexd=debug（オプションの詳細なログ）。
• HTTPを介したクエリ: GET /search?q=<text>&limit=<n> は {"hits":[{"doc_id","rel_path","score","summary","snippet","token_estimate"}...]} を返します；GET /snippet/:doc_id は焦点を絞ったスニペットとドキュメントメタデータを取得します。
• またはCLIを介したクエリ: docdexd query --repo <repo> --query "<text>" --limit 8（JSONを標準出力に出力）。
• ヘルスチェック: 検索リクエストを送信する前に GET /healthz が ok を返す必要があります。
• プロンプトにスニペットを挿入:

"You are building features for this repo. Use the following documentation snippets for context. If a snippet cites a path, keep that path in your response. Snippets:\n<insert docdex snippets here>\nQuestion: <your question>"

MCP (MCP対応クライアント用のオプションのstdioサーバー)

Docdexはstdioを介したMCPツールプロバイダーとして実行できます；これはHTTPデーモンを置き換えるものではなく、あなたのエージェント/エディタに適したものを選択してください。あなたのMCPクライアントがリソーステンプレートをサポートしている場合、Docdexは docdex_file テンプレート（docdex://{path}）を宣伝し、docdex_open に委任します。

• 実行: docdexd mcp --repo /path/to/repo --log warn --max-results 8（別名: --mcp-max-results 8）。
• 環境変数での上書き: DOCDEX_MCP_MAX_RESULTS で docdex_search の結果を制限します（最小1）。
• パッケージング: MCPサーバーはメインの docdexd バイナリに組み込まれています（npmバイナリから docdexd mcp または docdex mcp で呼び出されます）；別個の docdex-mcp のダウンロードは必要ありません。
• MCPクライアントへの登録: docdexd mcp --repo <repo> --log warn を実行する docdex という名前のサーバーを追加します。Codexの設定例:

  {
    "mcpServers": {
      "docdex": {
        "command": "docdexd",
        "args": ["mcp", "--repo", ".", "--log", "warn", "--max-results", "8"],
        "env": {}
      }
    }
  }
  

• MCPのクイック追加コマンド（人気のエージェント）:
  • Docdexヘルパー: docdex mcp-add --repo /path/to/repo --log warn --max-results 8 でサポートされるエージェントを自動検出します；--all を追加すると、すべての既知のクライアントを試し、UIのみのクライアントについては手動手順を表示します、または --remove でアンインストールします。
  • Codex CLI: codex mcp add docdex -- docdexd mcp --repo /path/to/repo --log warn --max-results 8。
  • 汎用JSON設定（Cursor、Continue、Windsurf、Cline、Claude Desktop devtools）: 上記の mcpServers.docdex ブロックをMCP設定ファイルに追加します（パスはクライアントによって異なります；ほとんどのクライアントは表示されている command/args スキーマを受け入れます）。
  • 手動/stdioのみのクライアント: 自分で docdexd mcp --repo /path/to/repo --log warn --max-results 8 を起動し、クライアントをそのコマンド/バイナリに向けます。
• 公開されているツール（CallToolResultのコンテンツ: result.content[0].textにJSONが含まれています）:
  • docdex_search — 引数: { "query": "<text>", "limit": <int optional>, "project_root": "<path optional>" }。返り値: { "results": [...], "repo_root": "...", "state_dir": "...", "limit": <int>, "project_root": "...", "meta": {...} }。
  • docdex_index — 引数: { "paths": ["relative/or/absolute"], "project_root": "<path optional>" }。paths が空の場合はすべてを再インデックス化します；それ以外の場合は指定されたファイルを取り込みます。
  • docdex_files — 引数: { "limit": <int optional, default 200, max 1000>, "offset": <int optional, default 0>, "project_root": "<path optional>" }。返り値: { "results": [{ "doc_id", "rel_path", "summary", "token_estimate" }], "total", "limit", "offset", "repo_root", "project_root" }。
  • docdex_open — 引数: { "path": "<relative file>", "start_line": <int optional>, "end_line": <int optional>, "project_root": "<path optional>" }。返り値: { "path", "start_line", "end_line", "total_lines", "content", "repo_root", "project_root" }（リポジトリ外のパスや大きなファイルは拒否されます）。
  • docdex_stats — 引数: { "project_root": "<path optional>" }。返り値: { "num_docs", "state_dir", "index_size_bytes", "segments", "avg_bytes_per_doc", "generated_at_epoch_ms", "last_updated_epoch_ms", "repo_root", "project_root" }。
• 呼び出し例:
  • 初期化: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
  • ワークスペースルートを指定した初期化: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"workspace_root":"/path/to/repo"}}（サーバーのリポジトリと一致する必要があります；後続の呼び出しのデフォルトのproject_rootを設定します）
  • ツールの一覧を表示: {"jsonrpc":"2.0","id":2,"method":"tools/list"}
  • 再インデックス化: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"docdex_index","arguments":{"paths":[]}}}
  • 検索: {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"docdex_search","arguments":{"query":"payment auth flow","limit":3,"project_root":"/repo"}}}
  • ファイルの一覧を表示: {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"docdex_files","arguments":{"limit":10,"offset":0}}}
  • ファイルを開く: {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"docdex_open","arguments":{"path":"docs/readme.md","start_line":1,"end_line":20}}}
  • 統計情報を表示: {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"docdex_stats","arguments":{}}}
• エラー: 無効なJSON → コード -32700；サポートされていない/欠落している jsonrpc → -32600；不明なツール/メソッド → -32601；無効なパラメータ（空のクエリ、不正な引数、project_rootの不一致） → -32602；内部エラーには error.data に reason 文字列が含まれています。
• エージェントのガイダンス: コーディング前に簡潔なクエリで docdex_search を呼び出します；数件のヒットのみを取得します；結果が古くなっているように見える場合は docdex_index を呼び出します；あなたのスタックがMCPに対応していない場合はHTTP/CLIを引き続き使用します。
• ヘルプ: docdexd mcp --help でMCPのフラグとデフォルト値を表示します；docdexd help-all にはツールと使用方法を列挙したMCPセクションが含まれています。

HTTPSとCertbot

• TLSはPKCS8、PKCS1/RSA、およびSEC1/ECの秘密鍵を受け入れます（Certbotの出力と互換性があります）。
• 手動の証明書/キー: docdexd serve --repo <repo> --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem。
• Certbotヘルパー: docdexd serve --repo <repo> --host 0.0.0.0 --port 46137 --certbot-domain docs.example.com（/etc/letsencrypt/live/docs.example.com/{fullchain.pem,privkey.pem} を使用）、または --certbot-live-dir /custom/live/dir を渡します。
• Certbotを使用する場合、更新後にdocdexを再起動/リロードするデプロイフックを設定してください（例：certbot renew --deploy-hook "systemctl restart docdexd.service" またはプロセス監視ツールに -HUP シグナルを送信）。
• 直接443にバインドする場合は特権が必要です；それ以外の場合はdocdexを127.0.0.1に維持し、リバースプロキシでTLSを終了させます。