@nervusdb/mcp

Official MCP server for NervusDB - Code knowledge graph with repomix integration

npm version License: MIT

Features

Code Knowledge Graph: Build cross-language code knowledge graphs using @nervusdb/core and repomix
Project Insights: Analyze code impact, find related files, and explore project structure
Workflow Automation: Task management with branch creation and PR submission
Code Operations: Read, write files, and run tests with safety checks
Database Tools: Query and maintain the knowledge graph index
Shadow Index Strategy: Ensures reliable indexing with fingerprint validation

Prerequisites

Node.js 20.0.0 or higher
pnpm 8.0.0 or higher

Quick Start

Install Dependencies

pnpm install

Run the Server

# For development pnpm start:stdio # Build for production pnpm build

Index a Project

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

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Alternatively, if you've installed the package globally:

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

Installation Options:

# Option 1: Use npx (recommended, no installation needed) # Just add the config above, Claude will run it automatically # Option 2: Install globally for faster startup npm install -g @nervusdb/mcp

Configuration

GitHub Authentication (for Workflow Tools)

Workflow tools (workflow.submitForReview) require GitHub authentication to create pull requests. The server supports 3 authentication methods with automatic fallback:

Method 1: Environment Variables (Recommended for CI/CD)

# Set GITHUB_TOKEN or GH_TOKEN export GITHUB_TOKEN=ghp_your_personal_access_token # Or in your shell profile (~/.zshrc or ~/.bashrc) echo 'export GITHUB_TOKEN=ghp_xxx' >> ~/.zshrc

Method 2: GitHub CLI (Recommended for Local Development)

# Install gh CLI brew install gh # macOS # Or see https://cli.github.com/ for other platforms # Authenticate gh auth login

Method 3: Claude Desktop Configuration

Add environment variables to Claude Desktop config:

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

Authentication Priority:

GITHUB_TOKEN environment variable (highest priority)
GH_TOKEN environment variable
gh auth token command (if gh CLI is authenticated)

If no authentication is available, workflow tools will provide clear error messages with setup instructions.

Available Tools

The NervusDB MCP server provides 13 tools across 4 categories:

1. Workflow Tools ⚙️

workflow.startTask - Create task branch and update ledger
workflow.submitForReview - Push branch and create pull request (requires GitHub authentication)

2. Project Tools

project.getStructure - Get project file structure with statistics
project.analyzeImpact - Analyze code impact based on knowledge graph
project.findRelatedFiles - Find files related to a target file
project.readFile - Read arbitrary file content

3. Code Tools

code.readFile - Read project file content
code.writeFile - Write content to project file (requires confirmation)
code.runTests - Run tests using Vitest and return results

4. Database Tools

db.getStats - Get index metadata and statistics
db.query - Execute typed or raw queries against knowledge graph
db.rebuildIndex - Rebuild project index with telemetry
db.getHealth - Check index health with fingerprint validation

Usage Example

// 1. Start a new task workflow.startTask({ taskId: '42', owner: 'alice', designDoc: 'docs/design/feature-42.md', }); // 2. Analyze code impact project.analyzeImpact({ projectPath: '/workspace/my-project', functionName: 'calculateTotal', limit: 20, }); // 3. Read a file code.readFile({ projectPath: '/workspace/my-project', file: 'src/services/orderService.ts', }); // 4. Run tests code.runTests({ projectPath: '/workspace/my-project', filter: 'orderService', }); // 5. Query the knowledge graph db.query({ projectPath: '/workspace/my-project', query: { type: 'typed', filter: { predicate: 'CONTAINS' }, options: { limit: 100 }, }, }); // 6. Submit for review workflow.submitForReview({ confirm: true, title: 'feat: optimize order calculation', reviewers: ['bob'], });

How It Works

Indexing: Uses repomix to collect project files and @nervusdb/core to build a knowledge graph
Storage: Maintains shadow indices with fingerprint validation for data integrity
Query: Provides typed and raw query interfaces to explore code relationships
Workflow: Integrates with Git workflows for task management

Project Structure

nervusdb-mcp/ ├── src/ │ ├── server/ # MCP server implementation │ ├── tools/ # Tool implementations (workflow, project, code, db) │ ├── services/ # Business logic services │ ├── domain/ # Core domain logic (indexing, query) │ └── utils/ # Shared utilities ├── bin/ # CLI executables ├── docs/ # Documentation └── tests/ # Test suites

Development

# Install dependencies pnpm install # Run tests pnpm test # Check code quality pnpm check # Build for production pnpm build

Documentation

Tools Overview - Detailed documentation for all 13 tools
Architecture Design
Quality Guidelines
Build and Release

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT

NervusDB MCP Server