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 瞭解開發指南。