Lightweight repo-local hybrid (semantic + keyword) code search over MCP. Pure npm — no Docker, no Ollama, no servers. 11 languages via tree-sitter, jina-code embeddings, LanceDB, live file watcher.
code-rag has well-structured tool definitions with complete input schemas and detailed descriptions. All 4 tools are explicitly registered with proper JSON Schema. Descriptions are comprehensive (194 - 392 chars, within baseline), explaining WHAT each tool does and WHEN to use it. Parameters have types and descriptions. However, output schemas are not documented, LLMs cannot predict response structure. Error handling is minimal (no recovery guidance, no categorization). Tool naming is clear (code_search, exists, get_chunk, index_stats) but lacks action verbs on some (index_stats reads like a noun). No tool annotations (readOnlyHint, destructiveHint) despite all being read-only operations.
Hybrid semantic + keyword search over the local repository (tree-sitter chunked, jina-code embedded, BM25-scored, RRF-fused). Returns ranked code snippets with file paths, line ranges, and per-result attribution (`via=semantic|keyword|both`, `kw_hits=N`). When the query contains literal identifiers (snake_case, CamelCase, ALL_CAPS), surfaces their corpus counts and flags low confidence if zero chunks contain them. Use this when intent matters more than exact strings (e.g. 'where do we handle JWT refresh'). For pure presence/absence questions ('does this string exist anywhere?'), prefer the `exists` tool — it's definitive and faster.
Definitive presence check for a literal substring across the indexed corpus. Grep-equivalent companion to `code_search` — returns count + sample locations, or zero. Use this for 'does X appear anywhere?' questions; it's faster than code_search and gives an unambiguous answer (no semantic noise, no ranking guesses).
Fetch the full content of a single chunk by its ID (returned by code_search).
Inspect the code-rag index: total chunks, total files, language distribution, stale-file estimate.
Output schemas not documented. LLMs cannot predict response structure (fields, types, pagination). Forces agents to guess what data is returned.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). All 4 tools are read-only but this is not declared in the schema, forcing LLMs to infer safety.
Error handling lacks recovery guidance. No categorization of errors as retryable, user-fixable, or fatal. Stack traces or bare error codes give agents no actionable next step.
index_stats tool name lacks action verb. 'index_stats' reads as a noun (data structure) rather than a verb (action). Better: 'get_index_stats' or 'describe_index'.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | 2026-07-28+ | v2 |
code_search and exists descriptions include example values ('e.g. src/addin/%', 'e.g. src/foo.ts:10-42'). LLMs tend to reuse examples literally rather than adapt to context.