• For bug report, use issues
• For real-time chat, community support, and to share your ideas, Join our Discord
• Have specific feedback or want a personal demo? Book a Chat on my Calendar

LangGraph-Dev-Navigator: Build Reliable AI with Grounded Assistants

AI coding assistants are powerful, but their general knowledge can be outdated or lead to plausible-but-incorrect code ("hallucinations"). This repository addresses that by providing a framework to ground an AI assistant in the executable truth of a specific, version-controlled codebase.

The goal is to create a development environment where AI-generated code is more reliable, robust, and aligned with project-specific best practices.

A Developer's Workflow: Before and After

This framework is designed to transform your daily development experience.

Before: The Standard AI Assistant Workflow

1. The Prompt: A developer asks a generic AI assistant: "Show me how to add memory to a LangGraph agent."
2. The AI's Response: The AI, relying on its vast but general training data, generates a plausible-looking code snippet. However, the snippet might use a function that was deprecated two months ago, or instantiate a class with parameters that are subtly incorrect for the langgraph version you're using.
3. The Debuging Cycle: The code fails to run. The developer copies the error message back to the AI, starting a lengthy back-and-forth conversation to debug the AI's own hallucinated code.
4. The Result: The developer loses time and trust, doing manual debugging that the AI was supposed to prevent.

After: The Grounded Assistant Workflow

1. The Prompt: A developer asks the LangGraph-Dev-Navigator assistant: "How do I add persistence to my graph?"
2. Grounded Response: The assistant uses perform_rag_query to find the canonical documentation on persistence from your specific version of LangGraph. It then uses search_code_examples to find a relevant, runnable example from the same source.
3. Validated Code: The assistant generates the necessary code. It then automatically uses check_ai_script_hallucinations to validate its own output against the actual library structure, ensuring it uses the correct classes and methods.
4. The Result: You get working, reliable code in minutes, with high confidence that it is correct for your environment.

Our Philosophy: Metric-Driven AI Improvement

We treat the enhancement of AI development assistance as a scientific endeavor. This project is a living experiment to systematically improve the reliability of AI assistants on LangGraph development. We measure our success by tracking key metrics:

• Reduction in Hallucinations: A quantifiable decrease in the generation of incorrect code.
• Increased Development Autonomy: A reduction in the number of conversational turns needed to complete a task.
• Improved First-Pass Success Rate: An increase in the percentage of AI-generated code that runs correctly without human modification.

By using this framework, you are not just getting a tool; you are participating in a structured approach to making AI a more reliable and efficient development partner.

How It Works

graph LR
    %% Style Definitions
    classDef user fill:#D6EAF8,stroke:#5DADE2,color:#000
    classDef assistant fill:#D5F5E3,stroke:#58D68D,color:#000
    classDef component fill:#FDEDEC,stroke:#F1948A,color:#000

    %% Define Nodes and Subgraphs
    subgraph User
        U[User Asks Question]:::user
    end

    subgraph "Grounded AI Assistant"
        A[Retrieve Context]:::assistant
        B[Generate Code]:::assistant
        C[Validate Code]:::assistant
        D[Deliver Verified Answer]:::assistant
    end

    subgraph "External Knowledge Components"
        RAG["Supabase RAG<br>(Docs & Examples)"]:::component
        KG["Neo4j Knowledge Graph<br>(Code Structure)"]:::component
    end

    %% Define Connections with Actions
    U -- "Asks a question" --> A
    A -- "Queries for docs" --> RAG
    RAG -- "Returns relevant info" --> B
    B -- "Generates code draft" --> C
    C -- "Validates against KG" --> KG
    KG -- "Returns validation result" --> C
    C -- "If valid, finalizes code" --> D
    D -- "Provides verified code" --> U

This project empowers developers to build robust, reliable, and well-documented LangGraph applications by ensuring AI-generated code adheres to best practices and leverages official, version-controlled documentation. It achieves this through two primary mechanisms:

1. A Local Knowledge Source: It uses a local git submodule of the official langchain-ai/langgraph repository as the ground truth for documentation and code structure.
2. An Advanced Knowledge Server: It includes the mcp-crawl4ai-rag server, which provides two powerful capabilities:
   • Retrieval-Augmented Generation (RAG): Performs semantic search across the entire LangGraph documentation. This allows an AI assistant to find the most relevant, up-to-date information to answer questions and generate accurate code.
   • Knowledge Graph (KG): Ingests the langgraph codebase into a graph database. This allows the server to validate AI-generated code against the actual structure of the library, drastically reducing code "hallucinations" (e.g., usage of non-existent functions or incorrect parameters).

Getting Started

For a high-level overview of the project's components, see the Architecture Diagram.

This guide provides a comprehensive, step-by-step walkthrough for setting up the langgraph-dev-navigator and all its features.

