Context Augmentation

Sonar Context Augmentation injects deep, repository-aware context into your AI agent's workflow, guiding code generation with architectural awareness and project-specific coding guidelines.

This feature is in Beta stage and is only available with SonarQube Cloud projects. See the Product release lifecycle page for more information on release stages.

The Agentic Workflow

Context Augmentation is the Guide phase of the SonarQube Agentic Workflow — a continuous loop that ensures AI-generated code is both architecturally sound and meets your quality standards.

1. Guide: Context Augmentation injects architectural awareness and coding guidelines into the LLM context before code generation.

2. Generate: The LLM generates code based on the augmented context.

3. Verify: Agentic Analysis verifies the generated code with full CI-level precision.

4. Loop: The LLM refines the code based on analysis results and repeats until quality gates pass.

This workflow unlocks AI productivity without trade-offs, ensuring clean pull requests pass quality gates the first time, leading to faster code reviews with no back-and-forth.

For the Verify phase, see Agentic Analysis.

---

Overview

Utilizing the Model Context Protocol (MCP), Context Augmentation bridges the gap between general-purpose AI agents (like Cursor, Copilot, and Codex) and the specific intricacies of your repository.

This capability ensures that the resulting AI-generated code is not generic and adheres to your repository's unique standards.

Core capabilities

• Architectural Awareness: Helps agents navigate complex class hierarchies, trace upstream/downstream call flows, and understand execution paths.

• Intelligent Guidelines: Automatically injects relevant coding rules, quality standards, and security requirements based on your project's history and the specific task at hand.

• Semantic Navigation: Moves beyond simple text matching to retrieve code based on its actual meaning and structure using Abstract Syntax Trees (AST), semantics, and control flow information.

Supported languages

The Architectural Awareness features are currently available for Java only. Intelligent Guidelines are supported for all languages available in SonarQube Cloud.

Automatic analysis is currently not supported by the architectural features.

Features

When Context Augmentation is activated, the SonarQube MCP Server is extended with additional MCP tools for LLM context augmentation for code generation:

• Guidelines tools enforcing "Do X, don't do Y" coding standards are added, based on Sonar Rules in the project Quality Profiles.

• Architecture tools augmenting the LLM context with intended architecture, codebase structure, code flow, and semantic navigation are added.

Context augmentation for guidelines

The MCP tool for guidelines injects relevant Sonar rules into the LLM context:

• based on your prompt

  • e.g. if the user prompt involves access to DB → include all guidelines about DB

• based on the SonarQube issues found in files modified or related to the LLM task

  • e.g. if the LLM plans to modify DBStorage.java → include guidelines from past issues in DBStorage.java

Context augmentation for architecture

The MCP Tools for architecture give the LLM structural understanding of the codebase, powered by semantic data from SonarQube Cloud's Architecture feature. These tools empower the LLM to:

• Build "the right thing", better aligning with user goals, avoiding mistakes and rework.

• Build "the thing right", provide an output that is inline with architecture expectations.

---

SonarQube MCP Server Integration

Prerequisites

Your project must be:

• Connected to SonarQube Cloud.

• Analyzed in your CI pipeline on a long-lived branch.

• Have SonarQube Cloud's Architecture feature enabled (for architectural features).

Context Augmentation is compatible with Claude Code, Cursor, Codex, Gemini CLI, and VS Code with Copilot.

Integration steps

Step 1: Install the SonarQube MCP Server

First, install the SonarQube MCP Server in your MCP client using the SonarQube Cloud setup. Detailed setup instructions are available for the most popular MCP clients; find yours in the IDE setup article.

Step 2: Export the SonarQube Token environment variable

Export the SONARQUBE_TOKEN environment variable with a valid Personal Access Token (PAT) for your project.

# macOS/Linux (Bash/Zsh)
export SONARQUBE_TOKEN="{<YourUserToken>}"

Step 3: Set the Agentic Analysis environment variable

Set your SONARQUBE_ADVANCED_ANALYSIS_ENABLED environment variable to true (default is false). This enables the run_advanced_code_analysis tool in the SonarQube MCP Server, which pairs with Context Augmentation to form the full Guide-and-Verify loop.

For more information on the tool, see the SonarQube MCP Tools section.

Step 4: Add or edit your project-specific MCP configuration file

Context Augmentation requires a project-specific configuration. Do not use your global MCP configuration.

Project-specific MCP settings files are located in the following files (relative to project root):

• .cursor/mcp.json for Cursor IDE

• .mcp.json for Claude Code

• .gemini/settings.json for Gemini CLI

• .codex/config.toml for Codex

  • use a TOML config instead of JSON

• .vscode/mcp.json for Copilot in Visual Studio Code

Replace the placeholders above with appropriate values:

• Paths must be absolute: Relative paths like ./ or ../ are not accepted.

  • ⚠️ The path format is critical.

