search-docs: Instructions file for Codex

🐕️ search-docs - Claude Code用プロジェクトガイド

プロジェクト概要

search-docsは、ローカル文書のVector検索システムです。プロジェクト毎に起動される検索サーバと、複数のクライアント形式で構成されています。

アーキテクチャ

プロセス構成

MCP Server (stdio)
  ├─ in-process: SearchDocsServer (read-only)
  ├─ in-process: WatcherProcess (write, heartbeat調停)
  ├─ in-process: DBEngine
  └─ subprocess: Embedding Server (stateless, 共有可能)
           │
           ▼
       LanceDB (共有ストレージ)

詳細: docs/client-server-architecture.md

アーキテクチャ構成

search-docsは以下の構成で動作します：

1. MCP Server (packages/mcp-server/)

   • Claude Code統合、stdio通信
   • SearchDocsServerをin-processで直接保持（HTTPデーモン不要）
   • SearchDocsServiceインターフェイス経由でサーバ機能を利用

2. JSON-RPC Server (packages/server/src/bin/server.ts)

   • search-docs server start コマンドでHTTPサーバとしてexposeする用途
   • WatcherProcess内蔵、Heartbeat調停で複数インスタンス間を自動協調
   • MCPサーバからは使用されない（外部クライアント向け）

3. Embedding Server (packages/db-engine/src/python/embedding_server.py)

   • Ollama API互換のHTTP埋め込みサーバ
   • 複数プロセスから共有利用可能

詳細: docs/architecture.md

データモデル

• DocumentStorage: 文書の永続化（パス形式のキー）
• SearchIndex: Vector検索（LanceDB + Ruri Embedding）
• Section: 分割データ（depth 0-3、トークン数ベース）

詳細: docs/data-model.md

システム全体

• TypeScript: サーバ、クライアント、CLI、MCP Server
• Python: LanceDB操作、Vector化（uvで管理）
• pnpm: モノレポ管理

詳細: docs/architecture.md

プロジェクト構造

search-docs/
├── packages/              # モノレポパッケージ
│   ├── server/           # 検索サーバ
│   ├── client/           # クライアントライブラリ
│   ├── cli/              # CLIツール
│   ├── mcp-server/       # Claude Code統合
│   ├── storage/          # DocumentStorage
│   └── db-engine/        # LanceDB Pythonラッパー
├── docker/               # Docker関連
│   ├── entrypoint.sh    # モード分岐（MCP/Embedding、簡素化済み）
│   └── compose.yaml     # 共有Embeddingサーバ構成例
├── docs/                 # ドキュメント
├── prompts/              # Claude Code設定
│   └── tasks/           # 作業メモ・計画
├── Dockerfile            # マルチステージビルド
├── pyproject.toml        # Python依存関係（uv）
├── pnpm-workspace.yaml   # pnpmワークスペース
└── package.json          # ルートパッケージ