@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/coreandrepomix - 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_TOKENenvironment variable (highest priority)GH_TOKENenvironment variablegh auth tokencommand (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 ledgerworkflow.submitForReview- Push branch and create pull request (requires GitHub authentication)
2. Project Tools
project.getStructure- Get project file structure with statisticsproject.analyzeImpact- Analyze code impact based on knowledge graphproject.findRelatedFiles- Find files related to a target fileproject.readFile- Read arbitrary file content
3. Code Tools
code.readFile- Read project file contentcode.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 statisticsdb.query- Execute typed or raw queries against knowledge graphdb.rebuildIndex- Rebuild project index with telemetrydb.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
repomixto collect project files and@nervusdb/coreto 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