Nervusdb MCP

🚀 @nervusdb/mcp

The official MCP server for NervusDB - A code knowledge graph integrated with repomix

🚀 Quick Start

Prerequisites

• Node.js 20.0.0 or higher
• pnpm 8.0.0 or higher

Installation and Running

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

✨ 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.

📦 Installation

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.

💻 Usage Examples

Basic Usage

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

📚 Documentation

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

Other Documentation

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

🔧 Technical Details

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

Contributing

See CONTRIBUTING.md for development guidelines.

📄 License

MIT