Skip to main content
Glama
yasinyaman

graphify-mcp

by yasinyaman
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

graphlore

CI License: MIT Python 3.10+

A Python MCP server that makes a Graphify codebase knowledge graph navigable — and joins it to the real source through a span engine. Graphify builds the graph (graphlore ships no extractor of its own); graphlore exposes it as 28 MCP tools, prompts and resources, and resolves every node to its true start..end symbol range — so an assistant orients structurally and cheaply (token-budgeted maps, then exact spans) instead of grepping and reading file after file.

Relationship to Graphify's own MCP server. Graphify ships an embedded MCP server (graphify ./raw --mcp), and the two overlap more than they differ. Graph navigation (query, node lookup, neighbors, communities, god nodes, stats, shortest path), token-budgeted subgraph rendering, an HTTP transport with API-key auth and DNS-rebinding protection, and multi-project serving are all already there — and it has PR triage tools graphlore does not.

What graphlore adds is the span engine: real start..end symbol ranges via stdlib ast and tree-sitter, and the layer that only becomes possible once you have them — semantic locate with hidden_links (a semantic chunk joined to the enclosing symbol, not a nearest-line guess), source hydration (graphlore_fetch / graphlore_skeleton), framework route → handler and package-API extraction, and cosmetic-vs-structural git freshness.

