Skip to content
yasinyamanPublic

About

MCP server that lets AI assistants explore a codebase through its knowledge graph (Graphify): natural-language locate with semantic search + hidden links, token-budgeted subgraphs, impact/blast radius, structural diff & freshness, duplication scan — 27 tools, multi-language, keyless by default.

Resources

Contributing

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

graphlore: an MCP server for codebase knowledge graphs

CI License: MIT Python 3.10+

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 with file:line.
  • Read only the code you need. graphlore_fetch returns 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=1 refuses every network path graphlore knows.

It works with any MCP client. Setup for Claude Code and Claude Desktop is below.

Quick start

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.json in 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)?

Tools

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

Benchmark

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

FAQ

What is graphlore used for?

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).

How is it different from Graphify's own MCP server?

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

Does it replace grep?

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.

Is it an agent memory?

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.

Does it need an API key or send my code anywhere?

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

Which languages are supported?

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.

Why do I see only 12 tools?

lean is the default surface. Set GRAPHLORE_TOOLSET=full for all 33.

How does the graph stay up to date?

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

Was this project called graphify-mcp?

Yes. It was renamed because graphifyy ships a graphify-mcp command of its own. The old GRAPHIFY_* environment variables still work.

Known limits

  • One active project at a time; graphlore_project switches it (stdio only).
  • No extractor of its own: the graphify CLI builds the graph, and build / query / path / explain / add are 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".

Documentation

Development

pip install -e ".[dev,treesitter]"
ruff check .
mypy
pytest -q

Licensed under MIT.

About

MCP server that lets AI assistants explore a codebase through its knowledge graph (Graphify): natural-language locate with semantic search + hidden links, token-budgeted subgraphs, impact/blast radius, structural diff & freshness, duplication scan — 27 tools, multi-language, keyless by default.

Resources

Contributing

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages