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.

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)
• 11 languages — Python, C, C++, C#, JavaScript, TypeScript, PHP, Dart, Swift, Kotlin, Java, Go
• 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.

Graph resolution labels

Reference edges are built by name matching plus ranked evidence, and every

caller/callee edge carries a `resolution` label saying how its target was

chosen: `same_file` (the caller's own file defines the name), `unique_file`

(all same-named candidates live in one file), `import` (the caller's imports

single out one file), `same_dir`, or `name_only`. Names appearing only in

comments or strings never become edges.

AI agents: `name_only` means a ranked candidate list across same-named

symbols — read it as "one of these", not a confirmed link; verify with

`get_symbol` or a reference search before acting on it. The stronger labels

are safe to treat as resolved.

Requirements

• Python 3.11+
• Git (for change intelligence and auto-reindex hooks)
• Ollama (optional, for semantic search / embeddings) — ollama.com
• NVIDIA GPU + cupy (optional, for GPU-accelerated vector search)
• Poppler (optional, for PaddleOCR scanned-PDF support) — `apt install poppler-utils` / `brew install poppler`

Quick Start

# Install from PyPI
pip install srclight

# Install from source
git clone https://github.com/srclight/srclight.git
cd srclight
pip install -e .

# Optional: document format support (PDF, DOCX, XLSX, HTML, images)
pip install 'srclight[docs,pdf]'

# Optional: OCR for scanned PDFs (also needs poppler-utils on your system)
pip install 'srclight[pdf,paddleocr]'

# Optional: OCR for images (needs tesseract on your system)
pip install 'srclight[docs,ocr]'

# Optional: GPU-accelerated vector search (requires CUDA 12.x)
pip install 'srclight[gpu]'

# Everything (docs + pdf + ocr + paddleocr + gpu)
pip install 'srclight[all]'

# Index your project
cd /path/to/your/project
srclight index

# Index with embeddings (requires Ollama running)
srclight index --embed qwen3-embedding

# Search
srclight search "lookup"
srclight search --kind function "parse"
srclight symbols src/main.py

# Start MCP server (for Claude Code / Cursor)
srclight serve

> Note: `srclight index` automatically adds `.srclight/` to your `.gitignore`. Index databases and embedding files can be large and should never be committed.

Semantic Search (Embeddings)

Srclight supports embedding-based semantic search for natural language queries like "find code that handles authentication" or "where is the database connection pool".

Setup

# Install Ollama (https://ollama.com)
# Pull an embedding model
ollama pull qwen3-embedding       # Best quality (8B params, needs ~6GB VRAM)
ollama pull nomic-embed-text      # Lighter alternative (137M params)

# Index with embeddings
srclight index --embed qwen3-embedding

# Or index workspace with embeddings
srclight workspace index -w myworkspace --embed qwen3-embedding

How It Works

1. Each symbol's name + signature + docstring + content is embedded as a float vector

2. Vectors are stored as BLOBs in `symbol_embeddings` table (SQLite)

3. After indexing, a `.npy` sidecar snapshot is built and loaded to GPU VRAM (cupy) or CPU RAM (numpy) for fast search

4. `semantic_search(query)` embeds the query and runs cosine similarity against the GPU-resident matrix (~3ms for 27K vectors on a modern GPU)

5. `hybrid_search(query)` combines FTS5 keyword results + embedding results via Reciprocal Rank Fusion (RRF)

Embedding Providers

# Use Voyage Code 3 (API, highest quality)
VOYAGE_API_KEY=your-key srclight index --embed voyage-code-3

Storage

Embeddings are stored in `symbol_embeddings` table in `.srclight/index.db`. After indexing, a `.npy` sidecar snapshot is built for fast GPU loading:

For ~27K symbols at 4096 dims (qwen3-embedding), that's ~428 MB on disk, ~450 MB in VRAM. Incremental: only re-embeds symbols whose content changed; sidecar rebuilt after each indexing run.

Multi-Repo Workspaces

Search across multiple repos simultaneously. Each repo keeps its own `.srclight/index.db`; at query time, srclight ATTACHes them all and UNIONs across schemas.

# Create a workspace
srclight workspace init myworkspace

# Add repos
srclight workspace add /path/to/repo1 -w myworkspace
srclight workspace add /path/to/repo2 -w myworkspace -n custom-name

# Index all repos (with optional embeddings)
srclight workspace index -w myworkspace
srclight workspace index -w myworkspace --embed qwen3-embedding

# Search across all repos
srclight workspace search "Dictionary" -w myworkspace
srclight workspace search "Dictionary" -w myworkspace --project repo1

# Status
srclight workspace status -w myworkspace
srclight workspace list

# Start MCP server in workspace mode
srclight serve --workspace myworkspace

Git submodules are not indexed automatically — `git ls-files` does not recurse into them. To index a submodule, clone it separately and add it as its own workspace project. See docs/usage-guide.md for details.

MCP Integration

Srclight supports two transport modes: stdio (one server per session) and SSE (persistent server, multiple sessions). SSE is recommended for workspaces.

Claude Code

Stdio (simplest — one server per session):

# Single repo
claude mcp add srclight -- srclight serve

# Workspace mode
claude mcp add srclight -- srclight serve --workspace myworkspace

# Make it available in all projects (user scope)
claude mcp add --scope user srclight -- srclight serve --workspace myworkspace

SSE (persistent server — recommended for workspaces):

Run srclight as a long-lived server, then point Claude Code at it:

# Start the server (default: http://127.0.0.1:8742/sse)
srclight serve --workspace myworkspace &

# Or install as a systemd user service (Linux/WSL)
# See docs/usage-guide.md for the service file

# Connect Claude Code to the running server
claude mcp add --transport sse srclight http://127.0.0.1:8742/sse

SSE mode supports multiple concurrent sessions and survives Claude Code restarts.

Cursor

SSE (recommended): Run srclight once, then connect Cursor to it. Best for responsiveness and no cold-start per session.

Start the server: `srclight serve --workspace myworkspace` (default SSE on port 8742).

• UI: Settings → Tools & MCP → Add new MCP server → Type: `streamableHttp`, URL: `http://127.0.0.1:8742/sse`.
• JSON (project `.cursor/mcp.json` or global `~/.cursor/mcp.json`):

"srclight": {
  "url": "http://127.0.0.1:8742/sse"
}

Stdio (alternative): One server process per Cursor session.

• UI: Type: `command`, Command: `srclight`, Args: `serve --workspace myworkspace` (or `serve` for single-repo).
• JSON:

"srclight": {
  "command": "srclight",
  "args": ["serve", "--workspace", "myworkspace"]
}

For single-repo: `"args": ["serve"]`. Restart Cursor completely after adding the server.

Verify: In Cursor chat, ask "What projects are in the srclight workspace?" or "List srclight tools" — the agent should call `list_projects()` or show srclight tools.

OpenClaw

OpenClaw connects to srclight via mcporter, its built-in MCP tool server CLI.

# 1. Add srclight to mcporter's home config
mcporter config add srclight http://127.0.0.1:8742/sse \
  --transport sse --scope home \
  --description "Srclight deep code indexing"

# 2. Verify the connection
mcporter call srclight.list_projects

# 3. Restart the OpenClaw gateway to pick up the new server
systemctl --user restart openclaw-gateway  # if using systemd
# or: openclaw daemon restart

The OpenClaw agent can then use srclight tools via the `mcporter` skill:

mcporter call srclight.search_symbols query="my_function"
mcporter call srclight.get_callers symbol_name="MyClass" project="my-repo"
mcporter call srclight.hybrid_search query="authentication logic"

> Prerequisite: Srclight must be running as an SSE server (see above). OpenClaw's mcporter connects over HTTP — stdio mode is not supported.

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "srclight": {
      "command": "srclight",
      "args": ["serve", "--workspace", "myworkspace"]
    }
  }
}

