Jqassistant Graph Rag

Java/Kotlin source Graph RAG (graphRAG) based on jQAssistant

This project transforms a Neo4j graph generated by jQAssistant into a semantically rich, AI-ready knowledge graph. It enriches the graph by linking compiled Java/Kotlin artifacts to their original source code and then generates multi-level, context-aware summaries for every component of the codebase, from individual methods to the entire project.

This enriched graph can be queried by AI agents and developers to gain deep insights into the software's architecture, behavior, and design.

Example Questions it Can Help With:

• "What is the primary role/responsibility of the user-service package?"
• "Show me the key components in the com.example.payment directory."
• "What is the workflow for processing a new order?"
• "How to refactor the payment process to improve performance?"

Table of Contents

• [Why This Project?](#why-this-project)
• [Key Features & Design Principles](#key-features--design-principles)
• [Prerequisites](#prerequisites)
• [jQAssistant graph](#jqassistant-graph)
• [Python Environment](#python-313-or-higher)
• [Usage (for graphRAG building)](#usage-for-graphrag-building)
• [Common Options](#common-options)
• [Interacting with the Graph: AI Agent](#interacting-with-the-graph-ai-agent)
• [Example Workflow](#example-workflow)
• [Documentation](#documentation)

---

Why This Project?

jQAssistant is a powerful tool for scanning compiled Java/Kotlin artifacts (.jar, .class files) and creating a structural graph of the classes in Neo4j. However, this graph represents the bytecode, which lacks two critical elements for modern AI-driven analysis:

1. No source code for analysis: The graph knows about com.example.UserService as a compiled type but doesn't have a robust, queryable structure to the source code structure like UserService.java where the real logic is expressed.
2. No code semantic understanding: A structural graph can show the dependencies between basic entities like method invocations, class inheritances, but it doesn't explain why and how the code is designed and implemented. It lacks the semantic "glue" that describes the purpose and role of each component.

This project bridges that gap. It ingests a jQAssistant graph and performs a two-stage enhancement process:

1. Graph Enrichment: Building on the jQAssistant graph, it parses the source code, and creates a rich set of properties and relationships to model the codebase accurately. It actually builds two overlay graphs on top of the jQAssistant graph: one for source code structure and another for class hierarchies.
2. RAG Generation: It walks the entire enriched graph in a structured, bottom-up manner, using a Large Language Model (LLM) to generate summaries for every method, type, file, directory, package, and the project itself.

The result is a powerful, multi-layered knowledge graph that combines structural accuracy with deep semantic understanding, making it an ideal foundation for advanced code analysis and AI agent interaction.

Key Features & Design Principles

Graph Enrichment

• Source structure overlay: Adds a source code structure overlay to the jQAssistant graph, enabling AI agents to understand the codebase's structure and relationships.
• Graph normalization: Normlizes the graph with conventional properties and relationships such as canonical absolute paths, fully qualified names, stable IDs, etc., faciliating AI agents to query and reason about the graphRAG.
• Modular & Extensible Architecture: Built with a clean separation of concerns (Orchestrator, Normalizer, Linker, Summarizers), making the system easy to understand and maintain.

RAG Generation

• Hierarchical, dependency-aware Summarization: Generates summaries in a dependency-aware order, starting from methods and building up to the project level.
• Scalable Token Management: Intelligently handles large source files and complex components by automatically chunking context to fit within the LLM's token limits.
• Incremental & Resumable Processing: Uses a resilient caching system to track progress and avoid re-processing unchanged code, saving significant time and LLM costs on subsequent runs.

Prerequisites

jQAssistant graph

You should setup your jQAssistant graph first. Download and install jQAssistant from here. You can configure it to use embedded Neo4j (by default) or connect to an external Neo4j instance.

An example configuration file to specify different ports (to avoid port conflicts with your other Neo4j instances) and plugins is given below that you can copy to ~/jqassistant/jqassistant.yml.

jqassistant:
  store:
    embedded:
      # Specify the ports here
      bolt-port: 7688 # default: 7687
      http-port: 7777 # default: 7474
      # Optional: listen on all interfaces (0.0.0.0) or just localhost
      listen-address: "0.0.0.0"
      # The neo4j apoc-core is always useful
      neo4j-plugins:
        - group-id: org.neo4j.procedure
          artifact-id: apoc-core
          classifier: core
          version: 5.26.2

  #analyze:
  #  concepts:
  #    - "java:MethodOverrides"

Your Java/Kotlin project should include both source code and compiled files. Make sure you have the compiled .class files or .jar files of your project, and the source code. jQAssistant mainly works with the compiled artifacts and generate the graph based on them. (If your source code are built to generate class files and also produce jar files for the same class files, suggest don't include both the class files and the jar files from the same source code, as jQAssistant will generate duplicate class hierarchy nodes in the graph.)

Generating the graph with jQAssistant: After installing jQAssistant, you can generate the graph by running the following commands.

• If your source tree and compiled artifacts are in the same directory:

``bash jqassistant scan -f java:classpath:: ``

• Note, the java:classpath: prefix is required by jQAssistant to indicate that the path is a classpath so that it will parse the class files inside it. (The source tree is not a classpath, but without it, jQAssistant will not parse the class files under the path.) To be safe, please always use the prefix, unless you provide the source tree and the build tree separately like below.

• If your source tree and compiled class/jar files have different paths, you can specify them separately:

``bash jqassistant scan -f -f java:classpath:: [-f java:classpath::] ``

Please refer to the jQAssistant documentation for more information.

Python 3.13 or higher.

Installation of required Python packages:

pip install -r requirements.txt

• The google-sdk package is for the example coding agent to run. If you don't plan to use the coding agent, you can skip this package.
• The fastmcp package is for the example mcp server to run. If you don't plan to use the mcp server, you can skip this package.

Usage (for graphRAG building)

After you have a running Neo4j instance with a graph already generated by jQAssistant, you can use this tool to enrich the graph and generate RAG summaries.

python3 main.py [--generate-summary --llm-api ] 

• Without --generate-summary, the tool will only perform the graph enrichment phase. This is to give you an option to check the enrichment results before generating summaries, which may cost time and money.

• With --generate-summary enabled, the tool will generate summary. By default it will use --llm-api fake to test the summary generation without actually calling an LLM API. You can use --llm-api [openai|deepseek|ollama|fake] to specify the LLM API to use. Option ollama will use local ollama setup. Please check the llm_client.py for the details.

• The generated summaries are cached in /.cache/summary_cache.json, so that you don't need to regenerate them if the source code remains unchanged. You can move or rename this file to force regeneration.

• The ` is the path to the project directory jQAssistant scanned. If you scanned multiple paths, the default ` is the common prefix of all the scanned paths.

Common Options

• --uri : Neo4j connection URI (default: bolt://localhost:7687).
• --user : Neo4j username (default: neo4j).
• --password : Neo4j password.
• --log-level : Set the console logging level (e.g., DEBUG, INFO; default: INFO).
• --log-file : Path to a file to store logs.
• --generate-summary: Flag to enable the RAG summary generation phase. By default, it is disabled.
• --llm-api : The name of the LLM API to use for summarization (e.g., fake, deepseek, openai, ollama). Default is fake, with which the LLM API returns a placeholder string.

Interacting with the Graph: AI Agent

Once the code graph is built and enriched, you can interact with it using natural language through an AI agent. The project provides an example implementation of an MCP tool server and an agent built with the Google Agent Development Kit (ADK) to enable this.

1. mcp_server.py: This is a tool server that exposes the Neo4j graph to an AI agent. It provides example tools like get_graph_schema, execute_cypher_query, and get_file_source_code_by_path, etc. They are bare minimum yet super powerful tools for AI agent to interact with the graph.
2. rag_adk_agent/: This directory contains an example agent built with the Google Agent Development Kit (ADK). This agent uses the tools from the MCP server to answer questions about your codebase. With an LLM API, it can do almost anything you can think of with your project, demonstrating what is possible with the tools provided.

Example Workflow

1. Start the Tool Server: After your jQAssistant server is running, in one terminal, start the MCP server. It will connect to Neo4j and wait for agent requests.

``bash python3 mcp_server.py ` It starts the MCP server at http://0.0.0.0:8800/mcp`.

1. Run the Agent: In another terminal, run the agent.

By default, the agent connects the MCP server at http://127.0.0.1:8800/mcp, and uses LLM model deepseek/deepseek-chat via LiteLlm package. You can change the LLM_MODEL by setting the LLM_MODEL variable in the rag_adk_agent/agent.py file. For whatever LLM model you use, you need setup its API key per request by LiteLlm package.

The recommended way is to use the ADK web UI. ``bash # For a web UI interaction adk web ` Then point to the server URL in your browser (default is http://127.0.0.1:8000) and select the agent ragadkagent`.

Or you can run it in a command-line session. ``bash # For an interactive command-line session adk run rag_adk_agent `` You can now ask the agent questions.

Documentation

For a deep dive into the project's architecture, component responsibilities, and the logic behind the hierarchical processing and iterative summarization, please refer to the comprehensive documentation in the [docs/](./docs/README.md) directory.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 2015xli
• Source: 2015xli/jqassistant-graph-rag
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.