Known limits. One project per server process (GRAPHLORE_PROJECT_DIR; use Graphify's embedded server if you need several repos from one process). No PR/review tooling. No extractor: graphifyy must be installed, and graphlore_build/query/path/explain/add are thin wrappers over its CLI. graphlore_locate and graphlore_duplication_scan need the optional [semble] extra; non-Python spans, routes and package APIs need [treesitter], without which non-Python files fall back to nearest-line matching.

Why graphlore_locate

One MCP call turns a natural-language question into a navigational map, not a wall of code:

  • 🔎 Semantic + structural, one call — semble finds the relevant code, the graph gives its neighborhood. ~235 tokens to orient vs ~61k for grep+read (263× fewer on httpx).

  • 🔗 hidden_links — semantically similar code that is structurally disconnected (duplication / missing-abstraction / sync-async-twin candidates) that neither search nor the graph surfaces alone.

  • 🌍 Multi-language, zero config — Python via stdlib ast; JS/TS · Go · Java · Rust · C++ · 165+ more via tree-sitter with automatic language detection. Span-join precision 70–96% on real HTTP-client repos in six languages, at 1 tool call / 0 file reads per orientation (benchmark).

  • 🕒 Cosmetic-aware freshness — graphlore_freshness ignores comment/format-only edits (in every language) so a reformat never triggers a needless rebuild.

One call beats running semble and graphify separately

semble finds what's relevant; graphify gives how it connects. They're complementary — but stitching them by hand means four calls, ~2.7k tokens, and manually aligning semble's line ranges to graph nodes. graphlore does that join for you, in one call:

per query

semble alone

graphify alone

both, by hand

graphlore_locate

Semantic search

✓

—

✓

✓

Graph structure

—

✓

✓

✓

Chunk → symbol join

—

—

you wire it

✓ automatic

hidden_links cross-check

—

—

—

✓ only here

Calls

1

1

4

1

Tokens to orient

1,613

1,107

2,721

235

→ 11.6× fewer tokens than running the two separately — in a single call, and hidden_links (semantically similar code that is structurally disconnected) is a signal neither tool produces alone. So the combined tool isn't just convenience: it's cheaper, and it surfaces something the parts can't. (full benchmark ↓)

Installation

# graphlore itself
pip install graphlore

# plus the Graphify CLI it wraps (needed for build/query/path/explain/add)
pip install graphifyy && graphify install

From source:

git clone https://github.com/yasinyaman/graphlore
cd graphlore
pip install -e ".[dev]"

Optional extras: [semble] (semantic locate + duplication scan), [treesitter] (non-Python span/API/route engines; usually already present via graphify), [tiktoken] (exact token counts), [watch] (filesystem watcher).

Related MCP server: repo-graphrag-mcp

Running

GRAPHLORE_PROJECT_DIR=/path/to/repo graphlore
# equivalently:
GRAPHLORE_PROJECT_DIR=/path/to/repo python -m graphlore

Renamed from graphify-mcp: the old name collided with the graphify-mcp console script that graphifyy ships for its embedded server, which forced the clunky graphify-mcp-server entry point. As graphlore the bare command is ours. The boot banner on stderr (graphlore vX.Y.Z | transport=… | project=…) confirms which server and project dir you're actually running.

Claude Code

Copy mcp.json to a .mcp.json at your project root. GRAPHLORE_PROJECT_DIR: "." uses the project root.

Claude Desktop / Cowork

Add the contents of claude_desktop_config.json to your Claude Desktop config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Transport (stdio default, optional HTTP)

stdio is the default and the right choice for a per-developer local server. To serve over HTTP instead (e.g. a shared graph for a team or a web MCP client):

GRAPHLORE_TRANSPORT=streamable-http GRAPHLORE_HOST=127.0.0.1 GRAPHLORE_PORT=8000 \
  GRAPHLORE_PROJECT_DIR=/path/to/repo graphlore

Any HTTP transport force-enables path containment (GRAPHLORE_RESTRICT_PATHS) so a network client can't drive graphlore_build to extract arbitrary filesystem paths. HTTP binds 127.0.0.1 by default. To expose it beyond localhost, set GRAPHLORE_API_KEY — every request must then send Authorization: Bearer <key> (constant-time checked, 401 otherwise); binding a non-loopback host without a key prints a warning.

When bound to a loopback host, the MCP SDK auto-enables DNS-rebinding protection: only Host: 127.0.0.1 / localhost / ::1 requests are accepted. A reverse proxy in front (nginx/caddy on a public name forwarding to 127.0.0.1) must therefore rewrite the Host header — or set GRAPHLORE_ALLOWED_HOSTS to the public name(s) (comma-separated, :* port wildcards allowed; * disables the protection for a trusted proxy).

The CLI is always invoked as an argument list with no shell (subprocess.run with shell=False), so a build path or query string can't inject shell commands. Per-file analyzers (spans/APIs/routes/fetch) are confined to the project directory through a single path-resolution boundary, so a hostile path in a graph or chunk can't read files outside the project. For a shared/network deployment, also consider lowering GRAPHLORE_TIMEOUT (default 600s) so a single slow graphlore_build can't tie up a worker for ten minutes.

GRAPHLORE_TRANSPORT=streamable-http GRAPHLORE_HOST=0.0.0.0 GRAPHLORE_API_KEY=$(openssl rand -hex 16) \
  GRAPHLORE_PROJECT_DIR=/path/to/repo graphlore

For a smaller tool surface (helps some models pick the right tool), set GRAPHLORE_TOOLSET=lean to expose only the core exploration tools — or GRAPHLORE_TOOLSET=locate for the minimal locate-first surface: orient with one graphlore_locate call, hydrate code with graphlore_fetch, stay in sync with graphlore_build/graphlore_freshness. locate needs a semantic backend (the [semble] extra or GRAPHLORE_SEMANTIC_BACKEND) and falls back to lean without one.

Tools

CLI-backed (the first two write state; the rest are read-only):

Tool

Purpose

graphlore_build

Build/update the graph (update, cluster_only, code_only, mode="deep")

graphlore_add

Add a source by URL (arXiv, tweet)

graphlore_query

Natural-language query (dfs, budget)

graphlore_path

Exact path between two nodes

graphlore_explain

Everything about a node

graph.json analysis (read-only, no CLI needed, as_json=True for structured output):

Tool

Purpose

graphlore_overview

Call first — size, god nodes, communities, surprises, suggested next steps

graphlore_god_nodes

Most connected nodes

graphlore_communities

Leiden community summaries

graphlore_surprises

Unexpected cross-file connections — listed from the graph's own flags when it has them, otherwise computed by scoring cross-file edges (confidence, file-type/directory/community crossing), with resolver noise and test↔source coupling suppressed; says plainly when nothing is computable rather than printing an empty list

graphlore_search

Node search

graphlore_neighbors

1-hop neighbors of a node

graphlore_subgraph

Token-budgeted BFS subgraph around a node — the cheap way to feed the model just the relevant slice (Graphify's embedded server does this too; pairing it with fetch/locate is what's specific here)

graphlore_impact

Reverse-dependency / blast radius — what breaks if a node changes (direction=dependents/dependencies/both), filterable by relation (relations="calls", "code", "imports", "types"), ordered by hop distance, each row carrying the recorded reference site

graphlore_node_details

Node metadata: type, source file/line, docstring, community

graphlore_skeleton

def/class signatures (decorators kept, bodies stripped) for a file/node/community — the middle layer between the map and full code

graphlore_fetch

Token-budgeted source hydration — reads the real code for a node (its enclosing def/class span ± context), the map→code other half of subgraph/locate

graphlore_freshness

Is the graph stale vs. git HEAD? Returns recommended_action (fresh/update/rebuild) + reason — lingering phantom nodes / large changes steer to a rebuild; junk files (.DS_Store, logs) land in non_source_changes and never hold the graph stale

graphlore_diff

Structural changeset between two git refs (default HEAD~1..HEAD) — added/removed/renamed/modified, with cosmetic-only changes separated (file-level, for review/audit)

graphlore_prune

Drop phantom nodes (and their edges) for deleted/renamed source files — the surgical alternative to a full rebuild (dry_run=True to preview)

graphlore_validate

Lint the graph for dangling/duplicate/self-loop edges and orphan nodes (read-only)

graphlore_duplication_scan

Repo-wide hidden-link / duplication audit — the batch form of locate's hidden_links (similar-but-structurally-far pairs); needs [semble], outside lean

graphlore_cycles

Circular dependencies — strongly-connected node groups in the directed graph (an architectural smell), self-loops listed separately

graphlore_package_apis

Symbol-level external API surface — which names each external package is actually used for (fastapi: Depends, APIRouter), with qualified paths (numpy.linalg.norm) for version-diff audits; a lower bound (dynamic/star/getattr use is invisible). Python via stdlib ast; JS/TS, Go, Java need [treesitter]

graphlore_routes

Framework route → handler table — which URL patterns hit which code, joined back to graph nodes (GET /items/{id} -> read_item (app.py:5)). FastAPI/Flask/Sanic/Quart/Litestar/Django, Express/NestJS (import-gated, so axios.get('/x') never registers), gin/chi/net-http (incl. Go 1.22 "GET /x" patterns, gin 3-arg Handle, chi nesting), Spring (method arrays split per verb); a lower bound (dynamic/chained registration is invisible). Python via stdlib ast; the rest need [treesitter]

Semantic naming (uses the host model via MCP sampling — no API key — or a backend key):

Tool

Purpose

graphlore_sampling_status

Capability test: reports whether the client supports host-LLM sampling, whether a backend key is set, and which method will be used

graphlore_label_communities

Give Leiden communities human-readable names. method="auto" (sampling → key → placeholder), "sampling", "cli", or "placeholder"

graphlore_set_labels

Persist assistant-provided community names (sampling-free fallback) to .graphify_labels.json and patch them into graph.html

Semantic bridge (optional [semble] extra — semantic search joined to graph structure):

Tool

Purpose

graphlore_locate

NL query → enclosing graph node → token-budgeted subgraph, plus hidden_links: semantically-similar code that is structurally disconnected (duplication / missing-abstraction candidates)

Typical workflow

  1. graphlore_locate("where do we retry failed requests?") — one-call orientation (or graphlore_overview() → graphlore_subgraph("SomeNode") without the semble extra)

  2. graphlore_fetch(["Client._send_single_request"]) — hydrate exactly the code you zeroed in on

  3. graphlore_impact("Response") / graphlore_cycles() / graphlore_routes() — targeted analysis

  4. graphlore_query("how does the auth flow work?") — free-form questions via the CLI

  5. After code changes: graphlore_freshness() → graphlore_build(update=True) (plus graphlore_prune() after deletes/renames)

Keeping the graph fresh

The analysis tools surface staleness for you: graphlore_overview and graphlore_subgraph carry a lightweight graph_age ("built 3 commits ago"), and graphlore_freshness gives a full recommended_action (fresh / update / rebuild). To stop thinking about it, regenerate on every commit with a git post-commit hook — the recommended first-class auto-update flow:

# .git/hooks/post-commit   (then: chmod +x .git/hooks/post-commit)
#!/bin/sh
# incremental, viz-free, backgrounded so the commit returns immediately
graphify . --update --no-viz >/dev/null 2>&1 &

Incremental --update only re-extracts changed files — it can't drop nodes for deleted/renamed code on its own. graphlore_prune closes that gap: it surgically removes the phantom nodes (and their edges) for source files that are gone from the working tree, so after a delete/rename you can graphlore_prune (preview with dry_run=True) + graphlore_build(update=True) instead of a full rebuild. graphlore_freshness knows about this — it only steers to a rebuild while phantom nodes for the removed files still linger, and reports them in phantom_files. An agent can also just call graphlore_build(update=True) when graph_age / graphlore_freshness says the graph drifted.

There's also an opt-in filesystem watcher (GRAPHLORE_WATCH=1, the [watch] extra): it re-syncs the graph on structural source changes, ignores cosmetic edits and non-source churn (VCS internals, virtualenvs, its own output), and debounces via GRAPHLORE_WATCH_DEBOUNCE.

Semantic bridge (optional [semble])

pip install "graphlore[semble]" adds graphlore_locate, which joins semble's semantic code search to the graph in one call. Graphify gives structure (how code connects); semble gives retrieval (which code is semantically relevant) — they're complementary.

graphlore_locate("how does retry backoff work"):

  1. semble finds the most relevant code and resolves the top hit to its enclosing graph node (better than label matching).

  2. returns the token-budgeted subgraph around it (structure).

  3. runs semble find_related and cross-checks: a cousin that is semantically similar but not within the seed's structural neighborhood is flagged as a hidden_link (with its hop distance) — a duplication / missing-abstraction / implicit-coupling candidate that neither tool surfaces alone.

The extra is optional: without it the core tools are unchanged and graphlore_locate returns an install hint. Any other embedding backend can be plugged in via GRAPHLORE_SEMANTIC_BACKEND=module.path:Factory (implementing search / find_related). It also pairs well with running semble's own MCP server alongside graphlore.

The chunk→node join and the freshness cosmetic-vs-structural check work across languages: Python uses the stdlib ast (no extra deps), and every other language (JS/TS, Go, Rust, Java, Ruby, C/C++, …) is handled by an optional tree-sitter backend — pip install "graphlore[treesitter]", also pulled in by graphify. Without it, non-Python files fall back to nearest-line matching.

Naming communities without an API key (MCP sampling)

The Leiden clustering is keyless, but turning Community 7 into Authentication needs a model. Three ways, in graphlore_label_communities's preference order:

  1. Host-LLM sampling — the server asks the connected client to run the completion via MCP sampling/createMessage. The model the user already uses (e.g. Claude in a sampling-capable client) does the naming; the server holds no API key. Subject to client support — call graphlore_sampling_status first; it degrades gracefully when unsupported. All communities are named in a single batched request, carried over whichever transport the negotiated protocol allows (the legacy back-channel, or input-required rounds on MCP 2026-07-28+), so it works with both older and modern clients.

  2. Backend API key (method="cli") — set GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / … (or run a local ollama) and graphify's own backend names them. This option always remains available.

  3. Placeholders — no model anywhere: names stay Community N.

If the client can't sample and you have no backend (e.g. Claude Code, which doesn't support sampling), use the assistant-driven fallback: the assistant is already a capable model in the loop, so it reads graphlore_communities and pushes names back via graphlore_set_labels({"0": "Authentication", ...}) — no key, no sampling, works in any client. The names persist to .graphify_labels.json and are patched into graph.html.

Benchmark

Averaged over 6 queries spanning httpx subsystems (send path, digest auth, redirects, content decoding, cookies, timeouts) on the 2,101-node graph. Each query orients an agent to a code area; tokens = what reaches the model's context (≈ chars/4).

Tokens to orient an agent across 6 httpx queries — lower is better

Approach

Tokens (avg)

Calls

Structure

Semantic

Hidden links

Naive 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

graphlore_locate averages 263× fewer tokens than grep+read and 11.6× fewer than running semble and graphify separately (one call instead of four) — and it's the only approach that surfaces hidden_links (semantically similar but structurally disconnected code), 5–10 per query.

Those ~235 tokens are a navigational map (seed file:line + structural neighborhood + hidden links), not raw code — you fetch the specific code only where needed. That's the trade graphlore optimizes: cheapest orientation plus the cross-check signal, then drill in precisely. The graphify alone row is its own token-budgeted subgraph output — the gap to 235 is the semantic seed (landing on the right node instead of a degree-sorted expansion), not a budgeting difference.

Case study — the hidden links are real. Asked "does httpx duplicate request-sending across sync and async?", graphlore_locate returned the seed Client._send_single_request and flagged hidden links. Checking the source confirmed every production flag is a genuine sync/async twin: Client._send_single_request (_client.py:1001) ↔ AsyncClient._send_single_request (:1717); BaseTransport.handle_request ↔ handle_async_request (in every transport); __enter__ ↔ __aenter__. ~500 tokens (one locate + a targeted read) surfaced a real architectural pattern that naively reading _client.py (~16k tokens) would. The far-distance bucket also held test files (related, not refactor targets) — the distance field separates production parallels (3–4) from that noise.