Any MCP Client (SSE)

Any MCP-compatible client can connect to the SSE endpoint:

http://127.0.0.1:8742/sse

MCP Tools (42)

Srclight exposes 42 MCP tools organized in seven tiers. The MCP server includes built-in instructions that guide AI agents on which tool to use and when — agents receive a session protocol, tool selection guide, and `project` parameter documentation automatically on connection.

Tier 1: Instant Orientation

Tier 2: Relationship Graph

Tier 2b: Community & Impact Analysis

Tier 3: Git Change Intelligence

Tier 4: Build & Config

Tier 5: Semantic Search (Embeddings)

Tier 6: Meta & Server

In workspace mode, `search_symbols`, `get_symbol`, `codebase_map`, and `hybrid_search` accept an optional `project` filter. Graph/git/build/community tools require `project` in workspace mode.

Strict Argument Validation

Since v0.20.2, srclight refuses unknown tool arguments instead of silently discarding them.

This is a deliberate behaviour change and it can break callers that were previously sending extra

keys without noticing.

Why

The MCP Python SDK's FastMCP drops arguments that are not in a tool's signature, and it does so

*before* the tool function runs. Combined with an `inputSchema` that omitted

`additionalProperties: false`, a mistyped argument produced a confident wrong answer rather than an

error. Measured on this server:

