GitNexus MCP 使用文档

简介

GitNexus 是一个基于知识图谱的代码智能工具，通过 MCP (Model Context Protocol) 为 AI 助手提供深度代码理解能力。

核心特性

预计算关系图谱：索引时预先计算所有依赖、调用链、执行流
混合搜索：BM25 关键词搜索 + 语义向量搜索 + RRF 融合
影响分析：精确计算代码变更的影响范围和置信度
多仓库支持：一个 MCP 服务器管理多个代码库
本地运行：所有数据本地存储，代码不上传任何服务器

支持的编辑器

编辑器	MCP	Skills	Hooks	支持程度
Claude Code	✅	✅	✅	完整支持
Cursor	✅	✅	❌	MCP + Skills
Windsurf	✅	❌	❌	仅 MCP
OpenCode	✅	✅	❌	MCP + Skills

支持的语言

TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP

快速开始

三步上手

# 1. 索引代码库（在项目根目录运行）
npx gitnexus analyze
 
# 2. 配置 MCP（一次性配置）
npx gitnexus setup
 
# 3. 重启编辑器，开始使用

验证安装

在 AI 助手中输入：

读取 gitnexus://repos

如果返回已索引的仓库列表，说明配置成功。

安装与配置

1. 索引代码库

在项目根目录运行：

npx gitnexus analyze

索引过程：

扫描文件树（~5%）
分析项目结构（~15%）
解析代码符号（~82%）
检测代码社区（~92%）
追踪执行流（~99%）
完成（100%）

索引产物：

.gitnexus/ - 本地知识图谱数据库（已自动加入 .gitignore）
~/.gitnexus/registry.json - 全局仓库注册表

常用选项：

# 强制重新索引
npx gitnexus analyze --force
 
# 跳过向量嵌入（更快，但无语义搜索）
npx gitnexus analyze --skip-embeddings
 
# 查看索引状态
npx gitnexus status
 
# 列出所有已索引仓库
npx gitnexus list
 
# 清理当前仓库索引
npx gitnexus clean
 
# 清理所有索引
npx gitnexus clean --all --force

2. 配置 MCP 服务器

方式一：自动配置（推荐）

npx gitnexus setup

自动检测已安装的编辑器并写入配置。

方式二：手动配置

Claude Code：

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Cursor（编辑 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Windsurf（编辑 ~/.windsurf/mcp.json）：

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

OpenCode（编辑 ~/.config/opencode/config.json）：

