kgraph 🧠
Knowledge Graph for Codebases
kgraph is a powerful Model Context Protocol (MCP) server that indexes your codebase into a knowledge graph, enabling semantic search, precise code navigation, and impact analysis for LLM agents.
Unlike simple text search or grep, kgraph understands the structure of your code—classes, functions, imports, and calls—allowing agents to answer complex questions like "Who calls this function?" or "What happens if I change this class?".
✨ Features
- Semantic Search: Find code by meaning ("auth middleware") not just keywords. Uses LanceDB for vector search.
- Precise Navigation: Jump to definitions and find references with 100% accuracy using Tree-sitter parsing.
- Structure Analysis: Understand file outlines (classes, methods, hooks) instantly.
- Impact Analysis:
validate_edittool checks for syntax errors and breaking changes before you apply edits. - React/TypeScript Support: First-class support for modern web frameworks (Components, Hooks, JSX).
- Multi-Language: Supports Python, JavaScript, TypeScript, Java, and more.
🚀 Installation
Prerequisites
- Python 3.10 or higher
uv(recommended) orpip
Install with uv (Recommended)
# Install directly from source
uv tool install --force --editable .
Install with pip
pip install .
⚡ Quick Start
-
Start the Server: Run the server using an MCP client (see below) or directly for testing:
kgraph -
Index Your Codebase: The first time you use
kgraphon a project, you must index it:- Use the
reindex_codebasetool with the path to your project. - Example:
reindex_codebase(root_path="/path/to/my/project")
- Use the
🛠️ MCP Tools
kgraph exposes the following tools to MCP clients:
🔍 Search & Navigation
-
search_code(query, limit=5, file_type="")- Performs a hybrid search (Semantic + Keyword) to find relevant code snippets.
- Great for: "Find the user authentication logic" or "Where is the payment processed?"
-
find_definitions(name)- Locates where a class, function, or component is defined.
- Returns file path, line number, and docstring.
-
find_references(name)- Finds all usages of a symbol (calls, imports, inheritance).
- Essential for refactoring and understanding dependencies.
📄 Code Understanding
-
get_structure(file_path)- Returns a structured outline of a file: imports, classes, functions, and methods.
- Supports React components, hooks, and event handlers.
-
get_usage_context(symbol)- Retrieves a 360° view of a symbol: Definition + References + Outgoing Calls.
- Optimized for LLMs to get full context in one shot.
-
get_file_summary(file_path)- Returns a token-efficient summary of a file (signatures and docstrings only).
🛡️ Validation
validate_edit(file_path, new_content)- Validates a proposed code edit before applying it.
- Checks for:
- Syntax Errors: Ensures code is valid (supports JSX/TSX).
- Breaking Changes: Warns if you remove a function used by other files.
- Signature Changes: Warns if you change a function signature used elsewhere.
⚙️ Management
reindex_codebase(root_path)- Scans and indexes the codebase. Run this initially and after major changes.
- Creates a
.kgraphdirectory in your project root.
🔌 MCP Client Configuration
Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"kgraph": {
"command": "uv",
"args": [
"tool",
"run",
"kgraph"
]
}
}
}
Cursor / Other Clients
If your client supports stdio MCP servers, use:
- Command:
uv - Args:
tool run kgraph
🏗️ Architecture
kgraph uses a hybrid storage approach:
- SQLite: Stores the structural graph (Nodes: Files, Functions, Classes; Edges: IMPORTS, CALLS, DEFINES).
- LanceDB: Stores vector embeddings of code snippets for semantic search.
- Tree-sitter: Used for robust, error-tolerant parsing of source code.
📝 License
MIT