CodeGraphContext

An MCP server that indexes local code into a graph database to provide context to AI assistants.

• Version: 0.1.16
• Authors: Shashank Shekhar Singh [email protected]
• License: MIT License (See LICENSE for details)
• Website: CodeGraphContext

• Code Indexing: Analyzes code and builds a knowledge graph of its components.
• Relationship Analysis: Query for callers, callees, class hierarchies, call chains and more.
• Live Updates: Watches local files for changes and automatically updates the graph.
• Interactive Setup: A user-friendly command-line wizard for easy setup.

CodeGraphContext is already being explored by developers and projects for:

• Static code analysis in AI assistants
• Graph-based visualization of projects
• Dead code and complexity detection

If you’re using CodeGraphContext in your project, feel free to open a PR and add it here! 🚀

• neo4j>=5.15.0
• watchdog>=3.0.0
• requests>=2.31.0
• stdlibs>=2023.11.18
• typer[all]>=0.9.0
• rich>=13.7.0
• inquirerpy>=0.3.4
• python-dotenv>=1.0.0
• tree-sitter==0.20.4
• tree-sitter-languages==1.10.2

1. Install: pip install codegraphcontext

2. Setup: cgc setup This interactive command guides you through configuring your Neo4j database connection and automatically setting up your IDE.

   ⚙️ Troubleshooting: In case, command cgc not found

   If you encounter "cgc: command not found" after installation, run the PATH fix script:

   Linux/Mac:

   # Download the fix script
   curl -O https://raw.githubusercontent.com/Shashankss1205/CodeGraphContext/main/scripts/post_install_fix.sh
   
   # Make it executable
   chmod +x post_install_fix.sh
   
   # Run the script
   ./post_install_fix.sh
   
   # Restart your terminal or reload shell config
   source ~/.bashrc  # or ~/.zshrc for zsh users

   Windows (PowerShell):

   # Download the fix script
   curl -O https://raw.githubusercontent.com/Shashankss1205/CodeGraphContext/main/scripts/post_install_fix.sh
   
   # Run with bash (requires Git Bash or WSL)
   bash post_install_fix.sh
   
   # Restart PowerShell or reload profile
   . $PROFILE

   Database Configuration:

   • Local Setup (Docker Recommended): Helps you set up a local Neo4j instance using Docker. Requires Docker and Docker Compose to be installed.
   • Local Setup (Linux Binary): For Debian-based Linux systems (like Ubuntu), cgc setup can automate the installation of Neo4j. Requires sudo privileges.
   • Hosted Setup: Allows you to connect to an existing remote Neo4j database (e.g., Neo4j AuraDB).

   IDE/CLI Configuration: After setting up your database, the wizard will ask to configure your development environment. It can automatically detect and configure the following:

   • VS Code
   • Cursor
   • Windsurf
   • Claude
   • Gemini CLI
   • ChatGPT Codex
   • Cline
   • RooCode
   • Amazon Q Developer

   Upon successful configuration, cgc setup will generate and place the necessary configuration files:

   • It creates an mcp.json file in your current directory for reference.
   • It stores your Neo4j credentials securely in ~/.codegraphcontext/.env.
   • It updates the settings file of your chosen IDE/CLI (e.g., .claude.json or VS Code's settings.json).

3. Start: cgc start

The cgc setup command attempts to automatically configure your IDE/CLI. If you choose not to use the automatic setup, or if your tool is not supported, you can configure it manually.

Add the following server configuration to your client's settings file (e.g., VS Code's settings.json or .claude.json):

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "cgc",
      "args": [
        "start"
      ],
      "env": {
        "NEO4J_URI": "YOUR_NEO4J_URI",
        "NEO4J_USERNAME": "YOUR_NEO4J_USERNAME",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD"
      },
      "tools": {
        "alwaysAllow": [
          "add_code_to_graph",
          "add_package_to_graph",
          "check_job_status",
          "list_jobs",
          "find_code",
          "analyze_code_relationships",
          "watch_directory",
          "find_dead_code",
          "execute_cypher_query",
          "calculate_cyclomatic_complexity",
          "find_most_complex_functions",
          "list_indexed_repositories",
          "delete_repository",
          "visualize_graph_query",
          "list_watched_paths",
          "unwatch_directory"
        ],
        "disabled": false
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Once the server is running, you can interact with it through your AI assistant using plain English. Here are some examples of what you can say:

• To index a new project:

  • "Please index the code in the /path/to/my-project directory." OR
  • "Add the project at ~/dev/my-other-project to the code graph."

• To start watching a directory for live changes:

  • "Watch the /path/to/my-active-project directory for changes." OR
  • "Keep the code graph updated for the project I'm working on at ~/dev/main-app."

  When you ask to watch a directory, the system performs two actions at once:

  1. It kicks off a full scan to index all the code in that directory. This process runs in the background, and you'll receive a job_id to track its progress.
  2. It begins watching the directory for any file changes to keep the graph updated in real-time.

  This means you can start by simply telling the system to watch a directory, and it will handle both the initial indexing and the continuous updates automatically.

• Finding where code is defined:

  • "Where is the process_payment function?"
  • "Find the User class for me."
  • "Show me any code related to 'database connection'."

• Analyzing relationships and impact:

  • "What other functions call the get_user_by_id function?"
  • "If I change the calculate_tax function, what other parts of the code will be affected?"
  • "Show me the inheritance hierarchy for the BaseController class."
  • "What methods does the Order class have?"