Nervusdb MCP

🚀 @nervusdb/mcp

@nervusdb/mcp 是 NervusDB 的官方 MCP 服务器，它构建了一个集成了 repomix 的代码知识图谱，可助力开发者更好地管理和分析代码项目。

🚀 快速开始

环境准备

• Node.js 20.0.0 或更高版本
• pnpm 8.0.0 或更高版本

安装依赖

pnpm install

启动服务器

# 开发环境
pnpm start:stdio

# 生产环境构建
pnpm build

索引项目

pnpm synapse:index -p /path/to/your/project

集成 Claude Desktop

将以下配置添加到你的 Claude Desktop 配置文件中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "nervusdb-mcp": {
      "command": "npx",
      "args": ["-y", "@nervusdb/mcp"]
    }
  }
}

或者，如果你已经全局安装了该包：

{
  "mcpServers": {
    "nervusdb-mcp": {
      "command": "nervusdb-mcp"
    }
  }
}

安装选项

# 选项 1：使用 npx（推荐，无需安装）
# 只需添加上述配置，Claude 会自动运行它

# 选项 2：全局安装以加快启动速度
npm install -g @nervusdb/mcp

✨ 主要特性

• 代码知识图谱：使用 @nervusdb/core 和 repomix 构建跨语言的代码知识图谱。
• 项目洞察：分析代码影响、查找相关文件并探索项目结构。
• 工作流自动化：通过创建分支和提交 PR 进行任务管理。
• 代码操作：读取、写入文件并运行测试，同时进行安全检查。
• 数据库工具：查询和维护知识图谱索引。
• 影子索引策略：通过指纹验证确保可靠的索引。

📦 安装指南

依赖安装

确保你已经安装了 Node.js 20.0.0 或更高版本以及 pnpm 8.0.0 或更高版本，然后运行以下命令安装依赖：

pnpm install

服务器启动

开发环境下，使用以下命令启动服务器：

pnpm start:stdio

生产环境下，先进行构建：

pnpm build

项目索引

使用以下命令对项目进行索引：

pnpm synapse:index -p /path/to/your/project

Claude Desktop 集成

按照上述配置步骤将 NervusDB MCP 集成到 Claude Desktop 中。

💻 使用示例

基础用法

// 1. 开始新任务
workflow.startTask({
  taskId: '42',
  owner: 'alice',
  designDoc: 'docs/design/feature-42.md',
});

// 2. 分析代码影响
project.analyzeImpact({
  projectPath: '/workspace/my-project',
  functionName: 'calculateTotal',
  limit: 20,
});

// 3. 读取文件
code.readFile({
  projectPath: '/workspace/my-project',
  file: 'src/services/orderService.ts',
});

// 4. 运行测试
code.runTests({
  projectPath: '/workspace/my-project',
  filter: 'orderService',
});

// 5. 查询知识图谱
db.query({
  projectPath: '/workspace/my-project',
  query: {
    type: 'typed',
    filter: { predicate: 'CONTAINS' },
    options: { limit: 100 },
  },
});

// 6. 提交审核
workflow.submitForReview({
  confirm: true,
  title: 'feat: optimize order calculation',
  reviewers: ['bob'],
});

📚 详细文档

工具概述

工具概述 提供了所有 13 个工具的详细文档。

架构设计

架构设计 阐述了项目的架构设计。

质量指南

质量指南 包含了项目的质量准则。

构建与发布

构建与发布 说明了项目的构建和发布流程。

🔧 技术细节

工作原理

1. 索引：使用 repomix 收集项目文件，并使用 @nervusdb/core 构建知识图谱。
2. 存储：通过指纹验证维护影子索引，确保数据完整性。
3. 查询：提供类型化和原始查询接口，以探索代码关系。
4. 工作流：与 Git 工作流集成，实现任务管理。

项目结构

nervusdb-mcp/
├── src/
│   ├── server/           # MCP 服务器实现
│   ├── tools/            # 工具实现（工作流、项目、代码、数据库）
│   ├── services/         # 业务逻辑服务
│   ├── domain/           # 核心领域逻辑（索引、查询）
│   └── utils/            # 共享工具
├── bin/                  # CLI 可执行文件
├── docs/                 # 文档
└── tests/                # 测试套件

开发流程

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 检查代码质量
pnpm check

# 生产环境构建
pnpm build

可用工具

NervusDB MCP 服务器提供了 4 个类别共 13 个工具：

1. 工作流工具 ⚙️

• workflow.startTask - 创建任务分支并更新账本
• workflow.submitForReview - 推送分支并创建拉取请求 (需要 GitHub 认证)

2. 项目工具

• project.getStructure - 获取项目文件结构及统计信息
• project.analyzeImpact - 根据知识图谱分析代码影响
• project.findRelatedFiles - 查找与目标文件相关的文件
• project.readFile - 读取任意文件内容

3. 代码工具

• code.readFile - 读取项目文件内容
• code.writeFile - 将内容写入项目文件（需要确认）
• code.runTests - 使用 Vitest 运行测试并返回结果

4. 数据库工具

• db.getStats - 获取索引元数据和统计信息
• db.query - 对知识图谱执行类型化或原始查询
• db.rebuildIndex - 重建项目索引并记录遥测数据
• db.getHealth - 通过指纹验证检查索引健康状况

配置

GitHub 认证（用于工作流工具）

工作流工具（workflow.submitForReview）需要 GitHub 认证才能创建拉取请求。服务器支持 3 种认证方法，并会自动降级：

方法 1：环境变量（推荐用于 CI/CD）

# 设置 GITHUB_TOKEN 或 GH_TOKEN
export GITHUB_TOKEN=ghp_your_personal_access_token

# 或者在你的 shell 配置文件（~/.zshrc 或 ~/.bashrc）中添加
echo 'export GITHUB_TOKEN=ghp_xxx' >> ~/.zshrc

方法 2：GitHub CLI（推荐用于本地开发）

# 安装 gh CLI
brew install gh # macOS
# 或者参考 https://cli.github.com/ 安装其他平台的版本

# 进行认证
gh auth login

方法 3：Claude Desktop 配置 在 Claude Desktop 配置中添加环境变量：

{
  "mcpServers": {
    "nervusdb-mcp": {
      "command": "npx",
      "args": ["-y", "@nervusdb/mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

认证优先级：

1. GITHUB_TOKEN 环境变量（最高优先级）
2. GH_TOKEN 环境变量
3. gh auth token 命令（如果 gh CLI 已认证）

如果没有可用的认证，工作流工具将提供清晰的错误消息和设置说明。

📄 许可证

本项目采用 MIT 许可证。

贡献

请参考 CONTRIBUTING.md 了解开发指南。