{
  "mcp": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

3. 重启编辑器

配置完成后，重启编辑器使 MCP 服务器生效。

MCP 工具详解

GitNexus 提供 7 个 MCP 工具，AI 助手可以直接调用。

1. list_repos

功能：列出所有已索引的仓库

用法：

list_repos()

返回示例：

[
  {
    "name": "my-app",
    "path": "/home/user/projects/my-app",
    "indexed_at": "2026-02-28T10:30:00Z",
    "symbols": 1348,
    "relationships": 3469
  }
]

2. query

功能：混合搜索（BM25 + 语义向量 + RRF 融合），结果按执行流分组

参数：

参数	类型	必填	说明
query	string	✅	搜索关键词
repo	string	❌	仓库名（多仓库时需要）
limit	number	❌	返回结果数量（默认 10）

用法：

query({query: "authentication middleware"})

返回示例：

processes:
  - summary: "LoginFlow"
    priority: 0.042
    symbol_count: 4
    process_type: cross_community
    step_count: 7
 
process_symbols:
  - name: validateUser
    type: Function
    filePath: src/auth/validate.ts
    process_id: proc_login
    step_index: 2
 
definitions:
  - name: AuthConfig
    type: Interface
    filePath: src/types/auth.ts

3. context

功能：查看符号的 360 度上下文（调用者、被调用者、所属进程）

参数：

参数	类型	必填	说明
name	string	✅	符号名称
repo	string	❌	仓库名

用法：

context({name: "validateUser"})

返回示例：

symbol:
  uid: "Function:validateUser"
  kind: Function
  filePath: src/auth/validate.ts
  startLine: 15
 
incoming:
  calls: [handleLogin, handleRegister, UserController]
  imports: [authRouter]
 
outgoing:
  calls: [checkPassword, createSession]
 
processes:
  - name: LoginFlow (step 2/7)
  - name: RegistrationFlow (step 3/5)

4. impact

功能：影响分析（爆炸半径分析）

参数：

参数	类型	必填	说明
target	string	✅	目标符号名称
direction	string	✅	upstream（依赖者）或 downstream（被依赖者）
repo	string	❌	仓库名
maxDepth	number	❌	最大深度（默认 3）
minConfidence	number	❌	最小置信度（0-1，默认 0.7）
relationTypes	string[]	❌	关系类型过滤
includeTests	boolean	❌	是否包含测试文件（默认 false）

用法：

impact({
  target: "UserService",
  direction: "upstream",
  minConfidence: 0.8
})

返回示例：

TARGET: Class UserService (src/services/user.ts)
 
UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    handleLogin [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
 
  Depth 2 (LIKELY AFFECTED):
    authRouter [IMPORTS] -> src/routes/auth.ts
    apiServer [IMPORTS] -> src/server.ts

置信度说明：

90%+：直接调用，必然受影响
70-90%：间接依赖，很可能受影响
50-70%：弱依赖，可能受影响

5. detect_changes

功能：检测 Git 变更的影响范围

参数：

参数	类型	必填	说明
scope	string	✅	staged（暂存区）或 all（所有变更）
repo	string	❌	仓库名

用法：

detect_changes({scope: "staged"})

返回示例：

summary:
  changed_count: 12
  affected_count: 3
  changed_files: 4
  risk_level: medium
 
changed_symbols:
  - validateUser (src/auth/validate.ts:15)
  - AuthService (src/services/auth.ts:8)
 
affected_processes:
  - LoginFlow (3 steps affected)
  - RegistrationFlow (2 steps affected)

风险等级：

low：影响 < 5 个符号
medium：影响 5-20 个符号
high：影响 > 20 个符号

6. rename

功能：多文件协调重命名（基于图谱 + 文本搜索）

参数：

参数	类型	必填	说明
symbol_name	string	✅	原符号名
new_name	string	✅	新符号名
repo	string	❌	仓库名
dry_run	boolean	❌	仅预览不执行（默认 false）

用法：

rename({
  symbol_name: "validateUser",
  new_name: "verifyUser",
  dry_run: true
})

返回示例：

status: success
files_affected: 5
total_edits: 8
graph_edits: 6        # 高置信度（基于图谱）
text_search_edits: 2  # 需人工审查（基于文本搜索）
 
changes:
  - file: src/auth/validate.ts
    line: 15
    old: "export function validateUser"
    new: "export function verifyUser"
    confidence: high
 
  - file: src/api/auth.ts
    line: 45
    old: "validateUser(req.body)"
    new: "verifyUser(req.body)"
    confidence: high

7. cypher

功能：执行原始 Cypher 图查询

参数：

参数	类型	必填	说明
query	string	✅	Cypher 查询语句
repo	string	❌	仓库名

用法：

cypher({
  query: "
    MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:MEMBER_OF]-(fn)
    MATCH (caller)-[r:CALLS]->(fn)
    WHERE r.confidence > 0.8
    RETURN caller.name, fn.name, r.confidence
    ORDER BY r.confidence DESC
  "
})

图模式：

节点类型：

File - 文件
Function - 函数
Class - 类
Interface - 接口
Method - 方法
Community - 代码社区
Process - 执行流

关系类型：

CALLS - 调用关系
IMPORTS - 导入关系
EXTENDS - 继承关系
IMPLEMENTS - 实现关系
DEFINES - 定义关系
MEMBER_OF - 社区成员关系
STEP_IN_PROCESS - 执行流步骤关系

MCP 资源

MCP 资源是预计算的轻量级上下文，可以直接读取。

可用资源

资源 URI	内容	大小
`gitnexus://repos`	所有已索引仓库列表	~100 tokens
`gitnexus://repo/{name}/context`	仓库统计、索引状态	~200 tokens
`gitnexus://repo/{name}/clusters`	所有功能集群	~300 tokens
`gitnexus://repo/{name}/cluster/{name}`	集群成员详情	~200 tokens
`gitnexus://repo/{name}/processes`	所有执行流	~400 tokens
`gitnexus://repo/{name}/process/{name}`	执行流完整追踪	~500 tokens
`gitnexus://repo/{name}/schema`	图模式（用于 Cypher）	~300 tokens

使用示例

# 查看所有仓库
读取 gitnexus://repos

# 查看仓库概览
读取 gitnexus://repo/my-app/context

# 查看所有功能集群
读取 gitnexus://repo/my-app/clusters

# 查看认证集群详情
读取 gitnexus://repo/my-app/cluster/Authentication

# 查看所有执行流
读取 gitnexus://repo/my-app/processes

# 查看登录流程详情
读取 gitnexus://repo/my-app/process/LoginFlow

# 查看图模式（用于编写 Cypher 查询）
读取 gitnexus://repo/my-app/schema

实际使用场景

场景 1：理解陌生代码库

任务：快速了解用户认证流程

步骤：

1. query({query: "user authentication login"})
   → 返回 LoginFlow 进程和相关符号

2. 读取 gitnexus://repo/my-app/process/LoginFlow
   → 查看完整调用链

3. context({name: "validateUser"})
   → 查看核心函数的上下文

场景 2：重构前评估风险

任务：修改 parseConfig 函数前评估影响

步骤：

1. impact({
     target: "parseConfig",
     direction: "upstream",
     maxDepth: 2
   })
   → 显示 12 个函数依赖它

2. 读取 gitnexus://repo/my-app/clusters
   → 查看影响了哪些功能模块

3. 决策：影响范围可控，可以重构

场景 3：提交前检查

任务：提交代码前检查影响范围

步骤：

1. detect_changes({scope: "staged"})
   → 你的改动影响了 LoginFlow 和 RegistrationFlow

2. impact({target: "AuthService", direction: "upstream"})
   → 确认影响范围在预期内

3. 运行测试，提交代码

场景 4：追踪 Bug

任务：用户登录失败，追踪问题

步骤：

1. query({query: "login error handling"})
   → 找到错误处理相关代码

2. 读取 gitnexus://repo/my-app/process/LoginFlow
   → 查看完整登录流程

3. context({name: "handleLoginError"})
   → 查看错误处理函数的调用关系

4. 定位问题：错误处理函数未正确传播错误

场景 5：安全审计

任务：查找所有直接操作数据库的代码

步骤：

cypher({
  query: "
    MATCH (fn)-[:CALLS]->(db)
    WHERE db.name =~ '.*query.*|.*execute.*|.*raw.*'
    RETURN fn.name, fn.filePath, db.name
  "
})

场景 6：性能优化

任务：找出调用次数最多的函数

步骤：

cypher({
  query: "
    MATCH (caller)-[:CALLS]->(fn)
    WITH fn, count(caller) as call_count
    WHERE call_count > 5
    RETURN fn.name, fn.filePath, call_count
    ORDER BY call_count DESC
    LIMIT 10
  "
})

高级用法

多仓库管理

GitNexus 支持同时管理多个代码库：

# 索引多个仓库
cd ~/projects/frontend && npx gitnexus analyze
cd ~/projects/backend && npx gitnexus analyze
cd ~/projects/shared && npx gitnexus analyze
 
# 查看所有仓库
npx gitnexus list

在 AI 助手中使用时，指定 repo 参数：

query({query: "authentication", repo: "backend"})
impact({target: "UserService", direction: "upstream", repo: "frontend"})

自定义 Cypher 查询

查找循环依赖：

MATCH path = (a)-[:CALLS*2..5]->(a)
WHERE a.label = 'Function'
RETURN [node in nodes(path) | node.name] as cycle
LIMIT 10

查找孤立函数（未被调用）：

MATCH (fn:Function)
WHERE NOT (fn)<-[:CALLS]-()
RETURN fn.name, fn.filePath

查找跨社区调用：

MATCH (c1:Community)<-[:MEMBER_OF]-(fn1)-[:CALLS]->(fn2)-[:MEMBER_OF]->(c2:Community)
WHERE c1.name <> c2.name
RETURN c1.name, c2.name, count(*) as cross_calls
ORDER BY cross_calls DESC

增量索引

当代码变更后，重新运行 analyze 会自动检测变更：

# 检查索引状态
npx gitnexus status
 
# 如果提示 "Index is stale"，重新索引
npx gitnexus analyze

GitNexus 会智能检测变更文件，只重新索引必要的部分。

生成文档

使用 LLM 从知识图谱生成文档：

# 需要设置 OPENAI_API_KEY 或其他 LLM API 密钥
export OPENAI_API_KEY=sk-...
 
# 生成文档
npx gitnexus wiki
 
# 使用自定义模型
npx gitnexus wiki --model gpt-4o
 
# 使用自定义 API 端点
npx gitnexus wiki --base-url https://api.anthropic.com/v1
 
# 强制重新生成
npx gitnexus wiki --force

本地 Web UI

启动本地服务器，在浏览器中可视化知识图谱：

npx gitnexus serve

然后访问 gitnexus.vercel.app，Web UI 会自动检测本地服务器并连接。

常见问题

Q1: 索引需要多长时间？

A: 取决于代码库大小：

小型项目（< 1000 文件）：1-2 分钟
中型项目（1000-5000 文件）：5-10 分钟
大型项目（> 5000 文件）：15-30 分钟

可以使用 --skip-embeddings 跳过向量嵌入加速索引。

Q2: 索引占用多少磁盘空间？

A: 通常是源码大小的 10-20%：

10MB 源码 → ~2MB 索引
100MB 源码 → ~15MB 索引
1GB 源码 → ~150MB 索引

Q3: 如何更新索引？

A: 重新运行 npx gitnexus analyze，GitNexus 会自动检测变更并增量更新。

Q4: 支持 monorepo 吗？

A: 支持。可以在 monorepo 根目录索引整个仓库，也可以分别索引各个子项目。

Q5: 索引数据会上传到服务器吗？

A: 不会。所有数据都存储在本地：

.gitnexus/ - 项目索引（已加入 .gitignore）
~/.gitnexus/ - 全局注册表

Q6: 如何卸载？

# 删除所有索引
npx gitnexus clean --all --force
 
# 删除全局注册表
rm -rf ~/.gitnexus
 
# 删除 MCP 配置（手动编辑配置文件移除 gitnexus 部分）

Q7: MCP 服务器无法连接？

A: 检查步骤：

确认已运行 npx gitnexus setup
重启编辑器
检查 MCP 配置文件是否正确
运行 npx gitnexus list 确认有已索引的仓库

Q8: 查询结果为空？

A: 可能原因：

索引未完成或失败 → 运行 npx gitnexus status 检查
搜索关键词不匹配 → 尝试更通用的关键词
跳过了向量嵌入 → 重新索引时不使用 --skip-embeddings

Q9: 如何提高搜索准确度？

使用更具体的关键词
结合 query 和 context 工具
使用 Cypher 查询进行精确匹配
查看 gitnexus://repo/{name}/processes 了解执行流

Q10: 支持私有代码库吗？

A: 完全支持。GitNexus 100% 本地运行，不需要网络连接，不会上传任何代码。

技术支持

GitHub Issues: https://github.com/abhigyanpatwari/GitNexus/issues
文档: https://github.com/abhigyanpatwari/GitNexus
Web UI: https://gitnexus.vercel.app

许可证

PolyForm Noncommercial 1.0.0

免费用于非商业用途。商业许可请联系作者。

Quartz 4

Explorer

GitNexus_MCP_使用文档

GitNexus MCP 使用文档

目录

简介

核心特性

支持的编辑器

支持的语言

快速开始

三步上手

验证安装

安装与配置

1. 索引代码库

2. 配置 MCP 服务器

方式一：自动配置（推荐）

方式二：手动配置

3. 重启编辑器

MCP 工具详解

1. list_repos

2. query

3. context

4. impact

5. detect_changes

6. rename

7. cypher

MCP 资源

可用资源

使用示例

实际使用场景

场景 1：理解陌生代码库

场景 2：重构前评估风险

场景 3：提交前检查

场景 4：追踪 Bug

场景 5：安全审计

场景 6：性能优化

高级用法

多仓库管理

自定义 Cypher 查询

增量索引

生成文档

本地 Web UI

常见问题

Q1: 索引需要多长时间？

Q2: 索引占用多少磁盘空间？

Q3: 如何更新索引？

Q4: 支持 monorepo 吗？

Q5: 索引数据会上传到服务器吗？

Q6: 如何卸载？

Q7: MCP 服务器无法连接？

Q8: 查询结果为空？

Q9: 如何提高搜索准确度？

Q10: 支持私有代码库吗？

技术支持

许可证

Graph View

Table of Contents