Knowledge Graph MCP Server

# 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_edit` tool 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) or `pip` ### Install with uv (Recommended) ```bash # Install directly from source uv tool install --force --editable . ``` ### Install with pip ```bash pip install . ``` ## ⚡ Quick Start 1. **Start the Server**: Run the server using an MCP client (see below) or directly for testing: ```bash kgraph ``` 2. **Index Your Codebase**: The first time you use `kgraph` on a project, you must index it: - Use the `reindex_codebase` tool with the path to your project. - Example: `reindex_codebase(root_path="/path/to/my/project")` ## 🛠️ 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: 1. **Syntax Errors**: Ensures code is valid (supports JSX/TSX). 2. **Breaking Changes**: Warns if you remove a function used by other files. 3. **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 `.kgraph` directory in your project root. ## 🔌 MCP Client Configuration ### Claude Desktop Add this to your `claude_desktop_config.json`: ```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