| 1 | # Hybrid Codebase Index (HCI) — MCP |
| 2 | |
| 3 | Local hybrid index for “search-before-read” workflows. Формальное решение **ADR 0105** — в репозитории **CascadeIDE**: [0105](https://github.com/KarataevDmitry/cascade-ide/blob/main/docs/adr/0105-hybrid-codebase-index-for-csharp-web.md); краткое обоснование без ADR-серии здесь — **[design-rationale.md](docs/design-rationale.md)**. Keyword-поиск (SQLite FTS5) по docs/config/web/axaml и опционально `*.cs` как текст; **семантическая корректность по C# — в Roslyn** (rename/usages/diagnostics). |
| 4 | |
| 5 | **Cursor:** примеры правил для копипаста и ссылки на соседние репо — **[docs/cursor-rules-examples.md](docs/cursor-rules-examples.md)**. |
| 6 | |
| 7 | ## What you get |
| 8 | |
| 9 | - **MCP server**: `HybridCodebaseIndex.Mcp` (stdio) |
| 10 | - **Index core**: NuGet **[AIGuiders.HybridCodebaseIndex.Core](https://www.nuget.org/packages/AIGuiders.HybridCodebaseIndex.Core)** (исходники — [hybrid-codebase-index-core](https://github.com/KarataevDmitry/hybrid-codebase-index-core); SQLite FTS5) |
| 11 | - **Tools**: |
| 12 | - `codebase_index_version` |
| 13 | - `codebase_index_status` |
| 14 | - `codebase_index_reindex` (incremental by default; `full_rebuild=true` for full rebuild) |
| 15 | - `codebase_index_search` (with optional path/ext filters) |
| 16 | - `codebase_index_explain` |
| 17 | |
| 18 | Generated docs: |
| 19 | - `mcp-tools.manifest.json` |
| 20 | - `docs/MCP-TOOLS.md` |
| 21 | |
| 22 | ## Install / publish (Windows) |
| 23 | |
| 24 | Run from repo root: |
| 25 | |
| 26 | ```powershell |
| 27 | .\publish-and-deploy.ps1 |
| 28 | ``` |
| 29 | |
| 30 | This produces a self-contained exe and mirrors it to: |
| 31 | - `D:\hybrid-codebase-index\HybridCodebaseIndex.Mcp.exe` |
| 32 | |
| 33 | ### Note: local publish vs releases |
| 34 | |
| 35 | - `.\publish-and-deploy.ps1` is for **local Cursor MCP** workflow: publish + mirror to a fixed target path (easy to point `mcp.json` at), and avoids “file locked” issues. |
| 36 | - If you add release automation (zip + upload), keep it separate from local publish (typically under `scripts/`). |
| 37 | |
| 38 | Then add to Cursor MCP config (`mcp.json`): |
| 39 | |
| 40 | ```json |
| 41 | { |
| 42 | "hybrid-codebase-index": { |
| 43 | "command": "D:\\hybrid-codebase-index\\HybridCodebaseIndex.Mcp.exe", |
| 44 | "args": [] |
| 45 | } |
| 46 | } |
| 47 | ``` |
| 48 | |
| 49 | ## Workspace settings |
| 50 | |
| 51 | Per-workspace override file: |
| 52 | - `<workspace>/.hybrid-codebase-index/settings.toml` |
| 53 | |
| 54 | Default settings are embedded into the **Core** assembly (packaged in the dependency): |
| 55 | - в репозитории ядра: `DefaultSettings/settings.default.toml` в [hybrid-codebase-index-core](https://github.com/KarataevDmitry/hybrid-codebase-index-core) |
| 56 | |
| 57 | ### Supported keys (snake_case) |
| 58 | |
| 59 | - `include_cs_in_fts` (bool): include `*.cs` as plain text documents. |
| 60 | - `extra_include_roots` (string[]): extra roots (relative to workspace root) to index. |
| 61 | - `include_extensions` (string[]): extensions to index (with or without dot). |
| 62 | - `exclude_extensions` (string[]): subtract from effective extensions. |
| 63 | - `exclude_path_segments` (string[]): denylist path segments (directory names) applied before ignore rules. |
| 64 | - `ignore_files` (string[]): which gitignore-like files to apply (paths relative to workspace root). |
| 65 | - `max_indexed_file_bytes` (int): files larger than this are skipped as `too_large`. |
| 66 | - `chunk_lines` (int): FTS chunk size (line windows). |
| 67 | - `chunk_overlap_lines` (int): overlap between chunks. |
| 68 | - `binary_probe_bytes` (int): probe size for NUL detection. |
| 69 | |
| 70 | ## Usage |
| 71 | |
| 72 | 1) Build (first time) / update index: |
| 73 | |
| 74 | ```json |
| 75 | { "workspace_path": "D:\\path\\to\\workspace" } |
| 76 | ``` |
| 77 | |
| 78 | Call `codebase_index_reindex`. |
| 79 | |
| 80 | 2) Search: |
| 81 | |
| 82 | ```json |
| 83 | { |
| 84 | "workspace_path": "D:\\path\\to\\workspace", |
| 85 | "query": "GroupedTreeFilterBuilder BuildItemWhereClause", |
| 86 | "top_n": 10, |
| 87 | "path_prefix": "src/", |
| 88 | "exclude_path_prefixes": ["bin/", "obj/"], |
| 89 | "extensions": ["md", "axaml", ".csproj"] |
| 90 | } |
| 91 | ``` |
| 92 | |
| 93 | 3) Then open the top hits in IDE, and use Roslyn MCP for exact refactors. |
| 94 | |
| 95 | |