Skip to content

user-guide.md

Latest commit

 

History

History
189 lines (142 loc) · 6.18 KB

user-guide.md

File metadata and controls

189 lines (142 loc) · 6.18 KB

CodeRAG User Guide

CodeRAG is a powerful MCP (Model Context Protocol) Server that creates a graph database representation of your codebase using Neo4J. This enables advanced code analysis, relationship mapping, and AI-powered insights about your code structure.

Quick Start

For a complete setup guide, see Installation & Setup.

Essential Steps

  1. Install Prerequisites: Node.js 18+, Neo4J 5.11+
  2. Clone and Build: git clone repo && npm install && npm run build
  3. Configure Environment: Create .env with Neo4J connection details
  4. Start Neo4J: Launch your Neo4J database
  5. Integrate with AI Tool: Configure MCP server in your AI assistant
  6. Scan Your Project: Use the scanner to populate the graph

Documentation Structure

This user guide is organized into focused sections:

🚀 Getting Started

🔍 Core Usage

📊 Advanced Features

🔧 Support

What CodeRAG Does

CodeRAG transforms your codebase into a searchable graph database, enabling:

  • 🔍 Advanced Code Analysis - Find complex relationships and dependencies
  • 🧠 Semantic Code Search - Find code by functionality using natural language queries
  • 📊 Quality Metrics - Calculate industry-standard metrics (CK metrics, package coupling)
  • 🏗️ Architecture Insights - Detect design patterns, architectural issues, and violations
  • 🤖 AI-Powered Exploration - Use natural language to query your codebase structure
  • 📈 Multi-Project Management - Analyze multiple codebases in a unified view
  • 🌐 Remote Repository Analysis - Scan GitHub, GitLab, and Bitbucket repositories directly
  • 🎯 Smart Language Detection - Automatically detects project languages from build files and metadata
  • 🏗️ Mono-Repository Support - Handles complex projects with multiple languages and sub-projects

Example Workflows

Analyzing a New Project

Local Project:

  1. Auto-scan the project (languages detected automatically): 
    Use scan_dir to scan /path/to/my/project with clear_existing=true
    The scanner will automatically detect TypeScript, Java, Python, etc. from build files

Remote Repository:

  1. Scan directly from GitHub/GitLab/Bitbucket:

    Use scan_remote_repo with repository_url=https://github.com/owner/repo.git

    Automatically clones, scans, and cleans up the repository

  2. Get overview with project metadata:

    Use get_project_summary to show me the codebase overview

    Includes auto-extracted project name, version, framework information

  3. Find issues:

    Use find_architectural_issues to identify problems

  4. Analyze key classes:

    Use calculate_ck_metrics for the main service classes

Understanding Dependencies

  1. Find a specific class:

    Use search_nodes to find classes containing "Service"

  2. Analyze its dependencies:

    Use find_dependencies prompt for target_class=UserService

  3. Check coupling:

    Use calculate_ck_metrics for the UserService class

Exploring Architecture

  1. Map inheritance:

    Use analyze_inheritance prompt for class_or_interface=BaseEntity

  2. Find implementations:

    Use find_classes_implementing_interface for Repository

  3. Check package structure:

    Use calculate_package_metrics for com.myapp.service

Semantic Code Discovery

  1. Search by functionality:

    Use semantic_search with query="functions that validate user input"

  2. Find similar code:

    Use get_similar_code for node_id="UserValidator.validateEmail"

  3. Update embeddings after changes:

    Use update_embeddings for project_id="my-project"

Quick Reference Card

Essential Commands

# Setup
npm install && npm run build

# Auto-detect and scan project (recommended)
npm run scan /path/to/project

# Scan remote repository
npm run scan https://github.com/owner/repo.git

# Scan multiple projects (multi-project support)
npm run scan /path/to/project1
npm run scan /path/to/project2

# List all scanned projects
Use list_projects tool to see all projects with statistics

# Start STDIO mode
npm start

# Start HTTP mode
npm start -- --sse --port 3000

Key MCP Tools

  • scan_dir - Scan local codebase
  • scan_remote_repo - Scan remote repositories
  • semantic_search - Natural language code search
  • get_project_summary - Overview
  • find_architectural_issues - Find problems
  • calculate_ck_metrics - Class quality
  • get_similar_code - Find similar code entities
  • get_inheritance_hierarchy - Class relationships

MCP Prompts

  • setup_code_graph - New project setup
  • analyze_codebase - General analysis
  • find_dependencies - Dependency analysis
  • analyze_inheritance - Inheritance analysis

Need More Help?

This overview gets you started quickly. For detailed information:

The combination of automated scanning, quality metrics, and AI-powered analysis makes CodeRAG a powerful tool for understanding and improving your codebase architecture.