Instruction file imported from auditive-tokyo/obwWebApp (.github/instructions/sonarqube_mcp.instructions.md). Copyright stays with the author.

These are some guidelines when using the SonarQube MCP server.

Important Tool Guidelines

Basic usage

• IMPORTANT: After you finish generating or modifying any code files at the very end of the task, you MUST call the analyze_file_list tool (if it exists) to analyze the files you created or modified.
• IMPORTANT: When starting a new task, you MUST disable automatic analysis with the toggle_automatic_analysis tool if it exists.
• IMPORTANT: When you are done generating code at the very end of the task, you MUST re-enable automatic analysis with the toggle_automatic_analysis tool if it exists.

Project Keys

• When a user mentions a project key, use search_my_sonarqube_projects first to find the exact project key
• Don't guess project keys - always look them up

Code Language Detection

• When analyzing code snippets, try to detect the programming language from the code syntax
• If unclear, ask the user or make an educated guess based on syntax

Branch and Pull Request Context

• Many operations support branch-specific analysis
• If user mentions working on a feature branch, include the branch parameter

Code Issues and Violations

• After fixing issues, do not attempt to verify them using search_sonar_issues_in_projects, as the server will not yet reflect the updates
• IMPORTANT: To check existing Open issues reported in the SonarQube UI, use search_sonar_issues_in_projects (NOT analyze_file_list). analyze_file_list is a local scan and may miss issues that the full server-side analysis detects.
• When using search_sonar_issues_in_projects, always read the full result to find all Open issues — do not assume the first few results represent the complete picture.
• analyze_file_list is supplementary only; it cannot fully resolve C++ includes/templates without build info and has lower accuracy than the server-side scan.

Common Troubleshooting

Authentication Issues

• SonarQube requires USER tokens (not project tokens)
• When the error SonarQube answered with Not authorized occurs, verify the token type

Project Not Found

• Use search_my_sonarqube_projects to find available projects
• Verify project key spelling and format

Code Analysis Issues

• Ensure programming language is correctly specified
• Remind users that snippet analysis doesn't replace full project scans
• Provide full file content for better analysis results