A
licenseA
qualityA
maintenanceNode.js server implementing Model Context Protocol (MCP) for filesystem operations.
14
668,809
90,042
Unlicense - libtelnet variant
graphlens-mcp
by Neko1313
This server provides coding agents with a semantic code graph of a project, enabling advanced cross-file and cross-language code navigation, dependency analysis, and impact assessment — rather than relying on text search or reading whole files.
Core Navigation & Analysis Tools:
search_symbols— Find symbols by name using full-text search (FTS5 prefix syntax) across the entire codebase.get_node_info— Retrieve full details for a specific symbol: source snippet, signature, docstring, kind, and file location.get_file_structure— Get a symbol outline (classes, functions, methods) of any file without reading its full contents.get_callees— Trace outgoing calls (dependencies) up to 10 hops deep to understand what a function relies on.get_callers— Find all callers of a symbol (up to 10 hops) — the primary tool for "what breaks if I change X?" impact analysis.get_neighbors— Explore all nodes within N hops in any direction around a symbol, useful for understanding unfamiliar code.find_references— Locate non-call usages (type annotations, assignments, imports) for complete impact analysis.get_cross_language_calls— Identify cross-service connections via HTTP, gRPC, or message queues.search_code— Search code content via regex/text (replaces grep).search_semantic/find_related— Optional semantic search by meaning or similarity to a symbol.list_clusters/get_cluster— Inspect semantic clusters in the codebase.
Graph Management:
Indexes and maintains a local semantic graph, automatically refreshed via a filesystem watcher.
Performs a reconciliation scan at startup to catch changes made while the server was offline.
Supports Python (out-of-the-box), TypeScript, Go, Rust, and PHP.
statuscommand reports language detection and toolchain resolution status.reindexforces a full re-indexing;removederegisters the server and optionally purges the local graph database.
Every tool response includes a resolver_status field (ok or degraded) so the agent always knows the confidence level of the returned data.
graphlens-mcp
A free, MIT-licensed MCP server that gives coding agents (Claude Code, Cursor, and compatible clients) a semantic code graph of your project — symbols, cross-file calls, references, imports and cross-language boundaries.
Instead of reading files top-to-bottom or grepping for names, the agent navigates the
structure: who calls this function, what does it depend on, what breaks if I change
its signature. It is a thin runtime layer over the
graphlens analysis engine: graphlens provides
the mechanisms (parsing, stable node identity, resolvers); graphlens-mcp owns the storage,
freshness and the agent-facing surface.
📖 Documentation: https://neko1313.github.io/graphlens-mcp/
Status: early. The core navigation works; see Known limitations.
Why
Coding agents discover structure the slow way — grep, glob, read one file at a time —
rebuilding call paths by hand before the real work even starts. The motivation is the same
as every other code-context tool: stop the agent from grepping. The approach is what
sets graphlens apart.
Most tools answer this by building their own model of your code — an ad-hoc graph
stitched from heuristics, where every tool maps the codebase a little differently and
nothing is authoritative. graphlens takes the opposite bet: it builds on the language's
own real analysis engines — rust-analyzer, gopls, the TypeScript compiler, the bundled
ty type engine — the LSP-grade tooling the industry already trusts. That yields a stable,
real picture of the project (who actually calls what, across files and languages), not a
bespoke approximation. And a stable foundation is something you can build on: attach context
to the parts of a change that matter, auto-extract semantic clusters, answer impact
questions reliably.
That foundation is the graphlens engine —
parsing, stable node identity, and the resolvers. graphlens-mcp is a smart, agent-facing
layer over it, and — honestly — a worked example of how to use the engine: it persists
the graph (so the whole thing isn't held in memory), adds a semantic + clustering layer on
top, keeps it fresh as you edit, and exposes it to agents as navigation tools plus a bundled
skill. From that example it is growing into a self-sufficient system — one that, measured
against the market's giants, aims for stable, reproducible results: better in some places,
worse in others, but honest about which (see How it compares).
Related MCP server: CodeGraph
How it compares
graphlens-mcp ships with a reproducible A/B benchmark (benchmarks/)
that drives the same agent against three interchangeable code-context MCP servers —
graphlens, semble (semantic search), and codegraph (graph index) — plus a no-tools
control that measures how much each server adds over the model's own memory. It runs across
real Go / Rust / Python / TypeScript codebases and grades answers deterministically
against oracle gold (no LLM judge), stratified into SIMPLE lookups vs HARD impact /
cross-file questions, and reports accuracy alongside token / tool-call / dollar cost —
because a cheaper arm at equal accuracy wins.
📊 Results (10 repos · 3 models, strong → genuinely weak · ~2,400 graded runs — full breakdown, significance tests and reproduction steps at docs: Benchmarks):
SIMPLE accuracy
HARD accuracy
HARD tokens (median)
HARD completion
graphlens
0.980 – 1.000
0.899 – 0.921
22.4k – 34.1k
≥ 0.959 on every model
codegraph
0.912 – 0.990
0.655 – 0.939
23.2k – 70.0k
drops to 0.765 on the weakest model
semble
0.647 – 0.961
0.555 – 0.850
21.6k – 74.9k
drops to 0.688 on the weakest model
none (control)
0.366 – 0.681
0.453 – 0.685
0.1k – 0.9k
—
Accuracy alone hides the number that matters to a bill: tokens paid per task. graphlens's HARD-tier token spend stays flat (22k–34k) whether the driving model is strong or weak; codegraph's and semble's balloon past 70k on the weakest model — more than double graphlens's ceiling — for a worse answer, not a better one. graphlens is the only arm that stays clearly ahead of the no-tools control and keeps completion above 0.95 at every model tier: on the weakest model tested (gpt-oss-20b) it holds 0.900 HARD accuracy at roughly half the token cost of codegraph. Pairwise Wilcoxon signed-rank tests (matched by task) confirm the gap is statistically significant on the weaker models, not an artifact of a few outlier tasks — see the notebook for per-model p-values and effect sizes.
Install
Requires Python ≥ 3.13 (a constraint inherited from graphlens).
uv tool install graphlens-mcp # or: pipx install graphlens-mcpPython language analysis works out of the box (the ty type engine ships as a
dependency). Other languages parse immediately and unlock full cross-file semantics once
their toolchain is present (Node for TypeScript, the Go toolchain, etc.); without it that
language is reported as degraded rather than blocking init.
Quickstart (two commands)
uv tool install graphlens-mcp # 1. install
cd your-project && graphlens-mcp init # 2. index + configure your agentinit detects the project's languages, indexes the code into a local graph, writes the
MCP server entry into your agent's config and installs the navigation skill. You do not
run serve yourself — your agent launches it from the config. Restart the agent and ask
it something like "what breaks if I change the signature of create_order?".
Commands
Command | What it does |
| Detect languages → toolchain doctor → full index → configure agents → install skill |
| Start the MCP server over stdio. Launched by the agent, not by you |
| Show detected languages, toolchain status, and graph size/freshness |
| Force a full rebuild (e.g. after installing a new toolchain) |
| Deregister from agents and (with |
Useful init flags: --root <dir>, --agent claude_code --agent cursor (repeatable),
--no-agent, --no-skills, --db <path>.
The graph lives at <project>/.graphlens/graph.db (SQLite). It is a regenerable cache —
safe to delete; reindex rebuilds it. Add .graphlens/ to your VCS ignore (the bundled
init flow assumes it is not committed).
Supported languages
Language | Engine | Out-of-box |
Python |
| Full semantics immediately |
TypeScript | Node bridge |
|
Go | Go toolchain |
|
Rust | SCIP / rust-analyzer |
|
PHP | PHP parser |
|
graphlens-mcp status reports the actual resolver status per language. When a toolchain is
missing, that language is reported as degraded (parsed structure, calls/types not fully
resolved) with an install hint — it never blocks init.
Agent tools
Three tools — everything a symbol or file needs comes back as a navigable graph node,
not a dead grep line. Each response carries a graph-quality status (ok | degraded) so the
agent never mistakes a partial answer for a complete one, plus an indexing flag (true
when a background reindex is running, so edges may be temporarily incomplete).
Tool | Purpose |
| Find code by NAME, CONTENT, or MEANING — the one way in. Returns graph nodes with their signature (often enough to answer without a follow-up call). Content is matched literally, not as a regex. Scope with |
| A symbol's neighbourhood in one call: callers, callees, implementors/subclasses, and non-call references — each with its signature. The impact-analysis tool ("what breaks if I change X?", "what implements X?") |
| Read a specific target: a symbol (node id or name) → source + signature + location; a file path → its symbol outline |
search and relations accept either a symbol name or a node id directly — you don't
need to look up a node id first. Both cap their response size (a large hit set is ranked by
relevance via a small bundled embedding model, not just truncated) and surface true counts
(callers_total, references_total, …) when a list is capped, so the agent sees "15 shown
of 22" instead of guessing. If the embedding model can't be fetched (e.g. a first run with no
network), search transparently falls back to name/content matching.
Freshness model
A single mechanism keeps the graph current: a filesystem watcher (serve starts it by
default; disable with --no-watch). When a file changes on disk the server re-indexes the
connected set — the changed file plus the files that import it and the files it imports —
with one full analyze, so cross-file edges are rebuilt correctly rather than left partial.
Deleting a file prunes its symbols and refreshes its importers. There is no polling and no
structure-only "skeleton" phase: every (re)index produces the full graph the resolver can
give. As a backstop, a tool that touches a file the watcher hasn't processed yet triggers the
same connected re-index on access.
Files created, deleted or edited while the server was down are invisible to an event-based
watcher, so serve runs a one-shot reconcile at startup: it scans the project, indexes
new files, prunes vanished ones, and refreshes any that changed — then hands off to the
watcher.
Known limitations
Connected-set re-link, deep ripples: the watcher re-links the connected set of a change (the changed file plus its direct importers and imports), not the entire project. A rename that ripples through many indirection layers may need a full
reindexfor an exact graph. Creating a file that an unchanged file already imports is handled — a second importer pass re-links that importer once the new file is indexed.Cross-language edges on incremental edits: synthesized
COMMUNICATES_WITHedges are re-synthesized for every boundary a re-indexed file touches, so a new or moved exposer/consumer is linked without a fullreindex. A change that leaves a boundary entirely (a file that stops exposing an endpoint others still consume) may still need a fullreindexfor an exact cross-language view; the boundary-based query resolves connections regardless.
Uninstall
graphlens-mcp remove deregisters the server from your agents; add --purge-db to also
delete the local .graphlens/ cache.
Development
uv sync --all-groups # install lint + test tooling
task check # ruff + format-check + ty + bandit + pytest (the CI gate)
task docs:serve # preview the docs site locally (needs Node + pnpm)See the Architecture and Semantic search pages on the documentation site for the design and invariants.
License
MIT — see LICENSE.
Available Tools
3 toolsinfoA
Read a specific target. A SYMBOL (node id or name) -> source, signature and location. A FILE path -> its symbol outline by default (default limit 200 symbols) — a cheap structural overview. Set mode='source' to read the file's actual current content instead: line-numbered (same shape as Read, safe to Edit from), windowable with offset/limit exactly like Read, plus which files import it. Use mode='source' instead of opening the file yourself whenever you need the body, not just its symbol list. If a symbol name matches several definitions, pass file (a path or suffix) to pin the right one — e.g. one UserService per service in a monorepo.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| mode | No | outline | |
| limit | No | Max nodes to return (clamped to 200) | |
| offset | No | ||
| target | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| node | No | |
| error | No | |
| source | No | |
| indexing | No | |
| docstring | No | |
| file_path | No | |
| signature | No | |
| truncated | No | |
| dependents | No | |
| file_nodes | No | |
| repeat_hint | No | |
| resolver_status | No | |
| dependents_total | No |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It describes the read-only nature ('Read a specific target'), details return content per target type, explains default limit clamping to 200, and mentions windowing with offset/limit. It does not explicitly state that the tool is non-destructive or require permissions, but the behavioral details are sufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, packing many details into a few sentences. While all sentences contribute value, the text is somewhat dense and could be better structured (e.g., bullet points) for quick scanning. Still, it avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema to cover return values, the description adequately explains the tool's behavior for both symbols and files, including default mode, limit clamping, and disambiguation. It lacks handling of not-found cases or errors, but covers the main use cases comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema coverage (only limit has a description), the description adds significant meaning to all parameters: target (symbol vs file path), mode (outline vs source), file (disambiguation), offset/limit (windowing defaults). It clarifies defaults and behavior beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Read a specific target', specifying that it takes a SYMBOL (node id or name) or a FILE path and returns structural info or source content. It distinguishes itself from generic file reading by advocating use of mode='source' instead of opening the file directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode: outline for cheap structural overview, source for actual content with line numbers and import information. It also explains when to use the file parameter to disambiguate symbol names. However, it does not compare this tool to its siblings (relations, search), which is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
relationsA
A symbol's neighbourhood in one call: who calls it, what it calls, what implements/subclasses it, and non-call references — each with its signature. Accepts a node id OR a name (default depth 2, limit 25). THE tool for impact analysis and 'what implements X'. If the name matches several definitions, pass file (a path or suffix) to pin the right one — e.g. one UserService per service in a monorepo.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| depth | No | Max traversal hops (clamped to 10) | |
| limit | No | Max nodes to return (clamped to 200) | |
| symbol | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| node | No | |
| error | No | |
| callees | No | |
| callers | No | |
| indexing | No | |
| truncated | No | |
| references | No | |
| repeat_hint | No | |
| implementors | No | |
| callees_total | No | |
| callers_total | No | |
| resolver_status | No | |
| references_total | No | |
| implementors_total | No |
TDQS
A4.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses default depth and limit, and mentions clamping from the schema. It describes the nature of results (neighbourhood with signatures). But it doesn't mention side effects, permissions, or data handling. The output schema covers return structure, so the description adds moderate context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, then parameter guidance, then usage hint. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the description covers input, defaults, and a disambiguation example, it is complete for a tool of moderate complexity. The description provides all necessary context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with depth and limit already documented. The description compensates by adding meaning for 'symbol' (accepts node id or name) and 'file' (disambiguation for matching names). This provides practical guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'A symbol's neighbourhood in one call: who calls it, what it calls, what implements/subclasses it, and non-call references — each with its signature', which is a specific verb+resource. It distinguishes from siblings by claiming 'THE tool for impact analysis and 'what implements X'', clearly differentiating from info and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance (impact analysis, 'what implements X') and explains when to use the file parameter for disambiguation when names match. However, it lacks explicit exclusions or comparisons to sibling tools like info or search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchA
Find code by NAME, CONTENT, or MEANING — the one way in (default limit 25). Returns graph nodes WITH their signatures (not dead text lines): often enough to answer without info(). Pass any node to relations/info. Use wherever you'd grep or search for a symbol; content hits fold into the enclosing symbol. text_matches = non-symbol hits. Content is matched LITERALLY (not regex) — write 'Request(' or 'getErrorMap(' as-is, no escaping needed. Scope with path_glob (e.g. 'tests/', '.ts', '!tests/' to exclude) — there is no file:/content: query syntax, so use this instead of guessing one. Test files are excluded by default unless you set path_glob yourself or the query says 'test' — pass path_glob='tests/' to search them on purpose. For 'list EVERY file that calls/imports X' — where the top-N node list could miss some — set exhaustive=true: returns every matching file path (no signatures), uncapped by the normal limit. If the response's note field is set, your exact text matched nothing — every node is a name/meaning guess, not a confirmed hit — simplify the query instead of repeating it.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max nodes to return (clamped to 200) | |
| query | Yes | ||
| path_glob | No | ||
| exhaustive | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| via | No | |
| note | No | |
| count | No | |
| error | No | |
| files | No | |
| nodes | No | |
| indexing | No | |
| truncated | No | |
| repeat_hint | No | |
| text_matches | No | |
| resolver_status | No |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully covers behavior: returns graph nodes with signatures, not dead text lines; text_matches for non-symbol hits; literal matching; note field indicates no exact matches; exhaustive mode returns all file paths without signatures; test file exclusion logic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but packed with valuable, non-redundant information. It is front-loaded with the main purpose and each sentence adds necessary detail. Slightly verbose but acceptable given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (4 parameters, multiple behaviors) and the presence of an output schema, the description covers all relevant aspects: parameter details, edge cases (note field, exhaustive, test files), and redirection to sibling tools. It is fully adequate for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only limit described), but the description compensates by detailing all parameters: limit (default 25, clamped to 200), query (search term), path_glob (scoping with examples and exclusion), exhaustive (boolean for full file listing). Adds significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool finds code by name, content, or meaning, and it is the primary search entry point, distinguishing it from the sibling tools 'info' and 'relations' which provide details and relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive usage guidance: use it like grep or search for symbols, how content hits fold, how to scope with path_glob (with examples), test file exclusion behavior, and the exhaustive option. It also implies when to use siblings after obtaining a node.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A4.6/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: 'search' finds code by various criteria, 'info' reads details of a specific target, and 'relations' explores a symbol's connections. There is no overlap or ambiguity.
Naming Consistency5/5
All tool names are single lowercase words ('info', 'relations', 'search'), following a consistent and predictable style. Although not verb_noun, the pattern is uniform.
Tool Count5/5
With exactly 3 tools, the server is well-scoped for code graph analysis. Each tool covers a fundamental operation (find, inspect, explore) without being too few or too many.
Completeness5/5
The tool surface covers the essential workflows for code navigation: searching for symbols, reading their details or file contents, and exploring relationships. No obvious gaps are present for the intended domain.
Maintenance
ActivityStale
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceSupercharges AI coding agents with a pre-indexed semantic code graph, enabling instant symbol relationships, impact analysis, and context retrieval across 20+ languages.113,76569,062MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.764Apache 2.0
- AlicenseNot gradedqualityCmaintenanceSemantic concept graph MCP server for codebases — what your code means, not just what it does.2MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Neko1313/graphlens-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server