Code Graph Knowledge System

Enterprise knowledge management platform with Neo4j graph database, multi-interface architecture (MCP/Web/REST), and intelligent code analysis for modern software development teams.

Overview

Code Graph Knowledge System is a production-ready platform that transforms code repositories and development documentation into a queryable knowledge graph. Built on Neo4j's graph database technology and powered by large language models, the system provides three distinct interfaces for different use cases: MCP protocol for AI assistants, Web UI for human users, and REST API for programmatic access.

The platform combines vector search, graph traversal, and LLM-driven analysis to deliver intelligent code intelligence capabilities including repository analysis, dependency mapping, impact assessment, and automated documentation generation.

Core Capabilities

Multi-Interface Architecture

MCP Protocol (Port 8000) - Model Context Protocol server for AI assistant integration

Direct integration with Claude Desktop, Cursor, and other MCP-compatible tools
25+ specialized tools for code analysis and knowledge management
Real-time task monitoring via Server-Sent Events
Supports stdio and SSE transport modes

Web UI (Port 8080) - Browser-based interface for team collaboration

Real-time task monitoring dashboard
Repository ingestion and management
Metrics visualization with interactive charts
Built with React 18, TypeScript, and shadcn/ui components

REST API (Ports 8000, 8080) - HTTP endpoints for system integration

Document ingestion and knowledge querying
Task management and monitoring
Prometheus metrics export
OpenAPI/Swagger documentation

Knowledge Graph Engine

Code Intelligence - Graph-based code analysis without requiring LLMs

Repository structure mapping and dependency tracking
Function and class relationship analysis
Impact analysis for code changes
Context pack generation for AI assistants
Support for 15+ programming languages

Memory Store - Project knowledge tracking with temporal awareness

Fact, decision, pattern, and insight recording
Memory evolution with superseding relationships
Automatic extraction from conversations, commits, and code
Vector search with embedding-based retrieval

Knowledge RAG - Document processing with hybrid search

Multi-format document ingestion (Markdown, PDF, code files)
Neo4j native vector indexing
Hybrid search combining vector similarity and graph traversal
Configurable chunking and embedding strategies

SQL Schema Parser - Database schema analysis with business domain classification

Multi-dialect support (Oracle, MySQL, PostgreSQL, SQL Server)
Configurable business domain templates (Insurance, E-commerce, Banking, Healthcare)
Automated relationship detection and documentation generation
Integration with knowledge graph for cross-referencing

Technology Stack

Backend Infrastructure

FastAPI - High-performance async web framework
Neo4j 5.x - Graph database with native vector indexing
Python 3.13+ - Modern Python with type hints
Uvicorn - ASGI server with WebSocket support

AI and ML Integration

LlamaIndex - Document processing and retrieval pipeline
Multiple LLM providers (Ollama, OpenAI, Gemini, OpenRouter)
Flexible embedding models (HuggingFace, Ollama, OpenAI)
Model Context Protocol (MCP) for AI assistant integration

Frontend Technology

React 18 - Modern UI library with concurrent features
TypeScript - Type-safe development
TanStack Router - Type-safe routing
shadcn/ui - Accessible component library
Vite - Fast build tooling

Quick Start

Prerequisites

Python 3.13 or higher
Neo4j 5.0 or higher
Docker (optional, for containerized deployment)
Node.js 18+ (for frontend development)

Querying Knowledge

# Query the knowledge base
response = httpx.post("http://localhost:8000/api/v1/knowledge/query", json={
    "question": "How does the authentication system work?",
    "mode": "hybrid",  # or "graph_only", "vector_only"
    "use_tools": False,
    "top_k": 5
})

# Search similar documents
response = httpx.post("http://localhost:8000/api/v1/knowledge/search", json={
    "query": "user authentication",
    "top_k": 10
})

Installation

Clone the repository and install dependencies:

git clone https://github.com/royisme/codebase-rag.git
cd codebase-rag
pip install -r requirements.txt
# or using uv (recommended)
uv pip install -e .

Configure environment variables:

cp env.example .env
# Edit .env with your Neo4j credentials and LLM provider settings

Start Neo4j database:

docker run --name neo4j-code-graph \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:5.15

Running the System

Complete System (MCP + Web UI + REST API)

python start.py

Access points:

MCP SSE Service: http://localhost:8000/sse
Web UI: http://localhost:8080
REST API Documentation: http://localhost:8080/docs
Prometheus Metrics: http://localhost:8080/metrics

MCP Server Only

python start_mcp.py

Docker Deployment

Three deployment modes available:

Minimal Mode - Code Graph only (no LLM required)

make docker-minimal

Standard Mode - Code Graph + Memory Store (embedding model required)

make docker-standard

Full Mode - All features (LLM + embedding required)

make docker-full

Usage Examples

MCP Integration

Configure in Claude Desktop or compatible MCP client:

{
  "mcpServers": {
    "code-graph": {
      "command": "python",
      "args": ["/path/to/start_mcp.py"],
      "cwd": "/path/to/codebase-rag"
    }
  }
}

Available MCP tools include:

code_graph_ingest_repo - Ingest code repository
code_graph_related - Find related code elements
code_graph_impact - Analyze change impact
query_knowledge - Query knowledge base
add_memory - Store project knowledge
extract_from_conversation - Extract insights from chat
watch_task - Monitor task progress

REST API

Ingest a repository:

curl -X POST http://localhost:8080/api/v1/repositories/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/user/repo.git",
    "mode": "incremental",
    "languages": ["python", "typescript"]
  }'

Query knowledge base:

