MCP-176 Provide structured content for tool's results (#127)

Author: nquinquenel

build.gradle.kts

@@ -86,6 +86,8 @@ dependencies {
 	implementation(libs.ayza)
 	implementation(libs.jetty.server)
 	implementation(libs.jetty.ee10.servlet)
+	implementation(libs.jsonschema.generator)
+	implementation(libs.jsonschema.module.jackson)
 	runtimeOnly(libs.logback.classic)
 	testImplementation(platform(libs.junit.bom))
 	testImplementation(libs.junit.jupiter)

gradle/libs.versions.toml

@@ -15,6 +15,7 @@ commons-text = "1.14.0"
 ayza = "10.0.0"
 logback = "1.5.20"
 jetty = "12.1.3"
+jsonschema-generator = "4.38.0"
 
 junit = "5.14.0"
 junit-launcher = "1.14.0"
@@ -35,6 +36,8 @@ commons-langs3 = { module = "org.apache.commons:commons-lang3", version.ref = "c
 commons-text = { module = "org.apache.commons:commons-text", version.ref = "commons-text" }
 ayza = { module = "io.github.hakky54:ayza", version.ref = "ayza" }
 logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
+jsonschema-generator = { module = "com.github.victools:jsonschema-generator", version.ref = "jsonschema-generator" }
+jsonschema-module-jackson = { module = "com.github.victools:jsonschema-module-jackson", version.ref = "jsonschema-generator" }
 
 jetty-server = { module = "org.eclipse.jetty:jetty-server", version.ref = "jetty" }
 jetty-ee10-servlet = { module = "org.eclipse.jetty.ee10:jetty-ee10-servlet", version.ref = "jetty" }

src/main/java/org/sonarsource/sonarqube/mcp/tools/SchemaToolBuilder.java

@@ -18,6 +18,7 @@
 
 import io.modelcontextprotocol.spec.McpSchema;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -29,18 +30,23 @@ public class SchemaToolBuilder {
   private static final String ITEMS_PROPERTY_NAME = "items";
   private final Map<String, Object> properties;
   private final List<String> requiredProperties;
-  private final Map<String, Object> def;
-  private final Map<String, Object> definitions;
+  private final Map<String, Object> outputSchemaFromClass;
   private String name;
   private String title;
   private String description;
-  private boolean additionalProperties;
 
-  public SchemaToolBuilder() {
+  public SchemaToolBuilder(Map<String, Object> outputSchemaFromClass) {
     this.properties = new HashMap<>();
     this.requiredProperties = new ArrayList<>();
-    this.def = new HashMap<>();
-    this.definitions = new HashMap<>();
+    this.outputSchemaFromClass = outputSchemaFromClass;
+  }
+
+  /**
+   * Factory method to create a SchemaToolBuilder with automatic output schema generation from a class.
+   * This is the recommended approach for defining structured output.
+   */
+  public static SchemaToolBuilder forOutput(Class<? extends Record> outputClass) {
+    return new SchemaToolBuilder(SchemaUtils.generateOutputSchema(outputClass));
   }
 
   public SchemaToolBuilder setName(String name) {
@@ -109,8 +115,8 @@ public McpSchema.Tool build() {
       throw new IllegalStateException("Cannot set a required property that does not exist.");
     }
 
-    var jsonSchema = new McpSchema.JsonSchema("object", properties, requiredProperties, additionalProperties, def, definitions);
+    var jsonSchema = new McpSchema.JsonSchema("object", properties, requiredProperties, false, Collections.emptyMap(), Collections.emptyMap());
 
-    return new McpSchema.Tool(name, title, description, jsonSchema, null, null, Map.of());
+    return new McpSchema.Tool(name, title, description, jsonSchema, outputSchemaFromClass, null, Map.of());
   }
 }

src/main/java/org/sonarsource/sonarqube/mcp/tools/SchemaUtils.java

@@ -0,0 +1,77 @@
+/*
+ * SonarQube MCP Server
+ * Copyright (C) 2025 SonarSource
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonarsource.sonarqube.mcp.tools;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.github.victools.jsonschema.generator.OptionPreset;
+import com.github.victools.jsonschema.generator.SchemaGenerator;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
+import com.github.victools.jsonschema.generator.SchemaVersion;
+import com.github.victools.jsonschema.module.jackson.JacksonModule;
+import com.github.victools.jsonschema.module.jackson.JacksonOption;
+import jakarta.annotation.Nullable;
+import java.util.Map;
+
+/**
+ * Utility class for generating JSON schemas from Java classes and serializing objects.
+ * Uses jsonschema-generator library for schema generation.
+ */
+public class SchemaUtils {
+
+  private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper()
+    .setSerializationInclusion(JsonInclude.Include.NON_NULL);
+  
+  private static final SchemaGenerator SCHEMA_GENERATOR;
+
+  static {
+    var configBuilder = new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON)
+      .with(new JacksonModule(JacksonOption.RESPECT_JSONPROPERTY_REQUIRED));
+    configBuilder.forFields()
+      .withRequiredCheck(field -> field.getAnnotationConsideringFieldAndGetter(Nullable.class) == null);
+    configBuilder.forMethods()
+      .withRequiredCheck(method -> method.getAnnotationConsideringFieldAndGetter(Nullable.class) == null);
+    SCHEMA_GENERATOR = new SchemaGenerator(configBuilder.build());
+  }
+
+  private SchemaUtils() {
+    // Static class
+  }
+
+  @SuppressWarnings("unchecked")
+  public static Map<String, Object> generateOutputSchema(Class<? extends Record> clazz) {
+    var schemaNode = SCHEMA_GENERATOR.generateSchema(clazz);
+    var schema = OBJECT_MAPPER.convertValue(schemaNode, Map.class);
+    schema.remove("$schema");
+    return schema;
+  }
+
+  @SuppressWarnings("unchecked")
+  public static Map<String, Object> toStructuredContent(Record obj) {
+    return OBJECT_MAPPER.convertValue(obj, Map.class);
+  }
+
+  public static String toJsonString(Record response) {
+    try {
+      return OBJECT_MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(response);
+    } catch (Exception e) {
+      throw new IllegalStateException("Failed to convert response to JSON string", e);
+    }
+  }
+
+}
+

src/main/java/org/sonarsource/sonarqube/mcp/tools/Tool.java

@@ -120,8 +120,17 @@ public List<String> getOptionalStringList(String argumentName) {
   }
 
   public static class Result {
-    public static Result success(String content) {
-      return new Result(McpSchema.CallToolResult.builder().isError(false).addTextContent(content).build());
+    /**
+     * Create a successful result from a response object.
+     * The response object will be serialized to both JSON text content and structured content.
+     * This follows the MCP spec recommendation that structured content should also be available as text.
+     */
+    public static Result success(Record responseObject) {
+      return new Result(McpSchema.CallToolResult.builder()
+        .isError(false)
+        .addTextContent(SchemaUtils.toJsonString(responseObject))
+        .structuredContent(SchemaUtils.toStructuredContent(responseObject))
+        .build());
     }
 
     public static Result failure(String errorMessage) {

src/main/java/org/sonarsource/sonarqube/mcp/tools/analysis/AnalysisTool.java

@@ -50,7 +50,7 @@ public class AnalysisTool extends Tool {
   private final ServerApiProvider serverApiProvider;
 
   public AnalysisTool(BackendService backendService, ServerApiProvider serverApiProvider) {
-    super(new SchemaToolBuilder()
+    super(SchemaToolBuilder.forOutput(AnalysisToolResponse.class)
       .setName(TOOL_NAME)
       .setTitle("Code File Analysis")
       .setDescription("Analyze a file or code snippet with SonarQube analyzers to identify code quality and security issues. " +
@@ -86,7 +86,8 @@ public Result execute(Arguments arguments) {
       var startTime = System.currentTimeMillis();
       var response = backendService.analyzeFilesAndTrack(analysisId, List.of(tmpFile.toUri()), startTime).get(30,
         TimeUnit.SECONDS);
-      return Tool.Result.success(buildResponseFromAnalysisResults(response));
+      var toolResponse = buildStructuredContent(response);
+      return Tool.Result.success(toolResponse);
     } catch (IOException | ExecutionException | TimeoutException e) {
       return Tool.Result.failure("Error while analyzing the code snippet: " + e.getMessage());
     } catch (InterruptedException e) {
@@ -122,49 +123,6 @@ private void applyRulesFromProject(@Nullable String projectKey) {
     backendService.updateRulesConfiguration(activeRules);
   }
 
-  private static String buildResponseFromAnalysisResults(AnalyzeFilesResponse response) {
-    var stringBuilder = new StringBuilder();
-
-    if (!response.getFailedAnalysisFiles().isEmpty()) {
-      stringBuilder.append("Failed to analyze the code snippet.");
-      return stringBuilder.toString();
-    }
-
-    if (response.getRawIssues().isEmpty()) {
-      stringBuilder.append("No Sonar issues found in the code snippet.");
-    } else {
-      stringBuilder.append("Found ").append(response.getRawIssues().size()).append(" Sonar issues in the code snippet");
-
-      for (var issue : response.getRawIssues()) {
-        stringBuilder.append("\n");
-        stringBuilder.append(issue.getPrimaryMessage());
-        stringBuilder.append("\n");
-        stringBuilder.append("Rule key: ").append(issue.getRuleKey());
-        stringBuilder.append("\n");
-        stringBuilder.append("Severity: ").append(issue.getSeverity());
-        stringBuilder.append("\n");
-        stringBuilder.append("Clean Code attribute: ").append(issue.getCleanCodeAttribute().name());
-        stringBuilder.append("\n");
-        stringBuilder.append("Impacts: ").append(issue.getImpacts().toString());
-        stringBuilder.append("\n");
-        stringBuilder.append("Description: ").append(issue.getPrimaryMessage());
-        stringBuilder.append("\n");
-        stringBuilder.append("Quick fixes available: ").append(issue.getQuickFixes().isEmpty() ? "No" : "Yes");
-
-        var textRange = issue.getTextRange();
-        if (textRange != null) {
-          stringBuilder.append("\n");
-          stringBuilder.append("Starting on line: ").append(textRange.getStartLine());
-        }
-      }
-    }
-
-    stringBuilder.append("\nDisclaimer: Analysis results might not be fully accurate as the code snippet is not part of a complete project context." +
-      " Use SonarQube for IDE for better results, or setup a full project analysis in SonarQube Server or Cloud.");
-
-    return stringBuilder.toString().trim();
-  }
-
   private static Path createTemporaryFileForLanguage(String analysisId, Path workDir, String fileContent, SonarLanguage language) throws IOException {
     var defaultFileSuffixes = language.getDefaultFileSuffixes();
     var extension = defaultFileSuffixes.length > 0 ? defaultFileSuffixes[0] : "";
@@ -180,4 +138,30 @@ private static void removeTmpFileForAnalysis(Path tempFile) throws IOException {
     Files.deleteIfExists(tempFile);
   }
 
+  public AnalysisToolResponse buildStructuredContent(AnalyzeFilesResponse response) {
+    var issues = response.getRawIssues().stream()
+      .map(issue -> {
+        AnalysisToolResponse.TextRange textRange = null;
+        if (issue.getTextRange() != null) {
+          textRange = new AnalysisToolResponse.TextRange(
+            issue.getTextRange().getStartLine(),
+            issue.getTextRange().getEndLine()
+          );
+        }
+        
+        return new AnalysisToolResponse.Issue(
+          issue.getRuleKey(),
+          issue.getPrimaryMessage(),
+          issue.getSeverity().toString(),
+          issue.getCleanCodeAttribute().name(),
+          issue.getImpacts().toString(),
+          !issue.getQuickFixes().isEmpty(),
+          textRange
+        );
+      })
+      .toList();
+
+    return new AnalysisToolResponse(issues, response.getRawIssues().size());
+  }
+
 }

src/main/java/org/sonarsource/sonarqube/mcp/tools/analysis/AnalysisToolResponse.java

@@ -0,0 +1,45 @@
+/*
+ * SonarQube MCP Server
+ * Copyright (C) 2025 SonarSource
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonarsource.sonarqube.mcp.tools.analysis;
+import jakarta.annotation.Nullable;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.util.List;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
+
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record AnalysisToolResponse(
+  @JsonPropertyDescription("List of issues found in the code snippet") List<Issue> issues,
+  @JsonPropertyDescription("Total number of issues") int issueCount
+) {
+  
+  public record Issue(
+    @JsonPropertyDescription("Rule key that triggered the issue") String ruleKey,
+    @JsonPropertyDescription("Primary issue message") String primaryMessage,
+    @JsonPropertyDescription("Issue severity level") String severity,
+    @JsonPropertyDescription("Clean code attribute") String cleanCodeAttribute,
+    @JsonPropertyDescription("Software quality impacts") String impacts,
+    @JsonPropertyDescription("Whether quick fixes are available") boolean hasQuickFixes,
+    @JsonPropertyDescription("Location in the code") @Nullable TextRange textRange
+  ) {}
+  
+  public record TextRange(
+    @JsonPropertyDescription("Starting line number") int startLine,
+    @JsonPropertyDescription("Ending line number") int endLine
+  ) {}
+}
+

src/main/java/org/sonarsource/sonarqube/mcp/tools/analysis/AnalyzeFileListTool.java

@@ -30,7 +30,7 @@ public class AnalyzeFileListTool extends Tool {
   private final SonarQubeIdeBridgeClient bridgeClient;
 
   public AnalyzeFileListTool(SonarQubeIdeBridgeClient bridgeClient) {
-    super(new SchemaToolBuilder()
+    super(SchemaToolBuilder.forOutput(AnalyzeFileListToolResponse.class)
       .setName(TOOL_NAME)
       .setTitle("Multiple File Analysis")
       .setDescription("Analyze files in the current working directory using SonarQube for IDE. " +
@@ -59,50 +59,27 @@ public Result execute(Arguments arguments) {
     }
 
     var results = analysisResult.get();
-    var issuesSummary = formatAnalysisResults(results);
+    var toolResponse = buildStructuredContent(results);
 
     LOG.info("Returning success result to MCP client");
-    return Result.success(issuesSummary);
+    return Result.success(toolResponse);
   }
 
-  private static String formatAnalysisResults(SonarQubeIdeBridgeClient.AnalyzeFileListResponse results) {
-    var sb = new StringBuilder();
-
-    sb.append("SonarQube for IDE Analysis Completed!\n\n");
-    sb.append("Analysis Summary:\n");
-
-    if (results.findings().isEmpty()) {
-      sb.append("No findings found! Your code looks good.\n\n");
-    } else {
-      var findings = results.findings();
-      sb.append("Issues Found (").append(findings.size()).append("):\n");
-      // Show max 100 issues
-      for (int i = 0; i < Math.min(100, findings.size()); i++) {
-        var issue = findings.get(i);
-        sb.append("  ").append(i + 1).append(". ").append(formatFinding(issue)).append("\n");
-      }
-      if (findings.size() > 100) {
-        sb.append("  ... and ").append(findings.size() - 100).append(" more issues\n");
-      }
-    }
-
-    sb.append("Next Steps:\n");
-    sb.append("Check SonarQube for IDE - issues are now displayed in your extension\n");
-    sb.append("Ask the agent to fix the issues.");
-
-    return sb.toString();
-  }
-
-  private static String formatFinding(SonarQubeIdeBridgeClient.AnalyzeFileListIssueResponse issue) {
-    var textRange = issue.textRange();
-    if (textRange == null) {
-      return String.format("[%s] %s (file: %s)",
-        issue.severity(), issue.message(), issue.filePath());
-    } else {
-      return String.format("[%s] %s (file: %s [Lines: %d to %d])",
-        issue.severity(), issue.message(), issue.filePath(),
-        issue.textRange().getStartLine(), issue.textRange().getEndLine());
-    }
+  private static AnalyzeFileListToolResponse buildStructuredContent(SonarQubeIdeBridgeClient.AnalyzeFileListResponse results) {
+    var findings = results.findings().stream()
+      .map(f -> {
+        AnalyzeFileListToolResponse.TextRange textRange = null;
+        if (f.textRange() != null) {
+          textRange = new AnalyzeFileListToolResponse.TextRange(
+            f.textRange().getStartLine(),
+            f.textRange().getEndLine()
+          );
+        }
+        return new AnalyzeFileListToolResponse.Finding(f.severity(), f.message(), f.filePath(), textRange);
+      })
+      .toList();
+
+    return new AnalyzeFileListToolResponse(findings, results.findings().size());
   }
 
 }