srclight/srclight

**Deep code indexing for AI agents.** SQLite FTS5 + tree-sitter + embeddings + MCP.
Srclight builds a rich, searchable index of your codebase that AI coding agents can query instantly — replacing dozens of grep/glob calls with precise, structured lookups. It is the most comprehensive code intelligence MCP server available: 42 tools covering symbol search, relationship graphs, community detection, impact analysis, git change intelligence, semantic search, build system awareness, and document extraction — capabilities no other single MCP server combines. Fully local and private: your code never leaves your machine.
Why?
AI coding agents (Claude Code, Cursor, etc.) spend **40-60% of their tokens on orientation** — searching for files, reading code to understand structure, hunting for callers and callees. Srclight eliminates this waste.
| Without Srclight | With Srclight |
|---|---|
| 8-12 grep rounds to find callers | get_callers("lookup") — one call |
| Read 5 files to understand module | codebase_map() — instant overview |
| "Find code that does X" → 20 greps | semantic_search("dictionary lookup") — one call |
| Edit a function, break 47 callers | detect_changes() — shows blast radius before you commit |
| 15-25 tool calls per bug fix | 5-8 tool calls per bug fix |
Features
- **Minimal dependencies** — single SQLite file per repo, no Docker/Redis/vector DB
- **Fully offline** — no API calls, works air-gapped (Ollama local embeddings)
- **Incremental** — only re-indexes changed files (content hash detection)
- **19 languages** — Python, C, C++, C#, Java, Kotlin, Swift, Dart, Go, Rust, JavaScript, TypeScript, PHP, Lua, Bash, SQL, Groovy, CMake, Markdown — include fragments (.inc, .inl, .ipp, .tcc) included, plus any extension you declare with --ext
- **Says what it skipped** — index_status names the extensions a run walked past, so an incomplete answer never reads as a complete one
- **10 document formats** — PDF, DOCX, XLSX, HTML, CSV/TSV, email (.eml), images (PNG/JPG/SVG/etc.), plain text, RST, Markdown
- **Optional OCR** — PaddleOCR for scanned/image-only PDF pages; pytesseract for images
- **4 search modes** — symbol names, source code (trigram), documentation (stemmed), semantic (embeddings)
- **Hybrid search** — RRF fusion of keyword + semantic results for best accuracy
- **Multi-repo workspaces** — search across all your repos simultaneously via SQLite ATTACH+UNION
- **MCP server** — works with Claude Code, Cursor, and any MCP client
- **CLI** — index, search, and inspect from the terminal
- **Auto-reindex** — git post-commit/post-checkout hooks keep indexes fresh
MCP argument validation
Srclight's MCP server **refuses unknown tool arguments** instead of silently dropping them — a
mistyped filter like projects= (for project=) is rejected with an error, never answered as if
the constraint were applied. Every tool advertises additionalProperties: false. The guard is the
shared mcpkit policy, vendored as one hash-verified file
(src/srclight/_mcpkit.py).
**AI agents:** if a call returns unknown argument(s): … running older code than you think …
reconnect, the running server predates the argument you sent (a long-lived daemon serves the code
it launched with). Nothing ran — check the reported revision and reconnect the MCP; don't retry the
same call.
Index freshness
Every symbol/graph result carries index_freshness: the short string
"verified-fresh" when the files behind the answer are byte-identical to what
was indexed, or a bounded object naming which files are stale, missing, or
not indexed. check_freshness(paths?) probes any paths — or the whole index —
on demand (unchanged files cost one stat each; never writes), and
index_status reports whole-index checked/stale_count.
**AI agents:** a result stamped stale describes the code **as indexed**, not as
it is now — reindex (srclight index) or read the live file before acting on
line numbers or bodies from it. "verified-fresh" is the affirmative signal;
its absence on a workspace-mode result means freshness was not checkable for
that result, never that it is fresh.
Index coverage
index_status reports both sides of what an index holds: indexed_extensions,
every suffix it reads, and unindexed_extensions, the {extension: file count}
this repo holds that the last run walked past, plus oversize_skipped for files
refused on size and failed_files for files that could not be read or parsed. list_projects carries the same per
project, and find_pattern attaches the tally plus a note whenever it is