Grafyx

Grafyx

为 AI 编码助手提供实时代码库理解能力。

---

什么是 Grafyx？

AI 编码工具读取原始文件时完全不了解代码架构——它们不知道谁调用了什么、类继承自哪里，也不清楚模块之间如何连接。Grafyx 通过 Graph-sitter（基于 tree-sitter）将整个代码库解析为完整的关系图，从而解决这个问题；随后，它通过 Model Context Protocol (MCP) 将该图提供给任何 AI 助手。你的助手可以追踪调用链、映射依赖关系、按描述查找相关代码、检测约定，并理解项目架构——所有操作均实时进行，文件监视器还会在你编辑时持续更新关系图。

---

快速开始

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

将以下内容添加到 MCP 配置文件中：

• Cursor：.cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）
• Windsurf：~/.codeium/windsurf/mcp_config.json
• Cline：VS Code 中的 Cline MCP 设置

{
  "mcpServers": {
    "grafyx": {
      "command": "uvx",
      "args": ["--from", "grafyx-mcp", "grafyx"]
    }
  }
}

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json：

{
  "servers": {
    "grafyx": {
      "command": "uvx",
      "args": ["--from", "grafyx-mcp", "grafyx"]
    }
  }
}

使用 pip 而非 uvx？ 将 command 替换为："command": "grafyx"（无需参数）。

---

可用工具

工具	描述
get_project_skeleton	完整的项目结构，并提供各模块的统计信息
get_function_context	函数的完整信息：调用方、被调用方、依赖项
get_file_context	文件内容、导入项、依赖项
get_class_context	类方法、继承关系、使用情况
find_related_code	在整个代码库中进行自然语言搜索
find_related_files	通过匹配符号，查找与某项功能相关的文件
get_dependency_graph	影响分析：依赖关系的指向
get_conventions	检测到的编码模式和约定
get_call_graph	向上游和下游追踪调用链
refresh_graph	强制重新解析代码库
get_module_context	目录/软件包中的符号（中间缩放级别）
get_subclasses	基类的继承树
get_unused_symbols	检测死代码
set_project	在运行时切换所服务的项目

---

工作原理

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. 启动——Grafyx 检测项目中的语言，并通过 Graph-sitter 将所有源文件解析为语义图。
2. 服务——FastMCP 服务通过 stdio 暴露 14 个工具。AI 助手会根据需要调用这些工具。
3. 实时更新——Watchdog 监视文件变更。保存文件后，经过短暂的防抖延迟，关系图会自动重新解析。

ML 增强搜索

Grafyx 的 find_related_code 使用预训练代码嵌入模型（默认： jinaai/jina-embeddings-v2-base-code，Apache-2.0，161M 参数），通过 fastembed 使用 ONNX 在 CPU 上运行。模型 会在首次使用时下载并缓存到本地——无需 GPU、守护进程或云端调用。

从 0.2.1 起，fastembed 是硬依赖，因此默认安装已包含编码器——无需额外安装。

基准测试（0.2.0，涵盖 FastAPI + Django 的 278 个文档字符串→函数查询）：

编码器	nDCG@10	MRR@10	p50 延迟
jina-v2（默认）	0.787	0.741	~1.5 s
coderankembed	0.663	0.623	~1.3 s
仅 tokens（无 fastembed）	0.335	0.297	~0.9 s

默认编码器的检索质量是纯源码 token 搜索的两倍以上（nDCG@10 提升 +135%）。

完整分析 + 每条查询的 JSONL：docs/benchmarks/0.2.0/。

通过 GRAFYX_ENCODER 环境变量切换编码器：

• jina-v2（默认）——Apache-2.0，原生支持 fastembed，约 150 MB。准确率最佳；除非有特定原因需要切换，否则推荐使用。
• coderankembed——MIT，137M，ONNX-int8，约 140 MB。延迟更低，但在我们的评测中比 jina-v2 低约 12 个 nDCG@10 点。托管于 Bilal7Dev/grafyx-coderankembed-onnx。

支持仅依赖 numpy 的 MLP（权重总计约 5 MB，已打包在 wheel 中）：

• M1 相关性排序器——包含 33 个特征的 MLP，利用结构信号（调用者数量、名称重叠、导出项）对编码器的候选结果进行重新排序。
• M3 源码 token 过滤器——从全文搜索中抑制噪声 token（导入项、字符串、魔术方法）。
• M4 符号重要性——根据调用者数量、导出项和结构信号为符号加权。
• 无意义文本检测器——字符二元组 MLP，可在查询进入索引前拦截无意义查询。

可复现的基准测试涵盖 FastAPI、Django 和 Home Assistant，包含在 benchmarks/ 中（python -m scripts.run_all）。

---

支持的语言

语言	扩展名
Python	.py、.pyi
TypeScript	.ts、.tsx
JavaScript	.js、.jsx

系统会自动检测语言。要手动指定：

grafyx --languages python,typescript

---

选项

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

默认忽略：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

---

多 Agent 支持

Grafyx 支持 Agent 团队。单个 Grafyx 实例可为连接到同一项目的所有 Agent 提供服务。当一个 Agent 修改代码时，文件监视器会自动更新图谱，因此其他 Agent 可立即看到更改。

---

参与贡献

git clone https://github.com/bilal07karadeniz/Grafyx.git
cd Grafyx
pip install -e ".[dev]"
pytest

---

故障排除

Windows：Graph-sitter 需要 Linux。请使用 WSL，并将 MCP 客户端配置为通过 wsl 启动：

{
  "mcpServers": {
    "grafyx": {
      "command": "wsl",
      "args": ["-e", "bash", "-c", "source ~/your-venv/bin/activate && grafyx"]
    }
  }
}

---

许可证

MIT——详情请参阅 LICENSE。