search_symbols(query="main", project="zhcorpus")    ->  20 hits, all from zhcorpus
search_symbols(query="main", projects="zhcorpus")   ->  20 hits, ZERO from zhcorpus
                                                        (19 from "bible", 1 from "bank-scraper")

One added letter. No error, identical hit count, identical result shape, real symbols — from repos

the caller never asked about. That is not a lossy call, it is a wrong one, and the caller has no

way to learn their filter was ignored.

What changed

• Unknown arguments now return an error naming the offending key, the accepted set, and stating

that nothing was executed. The tool body is never entered.

• Every tool advertises `additionalProperties: false` in `tools/list`, so the catalog matches

what the runtime enforces. Previously the runtime and the advertised schema disagreed.

• Zero-parameter tools are closed too (`index_status`, `codebase_map`, and three others). An

empty property set means "this tool takes no arguments", not "anything goes".

Scope: top-level arguments

This validates the top-level argument object. An argument that is itself a structured object is

validated by its own model, which this layer does not descend into. No srclight tool currently takes

an object argument, so the distinction is not reachable here today — but the guarantee is

"top-level", and a future tool taking a typed nested model would need `extra="forbid"` on that model

to get the same protection.

If this breaks your caller

The error names exactly what it received and what the tool accepts:

unknown argument(s): projects. Tool 'search_symbols' accepts: kind, limit, project, query.
Nothing was executed and no result was computed.

Fix the argument name. If you believe the argument *should* exist, the server may be running older

code than you expect — check its reported revision and reconnect.

If you cannot update your caller right now, pin the previous behaviour and update when you can:

pip install "srclight`)
   - **Content**: trigram index for substring matching
   - **Docs**: Porter stemming for natural language in docstrings
5. **Community detection** clusters symbols into functional modules via Louvain algorithm on call-graph edges, with TF-IDF auto-labeling
6. **Execution flows** are traced via BFS from entry points, and **impact analysis** scores each symbol's blast radius (LOW/MEDIUM/HIGH/CRITICAL)
7. Optional: **embedding vectors** are generated via Ollama or Voyage API and stored as BLOBs
8. A `.npy` **sidecar snapshot** is built and loaded to **GPU VRAM** (cupy) or CPU RAM (numpy) for fast search
9. The **MCP server** exposes structured query tools that AI agents call instead of grep
10. **Hybrid search** merges keyword (FTS5) and semantic (embedding) results via RRF

### Architecture (Workspace Mode)