• Windows users:

  • Use forward slashes. Example: C:/Users/john/projects/myapp

  • Do not use back slashes. Example: C:\Users\john\projects\myapp

{
  "mcpServers": {
    "sonarqube-context-augmentation": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=always",
        "-e", "SONARQUBE_URL",
        "-e", "SONARQUBE_TOKEN",
        "-e", "SONARQUBE_ORG",
        "-e", "SONARQUBE_PROJECT_KEY",
        "-e", "SONARQUBE_TOOLSETS",
        "-e", "SONARQUBE_ADVANCED_ANALYSIS_ENABLED",
        "-v", "/ABSOLUTE/PATH/TO/YOUR/PROJECT:/app/mcp-workspace:rw",
        "mcp/sonarqube"
      ],
      "env": {
        "SONARQUBE_URL": "https://sonarcloud.io",
        "SONARQUBE_ORG": "<YourOrganizationKey>",
        "SONARQUBE_PROJECT_KEY": "<YourProjectKey>",
        "SONARQUBE_TOOLSETS": "cag,projects,analysis",
        "SONARQUBE_ADVANCED_ANALYSIS_ENABLED": "true"
      }
    }
  }
}

Optional configurations:

• SONAR_SQ_BRANCH: Provide it when not using git, or when your git branch name doesn't match the branch name in SonarQube. Add "-e", "SONAR_SQ_BRANCH", to the args array and "SONAR_SQ_BRANCH": "<YourBranchName>" to the env object.

• Context Augmentation tools only: By default, SONARQUBE_TOOLSETS enables both Context Augmentation and Agentic Analysis tools (cag,projects,analysis). If you want to use Context Augmentation without Agentic Analysis, change the value to "cag,projects".

• Include default SonarQube MCP tools: To include the default SonarQube MCP tools in addition to the Agentic Workflow tools, change the SONARQUBE_TOOLSETS value to: "analysis,issues,projects,quality-gates,rules,duplications,measures,security-hotspots,dependency-risks,coverage,cag"

Step 5: Configure agent operational constraints (Recommended)

Tool usage can be inconsistent depending on available tools, context, and agent behavior. To ensure the agent follows the Guide-and-Verify workflow consistently, explicitly guide your AI agent to use the Context Augmentation tools appropriately.

How to configure:

• Cursor: Create a .cursor/rules/sonar-context-augmentation.md Cursor rule file

• Claude Code: Add the directive to your CLAUDE.md in the project root, or use Claude Skills

• Codex: Add the directive to your AGENTS.md file in the project root

• Gemini CLI: Add the directive to your GEMINI.md file in the project root

• Copilot: Add the directive to your CLAUDE.md in the project root

Example directive:

The example below covers the full Guide-and-Verify workflow. If you are only using Context Augmentation without Agentic Analysis, you can remove the VERIFY Phase section.

# SonarQube Agentic Workflow - Usage Directive (MUST FOLLOW)

**Always use the Guide-and-Verify workflow** for code generation and modification.

## GUIDE Phase - Before Generating Code

**Before generating or editing code** you MUST:
1. Call `get_guidelines` for project context and coding standards
2. Locate existing code with `search_by_signature_patterns` or `search_by_body_patterns`
3. Read implementation with `get_source_code`

**When changing architecture or dependencies** you MUST:
- Check `get_current_architecture` and `get_intended_architecture`
- Analyze impact using:
  - `get_upstream_call_flow` / `get_downstream_call_flow` - trace method calls
  - `get_references` - find all usages
  - `get_classlike_structure_hierarchy` - check inheritance

## VERIFY Phase - After Generating Code

You must strictly follow this Analyze-Then-Commit workflow for every code modification. No code is considered complete until it has passed the following SonarQube validation loop:

1. Read Phase: After any modification or before commit, use the `Read` tool to load the current state of all relevant source files.
2. Analysis Phase: For every new or modified file, you must call `run_advanced_code_analysis` using:
   * `projectKey`: <YourProjectKey>
   * `filePath`: The project-relative path to the file.
   * `fileContent`: The full, updated content of the file.
   * `branchName`: The active development branch.
   * `fileScope`: "MAIN" or "TEST" depending on the code type.
3. Evaluation & Remediation:
   * Rule Lookup: For every issue flagged, call `show_rule` with the specific rule key (e.g., `python:S1192`).
   * Mandatory Fixes: You are prohibited from committing code with **CRITICAL** or **HIGH** issues. You must implement fixes based on the rule's rationale and recommended guidance immediately.
4. Verification: After applying fixes, you must re-run the analysis to ensure the issues are resolved and no regressions were introduced.

Step 6: Restart your agent

Restart your agent and make sure that your MCP configuration is taken into account and applied correctly.

---

Related pages

• Agentic Analysis

• SonarQube MCP Server

• SonarQube MCP Server Tools

• Architecture