Nervusdb MCP

🚀 @nervusdb/mcp

NervusDBの公式MCPサーバー - repomix統合によるコード知識グラフ

✨ 主な機能

• コード知識グラフ：@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との統合

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

⚙️ 設定

GitHub認証（ワークフローツール用）

ワークフローツール（workflow.submitForReview）は、プルリクエストを作成するためにGitHub認証が必要です。サーバーは3つの認証方法をサポートし、自動的にフォールバックします。

方法1: 環境変数（CI/CDに推奨）

# GITHUB_TOKENまたはGH_TOKENを設定する
export GITHUB_TOKEN=ghp_your_personal_access_token

# または、シェルプロファイル（~/.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が認証されている場合）

認証が利用できない場合、ワークフローツールは設定手順を含む明確なエラーメッセージを表示します。

🛠️ 利用可能なツール

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 - 指紋検証によりインデックスの健全性をチェックします。

💻 使用例

// 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'],
});

🤔 仕組み

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

📚 ドキュメント

• Tools Overview - 13のツールすべての詳細ドキュメント
• Architecture Design
• Quality Guidelines
• Build and Release

🤝 コントリビューション

開発ガイドラインについては CONTRIBUTING.md を参照してください。

📄 ライセンス

MIT