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

The Prompt: A developer asks a generic AI assistant: "Show me how to add memory to a LangGraph agent."
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.
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.
The Result: The developer loses time and trust, doing manual debugging that the AI was supposed to prevent.

After: The Grounded Assistant Workflow

The Prompt: A developer asks the LangGraph-Dev-Navigator assistant: "How do I add persistence to my graph?"
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.
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.
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:

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.
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.

Clone the Repository:

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

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.

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

Navigate to the mcp-crawl4ai-rag directory.
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
```
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.

Navigate to the SQL Editor in your Supabase project dashboard.
Click "New query".
Copy the entire content of the mcp-crawl4ai-rag/crawled_pages.sql file and paste it into the query editor.
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 (Recommended)

This is the simplest way to get started.

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

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:/app/.env" \
  -v "$(pwd)/mcp-crawl4ai-rag/reports:/app/reports" \
  mcp-crawl4ai-rag \
  python -u run_one_time_ingestion.py

then validate successful data ingestion.

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

Configure Your AI Assistant to Launch the Server: The following are examples of how to configure your AI coding assistant to connect to the server. For more detailed configurations, please refer to the mcp-crawl4ai-rag/README.md (GitHub) | mcp-crawl4ai-rag/README.md (Local).

For Gemini CLI (.gemini/settings.json):

{
  "mcpServers": {
    "crawl4ai-rag-bash": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "--memory", "512m",
               "-v", "${pwd}/.env:/app/.env",
               "mcp-crawl4ai-rag",
               "bash", "/app/start_mcp_server.sh"],
      "timeout": 600
    }
  }
}

For GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "crawl4ai-rag": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i",
               "--memory", "512m",
               "-v", "$(pwd)/.env:/app/.env",
               "mcp-crawl4ai-rag",
               "bash", "/app/start_mcp_server.sh"]
    }
  }
}

Note: $(pwd) should be the absolute path to the mcp-crawl4ai-rag submodule.

Path B: Local Development Setup (Advanced)

This path is for developers who want to work on the server code directly.

Install uv if you don't have it:
```
pip install uv
```

Create and activate a virtual environment from within the mcp-crawl4ai-rag directory:

cd mcp-crawl4ai-rag
uv venv
source .venv/bin/activate # On Windows, use: .venv\Scripts\activate

Install dependencies:
```
uv pip install -e .
crawl4ai-setup
```
run the validation script in a temporary container (validate your .env enables you to connect to neo4j and Supabase)
```
uv run python validate_setup.py --stage 1
```
Run the One-Time Data Ingestion:
```
uv run python run_one_time_ingestion.py
```

Launch the MCP Server: The following are examples of how to configure your AI coding assistant to connect to the server. For more detailed configurations on configuring your specific AI assistant for local development, please refer to the mcp-crawl4ai-rag/README.md. For more advanced local mcp launch options (e.g. sse server), refer to the mcp-crawl4ai-rag/README.md "Integration with MCP Clients" section (GitHub) | section (Local) for detailed instructions on configuring your specific AI assistant for local development.

for gemini cli (configured in ./gemini/setting.json):

{
  "mcpServers": {
    "crawl4ai-rag-local-bash": {
      "command": "${pwd}/start_mcp_server.sh",
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "{api-key}",
        "SUPABASE_URL": "https://{your-id}.supabase.co",
        "SUPABASE_SERVICE_KEY": "api-key",
        "USE_KNOWLEDGE_GRAPH": "true",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "{password}"
      },
      "timeout": 600
    }
  }
}

for github copilot (configured in .vscode/mcp.json):

{
  // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    "crawl4ai-rag": {
      "type": "stdio",
      "command": "$(pwd)/start_mcp_server.sh"
    }
  }
}

Note: $(pwd) should be the absolute path to the mcp-crawl4ai-rag submodule.

3.5: Validate the Server Setup

After completing either setup path, run the validation script again from within the mcp-crawl4ai-rag directory to ensure everything is working correctly (data write into):

# Ensure you are in the mcp-crawl4ai-rag directory
cd mcp-crawl4ai-rag
uv run python validate_setup.py --stage 2

Step 4: Configure Your AI Assistant

This final step installs the project-specific instructions for your AI coding assistant, enabling it to use the knowledge server and follow the correct development methodology.

Run the following command and select your assistant from the interactive menu:

uv run python src/setup_dev_assistant.py

Advanced Usage & Recipes

Key Tools Unlocked by the MCP Server

Once the MCP server is running, your AI assistant gains access to a powerful new set of tools:

perform_rag_query: Asks a natural language question (e.g., "How do I add memory to a graph?") and gets back the most relevant sections of the LangGraph documentation.
search_code_examples: Searches specifically for runnable code snippets from the documentation.
check_ai_script_hallucinations: Takes a Python script as input and validates it against the Knowledge Graph to check for non-existent classes, methods, or incorrect function calls.
query_knowledge_graph: Allows for direct exploration of the LangGraph codebase structure via graph queries.

Aligning Docs & Code Version

This is an optional but recommended step to ensure the documentation source (for AI assistants to generate code) perfectly matches the version of the langgraph library you have installed.

Find your installed package version:
```
pip show langgraph
```
(Look for the Version: line, e.g., 0.0.56)

Align the submodule to that version tag and commit the change:

# Go into the submodule, check out the tag, then go back
(cd langgraph && git fetch --all --tags && git checkout tags/v0.0.56)

# Commit the new version pointer to your main project
git add langgraph
git commit -m "Align langgraph submodule with v0.0.56"

(Remember to replace v0.0.56 with the version you found in step 1.)

Project Documentation

docs/project_management_guide.md: The standard process for managing epics, stories, and tasks.
memory/tasks/epic_user_experience/README.md: The strategic plan for the User Experience epic.

Contributing

... (Add your contribution guidelines here) ...

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.vscode		.vscode
LICENSES		LICENSES
docs		docs
images		images
langgraph @ 7e73567		langgraph @ 7e73567
langgraph_dev		langgraph_dev
mcp-crawl4ai-rag @ 1f94ac4		mcp-crawl4ai-rag @ 1f94ac4
memory		memory
project_rules		project_rules
src		src
tools		tools
.gitignore		.gitignore
.gitmodules		.gitmodules
LICENSE		LICENSE
META_DOC.md		META_DOC.md
README.md		README.md
langgraph_tree_structure.md		langgraph_tree_structure.md
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

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

A Developer's Workflow: Before and After

Before: The Standard AI Assistant Workflow

After: The Grounded Assistant Workflow

Our Philosophy: Metric-Driven AI Improvement

How It Works

Getting Started

Step 1: Clone the Repository and Submodules

Step 2: Install Core Dependencies

Step 3: Set Up the Knowledge Server

3.1: Prerequisites

3.2: Configure Environment Variables

Understanding Key Configurations

3.3: Set Up the Supabase Database

3.4: Choose Your Server Setup Path

Path A: Docker Setup (Recommended)

Path B: Local Development Setup (Advanced)

3.5: Validate the Server Setup

Step 4: Configure Your AI Assistant

Advanced Usage & Recipes

Key Tools Unlocked by the MCP Server

Aligning Docs & Code Version

Project Documentation

Contributing

About

Uh oh!

Releases

Packages

Languages

License

botingw/langgraph-dev-navigator

Folders and files

Latest commit

History

Repository files navigation

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

A Developer's Workflow: Before and After

Before: The Standard AI Assistant Workflow

After: The Grounded Assistant Workflow

Our Philosophy: Metric-Driven AI Improvement

How It Works

Getting Started

Step 1: Clone the Repository and Submodules

Step 2: Install Core Dependencies

Step 3: Set Up the Knowledge Server

3.1: Prerequisites

3.2: Configure Environment Variables

Understanding Key Configurations

3.3: Set Up the Supabase Database

3.4: Choose Your Server Setup Path

Path A: Docker Setup (Recommended)

Path B: Local Development Setup (Advanced)

3.5: Validate the Server Setup

Step 4: Configure Your AI Assistant

Advanced Usage & Recipes

Key Tools Unlocked by the MCP Server

Aligning Docs & Code Version

Project Documentation

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages