Codebase Graph MCP Server

A comprehensive Model Context Protocol (MCP) server that provides a graph database for tracking software codebase components, their relationships, and associated tasks/goals. Built with Neo4j for powerful graph queries and analysis, featuring both STDIO MCP and HTTP/SSE interfaces.

Features

• Dual Interface Support: Both STDIO MCP and HTTP/SSE interfaces for maximum flexibility
• Component Management: Track files, functions, classes, modules, and systems with metadata support
• Relationship Mapping: Model dependencies, inheritance, imports, and other relationships between components
• Task Integration: Link tasks and goals directly to codebase components with progress tracking
• Bulk Operations: Efficient bulk creation of components, relationships, and tasks
• Multi-level Abstraction: Support analysis at any level from individual functions to entire systems
• Real-time Events: Server-Sent Events (SSE) for live updates and notifications
• Change History: Complete audit trail of all modifications with timestamp tracking
• Snapshot System: Create and restore database snapshots for backup and rollback capabilities
• Command Queue: Inter-agent communication system for coordinating work between multiple AI agents
• Voting System: Community-driven type proposals for extending the schema (optional)
• CLI Tools: Terminal-based queue waiters for non-MCP agent integration
• Flexible Configuration: Support for multiple databases, remote connections, and SSL
• MCP Compatible: Works with any MCP-compatible AI agent or tool

Prerequisites

Neo4j Database

1. Download Neo4j Community Edition: https://neo4j.com/download/
2. Install and start Neo4j:
   • Default URL: bolt://localhost:7687
   • Default username: neo4j
   • Default password: password (you may need to change this on first login)

Node.js

• Node.js 18+ required
• npm or yarn package manager

Installation

1. Clone and install dependencies:

cd codebase-graph-mcp
npm install

2. Set up the database:

npm run setup-db

3. Start the MCP server:

npm start

Server Modes

The server supports multiple operation modes:

1. Default Mode (STDIO + HTTP)

npm start
# or
node src/index.js

• Runs both STDIO MCP server and HTTP/SSE server
• Default HTTP port: 3000
• Suitable for development and full-featured access

2. HTTP-Only Mode

HTTP_ONLY=true HTTP_PORT=3001 npm run start:http

• Runs only the HTTP server with SSE support
• No STDIO MCP interface
• Ideal for web integrations and external tools

3. STDIO-Only Mode

ENABLE_HTTP=false npm start

• Runs only the STDIO MCP server
• No HTTP interface
• Minimal resource usage for MCP-only scenarios

Configuration

MCP Client Configuration

To connect an MCP client (like Claude Desktop) to this server, use one of these configurations:

Basic Configuration

{
  "mcpServers": {
    "codebase-graph": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "C:/Users/magne/codebase-graph-mcp"
    }
  }
}

Configuration with Custom Neo4j Settings

{
  "mcpServers": {
    "codebase-graph": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "C:/Users/magne/codebase-graph-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-secure-password"
      }
    }
  }
}

Configuration with Voting System Enabled

{
  "mcpServers": {
    "codebase-graph": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "C:/Users/magne/codebase-graph-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "ENABLE_VOTING": "true"
      }
    }
  }
}

Remote Neo4j Configuration

{
  "mcpServers": {
    "codebase-graph": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "C:/Users/magne/codebase-graph-mcp",
      "env": {
        "NEO4J_URI": "bolt://your-neo4j-host:7687",
        "NEO4J_USERNAME": "your-username",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Production Configuration with SSL

{
  "mcpServers": {
    "codebase-graph": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "/path/to/codebase-graph-mcp",
      "env": {
        "NEO4J_URI": "bolt+s://production-neo4j:7687",
        "NEO4J_USERNAME": "production-user",
        "NEO4J_PASSWORD": "secure-production-password",
        "NODE_ENV": "production"
      }
    }
  }
}

Multiple Database Instances

{
  "mcpServers": {
    "codebase-graph-main": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "C:/Users/magne/codebase-graph-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password"
      }
    },
    "codebase-graph-staging": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "C:/Users/magne/codebase-graph-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7688",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "staging-password"
      }
    }
  }
}