curl -X POST http://localhost:8080/api/v1/knowledge/query \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does authentication work in this codebase?",
    "mode": "hybrid",
    "top_k": 5
  }'

Monitor tasks:

curl http://localhost:8080/api/v1/tasks?status=processing

Web UI

Navigate to http://localhost:8080 to access:

Dashboard - System health and quick actions
Tasks - Real-time task monitoring with progress indicators
Repositories - Repository management and ingestion
Metrics - System performance and usage metrics

Configuration

Key environment variables:

# Server Ports
MCP_PORT=8000              # MCP SSE service
WEB_UI_PORT=8080           # Web UI and REST API

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j

# LLM Provider (ollama, openai, gemini, openrouter)
LLM_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2

# Embedding Provider (ollama, openai, gemini, openrouter)
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

# Processing Configuration
CHUNK_SIZE=512
CHUNK_OVERLAP=50
TOP_K=5
VECTOR_DIMENSION=384

For complete configuration options, see Configuration Guide.

Architecture

Dual-Server Design

The system employs a dual-server architecture optimized for different access patterns:

Port 8000 (Primary) - MCP SSE Service

Server-Sent Events endpoint for real-time communication
Optimized for AI assistant integration
Handles long-running task monitoring
WebSocket support for bidirectional communication

Port 8080 (Secondary) - Web UI + REST API

React-based monitoring interface
RESTful API for external integrations
Prometheus metrics endpoint
Static file serving for frontend

Both servers share the same backend services and Neo4j database, ensuring consistency across all interfaces.

Component Architecture

┌─────────────────────────────────────────────────────────┐
│                   Client Interfaces                      │
├──────────────┬──────────────┬──────────────────────────┤
│  MCP Client  │   Web UI     │      REST API            │
│  (AI Tools)  │  (Browser)   │   (External Systems)     │
└──────┬───────┴──────┬───────┴──────────┬───────────────┘
       │              │                  │
       └──────────────┼──────────────────┘
                      │
       ┌──────────────▼──────────────┐
       │     FastAPI Application      │
       ├──────────────┬──────────────┤
       │   Services   │  Task Queue  │
       └──────┬───────┴──────┬───────┘
              │              │
       ┌──────▼──────┐  ┌───▼────┐
       │   Neo4j     │  │  LLM   │
       │  Database   │  │Provider│
       └─────────────┘  └────────┘

Development

Project Structure

codebase-rag/
├── src/codebase_rag/
│   ├── api/                    # FastAPI routes
│   ├── core/                   # Application core
│   ├── services/               # Business logic
│   │   ├── code_ingestor.py    # Code repository processing
│   │   ├── graph_service.py    # Graph operations
│   │   ├── memory_store.py     # Project memory management
│   │   ├── neo4j_knowledge_service.py  # Knowledge base
│   │   ├── task_queue.py       # Async task processing
│   │   └── sql/                # SQL parsing services
│   └── mcp/                    # MCP protocol handlers
├── frontend/                   # React Web UI
│   ├── src/
│   │   ├── components/         # UI components
│   │   ├── routes/             # Page routes
│   │   └── lib/                # API client
│   └── package.json
├── tests/                      # Test suite
├── docs/                       # Documentation
└── scripts/                    # Utility scripts

Running Tests

# Backend tests
pytest tests/ -v

# Frontend tests
cd frontend && npm test

# Integration tests (requires Neo4j)
pytest tests/ -m integration

# Coverage report
pytest tests/ --cov=src --cov-report=html

Code Quality

# Format code
black .
isort .

# Linting
ruff check .
ruff check . --fix

# Type checking
mypy src/

Frontend Development

cd frontend
npm install
npm run dev        # Start dev server at http://localhost:3000
npm run build      # Build for production
npm run lint       # Check for issues
npm test           # Run tests

Deployment

Production Deployment

See Docker Deployment Guide for production deployment configurations including:

Multi-stage Docker builds
Environment-specific configurations
Scaling and load balancing
Security best practices
Monitoring and logging setup

System Requirements

Minimum Configuration

CPU: 2 cores
RAM: 4 GB
Storage: 10 GB

Recommended Configuration

CPU: 4+ cores
RAM: 8+ GB
Storage: 50+ GB SSD
Network: 100 Mbps+

Documentation

Complete documentation available at https://vantagecraft.dev/docs/code-graph

Key Documentation Sections

Quick Start Guide - Get up and running in 5 minutes
Architecture Overview - System design and components
MCP Integration - AI assistant integration
REST API Reference - Complete API documentation
Deployment Guide - Production deployment
Development Guide - Contributing and development

Community and Support

Documentation: Complete Documentation
Neo4j Guide: README_Neo4j.md
Issues: GitHub Issues
Discussions: GitHub Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with excellent open source technologies:

Neo4j - Graph database platform
LlamaIndex - Data framework for LLM applications
FastAPI - Modern web framework for Python
React - Library for building user interfaces
Model Context Protocol - AI assistant integration standard

Name		Name	Last commit message	Last commit date
Latest commit History 180 Commits
.github		.github
docker		docker
docs		docs
examples		examples
frontend		frontend
mcp-registry-submission		mcp-registry-submission
scripts		scripts
src/codebase_rag		src/codebase_rag
tests		tests
.bumpversion.toml		.bumpversion.toml
.cursorignore		.cursorignore
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
README_CN.md		README_CN.md
README_Neo4j.md		README_Neo4j.md
docker-compose.yml		docker-compose.yml
env.example		env.example
mcp_config.json		mcp_config.json
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt

royisme/codebase-rag

Folders and files

Latest commit

History

Repository files navigation