Step 1: Clone the Repository and Submodules

This step clones the main repository and the required langgraph submodule, which serves as the local knowledge source.

1. Clone the Repository:

   git clone --recursive https://github.com/botingw/langgraph-dev-navigator.git
   cd langgraph-dev-navigator
   

2. Initialize Submodules (if not cloned recursively): If you cloned the repository without the --recursive flag, you must initialize the submodules manually:

   git submodule update --init --recursive
   

Step 2: Install Core Dependencies

Install the required Python packages for the project. they are dependencies for langgraph development.

# from the root of the langgraph-dev-navigator directory
uv pip install -r requirements.txt

Step 3: Set Up the Knowledge Server

This section activates the powerful RAG and Knowledge Graph capabilities of the project by configuring and launching the mcp-crawl4ai-rag server submodule.

Are you a hosted (remote) MCP client only? Skip local setup and read the Remote MCP Client Quickstart for the lightweight flow (hosted URL + attached langgraph-ai-rules_v4_1.md, no need to clone this repo).

You have three paths:

• Path A/B (Local): Run your own backend. Complete all substeps (3.1–3.5).
• Path C (Hosted MCP / Remote only): If you received the hosted URL from the maintainer, skip local backend setup, use Path C to configure your client, then jump to Step 4. The real URL is shared privately; the placeholder remains in this repo.

3.1: Prerequisites

Before you begin, ensure you have the following:

• Docker: For the recommended container-based setup.
• Python 3.12+ & uv: Required for the local development path and validation scripts.
• API Keys & Credentials:
  • OpenAI API Key: Required for generating embeddings for the RAG system. Get your API Key here.
  • Supabase Project: Used as a vector database to store the LangGraph documentation for RAG. Create a Supabase project. You will need your Project URL and service_role key.
  • Neo4j Instance: Used as a graph database for the Knowledge Graph. Sign up for Neo4j AuraDB (cloud) or Install Neo4j Desktop (local).

Here is the video for Supabase, Neo4j, OpenAI API key setup guide.

For more detailed information on setting up these services, refer to the Database Setup (GitHub) | Database Setup (Local) and Knowledge Graph Setup (GitHub) | Knowledge Graph Setup (Local) sections in the submodule's README.

3.2: Configure Environment Variables

1. Navigate to the mcp-crawl4ai-rag directory.
2. Create a .env file by copying the example file. The example file is pre-configured with the recommended settings for this project.

   cp mcp-crawl4ai-rag/.env.example mcp-crawl4ai-rag/.env
   

3. Edit mcp-crawl4ai-rag/.env and fill in your API keys and service URLs from the prerequisites. If do not know where to find environment variables for Supabase, neo4j, OpenAI API key, this video is helpful.

Understanding Key Configurations

The .env.example file is set up with the following recommended defaults:

• TRANSPORT='stdio': This is the recommended setting. It allows your AI coding assistant to start and stop the MCP server on demand, which is the most seamless experience. You might change this to sse if you plan to have multiple different clients connect to a single, long-running server instance.
• USE_KNOWLEDGE_GRAPH=true: This enables the powerful AI code hallucination checker.
• USE_AGENTIC_RAG=true: This enables the specialized tool for finding code examples.
• NEO4J_URI='bolt://host.docker.internal:7687': This is the correct setting for the recommended Docker setup, as it allows the container to connect to the Neo4j database running on your host machine. If you are using the advanced local setup, you should change this to bolt://localhost:7687.

For a detailed explanation of all available RAG strategies and other advanced settings, please see the Configuration (GitHub) | Configuration (Local) section in the submodule's README.

3.3: Set Up the Supabase Database

This is a one-time setup step to prepare your Supabase project to store the crawled documentation.

1. Navigate to the SQL Editor in your Supabase project dashboard.
2. Click "New query".
3. Copy the entire content of the mcp-crawl4ai-rag/crawled_pages.sql file and paste it into the query editor.
4. Click "Run" to execute the script and create the necessary tables and functions.

3.4: Choose Your Server Setup Path

Now, choose one of the following paths to install and run the MCP server.

Path A: Docker Setup (Local, Recommended)

This is the simplest way to get started.

1. Build the Docker Image:

   docker build -t mcp-crawl4ai-rag -f mcp-crawl4ai-rag/Dockerfile mcp-crawl4ai-rag
   

   Then, run the validation script in a temporary container (validate your .env enables you to connect to neo4j and Supabase):

   docker run --rm --memory "512m" -v "$(pwd)/.env:/app/.env" mcp-crawl4ai-rag python -u validate_setup.py --stage 1
   

2. Run the One-Time Data Ingestion: This command runs a temporary container to crawl the documentation and populate your Supabase and Neo4j databases.

   docker run --rm --memory "512m" \
     -v "$(pwd)/mcp-crawl4ai-rag/.env:/ap