Across languages — real HTTP-client repos. The span join and freshness check aren't Python-only. I built AST-only graphs for an HTTP client in five more languages and ran the same kind of queries (send · redirects · timeout/retry · headers/auth · transport):

Span-join precision across languages — Python 96%, Go 93%, JS/TS 89%, Java 85%

Language

Repo

Span-join precision

Qualname

Hidden / q

locate vs grep

Calls (locate vs naive)

Python (ast)

encode/httpx

96% (52/54)

67%

3.2

272×

1 vs 15 (0 vs 14 reads)

JavaScript / TS

sindresorhus/got

89% (48/54)

67%

2.3

583×

1 vs 9 (0 vs 8 reads)

Go

go-resty/resty

93% (50/54)

100%

1.8

911×

1 vs 17 (0 vs 16 reads)

Java

square/retrofit

85% (46/54)

50%

2.3

217×

1 vs 18 (0 vs 17 reads)

Rust

algesten/ureq

70% (38/54)

83%

3.7

577×

1 vs 22 (0 vs 21 reads)

C++

libcpr/cpr

72% (39/54)

100%

4.3

195×

1 vs 16 (0 vs 15 reads)

Python uses the stdlib ast; JS/TS · Go · Java · Rust · C++ go through tree-sitter with automatic language detection — one tool, zero per-language config. Span-join precision = share of semantic hits landing inside the resolved symbol's real span (any overload of it — C++ collapses same-name overloads into one graph node while each keeps its own span; cpr's Session::SetOption has 46). It's 70–96% across six 350–2,095-node graphs, hidden-links keep surfacing 2–4/query, and locate stays 195–911× cheaper than grep+read. Orientation is also one tool call with zero file reads by construction, where the grep-driven baseline spends 9–22 calls opening 8–21 files per query — 89–95% fewer calls, on the same grep baseline as the token numbers. Rust and C++ trail at 70–72% — their misses are mostly file-top/whole-file chunks and namespace-level free functions where the resolution is still correct (they recover qualified names at 83–100%). graphlore_freshness's cosmetic-vs-structural check is correct in every language too (comment/reformat → cosmetic; operator/rename → structural). Re-measured 2026-08 on the MCP v2 SDK, Python 3.14, fresh repo HEADs. Reproduce with benchmarks/multilang.py (--json persists a run; benchmarks/results-multilang.json is the committed record of the call/token baseline — its span-join counts predate the overload-family re-count above).

