内容
# vb-knowledge-graph-mcp
> **用于通过 Roslyn 支持的知识图谱导航 VB.NET 代码库的 MCP 服务器。**
一款模型上下文协议（MCP）服务器，使用 Roslyn 索引 VB.NET 代码库，将图谱持久化存储在 SQLite 中，并提供工具让 AI 代理搜索符号、遍历继承层次结构、查找引用 —— 所有这些都不需要代理通过数千个 `.vb` 文件进行 grep。
[](https://github.com/JCKirwin/vb-knowledge-graph-mcp/actions/workflows/build.yml)
---
## 为什么
现代 AI 编程助手都围绕 C 家族语言构建。当它们遇到大型 VB.NET 项目（常见于遗留企业系统）时，它们会退回到正则表达式 grep，错过继承边，并烧掉 token 读取整个文件以确认方法签名。
这个 MCP 服务器为代理提供了一个结构化视图：“查找所有继承自 `Page` 的类”或“显示 `SaveCustomer` 的签名和 Handles 子句”返回毫秒级的精确答案。
---
## 索引内容
| 符号类型 | 边 |
|---|---|
| 类、模块、接口、枚举、结构体 | 继承 |
| 子过程、函数、属性、事件、字段 | 实现 |
| WithEvents 字段、嵌套类型 | 处理 |
| 命名空间和导入 | （导入单独跟踪） |
符号类型可以单独搜索，边可以双向查询（基类 + 派生类型）。
---
## 安装
### 先决条件
- [.NET 10 SDK](https://dotnet.microsoft.com/download)
- 支持 MCP 的客户端（例如 [Claude Code](https://claude.com/claude-code)）
### 作为全局工具安装（推荐）
```bash
dotnet tool install -g vb-knowledge-graph-mcp
```
安装后，该工具在您的 PATH 上可用作 `vb-knowledge-graph-mcp`。
### 从源代码构建
```bash
git clone https://github.com/JCKirwin/vb-knowledge-graph-mcp.git
cd vb-knowledge-graph-mcp
dotnet build -c Release
```
二进制文件位于 `bin/Release/net10.0/vb-knowledge-graph.dll`。
---
## 配置
### 在 Claude Code 中注册（`.mcp.json`）
如果作为全局工具安装：
```json
{
"mcpServers": {
"vb-knowledge-graph": {
"command": "vb-knowledge-graph-mcp",
"args": ["--repo-path", "C:/path/to/your/vb-project"]
}
```
如果从源代码构建：
```json
{
"mcpServers": {
"vb-knowledge-graph": {
"command": "dotnet",
"args": [
"C:/path/to/vb-knowledge-graph-mcp/bin/Release/net10.0/vb-knowledge-graph.dll",
"--repo-path", "C:/path/to/your/vb-project"
]
}
}
}
```
### 命令行标志
| 标志 | 描述 | 默认值 |
|---|---|---|
| `--repo-path <path>` | 递归扫描以查找 `*.vb` 文件的根目录 | `$VB_ROOT_PATH` 环境变量，然后是当前工作目录 |
| `--db-path <path>` | SQLite 索引位置 | `$VB_DB_PATH` 环境变量，然后是 `~/.cache/vb-knowledge-graph/vb-index.db` |
| `--reindex` | 强制启动时完全重新索引（清除现有索引） | — |
| `--bridge-config <path>` | 可选的跨语言桥接 JSON 的路径（参见下文） | `$VB_BRIDGE_CONFIG` 环境变量 |
首次运行时会自动索引；后续运行会重用缓存的数据库。在大型重构后使用 `--reindex`，或从代理会话中调用 `reindex_vb` MCP 工具。
### 跨语言桥接（可选）
VB.NET 项目通常通过 `Imports` 委托给可以通过 C# 层访问的 C# 层。如果您还运行一个 C# 知识图 MCP 服务器（例如 [codebase-memory-mcp](https://github.com/anthropics/codebase-memory-mcp)），该服务器将其索引写入具有 `nodes(project, label, qualified_name, name, file_path)` 架构的相邻 SQLite 数据库，您可以将两个图谱连接起来。
传递 `--bridge-config <path>`（或设置 `VB_BRIDGE_CONFIG`）。文件是 JSON；请参见 [`bridge-config.example.json`](bridge-config.example.json)：
```jsonc
{
"enabled": true,
"cmmDbPath": "C:/Users/me/.cache/codebase-memory-mcp/MyProject.db",
"cmmProjectKey": "C-Projects-MyProject",
"namespaceFilters": ["MyCompany.%", "MyApp.%"],
"csharpLabels": ["Class", "Interface", "Enum"]
}
```
启用后，服务器以只读方式打开相邻的数据库，并填充一个本地的 `bridge_mappings` 表，该表将每个 VB.NET 导入命名空间映射到匹配的 C# 节点。这解锁了两个额外的工具：
| 工具 | 目的 |
|---|---|
| `bridge_vb_imports` | 列出通过 VB.NET 文件或类型的 `Imports` 可以访问的 C# 类型 |
| `trace_vb_calls` | VB.NET 子过程/函数/类的启发式跨语言调用跟踪 |
| `rebuild_vb_bridge` | 在重新索引相邻图谱后重新构建桥接映射 |
如果省略 `--bridge-config`，则桥接被禁用，这些工具返回一行提示而不是错误。上面的七种核心工具无论如何都可以使用。
---
## MCP 工具
| 工具 | 目的 |
|---|---|
| `search_vb_symbols` | 按名称搜索，可选按种类/访问筛选 |
| `get_vb_type` | 类/模块/接口/枚举/结构体的完整详细信息：成员、继承、位置 |
| `get_vb_method` | 方法签名、Handles/Implements 子句、源代码片段 |
| `list_vb_hierarchy` | 给定类型的基类（扩展/实现）和派生类型 |
| `find_vb_references` | 通过边 + 名称匹配 + 导入引用的结构化引用 |
| `search_vb_code` | 具有结构化上下文的文本搜索（哪个类/方法包含匹配） |
| `reindex_vb` | 从代理会话内部触发完全重新索引 |
---
## 使用示例
### 1. “查找所有继承自 `Page` 的类”
```
search_vb_symbols(query="Page", kind="Class")
list_vb_hierarchy(name="Page")
```
层次结构工具返回具有文件路径和行号的派生类型列表。
### 2. “`SaveCustomer` 子过程的作用是什么？”
```
get_vb_method(name="SaveCustomer")
```
返回签名、Handles/Implements 子句和内联源代码片段（最多 60 行）。
### 3. “在哪里引用了 `LoanStatus.Active`？”
```
find_vb_references(name="LoanStatus.Active")
```
返回结构化边 + 索引图谱中的名称匹配。
---
## 工作原理
1. **索引器**（Roslyn `Microsoft.CodeAnalysis.VisualBasic`）遍历存储库根目录下的所有 `*.vb` 文件，将每个文件解析为语法树，并提取符号 + 边。
2. **存储**（SQLite）使用符号名称和签名的 FTS5 全文搜索持久化图谱。
3. **MCP 服务器**（通过 [`ModelContextProtocol`](https://www.nuget.org/packages/ModelContextProtocol) 的标准输入/输出传输）公开上述七种工具。
4. **边解析**在索引后运行 — `target_name` 字符串链接到存在合格名称匹配的 `target_id` 外键。
5. **增量重新索引**（通过 `reindex_vb`）比较每个文件的 SHA-256 哈希，并跳过未更改的文件。
扫描时跳过：`*.designer.vb`、`AssemblyInfo.vb`、`Reference.vb`、`My Project/`、`bin/`、`obj/`。
---
## 性能
对于一个包含约 3000 个文件的 VB.NET 代码库：完整索引需要 ~60-90 秒，增量重新索引需要 ~5 秒，符号查询返回时间小于 50 毫秒。
---
## 路线图
- **v0.2** — 跨语言桥接：从 VB.NET 导入到姐妹语言的符号图的可配置映射（例如，存储在另一个 SQLite 数据库中的 C# 图谱）。最初从耦合实现中提取；重新引入为干净的可配置功能。
- **NuGet `dotnet tool` 包** — `dotnet tool install --global vb-knowledge-graph` 实现一键安装。
- **测试套件** — 覆盖索引器 + 每个 MCP 工具的冒烟测试，针对固定 VB 项目。
问题和 PR 欢迎。
---
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。
