@nervusdb/mcp

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

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:

1. GITHUB_TOKEN environment variable (highest priority)
2. GH_TOKEN environment variable
3. 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

1. Indexing: Uses repomix to collect project files and @nervusdb/core to build a knowledge graph
2. Storage: Maintains shadow indices with fingerprint validation for data integrity
3. Query: Provides typed and raw query interfaces to explore code relationships
4. 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