SC-50740 Implement agentic-readiness tools

[stanislavhh]

This PR introduces tools for agentic-readiness private beta feature under the flag.

Tool	Description
start_agentic_readiness_assessment	Trigger a new SARA assessment for a project (optionally on a branch)
get_agentic_readiness_assessment	Poll an assessment by ID until it completes
list_agentic_readiness_assessments	List past assessments for a project

Validated on dev12 environment:

"was-mcp-server": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/Users/{me}/projects/sonarqube-mcp-server/build/libs/sonarqube-mcp-server-1.20-SNAPSHOT.jar"],
      "env": {
        "SONARQUBE_URL": "https://dev12.sc-dev12.io",
        "SONARQUBE_TOKEN": "**",
        "SONARQUBE_ORG": "**",
        "SONARQUBE_CLOUD_API_URL": "https://api.sc-dev12.io",
        "STORAGE_PATH": "/tmp/sonarqube-mcp-storage"
      }

Flag on:

Flag off:

Tools in CLI:

Example of execution with simple prompt:

---

Summary by Gitar

• New Agentic Readiness API:
  • Introduced AgenticReadinessApi to interact with WaS experiment endpoints.
  • Added WasFeatureFlagsApi to verify SARA feature flag status for organizations.
• New MCP Tools:
  • Registered StartAgenticReadinessAssessmentTool, GetAgenticReadinessAssessmentTool, and ListAgenticReadinessAssessmentsTool.
  • Added AGENTIC_READINESS to ToolCategory and implemented tool registration logic gated by feature flags.
• Infrastructure Improvements:
  • Updated ProjectBranchesApi with getProjectUuid to support assessment operations.
  • Enhanced MockWebServer stubbing capabilities to properly resolve URL paths for testing.
  • Added unit tests for new agentic readiness tools in GetAgenticReadinessAssessmentToolTests and related test suites.

_{This will update automatically on new commits.}

[hashicorp-vault-sonar-prod]

SC-50740

[nquinquenel]

Overall it's looking good, some comments though.

[nquinquenel]

Looks good, just some comments about consistency with the codebase and how we do things. Please use a xxToolResponse object per tool, with concise description of each field (it's per the MCP recommendations).

We have a test tool_names_should_be_descriptive that verifies tool naming. It's not effective in your case because the tools are not in the test path. However it'd be great to add start as part of the allowed keywords, matching your tool

[nquinquenel]

LGTM! 2 small comments

Thanks for contributing to the MCP :)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
1 Accepted issue
0 New dependency risks

Measures
0 Security Hotspots
90.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[gitar-bot]

Code Review ✅ Approved 6 resolved / 6 findings

Implements agentic-readiness MCP tools gated by feature flags, including assessment lifecycle management and API integration. Resolved issues regarding inconsistent SARA readiness level scales and potential NullPointerExceptions in assessment signals.

✅ 6 resolved

✅ Quality: SARA readiness level scale is inconsistent and has duplicate text

📄 src/main/java/org/sonarsource/sonarqube/mcp/SonarQubeMcpServer.java:134-139 📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/StartAgenticReadinessAssessmentTool.java:37 📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/GetAgenticReadinessAssessmentTool.java:39
The readiness-level scale described to the LLM is internally contradictory, which can cause the agent to mis-explain assessment results to users.

1. In AGENTIC_READINESS_INSTRUCTIONS the intro says scores range "from L0 to L3" but the bullet list immediately enumerates five levels L1–L5 (SonarQubeMcpServer.java:134-139).
2. The tool descriptions state a different scale again: StartAgenticReadinessAssessmentTool says "L0 (unfit) to L3 (agent-native)" and GetAgenticReadinessAssessmentTool says "overallLevel (L0-L3)", neither of which matches the L1–L5 list.
3. The L4 and L5 entries have identical descriptions ("Built for machine actors. The environment is self-describing and self-correcting."), which looks like a copy/paste error.

Pick a single authoritative scale (label range and per-level meaning) and make the instructions block and both tool descriptions agree, and give L4 and L5 distinct text.

✅ Edge Case: Removed null guard on SubSignal.evidence() risks NPE

📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/GetAgenticReadinessAssessmentTool.java:103-105 📄 src/main/java/org/sonarsource/sonarqube/mcp/serverapi/agenticreadiness/AgenticReadinessApi.java:107-110
This commit removed the previous defensive signal.evidence() == null ? null : ... guard and now calls signal.evidence().stream() directly. The evidence field of AgenticReadinessApi.AssessmentResponse.SubSignal is deserialized by Gson, which leaves a field as null when it is absent (or explicitly null) in the JSON payload, regardless of the lack of a @Nullable annotation. If the SARA API ever returns a sub-signal without an evidence array, mapSubSignals will throw a NullPointerException and fail the whole get_agentic_readiness_assessment call. Since assessments are polled while still in progress, partially-populated sub-signals are plausible. Consider restoring a null-safe path (e.g. using Optional.ofNullable(signal.evidence()).orElseGet(List::of)), or guarantee the field is always present.

✅ Quality: Start assessment tool marked read-only but creates a resource

📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/StartAgenticReadinessAssessmentTool.java:43 📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/StartAgenticReadinessAssessmentTool.java:50-57 📄 src/main/java/org/sonarsource/sonarqube/mcp/serverapi/agenticreadiness/AgenticReadinessApi.java:41-50 📄 src/test/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/StartAgenticReadinessAssessmentToolTests.java:89-93
StartAgenticReadinessAssessmentTool calls setReadOnlyHint(), and it_should_validate_annotations asserts readOnlyHint() is true. However its execute() performs api.agenticReadinessApi().createAssessment(...), which issues a POST (helper.postApiSubdomain) that creates a new assessment resource on the server. The MCP readOnlyHint is documented (SchemaToolBuilder.setReadOnlyHint: "it only reads data and doesn't modify any state") to mean the tool does not modify its environment. Marking a state-changing operation as read-only is misleading and can cause MCP clients to auto-approve/execute the tool without user confirmation. The existing convention in this repo confirms this: CreateWebhookTool (also a write/POST) does NOT set setReadOnlyHint(), while read-only tools like ListWebhooksTool do. Recommend removing setReadOnlyHint() from StartAgenticReadinessAssessmentTool (keeping it on the Get/List tools, which are genuinely read-only) and updating the annotation test accordingly.

✅ Quality: Inconsistent & duplicated SARA readiness level scale

📄 src/main/java/org/sonarsource/sonarqube/mcp/SonarQubeMcpServer.java:134-139 📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/StartAgenticReadinessAssessmentTool.java:37 📄 src/main/java/org/sonarsource/sonarqube/mcp/tools/agenticreadiness/GetAgenticReadinessAssessmentTool.java:39
The readiness level scale presented to the model is inconsistent across the three places it is documented, which will confuse an LLM consuming these tools:

• AGENTIC_READINESS_INSTRUCTIONS describes levels L1–L5 (5 levels).
• StartAgenticReadinessAssessmentTool description says levels go from L0 (unfit) to L3 (agent-native).
• GetAgenticReadinessAssessmentTool description says overallLevel (L0-L3).

In addition, in the instructions block the L4 and L5 descriptions are identical copy-paste text ("Built for machine actors. The environment is self-describing and self-correcting."), so even within a single source the scale is malformed.

Pick a single authoritative scale (range and per-level meaning) and use it consistently in all three descriptions, and give L5 its own distinct text.

✅ Quality: Duplicate L4/L5 readiness-level descriptions in SARA instructions

📄 src/main/java/org/sonarsource/sonarqube/mcp/SonarQubeMcpServer.java:134-139
In AGENTIC_READINESS_INSTRUCTIONS the L4 and L5 entries carry the same description text: "Built for machine actors. The environment is self-describing and self-correcting." L4 is labelled "Agent-optimized" and L5 "Agent-native", but the explanatory sentence is identical, so an agent reading these instructions cannot distinguish the two top levels. This also conflicts with the tool descriptions which describe the scale as "L1 (pre-agentic) to L5 (agent-native)". Give L4 and L5 distinct, accurate descriptions so the readiness scale is unambiguous.

...and 1 more resolved from earlier reviews

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}