Grafyx
Grafyx is an MCP server that provides real-time codebase understanding for AI coding assistants by parsing your project into a semantic graph and exposing 14 tools for architecture analysis, code inspection, and natural language search.
Project Structure & Navigation
get_project_skeleton– Full project skeleton with file tree and statistics.get_module_context– Symbols overview in a directory/package with pagination.get_file_context– Comprehensive context for a file: functions, classes, imports, relationships.
Function & Class Insights
get_function_context– Detailed context for a function: signature, callers, callees, dependencies.get_class_context– Class details: methods, inheritance chain, usages.get_subclasses– Find all subclasses of a base class recursively.
Dependency & Impact Analysis
get_call_graph– Recursive call chain tracing (callers/callees).get_dependency_graph– Dependency mapping for impact analysis.get_unused_symbols– Detect dead code (functions/classes with no inbound references).
Search & Discovery
find_related_code– Natural language semantic search for related functions, classes, files.find_related_files– Find files relevant to a concept/feature using ML embeddings.
Code Quality & Conventions
get_conventions– Detect coding patterns and conventions used in the codebase.
Runtime Management
set_project– Switch the analyzed project directory at runtime.refresh_graph– Force a full re-parse of the codebase graph.
The server automatically watches files and updates the graph in real time, keeping code understanding current.
Integrates with Windsurf (Codeium) to deliver codebase relationship graph analysis and live updates through MCP.
Enables GitHub Copilot in VS Code to access codebase structure, function context, and dependency graphs via MCP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Grafyx get the call chain for the main function"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Grafyx
Real-time codebase understanding for AI coding assistants.
What is Grafyx?
AI coding tools read raw files with zero architectural understanding -- they don't know what calls what, which classes inherit from where, or how your modules connect. Grafyx fixes this by parsing your entire codebase into a full relationship graph using Graph-sitter (built on tree-sitter), then exposing that graph to any AI assistant through the Model Context Protocol (MCP). Your assistant can trace call chains, map dependencies, find related code by description, detect conventions, and understand your project's architecture -- all in real time, with a file watcher that keeps the graph current as you edit.
Related MCP server: tree-sitter-analyzer
Quick Start
Claude Code
# Zero-install (recommended)
claude mcp add --scope user grafyx -- uvx --from grafyx-mcp grafyx
# Or install with pip first
pip install grafyx-mcp
claude mcp add --scope user grafyx -- grafyxCursor / Windsurf / Cline
Add to your MCP config file:
Cursor:
.cursor/mcp.json(project) or~/.cursor/mcp.json(global)Windsurf:
~/.codeium/windsurf/mcp_config.jsonCline: Cline MCP settings in VS Code
{
"mcpServers": {
"grafyx": {
"command": "uvx",
"args": ["--from", "grafyx-mcp", "grafyx"]
}
}
}VS Code (GitHub Copilot)
Add to .vscode/mcp.json:
{
"servers": {
"grafyx": {
"command": "uvx",
"args": ["--from", "grafyx-mcp", "grafyx"]
}
}
}Using pip instead of uvx? Replace the command with:
"command": "grafyx"(no args needed).
Available Tools
Tool | Description |
| Full project structure with stats per module |
| Everything about a function: callers, callees, deps |
| File contents, imports, dependencies |
| Class methods, inheritance, usages |
| Natural language search across the codebase |
| Find files relevant to a feature by matching symbols |
| Impact analysis: what depends on what |
| Detected coding patterns and conventions |
| Call chain tracing upstream and downstream |
| Force re-parse of the codebase |
| Symbols in a directory/package (intermediate zoom) |
| Inheritance tree for a base class |
| Dead code detection |
| Switch the served project at runtime |
How It Works
Your AI Assistant
|
| MCP Protocol (stdio)
v
+-----------+
| Grafyx | FastMCP server with 14 tools
| Server |
+-----------+
|
+-----------+ +-----------+ +-------------+
| Graph |---->| Search | | Convention |
| Engine |---->| Engine | | Detector |
+-----------+ +-----------+ +-------------+
|
v
+-----------+
| Graph- | Tree-sitter based parsing
| sitter |
+-----------+
|
+-----------+
| Watchdog | File watcher for live updates
+-----------+Startup -- Grafyx detects languages in your project and parses all source files into a semantic graph via Graph-sitter.
Serving -- The FastMCP server exposes 14 tools over stdio. Your AI assistant calls them as needed.
Live updates -- Watchdog monitors file changes. When you save, the graph is automatically re-parsed after a short debounce.
ML-augmented search
Grafyx's find_related_code uses a pretrained code embedding model (default:
jinaai/jina-embeddings-v2-base-code, Apache-2.0, 161M params) running on CPU
via ONNX through fastembed. The model
is downloaded on first use and cached locally — no GPU, no daemon, no cloud
calls.
Since 0.2.1, fastembed is a hard dependency, so the default install
already includes the encoder — no extra needed.
Benchmark (0.2.0, 278 docstring→function queries across FastAPI + Django):
Encoder | nDCG@10 | MRR@10 | p50 latency |
jina-v2 (default) | 0.787 | 0.741 | ~1.5 s |
coderankembed | 0.663 | 0.623 | ~1.3 s |
tokens-only (no fastembed) | 0.335 | 0.297 | ~0.9 s |
The default encoder more than doubles retrieval quality over plain source-token search (+135% nDCG@10).
Full breakdown + per-query JSONL: docs/benchmarks/0.2.0/.
Switch encoders via the GRAFYX_ENCODER env var:
jina-v2(default) — Apache-2.0, fastembed-native, ~150 MB. Wins on accuracy; recommended unless you have a specific reason to switch.coderankembed— MIT, 137M, ONNX-int8, ~140 MB. Lower latency but ~12 nDCG@10 points behind jina-v2 in our eval. Hosted atBilal7Dev/grafyx-coderankembed-onnx.
Supporting numpy-only MLPs (~5 MB total weights, bundled in the wheel):
M1 Relevance ranker — 33-feature MLP that re-ranks the encoder's top candidates using structural signals (caller count, name overlap, exports).
M3 Source token filter — suppresses noise tokens (imports, strings, magic methods) from full-text search.
M4 Symbol importance — weights symbols by caller count, exports, and structural signals.
Gibberish detector — character-bigram MLP that blocks nonsense queries before they hit the index.
Reproducible benchmarks against FastAPI, Django, and Home Assistant ship in
benchmarks/ (python -m scripts.run_all).
Supported Languages
Language | Extensions |
Python |
|
TypeScript |
|
JavaScript |
|
Languages are auto-detected. To specify manually:
grafyx --languages python,typescriptOptions
grafyx [OPTIONS]
--project PATH Project to analyze (default: current directory)
--languages LANGS Comma-separated languages (default: auto-detect)
--ignore PATTERNS Additional directories to ignore
--no-watch Disable file watching
--verbose, -v Debug logging
--version Show versionDefault ignored: node_modules, .git, __pycache__, .venv, venv, .env, dist, build, .tox, .mypy_cache, .pytest_cache, .ruff_cache, egg-info, .eggs, .next, .nuxt, coverage, .coverage, .nyc_output
Multi-Agent Support
Grafyx works with agent teams. A single Grafyx instance serves all agents connected to the same project. When one agent modifies code, the file watcher updates the graph automatically, so other agents immediately see the changes.
Contributing
git clone https://github.com/bilal07karadeniz/Grafyx.git
cd Grafyx
pip install -e ".[dev]"
pytestTroubleshooting
Windows: Graph-sitter requires Linux. Use WSL and configure your MCP client to launch via wsl:
{
"mcpServers": {
"grafyx": {
"command": "wsl",
"args": ["-e", "bash", "-c", "source ~/your-venv/bin/activate && grafyx"]
}
}
}License
MIT -- see LICENSE for details.
Available Tools
14 toolsget_call_graphA
Get the call graph for a function: what it calls and what calls it, recursively up to the specified depth.
Supports 'ClassName.method_name' syntax (e.g., 'SkillManager.initialize'). If multiple functions share the same name, returns a disambiguation list.
Use this to trace execution flow and understand how a function fits into the larger call chain. By default, Python builtins and common stdlib methods (len, append, strip, etc.) are filtered out for clarity. Set include_builtins=True to see everything.
Inputs: function_name (required), depth, include_builtins. Returns: object
get_class_contextA
Get comprehensive context for a class: methods, properties, inheritance chain, and usages throughout the codebase.
Use this when you need to understand a class's interface and where it is used.
Inputs: class_name (required), detail, include_hints. Returns: object
get_conventionsA
Detect and report coding conventions used in this codebase.
Use this to understand the project's style BEFORE writing new code, so your additions are consistent with existing patterns.
Inputs: no named parameters. Returns: object
get_dependency_graphA
Get the dependency graph for a symbol: what it depends ON and what depends on IT, up to the specified depth.
Use this to understand the impact radius of changing a symbol.
Inputs: symbol_name (required), depth. Returns: object
get_file_contextB
Get comprehensive context for a file: functions, classes, imports, and relationships to other files.
Use this when you need to understand what a file contains and how it connects to the rest of the codebase.
Inputs: file_path (required), detail, include_hints. Returns: object
get_function_contextA
Get comprehensive context for a function: signature, parameters, callers, callees, dependencies, and docstring.
Supports 'ClassName.method_name' syntax (e.g., 'ToolExecutor.execute').
For two top-level functions sharing the same name in different
files (where ClassName.method doesn't apply), pass file_path
to pick one. If multiple matches remain, returns a disambiguation list.
Use this when you need to understand what a function does, who calls it, and what its blast radius is for modifications.
Inputs: function_name (required), detail, file_path, include_hints. Returns: object
get_module_contextA
Get an overview of all symbols in a directory/package.
This is the intermediate zoom level between get_project_skeleton (whole project) and get_file_context (single file). Use it to understand what a package contains before drilling into specifics.
Inputs: limit, detail, offset, module_path, +1 more. Returns: object
get_project_skeletonA
Get the full project structure with file tree and statistics.
Call this first when starting work on a project to understand its overall shape, module layout, and code distribution.
Inputs: detail, max_depth, include_hints. Returns: object
get_subclassesA
Find all classes that extend a given class, recursively.
Use this to understand the impact of changing a class's interface: which subclasses would need updating?
Supports multi-level inheritance trees up to the specified depth.
When the codebase has multiple classes sharing class_name (e.g.
Django defines Field in both contrib/gis/gdal/field.py and
db/models/fields/__init__.py), pass file_path to pick the
intended definition. Without it, the first match wins and the
response includes ambiguous: True plus a candidates list so
you can retry.
Inputs: class_name (required), depth, file_path. Returns: object
get_unused_symbolsA
Find functions and classes with zero inbound references (dead code detection).
Analyzes the caller index and import graph to identify symbols that are never called, subclassed, or referenced from other code.
Excludes common false positives: dunder methods, framework-decorated handlers, entry points, and exception classes.
Inputs: max_results, symbol_type, include_tests. Returns: object
refresh_graphA
Bring the codebase graph up to date with the code on disk.
Use this after making changes to the codebase, or if the graph seems stale. On mirrored (Windows-mount) projects the mirror is re-synced first and only the changed files are re-parsed (incremental, ~seconds); a full re-parse runs only when the change set can't be determined. Normally the file watcher handles this automatically on native projects.
Inputs: no named parameters. Returns: object
set_projectA
Set or change the project directory that Grafyx analyzes.
Call this when Grafyx reports 'No project loaded' — typically when running as a global MCP server. Pass the workspace root path.
After calling this, all other Grafyx tools will work on the specified project. Re-call with a different path to switch projects.
Inputs: project_path (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools are clearly scoped by level (project, module, file, function, class). Two pairs have conceptual overlap — find_related_code/find_related_files and get_dependency_graph/get_call_graph — but their descriptions clarify different output types (symbols vs files; dependencies vs call chains). Slight ambiguity remains when choosing between the graph tools for a function.
All 14 tools use lowercase verb_noun snake_case, with verbs limited to get/find/set/refresh. The pattern is consistent and predictable.
14 tools is within the ideal 3–15 range and each tool addresses a distinct analysis need, from setup (set_project) to refresh, to various context scopes and relationship queries. No tool feels unnecessary.
The server covers the full code-understanding lifecycle: set project, refresh graph, view skeleton, drill into modules/files/functions/classes, find related items, explore dependencies/calls, check conventions, and detect dead code/unused symbols. The only minor gap is a direct search-by-symbol-name tool, but find_related_code covers conceptual lookup.
Maintenance
Related MCP Connectors
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with a structured, token-efficient map of a codebase's symbols, dependencies, and relationships via MCP tools like overview, query, and impact analysis.9MIT
- AlicenseBqualityBmaintenanceAn MCP code-intelligence server for AI agents with pre-indexed AST cache, 62 MCP tools, and TOON-compressed output, enabling token-efficient code analysis and project health grading entirely locally.9256 PyPI61MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI-powered architecture analysis and visualization of codebases, exposing 17 MCP tools for querying components, dependencies, and generating interactive diagrams.6MIT
- AlicenseNot gradedqualityCmaintenanceProvides code intelligence for AI coding agents by indexing repositories into a hybrid knowledge graph, enabling agents to query dependencies, impact, and context through 28 MCP tools.4Apache 2.0