→ Full benchmark report (interactive HTML, per-query breakdown + the cross-language tables) — or open docs/benchmark.html locally. (Türkçe)

httpx headline measured 2026-06 with semble 0.3.4 (6 queries, per-query locate 189–286 tokens); cross-language table re-measured 2026-08 with semble 0.5.5 + the tree-sitter span backend — 6 queries × 54 hits each on httpx / got / resty / retrofit / ureq / cpr, call counts from the same run. Sample bias: every repo benchmarked here is an HTTP-client library — a deliberately uniform family chosen for cross-language comparability. Token savings and span-join precision will differ on other architectures (data pipelines, GUI apps, sprawling monorepos), so treat these as indicative, not guarantees. Numbers vary by codebase and query.

Resources

  • graphlore://report — GRAPH_REPORT.md

  • graphlore://graph — graph.json (raw)

  • graphlore://community/{id} — per-community wiki (members + internal/boundary edges)

Prompts

Reusable templates that orchestrate the tools for the assistant:

  • onboard — orient to the codebase (overview → communities → subgraphs → surprises → summary)

  • trace_bug(symptom) — find likely root-cause locations through the graph

  • explain_flow(flow) — end-to-end walkthrough of a named flow with file:line refs

LLM-friendliness

  • Tool annotations (read_only_hint, destructive_hint, titles) tell the model which tools are safe to call freely vs. which mutate state.

  • Server instructions describe the recommended flow (locate/overview → targeted subgraph/fetch → build update).

  • as_json output on every analysis tool — including error and no-match paths — returns structured data the model can chain on instead of re-parsing prose.

  • Token budgeting on source, not just structure — budgeted subgraph rendering is Graphify's own (its embedded server does the same); graphlore extends the discipline to code: graphlore_fetch and graphlore_skeleton hydrate real spans under a cap, so escalating map → signatures → source never blows the context.

  • Unambiguous names — when several nodes share a bare label (five .auth_flow()s across auth classes), rendered output qualifies them with the span-recovered FQN (DigestAuth.auth_flow()) or a file:line suffix, so an arrow always names exactly one symbol.

  • Host-LLM sampling (graphlore_label_communities) lets the server borrow the client's model via MCP sampling/createMessage, so semantic naming works with no server-side API key — with a capability test (graphlore_sampling_status) and a backend-key fallback.

Environment variables

Variable

Default

Description

GRAPHLORE_PROJECT_DIR

.

Project root to extract the graph from

GRAPHLORE_OUT_DIR

graphify-out

Output folder name

GRAPHLORE_BIN

graphify

CLI path

GRAPHLORE_TIMEOUT

600

CLI timeout (seconds)

GRAPHLORE_RESTRICT_PATHS

0

Confine graphlore_build's path to the project dir (auto-on for HTTP)

GRAPHLORE_TRANSPORT

stdio

stdio | streamable-http | sse

GRAPHLORE_HOST

127.0.0.1

Bind host for HTTP transports

GRAPHLORE_PORT

8000

Bind port for HTTP transports

GRAPHLORE_API_KEY

(unset)

Require Authorization: Bearer <key> on HTTP transports

GRAPHLORE_ALLOWED_HOSTS

(unset)

DNS-rebinding Host allowlist for HTTP (comma-separated, :* port wildcards; * disables). Unset = SDK default: loopback-only when bound to loopback

GRAPHLORE_TOOLSET

full

full | lean (core exploration tools only) | locate (minimal locate-first surface; falls back to lean without a semantic backend)

GRAPHLORE_TOKENIZER

(heuristic)

tiktoken → exact token counts (needs the [tiktoken] extra); else chars/3.5 estimate

GRAPHLORE_SEMANTIC_BACKEND

semble

Semantic index: semble, or module.path:Factory implementing search/find_related (validated at boot)

GRAPHLORE_WATCH

0

Filesystem watcher: auto re-sync on structural changes ([watch] extra)

GRAPHLORE_WATCH_DEBOUNCE

2.0

Watcher debounce window (seconds)

Every variable is also honored under its legacy GRAPHIFY_* spelling (the pre-rename names); when both are set, GRAPHLORE_* wins. Artifacts of the wrapped Graphify CLI keep their own names regardless (graphify-out/, .graphify_labels.json, the graphify binary).

Project layout

graphlore/
├── src/graphlore/          # package
│   ├── server.py           #   MCP server: 28 tools, prompts, resources, transports
│   ├── graph.py            #   graph.json loading, node/edge accessors, BFS, adjacency
│   ├── spans.py            #   span engine: ast + tree-sitter, chunk→node join, structural diff
│   ├── apis.py             #   symbol-level external-API extraction
│   ├── routes.py           #   framework route → handler extraction
│   └── config.py           #   project dir / out dir
├── tests/                  # pytest suite (in-process MCP client + unit tests)
├── benchmarks/             # multilang benchmark + committed results JSON
├── docs/                   # benchmark reports (HTML/SVG)
├── .claude/skills/         # graphlore-explore skill for Claude Code
├── .github/workflows/      # CI: ruff + mypy + pytest on py 3.10–3.12
├── mcp.json                # Claude Code example config
└── claude_desktop_config.json

