Skip to main content
Glama

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

Related MCP server: repo-graphrag-mcp

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.

Available Tools

16 tools
graphify_addA

Add an external source to the graph (arXiv paper, tweet, etc.). http/https only.

Args: url: Source URL to add. author: Original author tag (optional). contributor: Tag for who added it (optional).

Inputs: url (required), author, contributor. Returns: result

graphify_buildA

Build or update a knowledge graph from a folder. (Writes to graphify-out/.)

Args: path: Folder to extract the graph from (relative to the project dir or absolute). mode: "deep" -> more aggressive INFERRED edges; empty -> default. update: True -> re-extract only changed files and merge into the existing graph. cluster_only: True -> rerun clustering only, without re-extraction. no_viz: True -> skip the HTML visualization (faster for development).

Inputs: path, mode, update, cluster_only, +1 more. Returns: result

graphify_communitiesB
Read-only

Summarize Leiden communities with sizes and sample members.

Inputs: as_json. Returns: result

graphify_explainC
Read-only

Return everything Graphify knows about a node.

Inputs: node (required). Returns: result

graphify_freshnessA
Read-only

Check whether graph.json is stale relative to the current git HEAD.

Prefers the commit graphify recorded the graph was built from (built_at_commit) over the file mtime — robust across checkouts where mtime is reset — and flags both modified and newly-added (untracked) files. Recommends graphify_build(update=True) if stale.

Inputs: as_json. Returns: result

graphify_god_nodesB
Read-only

List the highest-degree (most connected) 'god nodes'.

Inputs: top_n, as_json. Returns: result

graphify_label_communitiesA

Give the Leiden communities human-readable names.

Args: method: "auto" -> host-LLM sampling if the client supports it, else a configured backend key (graphify CLI), else "Community N" placeholders. "sampling" -> force host-LLM sampling (no API key needed). "cli" -> force the graphify backend (GEMINI_API_KEY/OPENAI_API_KEY/... or a local ollama). "placeholder" -> no LLM at all. limit: Only the largest limit communities are named, to stay cheap. sample_size: Member labels per community handed to the model.

Inputs: method, limit, sample_size, as_json. Returns: result

graphify_neighborsC
Read-only

List the direct (1-hop) neighbors of a node, with relations.

Inputs: node (required), as_json. Returns: result

graphify_node_detailsC
Read-only

Show a node's full metadata: type, source file/line, docstring, community.

Inputs: node (required), as_json. Returns: result

graphify_overviewA
Read-only

One-shot orientation: call this FIRST.

Returns graph size, top god nodes, community count, surprise-edge count and suggested starting questions — enough to plan further exploration cheaply.

Inputs: top_n, as_json. Returns: result

graphify_pathB
Read-only

Find the exact path between two nodes (e.g. "DigestAuth" -> "Response").

Inputs: node_a (required), node_b (required). Returns: result

graphify_queryA
Read-only

Run a natural-language query against the graph.

Args: question: Natural-language question, e.g. "what connects attention to the optimizer?" dfs: True -> trace a specific path in depth. budget: If >0, cap the number of tokens returned (e.g. 1500).

Inputs: question (required), dfs, budget. Returns: result

graphify_sampling_statusA
Read-only

Capability test: how can semantic naming be produced in this session?

Reports whether the connected client supports host-LLM sampling (so the server needs no API key), whether a backend API key is configured as a fallback, and which method graphify_label_communities will pick.

Inputs: as_json. Returns: result

graphify_subgraphA
Read-only

Extract a BFS subgraph around a node, capped at a token budget.

This is the token-cheap way to hand the model just the relevant slice of a large codebase instead of the whole graph.

Args: node: Center node (exact or fuzzy match). hops: BFS depth from the center. budget_tokens: Approximate cap on returned size; expansion stops when hit.

Inputs: node (required), hops, budget_tokens, as_json. Returns: result

graphify_surprisesC
Read-only

List unexpected cross-file/cross-domain connections (surprise edges).

Inputs: limit, as_json. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: adding sources, building graphs, checking freshness, exploring nodes and paths, analyzing communities, and querying. There is no overlap between tool functionalities.

    Naming Consistency4/5

    All tools use the 'graphify_' prefix followed by descriptive names. While some are verbs (e.g., graphify_build) and others nouns (e.g., graphify_communities), the pattern is consistent and names clearly indicate tool purpose.

    Tool Count5/5

    With 16 tools, the server covers the core operations for knowledge graph management—building, adding sources, exploring, and analyzing—without being bloated. Each tool serves a clear need.

    Completeness4/5

    The tool set covers building, adding, exploring, querying, and community analysis. Missing are tools for deletion or modification of nodes/edges, but the surface is largely complete for the intended exploration and building workflow.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms codebases into knowledge graphs using Neo4J, enabling AI assistants to understand code structure, relationships, and metrics for more context-aware assistance.
      28
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An in-memory knowledge graph MCP server that gives coding agents structural and semantic recall over codebases by indexing Python source, ADR documents, and project configuration, exposing 7 tools for search, traversal, context retrieval, and natural-language Q&A.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A universal MCP server providing persistent, structured memory through a knowledge graph with graph storage, semantic vector search, and multi-hop traversal for AI agents and IDEs.
      1
      MIT