repo1/.srclight/index.db ──┐

repo2/.srclight/index.db ──┼── ATTACH ──→ :memory: ──→ UNION ALL queries

repo3/.srclight/index.db ──┘

Each repo is indexed independently. At query time, SQLite's ATTACH mechanism joins them into a single searchable namespace. Handles >10 repos via automatic batching (SQLite's ATTACH limit).

## How Srclight Compares

A survey of 50+ MCP code intelligence servers across all major registries (Official MCP Registry, Smithery, Glama, mcp.so, awesome-mcp-servers) found that no other single server combines srclight's full capabilities:

| Capability | srclight | grep/glob (default) | CodeMCP (SCIP) | Claude Context (Zilliz) |
|-----------|----------|---------------------|----------------|------------------------|
| Symbol search (FTS5) | 3 indexes (name, content, docs) | None | SCIP-based | BM25 |
| Semantic search (embeddings) | GPU-accelerated, ~3ms | None | None | OpenAI API + Milvus |
| Hybrid search (keyword + semantic) | RRF fusion | None | None | BM25 + vector |
| Relationship graph (callers, callees) | tree-sitter edges | None | SCIP edges | None |
| Community detection (module clusters) | Louvain on call graph | None | None | None |
| Impact analysis (blast radius + risk) | Per-symbol + diff-level | None | None | None |
| Git change intelligence | blame, hotspots, WIP, detect_changes | None | None | None |
| Build system awareness | CMake, .csproj, #ifdef | None | None | None |
| Multi-repo workspace | ATTACH+UNION | None | None | None |
| Infrastructure required | `pip install`, SQLite | None | SCIP indexer | Docker, Milvus, OpenAI API |
| Fully local / private | Yes, zero API calls | Yes | Yes | No (needs OpenAI) |
| Languages | 11 | Any (regex) | 5 (SCIP) | Any (chunking) |
| MCP tools | 42 | 2 (grep, glob) | 80+ | ~10 |

Unlike grep-based tools, srclight builds a persistent index with structured lookups. Unlike cloud-based solutions, everything runs locally — your code never leaves your machine. Unlike IDE plugins, srclight works with any MCP client.

## Roadmap

### Done
- [x] Symbol intelligence + 3x FTS5 search
- [x] Relationship graph: callers, callees, hierarchy
- [x] Blast radius, test discovery, implementors
- [x] Git change intelligence: blame, hotspots, recent changes
- [x] Build system awareness: CMake, .csproj, platform conditionals
- [x] Semantic search: embeddings via Ollama/Voyage, hybrid RRF
- [x] GPU-accelerated vector search: `.npy` sidecar, cupy/numpy vectorized math
- [x] Multi-repo workspaces (ATTACH+UNION)
- [x] Auto-reindex git hooks (post-commit + post-checkout)
- [x] Document extraction: PDF, DOCX, XLSX, HTML, CSV, email, images, text (heading detection, tables, metadata)
- [x] Optional OCR: PaddleOCR for scanned PDFs, pytesseract for images
- [x] MCP agent guidance: comprehensive instructions, tool selection guide, session protocol
- [x] Workspace config hot-reload (no server restart needed to add repos)
- [x] VectorCache sidecar re-discovery (no restart needed after embedding)
- [x] Project name suggestions in error messages
- [x] Community detection: Louvain clustering on call-graph edges with TF-IDF auto-labeling
- [x] Execution flow tracing: BFS from entry points across community boundaries
- [x] Impact analysis: per-symbol blast radius with risk scoring (LOW/MEDIUM/HIGH/CRITICAL)
- [x] `detect_changes`: map git diff to affected symbols and aggregate blast radius

### Next
- [ ] Cross-language concept mapping (explicit edges between equivalent symbols across languages)
- [ ] Pattern intelligence (convention detection, coding pattern extraction)
- [ ] AI pre-computation (symbol summaries via cheap LLM)

## License

MIT — Gig8 LLC