Local project map, search and file reader for AI agents.
Model Context Protocol (MCP) Server: io.github.AMRITO-KUNDU/llmscribe
The MCP server io.github.AMRITO-KUNDU/llmscribe provides a deterministic repository map along with search and file reader capabilities for AI agents. Its purpose is to help agents locate and read repository content in a consistent way, based on the serverβs described functionality.
π οΈ Key Features
Deterministic repo map
Search
File reader
π Use Cases
Repo content discovery for AI agents
Searching within a repository
Reading specific files as input to agent workflows
β‘ Developer Benefits
Deterministic mapping to support consistent agent behavior
Direct search and file reading functions for repository-grounded tasks
β οΈ Limitations
No additional details (e.g., tool names, configuration, or supported formats) are provided in the available server data.
An agent that wants to look at your code has one interface: the shell. ls, find,
grep, cat β built for a human reading a terminal, not for a program building a
model of a repository.
LLMScribe gives it one structured interface instead: the same seven operations, the
same JSON, the same bytes, on Linux, macOS and Windows.
No AI. No embeddings. No hidden ranking. Apache-2.0, and it runs entirely on your
machine β no network, no account.
Works with Cursor, Claude Code, Claude Desktop, Codex, VS Code, Windsurf, Zed,
Cline, Continue, JetBrains and LM Studio β any MCP client β plus pip install and a
standalone Windows EXE.
The problem: agents drive your OS through a human interface
What the agent needs
Linux / macOS
Windows
list a directory
ls -la
dir /a
find files by name
find . -name '*.py'
Get-ChildItem -Recurse -Filter *.py
search inside files
grep -rn 'auth' .
Select-String -Pattern auth
read a file
cat app.py
type app.py
structural diff
diff -ru old new
fc /r (no recursive equivalent)
Three things go wrong every time:
The output is for eyes, not parsers. Columns, colour, locale-dependent sort order,
and warnings interleaved with results.
The commands are not portable. An agent that works on your laptop fails in CI, or
on a contributor's Windows machine.
The agent has to interpret. Every one of those returns text it must re-parse, and
re-parsing is where it drifts.
Proving it, not claiming it
scripts/cross_platform_check.py builds a fixed fixture project, runs map, overview,
search, read, read_many and dependencies over it, scrubs the absolute path, and
digests each result. The Cross-platform output
workflow runs that on Ubuntu, macOS and Windows and fails the build if the digests
differ:
text
llmscribe <version>
python 3.12
map <sha256>
map_depth2 <sha256>
overview <sha256>
search <sha256>
read <sha256>
read_many <sha256>
dependencies <sha256>
combined <sha256> <- must be identical on all three
The fixture is written as bytes, not text, so the files themselves are byte-identical on
every platform β write_text would turn \n into \r\n on Windows and the comparison
would be meaningless.
What that costs
Your agent does not have an intelligence problem. It has a retrieval problem β and
no model upgrade fixes a context window filled with the wrong files.
On a 1.4-million-line codebase, one benchmark agent burned 6,000 seconds and produced nothing β no analysis, no output, zero score.
The same model, given structured code search instead of free-form file reading, finished the same task in 89 seconds and scored 0.90.
Across another benchmark, Codex CLI completed its entire turn sequence without ever reaching the file that would have solved the task in 27β29% of runs.
Handed the right context up front, its score nearly doubled.
The bottleneck is not the model. It is what goes into the context window.
What users keep reporting:
The agent explores 200 files to change one line, and admits it is "looking at unnecessary files"
Nine searches and fourteen files to find one constant, because the search itself is not ranked
The same files re-read in a loop, with no reasoning between the reads
Stale fixtures, mock data and outdated comments read as current truth
Search reporting "no matches found" when a plain grep finds the text immediately
Truncation that hides itself, and build output filling the window with noise
What LLMScribe does about it
The failure
What LLMScribe does
Reads 200 files to change one line
project_map returns the whole tree with contents excluded, before a single file is read
Re-reads the same files in a loop
Same input, same bytes, every run
Misses the file that actually mattered
project_dependencies resolves local, stdlib, external and unresolved imports, plus reverse dependencies
Search returns nothing when the text exists
search returns path, line, matched text and match type, or a stable error code β never a silent empty
Stale fixtures read as current truth
Nothing is inferred, embedded or ranked; you get the files as they are, plus a Git diff
Build output and binaries fill the context
Real .gitignore semantics; binaries and oversized files are skipped
Context silently truncated
Every cut is reported: truncated, truncation_note, omitted_files
The file an agent needs next is usually the one structurally related to the file it is already looking at β a dependent, a sibling module, a test fixture. That is a graph question, not a similarity question, which is why LLMScribe ships dependency analysis and a real tree instead of embeddings.
Export the complete structure and supported file contents
Quick Start
Install LLMScribe from PyPI:
bash
pip install llmscribe
Then point it at any project directory on your machine. No API key, no network access, no account.
The project_map(...), search(...), read(...) snippets below show MCP tool calls. The same operations are available from the CLI (local directories) and from Python through llmscribe.core (see Python API).
Map
Generate a clean directory tree without file contents. This is the best first step when exploring an unfamiliar repository.
python
project_map()
CLI / MCP
CLI
bash
llmscribe map
llmscribe map --depth 2 # only the first two levels, like `tree -L 2`
llmscribe map --json
MCP
text
project_map
project_map(depth=2)
--depth N (or max_depth=N from Python) limits the listing to the first N path
levels. A top-level file is depth 1, so --depth 2 keeps a/b.py and drops
a/b/c.py. It prunes the tree and the file list, which means overview --depth 2
never reads the files it excluded β useful for fitting a large repository into a small
context window.
Safely retrieve the contents of a specific file. LLMScribe validates paths and prevents path traversal outside the project.
python
read(file_path="src/auth/service.py")
CLI / MCP
CLI
bash
llmscribe read src/auth/service.py
MCP
text
read
Every read also reports byte_size and line_count for the whole file, not just the
part returned β so the agent can answer "how big is this" and "how many lines" without a
second command, and without being misled when the body was clipped. That is the
stat / wc -l / file information, in the same shape on every OS.
Paths are flexible. Every command takes an optional directory, so --path is never required:
bash
llmscribe . # map the current directory
llmscribe ./src # map a specific directory
llmscribe map ./src # the same thing, spelled out
llmscribe search "auth" ./src # search inside a directory
Aliases for the verbs you already type:
Alias
Command
ls
map
tree
overview
grep, find
search
cat
read
deps
dependencies
read accepts several files and switches to a batch read automatically:
bash
llmscribe cat src/main.py src/util.py
llmscribe -V prints the version.
Configuration
LLMScribe runs entirely on your machine and needs no configuration.
Two optional environment variables restrict which directories the MCP server may read:
Variable
Description
Default
MCP_ALLOWED_ROOTS
Directories (separated by : on POSIX, ; on Windows) the tools may read
all paths
MCP_ALLOW_LOCAL_PATHS
0 disables local path access entirely
enabled
Python API
python
from llmscribe import Repository, LLMScribeError
repo = Repository(".") # or Repository(Path("."))print(repo.map().tree) # tree, no file contentsprint(repo.search("auth").match_count)
match = repo.read("src/app.py") # returns a result, never raisesifmatch.ok:
print(match.content)
batch = repo.read_many(["README.md", "missing.py"]) # per-file errors, never raisesprint(batch.success_count, batch.error_count)
deps = repo.dependencies("src/app.py") # raises LLMScribeErrorprint(deps.file_dependencies.local_dependencies)
print(deps.used_by) # what imports it
Two error conventions, and the difference matters:
read and read_manyreturn results carrying ok and error_code, so a batch
reports per-file failures instead of dying on the first one.
dependencies and diffraiseLLMScribeError, whose .code is a stable
machine-readable string.
Every method returns the same dataclasses the CLI and MCP server produce, and each one
has .to_dict() for JSON. llmscribe.core still exposes the underlying functions if you
want to call them directly.
Runnable examples live in examples/: chunking a repo for a RAG pipeline,
reviewing what a change touches, and a repo summary.
Behavior reference
Ignore rules
Defaults (.git, node_modules, venv, dist, build, .env, *.log, β¦), the root .gitignore and nested .gitignore files are applied with real Git semantics: wildcards, directories, ! negation, and root-anchored patterns.
Hidden files are included unless ignored.
Symlinks are never followed or listed.
Supported text files
Known source, config and doc extensions, plus names such as Dockerfile, Makefile, LICENSE and .gitignore.
Other files appear in the tree, but cannot be read or searched.
Limits
One source of truth: llmscribe.core.limits.
400,000 content characters per project_overview / read_many
50 files per read_many
1,000 search matches
20,000 map entries
2 MiB per file
200,000 diff characters
100,000 scanned entries
Anything cut is reported: truncated, truncation_note, omitted_files.
Errors
Every failure has a stable, machine-readable code:
Supported languages: Python, JavaScript/TypeScript, Java, Go, Rust, and C/C++.
Each reference is classified as one of:
local β resolved to a file or directory inside the project
stdlib β part of the language's standard library
external β not in the project, assumed third-party
unresolved β a relative or local-looking reference that matches nothing
used_by lists the reverse dependencies.
Git diff
Runs git with an argument list, a 30 s timeout, a minimal environment, and without external diff/textconv drivers.
Migration notes
Legacy tool names (project_get_file, project_get_files, project_search, project_list_files) are gone; use read, read_many, search.
Error code path_traversal is now invalid_path; not_text_file is unsupported_file_type.
project_dependencies results: all_local_files/all_external_deps/all_unresolved were replaced by used_by and per-category lists (stdlib_dependencies added).
llmscribe.core functions raise LLMScribeError (not FileNotFoundError) for a bad root.
1.3.0: the online GitHub source was removed β LLMScribe is now local-only. The repo and ref arguments, the in-memory snapshot cache, the llmscribe.github package, and the hosted HTTP transport are gone. Point the tools at a local path.
Architecture
All interfaces share one core engine, so behavior stays consistent everywhere.
LLMScribe intentionally stays simple. The goal is not to make the repository "smarter." The goal is to make the repository accessible to software.
One consequence is worth stating precisely: LLMScribe is deterministic β the same
input produces the same bytes on every run. An agent can rely on what it learned last
turn, and you can diff two runs of the same command and see only what actually changed.
We provide
Repository extraction
Literal search
Structured project data
File retrieval
Dependency information
Git information
Multiple interfaces
We don't provide
β AI-generated answers
β Embedding-based search
β Semantic ranking
β Autonomous coding
β An AI coding agent
β A generic Git client
Use Cases
AI coding agents
MCP applications
Developer tools
Code search interfaces
Repository explorers
Documentation systems
Code analysis pipelines
Automation scripts
Local LLM applications
Exploring unfamiliar open-source projects
Open Source
LLMScribe is open source under the Apache License 2.0. Inspect the source, modify it, and build your own integrations.
There is no hosted service and no telemetry. It reads your files, and nothing leaves your machine.