For Claude Desktop:

1. Copy one of the configurations above
2. Add it to your Claude Desktop MCP settings
3. Restart Claude Desktop
4. The codebase-graph tools will be available

Configuration Files:

• claude-desktop-config.json - Basic configuration for Claude Desktop
• mcp-config.json - Configuration with environment variables
• config-examples.json - Complete examples for different setups

Environment Variables

Database Connection

• NEO4J_URI - Neo4j connection URI (default: bolt://localhost:7687)
• NEO4J_USERNAME - Neo4j username (default: neo4j)
• NEO4J_PASSWORD - Neo4j password (default: password)

Server Configuration

• ENABLE_HTTP - Enable/disable HTTP server (default: true)
• HTTP_ONLY - HTTP-only mode, disable STDIO (default: false)
• HTTP_PORT - HTTP server port (default: 3000)
• HTTP_HOST - HTTP server host (default: localhost)
• CORS_ORIGIN - CORS origin setting (default: *)

Feature Flags

• ENABLE_VOTING - Enable voting system for community-driven type proposals (default: false)
• ENABLE_AUTH - Enable authentication (default: false)
• NODE_ENV - Environment mode (development, production)
• DEBUG - Enable debug logging (default: false)

Usage Examples

# Local development with custom credentials
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=your_password
npm start

# Enable voting system
export ENABLE_VOTING=true
npm start

# Production setup with SSL
export NEO4J_URI=bolt+s://production-host:7687
export NEO4J_USERNAME=prod_user
export NEO4J_PASSWORD=secure_password
export NODE_ENV=production
npm start

# HTTP-only mode
export HTTP_ONLY=true
export HTTP_PORT=3001
npm run start:http

# STDIO-only mode (minimal resource usage)
export ENABLE_HTTP=false
npm start

Usage

Component Types

Code Components

• FILE: Source code files
• FUNCTION: Functions or methods
• CLASS: Classes or types
• MODULE: Modules or packages
• SYSTEM: High-level system components
• INTERFACE: Interfaces or contracts
• VARIABLE: Variables or constants
• CONSTANT: Constants or configuration

Requirements & Specifications

• REQUIREMENT: System or functional requirements
• SPECIFICATION: Technical specifications
• FEATURE: Feature definitions
• USER_STORY: User stories and scenarios
• ACCEPTANCE_CRITERIA: Acceptance criteria for features
• TEST_CASE: Test cases and scenarios

Relationship Types

Code Relationships

• DEPENDS_ON: Component depends on another
• IMPLEMENTS: Implements an interface
• EXTENDS: Inherits from another component
• CONTAINS: Contains another component
• CALLS: Calls a function or method
• IMPORTS: Imports another module
• EXPORTS: Exports functionality
• OVERRIDES: Overrides parent functionality
• USES: Uses another component
• CREATES: Creates instances of another component

Requirements & Traceability

• SATISFIES: Satisfies a requirement or specification
• DERIVES_FROM: Derived from another requirement
• REFINES: Refines or elaborates on another component
• TRACES_TO: Traces to another component for compliance
• VALIDATES: Validates another component
• VERIFIES: Verifies implementation of another component
• CONFLICTS_WITH: Conflicts with another component
• SUPPORTS: Supports or enables another component
• ALLOCATES_TO: Allocates resources to another component
• REALIZES: Realizes or implements a specification

Task Status

• TODO: Not started
• IN_PROGRESS: Currently being worked on
• DONE: Completed
• BLOCKED: Blocked by dependencies
• CANCELLED: Cancelled

MCP Tools

Component Management

• create_component: Create a new component with type, name, description, path, codebase, and metadata
• get_component: Retrieve component by ID
• search_components: Search components with filters (type, name, codebase)
• update_component: Update component properties
• delete_component: Delete a component and its relationships

Bulk Operations (⭐ Preferred for 2+ Items)

• create_components_bulk: Create multiple components efficiently
• create_relationships_bulk: Create multiple relationships efficiently
• create_tasks_bulk: Create multiple tasks efficiently

Relationship Management

• create_relationship: Create relationship between components with optional details
• get_component_relationships: Get all relationships for a component (incoming, outgoing, or both)
• get_dependency_tree: Get dependency tree with configurable maximum depth

Task Management

• create_task: Create a new task with name, description, status, progress, and related components
• get_task: Get task by ID with full details
• get_tasks: Get all tasks with optional status filtering
• update_task_status: Update task status and progress percentage

Change History & Snapshots

• get_change_history: Get change history for entities or recent changes
• create_snapshot: Create a snapshot of current database state
• list_snapshots: List all available snapshots
• restore_snapshot: Restore database from a snapshot
• replay_to_timestamp: Replay changes to recreate state at specific time
• get_history_stats: Get statistics about change history

Command Queue System

• wait_for_command: Wait for commands from external systems
• send_command: Send commands to waiting agents
• get_waiting_agents: Get status of agents waiting for commands
• get_pending_commands: Get queued but undelivered commands
• cancel_command: Cancel a pending command
• cancel_wait: Cancel an agent's wait for commands
• get_command_history: Get command queue execution history

Voting System (Optional)

• propose_type: Propose new component or relationship types
• vote_on_type: Vote on proposed types
• get_proposed_types: Get all proposed types with status filter
• get_proposed_type: Get details of specific proposed type
• apply_approved_type: Apply approved types to the system
• get_voting_stats: Get voting system statistics

Analysis Tools

• get_codebase_overview: Get comprehensive statistics for a codebase

CLI Queue Waiter Tools

For terminal-enabled agents, the system provides CLI-based queue waiters that don't require MCP client integration:

Start a CLI Queue Waiter

# Wait indefinitely with auto-generated ID
node examples/cli-queue-waiter.js

# Wait with custom session name
node examples/cli-queue-waiter.js my-analysis-agent
node examples/cli-queue-waiter.js build-agent-1

Monitor Agent Capacity

# Show current waiting agents and capacity
node examples/list-agents.js

# Continuous monitoring (refreshes every 5 seconds)
node examples/list-agents.js --watch

# JSON output for programmatic use
node examples/list-agents.js --json

CLI Queue Waiter Features

• Indefinite waiting: Runs until manually canceled (Ctrl+C)
• Named sessions: Custom agent IDs for identification
• Capacity reporting: Automatically reports availability to the system
• Status updates: Real-time uptime and command processing stats
• Graceful shutdown: Clean session termination with statistics
• Auto-reconnection: Automatically re-registers after processing commands

HTTP/SSE API

The server also provides an HTTP REST API with Server-Sent Events for real-time updates:

HTTP Endpoints

• Components: GET|POST|PUT|DELETE /api/components[/:id]
• Relationships: GET|POST /api/relationships
• Tasks: GET|POST|PUT /api/tasks[/:id]
• Bulk Operations: POST /api/{components|relationships|tasks}/bulk
• Analysis: GET /api/codebase/:name/overview
• Change History: GET /api/history
• Command Queue: GET|POST|DELETE /api/commands

Server-Sent Events

• Connection: GET /events
• Events: component-created, component-updated, task-created, etc.
• Bulk Events: components-bulk-created, relationships-bulk-created, etc.
• Real-time Updates: Live notifications of all database changes

Testing HTTP API

# Test bulk operations
node test-bulk-operations.js

# Test SSE connection
node test-sse-client.js

Example Usage

Bulk Operations (Recommended)

// Create multiple components efficiently
const components = [
  {
    type: 'FILE',
    name: 'UserService.ts',
    codebase: 'my-app',
    description: 'User management service'
  },
  {
    type: 'CLASS', 
    name: 'UserService',
    codebase: 'my-app',
    description: 'Main user service class'
  }
];

const result = await createComponentsBulk({ components });
console.log(`Created ${result.length} components`);

Creating Components

// Create a file component
await createComponent({
  type: 'FILE',
  name: 'UserService.ts',
  description: 'User management service',
  path: '/src/services/UserService.ts',
  codebase: 'my-app'
});

// Create a class component  
await createComponent({
  type: 'CLASS',
  name: 'UserService',
  description: 'Handles user CRUD operations',
  path: '/src/services/UserService.ts',
  codebase: 'my-app'
});

Creating Relationships

// File contains class
await createRelationship({
  type: 'CONTAINS',
  sourceId: fileId,
  targetId: classId,
  details: { location: 'line 10' }
});

// Class depends on database
await createRelationship({
  type: 'DEPENDS_ON', 
  sourceId: classId,
  targetId: databaseId,
  details: { reason: 'data persistence' }
});

Creating Tasks

// Create a task linked to components
await createTask({
  name: 'Add user validation',
  description: 'Implement input validation for user creation',
  status: 'TODO',
  progress: 0,
  relatedComponentIds: [userServiceId, validatorId]
});

Analysis Queries

// Get all components in a codebase
const components = await searchComponents({ 
  codebase: 'my-app' 
});

// Get dependency tree
const dependencies = await getDependencyTree(componentId, 3);

// Get codebase overview
const overview = await getCodebaseOverview('my-app');

Integration with AI Agents

This MCP server is designed to work with AI agents for:

1. Code Analysis: Understanding existing codebase structure
2. Impact Assessment: Analyzing changes and their effects
3. Architecture Planning: Designing new features and components
4. Task Management: Tracking development goals and progress
5. Dependency Management: Understanding and managing dependencies

Example Agent Queries

• "What components depend on the User class?"
• "Show me all TODO tasks related to authentication"
• "What would be affected if I change the Database interface?"
• "Create a task to refactor the payment system"

Development

Running Tests

npm test

Development Mode (with auto-reload)

npm run dev

Database Reset

To reset the database:

1. Stop the server
2. Clear Neo4j database (in Neo4j Browser: MATCH (n) DETACH DELETE n)
3. Run setup again: npm run setup-db

Data Model

Neo4j Schema

• Components: Nodes with labels [:Component:TYPE]
• Tasks: Nodes with label [:Task]
• Relationships: Edges between components with type-specific labels
• Task Relations: [:RELATES_TO] edges between tasks and components

Constraints and Indexes

• Unique constraints on component and task IDs
• Indexes on component name, type, and codebase
• Index on task status

Troubleshooting

Common Issues

1. Neo4j Connection Failed

   • Ensure Neo4j is running
   • Check connection details
   • Verify authentication credentials

2. Schema Initialization Failed

   • Check Neo4j permissions
   • Ensure database is empty or compatible

3. MCP Connection Issues

   • Verify stdio transport setup
   • Check MCP client configuration
   • For port conflicts with HTTP server, use MCP-only mode: node src/mcp-only.js

4. "Child process ended (EOF on stdout)" Error

   • This usually indicates the server process crashed during startup
   • Check if another process is using port 3000 (lsof -i :3000)
   • Use the MCP-only entry point to avoid HTTP server conflicts
   • For Goose: Update config to use src/mcp-only.js instead of src/index.js

Logs

Server logs are written to stderr and include:

• Database connection status
• Schema initialization progress
• Error messages with details

Recipes & Best Practices

The recipes/ folder contains structured workflows and best practices for common operations:

Available Recipes

• INGEST_NOTE.md: Step-by-step guide for AI agents to transform unstructured notes into structured component graphs
  • Process for creating NOTE, IDEA, FEATURE, and other component types
  • Relationship modeling patterns
  • Bulk operation workflows
  • Quality checklists and pro tips

Using Recipes

These recipes are designed to help AI agents and developers:

1. Maintain consistency in how data is structured
2. Follow proven patterns for component relationships
3. Use efficient bulk operations for better performance
4. Preserve context and traceability

Recipes include concrete examples, type selection guides, and quality checklists to ensure reliable results across different use cases.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details