sourcelens MCP server
Commit Oct 26, 2026Indexes codebases using tree-sitter AST parsing to allow AI clients to query specific symbols and function bodies without reading entire files.
Also known as Phyzx72/sourcelens
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 26, 2026
- License
- MIT
What is sourcelens MCP?
sourcelens indexes codebases using tree-sitter AST parsing to allow AI clients to query specific symbols and function bodies without reading entire files.
Summary generated from the project's README
About sourcelens MCP server
Indexing codebases with tree-sitter AST parsing allows AI clients to query specific symbols and function bodies without reading entire files. This local-first MCP server prevents token waste by storing symbol names, kinds, signatures, and exact byte offsets in a SQLite database. Instead of pulling an entire 800-line module into a context window, developers can request only the specific function or class they need.
Users set up the server locally using Python 3.10+ and can run it via stdio or through an HTTP transport for remote clients. The server provides specialized tools like index_folder to parse a directory, search_symbols to find names by substring, and get_symbol_source to fetch precise code bodies. It supports multiple languages including Python, JavaScript, TypeScript, Go, Rust, and C/C++.
By utilizing the get_file_outline and find_importers tools, an AI can navigate complex project structures efficiently. The system manages its own index at a default path in the user directory, which can be customized via environment variables.
What you can do with it
- 1Retrieve specific function bodiesAsk the AI to fetch the exact code for a single function without reading the surrounding file.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
SOURCELENS_HTTP
| Name | Description | |
|---|---|---|
| SOURCELENS_HTTP | — |
README
View on GitHubsourcelens
Token-efficient local code retrieval as an MCP server. Index a codebase once with tree-sitter AST parsing, then query exact symbols — functions, classes, methods — instead of re-reading whole files into your context window.
Built from scratch, MIT-licensed. No paid license, no network, local-first.
Why
Reading whole files to find one function is a token incinerator. sourcelens parses source into an AST once, stores each symbol's name, kind, qualified name, signature, and exact byte offsets, then serves precise bodies on demand. Pull only the function you need — not the 800-line module around it.
Install
git clone https://github.com/Phyzx72/sourcelens.git
cd sourcelens
uv venv .venv && source .venv/bin/activate
uv pip install -e .
Requires Python 3.10+.
Run
Stdio (default MCP transport):
sourcelens # or: python -m sourcelens.server
HTTP (for remote clients):
SOURCELENS_HTTP=1 SOURCELENS_PORT=8766 sourcelens
The index is a SQLite file at ~/.sourcelens/index.db by default. Override with SOURCELENS_DB=/path/to/index.db.
Tools
| Tool | What it does |
|---|---|
index_folder(path) |
Walk + parse every supported file, store symbols + imports |
search_symbols(query, kind?, language?) |
Find symbols by name substring |
get_symbol_source(id? / name?+file?) |
Fetch a symbol's exact body (byte-precise, no whole-file read) |
get_file_outline(file) |
List all symbols in a file, source order |
find_importers(target) |
Which files import a module |
find_imports(file) |
What a file imports |
stats() |
Index counts + per-language breakdown |
list_languages() |
Supported languages |
Supported languages
Python (.py), JavaScript (.js/.jsx), TypeScript (.ts/.tsx), Go (.go), Rust (.rs), C/C++ (.c/.h/.cpp/.hpp).
Usage pattern (the whole point)
index_folder("/path/to/repo")— once.search_symbols("handle_request")— find it.get_symbol_source(name="handle_request")— get only that function's body.
Never Read a whole file to find one symbol again.
Tests
pip install -e '.[dev]'
python -m pytest tests/ -v
License
MIT. See LICENSE.
sourcelens MCP questions
How does sourcelens save tokens?
It parses source into an AST once and serves precise symbol bodies on demand instead of reading whole files into the context window.
What languages are supported?
Supported languages include Python, JavaScript, TypeScript, Go, Rust, and C/C++.
Where is the index stored?
The index is stored in a SQLite file located at ~/.sourcelens/index.db by default.