Development

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

See CONTRIBUTING.md. 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).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
authorNo
contributorNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the additive nature and the http/https constraint. Annotations indicate destructiveHint=false, which aligns with adding. However, it does not explain whether the addition is permanent, if duplicates are checked, or what the response looks like.

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 extremely concise: two sentences plus a bullet list of arguments. It front-loads the purpose and constraints, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema, the description covers the core action. However, it could benefit from mentioning validation behavior or side effects on the graph. It is adequate but not thorough.

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?

With 0% schema description coverage, the description adds meaningful semantics for all three parameters: url is the source URL, author is the original author tag, contributor is the tag for who added it. This compensates for the lack of schema descriptions, though it could provide more format details.

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 verb 'Add' and the resource 'external source to the graph', with concrete examples (arXiv paper, tweet) and a protocol constraint (http/https only). It distinguishes this tool from siblings by its unique function of adding external sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it specify prerequisites or exclusions. The usage is implied by the name, but there is no contextual advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNo.
modeNo
updateNo
cluster_onlyNo
no_vizNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=false, and the description adds behavioral details: writing to graphify-out/, incremental update behavior, and optional skip of visualization. This goes beyond what annotations alone provide, though it lacks information on auth or rate limits.

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 well-structured with an Args list, front-loaded with the main purpose. It is slightly verbose but every sentence adds value. Could be tightened slightly but remains efficient.

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 0% schema coverage and 5 parameters, the description covers all key inputs and the primary output (graphify-out/). The presence of an output schema means return values need not be explained. The description is complete enough for correct tool selection and 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 description coverage is 0%, but the description compensates fully by explaining each parameter: path, mode (deep vs empty), update (re-extract changed files), cluster_only (rerun clustering), and no_viz (skip HTML). This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Build or update' and the resource 'knowledge graph from a folder', including the output destination. It is specific enough to differentiate from some siblings like graphify_add, though it doesn't explicitly contrast with all siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains parameter modes (deep, update, cluster_only, no_viz) with brief guidance on when to use each. However, it does not provide explicit context on when to use this tool versus alternatives like graphify_add or graphify_query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_communitiesB
Read-only

Summarize Leiden communities with sizes and sample members.

ParametersJSON Schema
NameRequiredDescriptionDefault
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, so the agent knows it's safe. The description adds no extra behavioral context beyond that.

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 very short and to the point. It could be slightly more informative but is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple structure (one boolean param, output schema exists), the description is adequate but lacks guidance on usage and parameter semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should explain the 'as_json' parameter but does not. The parameter name gives some hint, but no extra meaning is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Summarize Leiden communities with sizes and sample members' clearly states the action and output. It distinguishes from siblings like graphify_label_communities, but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when or when not to use this tool. The description lacks context for selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_explainC
Read-only

Return everything Graphify knows about a node.

ParametersJSON Schema
NameRequiredDescriptionDefault
nodeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, so the tool is safe. The description adds 'Return everything Graphify knows', which implies it may be expensive or broad, but no further behavioral traits are disclosed (e.g., what 'everything' includes). Given the annotation covers safety, a score of 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but lacks structure. It front-loads the purpose but omits details that would be helpful. It could be improved by adding a brief note on the parameter and perhaps a usage hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, the description does not need to explain return values. However, with multiple sibling tools and a vague 'everything' claim, the description is minimally complete. It tells the agent what the tool does but not enough to differentiate or set expectations fully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, meaning the parameter 'node' has no description in the schema. The description does not explain what the parameter expects (e.g., node name, ID, format). It only implies it refers to a node. This is insufficient for an agent to correctly invoke the tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Return everything Graphify knows about a node' clearly states the action (return) and the resource (everything about a node). It distinguishes from sibling tools like graphify_node_details or graphify_neighbors, which imply more focused queries, but does not explicitly differentiate. The purpose is clear but could be more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not specify when to use this tool versus other similar tools such as graphify_node_details or graphify_search. There is no guidance on prerequisites, limitations, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as readOnlyHint=true, and the description adds behavioral context: it uses built_at_commit over mtime, handles modified and untracked files, and flags staleness. This complements the annotations without contradiction.

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 concise (two sentences), front-loaded with the core purpose, and every sentence adds value. No extraneous information.

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 tool's simplicity (1 optional param, 0 required) and the presence of an output schema, the description covers the essential behavior. It explains the staleness check logic and recommends next steps, though it could briefly mention that output includes a boolean result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter (as_json) with no description (0% schema_description_coverage). The tool description does not mention this parameter or its effect on output, so it provides no added value over 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 clearly states the tool checks whether graph.json is stale relative to the current git HEAD. It uses a specific verb ('check') and resource ('graph.json staleness'), and distinguishes itself from sibling tools by recommending graphify_build(update=True) if stale.

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 explains that it prefers built_at_commit over file mtime, and recommends graphify_build(update=True) if stale. This provides clear guidance on when to use and what to do next, though it lacks explicit exclusions or alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_god_nodesB
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
top_nNo
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, consistent with listing. Description adds the concept of 'god nodes' and highest-degree ordering, but no extra behavioral traits (e.g., pagination, data freshness). Minimal added value beyond annotations.

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?

