README.md•6.46 kB
# @nervusdb/mcp
> Official MCP server for NervusDB - Code knowledge graph with repomix integration
[](https://www.npmjs.com/package/@nervusdb/mcp)
[](https://opensource.org/licenses/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**
```bash
pnpm install
```
**Run the Server**
```bash
# For development
pnpm start:stdio
# Build for production
pnpm build
```
**Index a Project**
```bash
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):
```json
{
"mcpServers": {
"nervusdb-mcp": {
"command": "npx",
"args": ["-y", "@nervusdb/mcp"]
}
}
}
```
Alternatively, if you've installed the package globally:
```json
{
"mcpServers": {
"nervusdb-mcp": {
"command": "nervusdb-mcp"
}
}
}
```
**Installation Options:**
```bash
# 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)**
```bash
# 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)**
```bash
# 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:
```json
{
"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
```typescript
// 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
```bash
# Install dependencies
pnpm install
# Run tests
pnpm test
# Check code quality
pnpm check
# Build for production
pnpm build
```
## Documentation
- [Tools Overview](docs/tools/overview.md) - Detailed documentation for all 13 tools
- [Architecture Design](docs/architecture/ADR-002-Architecture-Design.md)
- [Quality Guidelines](docs/quality-guidelines.md)
- [Build and Release](docs/build-and-release.md)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
## License
MIT