graphlore is a Model Context Protocol (MCP) server that lets AI coding
assistants navigate a codebase through its knowledge graph, instead of grepping
and reading file after file. It reads a graph built by
Graphify, joins every node to its real start..end
source span (Python via ast, other languages via tree-sitter), and answers
the questions text search cannot: who calls this, what breaks if it changes,
where a behavior lives.
- Find code by what it does.
graphlore_locate("where are failed requests retried?")returns the enclosing symbol, its neighborhood and similar-but-unconnected code in one call: about 235 tokens, against about 61,800 for grep + read on httpx (benchmark). - See the blast radius of a change.
graphlore_impact("Response")lists what depends on a symbol, production code before tests, each row withfile:line. - Read only the code you need.
graphlore_fetchreturns a symbol's exact span under a token budget. - Know how far to trust an answer. Results say how a name was matched, what a budget cut left out, and which files changed since the graph was built.
- Local by default. The analysis tools read local files and need no API
key;
GRAPHLORE_OFFLINE=1refuses every network path graphlore knows.
It works with any MCP client. Setup for Claude Code and Claude Desktop is below.
Claude Code plugin (needs uv): installs the
server, the Graphify CLI and an exploration skill, with nothing to configure.
/plugin install graphlore --marketplace yasinyaman/graphlore
On Claude Code older than 2.1.275, run /plugin marketplace add yasinyaman/graphlore
and then /plugin install graphlore@graphlore.
Any other MCP client: install graphlore and the Graphify CLI that builds the graph, then register the server.
# graphlore is not on PyPI yet: install from GitHub
pip install "graphlore @ git+https://github.com/yasinyaman/graphlore"
pip install graphifyy && graphify install{
"mcpServers": {
"graphlore": {
"command": "graphlore",
"env": { "GRAPHLORE_PROJECT_DIR": "/absolute/path/to/your/project" }
}
}
}- Claude Code: save this as
.mcp.jsonin the project root ("."works as the path). - Claude Desktop: add it to
claude_desktop_config.json(macOS~/Library/Application Support/Claude/, Windows%APPDATA%\Claude\).
Optional extras, installed as graphlore[extra]: semble (semantic
graphlore_locate and the duplication scan), treesitter (spans for non-Python
languages; usually already present through Graphify), tiktoken (exact token
counts), watch (re-sync on file changes). Until the first PyPI release, use
the GitHub form wherever a message says pip install "graphlore[extra]":
pip install "graphlore[semble] @ git+https://github.com/yasinyaman/graphlore".
Then ask. The assistant builds the graph once and explores from there (output from the repository's small test fixture):
graphlore_build(".") # once; graphlore_build(".", update=True) after changes
graphlore_overview() # size, hubs, subsystems, suggested next steps
graphlore_impact("Response", hops=1)
2 node(s) depend on Response (≤1 hops, direction=dependents):
Client (distance 1) [returns] def: httpx/_client.py:50
DigestAuth (distance 1) [inferred] def: httpx/_auth.py:120
A misspelled name gets a suggestion, not a guess:
No node matching 'Clinet'. Did you mean: Client (httpx/_client.py:50)?
The server starts on the lean surface, 12 tools that cover the whole explore
loop (orient, find, traverse, blast radius, read the code). A small surface
helps a model pick the right tool.
| Tool | What it answers |
|---|---|
graphlore_overview |
Call first: size, most connected nodes, communities, suggested next steps |
graphlore_locate |
A natural-language question → the enclosing symbol, its subgraph and hidden links (needs [semble]) |
graphlore_search |
Which nodes match this name or id |
graphlore_neighbors |
The direct neighbors of a node |
graphlore_subgraph |
The neighborhood around a node, under a token budget |
graphlore_impact |
Blast radius: what depends on a node, or what it depends on |
graphlore_node_details |
A node's type, file:line, docstring and community |
graphlore_fetch |
A node's source code: the exact span, under a token budget |
graphlore_communities |
The subsystems (Leiden communities) of the codebase |
graphlore_freshness |
Is the graph stale against git: fresh, update or rebuild |
graphlore_build |
Build or update the graph with the Graphify CLI |
graphlore_project |
Show or switch the project directory the server reads |
GRAPHLORE_TOOLSET=full exposes all 33: structure review (import and call
cycles, layer rules, dead-code candidates, same-named symbols, duplication),
framework routes and package API usage, tests for a symbol, signatures, git
diffs, community naming and the Graphify CLI passthroughs. The Claude Code
plugin runs on full.
→ Tool reference (all 33 tools, resources, prompts) · choosing a toolset
Tokens that reach the model to orient it in a code area, averaged over 6
queries on encode/httpx (2,101-node graph):
| Approach | Tokens | Calls | Graph structure | Semantic search | Hidden links |
|---|---|---|---|---|---|
| grep + read | 61,836 | ~14 | — | — | 0 |
| semble alone | 1,613 | 1 | — | ✓ | 0 |
| Graphify alone | 1,107 | 1 | ✓ | — | 0 |
| semble + Graphify, separately | 2,721 | 4 | ✓ | ✓ | 0 |
graphlore_locate |
235 | 1 | ✓ | ✓ | 7 |
That is 263× fewer tokens than grep + read and 11.6× fewer than running the two
tools separately. Those 235 tokens are a map (file:line plus neighborhood),
not the code; the code is fetched only where needed. Across Python, JS/TS, Go,
Java, Rust and C++ repositories, 70–96% of semantic hits land inside the
resolved symbol's real span.
Every repository measured is an HTTP-client library and the baseline is a naive grep, so treat the numbers as indicative. → Method, per-language results and caveats
Giving an AI coding assistant a cheap, structural view of a repository: onboarding to unfamiliar code, tracing how a feature works end to end, finding what a change would break, and reviewing structure (cycles, layering, dead or duplicated code).
They overlap more than they differ. Graphify's embedded server already has
graph navigation, token-budgeted subgraphs, an HTTP transport, multi-project
serving and PR triage tools graphlore lacks. graphlore adds the span engine and
what it makes possible: semantic locate joined to the enclosing symbol,
source hydration (fetch, skeleton), route and package-API extraction,
cosmetic-vs-structural freshness, and calls through a module object
(mod.func()) that the graph leaves out. Prefer one server per project.
→ How graphlore works
No. An exact identifier is found faster with rg. graphlore earns its place on
multi-hop questions (who calls this, what breaks if it changes) and on
orientation in unfamiliar code. Every answer carries file:line, so it can be
checked with a plain read.
No. It has no remember or recall tools and keeps no notes between sessions. It is a read-mostly view of a code graph; the only thing it persists is community names.
The analysis tools read local files and need no key. A few paths can reach the
network: the first semantic search downloads an embedding model, the first use
of a language downloads its tree-sitter grammar, Graphify can call an LLM
backend when you set its key, and graphlore_add fetches a URL.
GRAPHLORE_OFFLINE=1 refuses or restricts the ones graphlore controls; the
table linked below also lists what it cannot constrain.
→ What reaches the network, and when
Python works out of the box through the standard library. JS/TS, Go, Java,
Kotlin, Scala, C#, Rust, Swift, C/C++, Ruby, PHP and the other languages
tree-sitter covers need the [treesitter] extra; without it, non-Python files
fall back to nearest-line matching. Package-API extraction reads all of
these; route extraction reads Python, JS/TS, Go, Java, Kotlin, C#, Rust, Ruby
and PHP frameworks
(tool reference),
and both say which files they did not read.
What was measured in each language,
on 31 real repositories.
lean is the default surface. Set GRAPHLORE_TOOLSET=full for all 33.
graphlore_freshness says whether to update or rebuild, and
graphlore_build(".", update=True) re-extracts changed files. Answers also flag
their own files that changed since the build. A git post-commit hook or the
opt-in watcher automates it.
→ Keeping the graph fresh
Yes. It was renamed because graphifyy ships a graphify-mcp command of its
own. The old GRAPHIFY_* environment variables still work.
- One active project at a time;
graphlore_projectswitches it (stdio only). - No extractor of its own: the
graphifyCLI builds the graph, andbuild/query/path/explain/addare thin wrappers over it. - No PR or review-thread tooling.
- Calls through an object, a callback or dynamic dispatch are not in the graph, so an empty answer means "no edge was indexed", not "nothing calls this".
- Tool reference: all 33 tools, resources, prompts, what a result carries
- How graphlore works: resolved edges, import checks, analysis scope, freshness, semantic bridge, naming communities
- Configuration: toolsets, HTTP transport and security, offline mode, environment variables
- Benchmark: method, cross-language results, caveats
- Changelog · Contributing · Guidance for coding agents
pip install -e ".[dev,treesitter]"
ruff check .
mypy
pytest -qLicensed under MIT.