Single sentence, concise and front-loaded. Efficient but could add slight detail without losing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, covering return structure. Description explains the core concept. However, with 0% schema coverage and no parameter explanations, an agent may lack complete information for invocation, especially for 'as_json' and 'top_n' semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description does not explain parameters. 'top_n' and 'as_json' meanings are absent. The description only mentions 'highest-degree' without linking to parameters.

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?

Description uses specific verb 'list' and resource 'god nodes', clearly defining them as 'highest-degree (most connected)' nodes. This distinguishes it from siblings like graphify_neighbors or graphify_node_details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Does not mention context like global scope or preconditions. Among many sibling graph tools, explicit usage notes are lacking.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
methodNoauto
limitNo
sample_sizeNo
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-destructive and non-read-only behavior. The description adds value by explaining that host-LLM sampling may be used without an API key, that names are generated with cost implications, and that only the largest communities are named. It does not disclose if the tool modifies the graph permanently or any rate limits, but overall adds useful behavioral context beyond annotations.

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 concise, with a single opening sentence stating purpose, then a clear bullet-style list for each parameter. No unnecessary text or repetition. Every sentence adds value.

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 tool's complexity (4 optional parameters with defaults) and the presence of an output schema, the description covers the main inputs and behavior well. However, it does not mention prerequisites (e.g., need for an existing graph or communities) or the exact side effect of naming (whether it persists or is ephemeral). Still, it is largely complete for typical 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?

The description adds significant meaning to three of the four parameters ('method', 'limit', 'sample_size'), explaining their options, defaults, and behavioral effects. However, the 'as_json' parameter is not mentioned at all, leaving its purpose unclear. Since schema coverage is 0%, the description compensates well for most but not all parameters.

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's purpose: 'Give the Leiden communities human-readable names.' It uses a specific verb ('give') and resource ('communities'), and the outcome is clear. Among siblings like graphify_communities (which likely lists or computes communities) and graphify_build, this tool uniquely handles naming, providing good differentiation.

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 detailed guidance on the 'method' parameter, explaining when to use 'auto', 'sampling', 'cli', or 'placeholder', including fallback logic and cost considerations for 'limit'. However, it does not explicitly state when to use this tool versus alternatives (e.g., other graphify tools) or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_neighborsC
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
nodeYes
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, so description adds minimal behavioral context beyond 'with relations'. Does not disclose behavior for missing nodes, format of output, or any side effects. Schema coverage is 0%, so description bears more burden but fails to provide sufficient detail.

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?

Single concise sentence with no wasted words. However, the brevity leaves significant gaps in clarity. It is appropriately front-loaded but would benefit from more detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema (unknown content), the description lacks context for parameters and does not specify what 'relations' means or how results are structured. The tool is simple, but with 0% schema coverage, the description should compensate more.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain what 'node' should be (e.g., ID, name) or what 'as_json' does. The agent receives no guidance on parameter values beyond the schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists direct (1-hop) neighbors with relations, using a specific verb and resource. It distinguishes from sibling tools like 'graphify_node_details' or 'graphify_path' by specifying 'neighbors', but lacks explicit comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool over alternatives. Does not mention any context where it is appropriate or inappropriate, nor reference sibling tools for different needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_node_detailsC
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
nodeYes
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds context about the type of metadata returned (type, source file/line, docstring, community), which is beyond the readOnlyHint annotation. However, it does not disclose error conditions, performance implications, or whether the node must exist in a built graph.

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 a single sentence with no wasted words. It efficiently conveys the tool's purpose, though it could be slightly expanded with parameter details without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the schema lacks descriptions and there is no output schema shown, the description should provide more context about usage and return values. It is too brief to fully inform an AI agent about the tool's behavior and prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not explain the parameters 'node' or 'as_json' at all. With 0% schema description coverage, the description fails to add meaning beyond the parameter titles and types. For example, it does not clarify expected format of 'node' or impact of 'as_json'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool shows a node's full metadata including type, source file/line, docstring, and community. This is specific and actionable, but it does not differentiate from sibling tools like graphify_neighbors or graphify_overview, which could overlap in purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus its siblings. The description lacks context about prerequisites, when not to use it, or which alternative tools might be more appropriate for related tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
top_nNo
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true; the description adds context that it is a lightweight, cheap call for orientation, which is consistent and provides additional behavioral insight beyond annotations.

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?

