使用说明

kgraph🧠

代码库的知识图谱

kgraph 是一个功能强大的模型上下文协议（MCP）服务器，它将您的代码库索引到知识图中，为LLM代理提供语义搜索、精确的代码导航和影响分析。

与简单的文本搜索或grep不同， kgraph 理解结构允许代理回答复杂的问题，如“谁调用这个函数？”或“如果我更改这个类会发生什么？”。

✨ 特性

语义搜索：按含义查找代码（“身份验证中间件”），而不仅仅是关键字。使用LanceDB进行矢量搜索。
精确导航：跳转到定义，使用树保姆解析以100%的准确率查找引用。
结构分析：立即理解文件大纲（类、方法、钩子）。
影响分析: validate_edit 工具检查语法错误和破坏性更改之前您可以应用编辑。
React/TypeScript支持：对现代web框架（组件、钩子、JSX）的一流支持。
多语言：支持Python、JavaScript、TypeScript、Java等。

🚀 安装

先决条件

Python 3.10或更高版本
uv （推荐）或 pip

使用紫外线进行安装（推荐）

# Install directly from source
uv tool install --force --editable .

使用pip安装

pip install .

⚡ 快速开始

启动服务器: 使用MCP客户端（见下文）或直接运行服务器进行测试：
```
kgraph
```
索引您的代码库: 你第一次使用 kgraph 在项目上，您必须对其进行索引：
- 使用 reindex_codebase 带有项目路径的工具。
- 例子： reindex_codebase(root_path="/path/to/my/project")

🛠️ MCP工具

kgraph 向MCP客户端公开以下工具：

🔍 搜索和导航

search_code(query, limit=5, file_type="")
- 执行混合搜索（语义+关键字）以查找相关代码片段。
- 非常适合：“查找用户身份验证逻辑”或“付款在哪里处理？”
find_definitions(name)
- 定位定义类、函数或组件的位置。
- 返回文件路径、行号和docstring。
find_references(name)
- 查找符号的所有用法（调用、导入、继承）。
- 对于重构和理解依赖关系至关重要。

📄 代码理解

get_structure(file_path)
- 返回文件的结构化大纲：导入、类、函数和方法。
- 支持React组件、钩子和事件处理程序。
get_usage_context(symbol)
- 检索符号的360°视图：定义+引用+传出调用。
- 针对LLM进行了优化，可一次性获得完整的上下文。
get_file_summary(file_path)
- 返回文件的令牌高效摘要（仅限签名和文档字符串）。

🛡️ 验证

validate_edit(file_path, new_content)
- 验证拟议的代码编辑之前应用它。
- 检查：
  1. 语法错误：确保代码有效（支持JSX/TSX）。
  2. 突破性变化：如果删除其他文件使用的函数，则发出警告。
  3. 签名更改：如果更改其他地方使用的函数签名，则发出警告。

⚙️ 管理

reindex_codebase(root_path)
- 扫描并索引代码库。在最初和重大更改后运行此程序。
- 创建一个 .kgraph 项目根目录中的目录。

🔌 MCP客户端配置

克劳德桌面版

将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "kgraph": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "kgraph"
      ]
    }
  }
}

光标/其他客户端

如果您的客户端支持stdio MCP服务器，请使用：

命令: uv
参数: tool run kgraph

🏗️ 建筑

kgraph 使用混合存储方法：

SQLite：存储结构图（节点：文件、函数、类；边：导入、调用、定义）。
LanceDB：存储用于语义搜索的代码片段的向量嵌入。
树保姆：用于对源代码进行稳健、容错的解析。

📝 许可证

麻省理工学院