Skip to main content
Glama

Grafyx

PyPI Downloads CI License: MIT Python 3.12+ MCP Grafyx MCP server

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 -- grafyx

Cursor / Windsurf / Cline

Add to your MCP config file:

  • Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

  • Windsurf: ~/.codeium/windsurf/mcp_config.json

  • Cline: 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

get_project_skeleton

Full project structure with stats per module

get_function_context

Everything about a function: callers, callees, deps

get_file_context

File contents, imports, dependencies

get_class_context

Class methods, inheritance, usages

find_related_code

Natural language search across the codebase

find_related_files

Find files relevant to a feature by matching symbols

get_dependency_graph

Impact analysis: what depends on what

get_conventions

Detected coding patterns and conventions

get_call_graph

Call chain tracing upstream and downstream

refresh_graph

Force re-parse of the codebase

get_module_context

Symbols in a directory/package (intermediate zoom)

get_subclasses

Inheritance tree for a base class

get_unused_symbols

Dead code detection

set_project

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
  +-----------+
  1. Startup -- Grafyx detects languages in your project and parses all source files into a semantic graph via Graph-sitter.

  2. Serving -- The FastMCP server exposes 14 tools over stdio. Your AI assistant calls them as needed.

  3. Live updates -- Watchdog monitors file changes. When you save, the graph is automatically re-parsed after a short debounce.

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 at Bilal7Dev/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

.py, .pyi

TypeScript

.ts, .tsx

JavaScript

.js, .jsx

Languages are auto-detected. To specify manually:

grafyx --languages python,typescript

Options

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 version

Default 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]"
pytest

Troubleshooting

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 tools
get_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

    A4.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All 14 tools use lowercase verb_noun snake_case, with verbs limited to get/find/set/refresh. The pattern is consistent and predictable.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      9
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      An 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.
      9
      256 PyPI
      61
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI-powered architecture analysis and visualization of codebases, exposing 17 MCP tools for querying components, dependencies, and generating interactive diagrams.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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.
      4
      Apache 2.0