Very concise and front-loaded; first sentence is clear and imperative, and every sentence adds value without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/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, the description adequately lists return values, but fails to describe input parameters, making it incomplete for a tool with undocumented parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not explain the two parameters (top_n, as_json) or their meaning, leaving the AI agent without guidance on parameter values despite having defaults.

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?

Clearly states the tool's purpose as a one-shot orientation to call first, listing specific outputs (graph size, top god nodes, community count, etc.) and differentiates from sibling tools by positioning it as the initial cheap exploration call.

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?

Explicitly instructs to call this tool first and describes it as a one-shot orientation for cheap planning, but does not specify when not to use it or mention alternative tools by name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_pathB
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
node_aYes
node_bYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. The description adds minimal extra behavioral context beyond 'exact path', without explaining the algorithm or constraints.

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?

Single sentence with example, front-loaded and efficient without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Has output schema covering return values, but lacks parameter descriptions. For a simple two-param tool, it is somewhat incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It does not describe parameters node_a and node_b beyond the example, adding no semantic value.

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 it finds the exact path between two nodes, with a concrete example. This distinguishes it from siblings like graphify_neighbors or graphify_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing a path between two specific nodes, but lacks explicit guidance on when not to use it or alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
questionYes
dfsNo
budgetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the agent knows it's safe. The description adds valuable behavioral details: dfs enables depth tracing, budget caps tokens. This goes beyond the title 'Query graph' in annotations.

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 concise: one sentence for purpose, then parameter docs. No superfluous text. Front-loaded with the main action.

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 presence of an output schema (handling return values), the description adequately covers all input parameters and basic behavior. For a 3-param tool with low schema coverage, this is sufficient.

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 description coverage is 0%, placing full burden on the description. It explains all three parameters: question with an example, dfs as depth tracing, budget as token cap. This adds significant meaning beyond the schema's bare types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Run' and the resource 'natural-language query against the graph,' distinguishing it from sibling tools like graphify_search or graphify_explain which have different query modes. However, it does not explicitly contrast with siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. The description only explains parameters, not usage context or exclusions. For example, it does not say 'use this for natural language queries; use graphify_search for keyword search.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds detailed behavioral context beyond the readOnlyHint annotation by specifying exactly what status is reported (client support, API key configuration, and impact on graphify_label_communities). No contradictions with annotations.

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 concise (three sentences) and front-loaded with 'Capability test'. However, it could be slightly more structured (e.g., listing what is reported). Minimal waste.

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 tool's simplicity (one boolean parameter, readOnly annotation, and output schema), the description sufficiently covers what the tool does and its output meaning, including the relation to graphify_label_communities. It is complete for its purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description does not explain the single parameter 'as_json'. The parameter name is self-explanatory, but the description adds no value beyond the schema, failing to compensate for the low coverage.

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 reports whether the client supports host-LLM sampling, whether a backend API key is configured, and which method graphify_label_communities will pick. This is a specific verb+resource combination and distinguishes itself from siblings by focusing on sampling/LLM status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Capability test' implying it's used to check sampling capabilities, but it does not explicitly state when to use it vs. alternatives or when not to use it. The usage context is implied but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nodeYes
hopsNo
budget_tokensNo
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. The description adds that it uses BFS, caps tokens, and supports fuzzy matching, but does not disclose behavior on budget exceedance, missing nodes, or the output format beyond what the output schema provides.

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 concise with two sentences and a bulleted args list. It is front-loaded and well-structured, though the args section could be integrated more seamlessly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers core functionality and parameters but misses details on the 'as_json' parameter and error handling. The presence of an output schema reduces the need to explain return values, but extra context would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains node, hops, and budget_tokens, but omits the 'as_json' parameter entirely. This incomplete coverage lowers the score.

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 it extracts a BFS subgraph around a node with a token budget. This specific verb+resource is distinct from sibling tools, and the phrase 'token-cheap way to hand the model just the relevant slice' further differentiates it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for obtaining a relevant subgraph slice versus the whole graph, but it lacks explicit guidance on when not to use it or alternatives among the 15 siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

graphify_surprisesC
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
as_jsonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, indicating safe read. The description adds minimal behavioral context beyond the purpose, not expanding on what 'unexpected' means or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Despite being concise (one sentence), it omits essential details about parameters and usage, making it under-specified rather than effectively concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 16 sibling tools and 2 parameters with no description, the description fails to provide sufficient context for an agent to correctly select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no explanation of parameters like 'limit' or 'as_json'. This is a critical gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists unexpected cross-file/cross-domain connections (surprise edges), specifying the verb 'list' and the unique resource type. However, it does not differentiate from siblings like graphify_neighbors or graphify_communities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not mention when not to use it or provide context about typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
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
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

Related MCP Servers

  • CodeRAG

    JonnoC
    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.
    27
    MIT

  • kg-memory-mcp

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

  • Graph-Mem MCP

    Sathvik-1007
    A
    license
    Not graded
    quality
    A
    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

Latest Blog Posts

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/yasinyaman/graphlore'

If you have feedback or need assistance with the MCP directory API, please join our Discord server