feat(#9): Support MCP tool outputSchema and structuredContent

Author: codeboyzhou

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaDefinition.java

@@ -13,7 +13,7 @@
  * supported by the MCP protocol. This allows you to use more complex data models in your MCP
  * server.
  *
- * @see McpJsonSchemaDefinitionProperty
+ * @see McpJsonSchemaProperty
  * @author codeboyzhou
  */
 @Target(ElementType.TYPE)

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaDefinitionProperty.java renamed to src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaProperty.java

@@ -19,7 +19,7 @@
  */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
-public @interface McpJsonSchemaDefinitionProperty {
+public @interface McpJsonSchemaProperty {
   /**
    * The name of the JSON schema property. If not specified, the field name will be used.
    *

src/main/java/com/github/codeboyzhou/mcp/declarative/reflect/MethodCache.java

@@ -28,6 +28,9 @@ public final class MethodCache {
   /** The parameters of the cached method. */
   private final Parameter[] parameters;
 
+  /** The return type of the cached method. */
+  private final Class<?> returnType;
+
   /** The signature of the cached method. */
   private final String methodSignature;
 
@@ -50,6 +53,7 @@ public MethodCache(Method method) {
     this.methodName = method.getName();
     this.declaringClass = method.getDeclaringClass();
     this.parameters = method.getParameters();
+    this.returnType = method.getReturnType();
     this.methodSignature = method.toGenericString();
     this.mcpResourceAnnotation = method.getAnnotation(McpResource.class);
     this.mcpPromptAnnotation = method.getAnnotation(McpPrompt.class);
@@ -102,6 +106,15 @@ public Parameter[] getParameters() {
     return parameters.clone();
   }
 
+  /**
+   * Returns the return type of the cached method.
+   *
+   * @return the return type of the cached method
+   */
+  public Class<?> getReturnType() {
+    return returnType;
+  }
+
   /**
    * Returns the signature of the cached method.
    *

src/main/java/com/github/codeboyzhou/mcp/declarative/server/McpStructuredContent.java

@@ -0,0 +1,123 @@
+package com.github.codeboyzhou.mcp.declarative.server;
+
+import com.github.codeboyzhou.mcp.declarative.server.component.McpServerTool;
+import io.modelcontextprotocol.spec.McpSchema;
+
+/**
+ * Marker interface for MCP tool method results that return structured content.
+ *
+ * <p>This interface is used to distinguish between simple text results and complex results
+ * containing structured data. When an MCP tool method returns an object implementing this
+ * interface, the MCP server will provide both text representation and structured data
+ * representation.
+ *
+ * <h2>Usage Scenarios</h2>
+ *
+ * <ul>
+ *   <li><strong>Simple Text Results</strong>: When tool methods return String or other primitive
+ *       types, only text content is provided
+ *   <li><strong>Structured Results</strong>: When tool methods return objects implementing this
+ *       interface, both text and structured data are provided
+ * </ul>
+ *
+ * <h2>Example Usage</h2>
+ *
+ * <pre>{@code
+ * public class WeatherTool {
+ *
+ *   @McpTool(description = "Get weather information")
+ *   public WeatherData getWeather(@McpToolParam(name = "city") String city) {
+ *     final int temperature = 25;
+ *     final String condition = "Sunny";
+ *     return new WeatherData(city, temperature, condition);
+ *   }
+ *
+ *   // Structured result class implementing McpStructuredContent
+ *   public record WeatherData(
+ *       @McpJsonSchemaProperty(description = "City name") String city,
+ *       @McpJsonSchemaProperty(description = "Temperature") int temperature,
+ *       @McpJsonSchemaProperty(description = "Condition") String condition)
+ *       implements McpStructuredContent {
+ *
+ *     @Override
+ *     public String asTextContent() {
+ *       return String.format("City: %s, Temperature: %d°C, Condition: %s",
+ *           city, temperature, condition);
+ *     }
+ *   }
+ * }
+ * }</pre>
+ *
+ * <h2>MCP Response Format</h2>
+ *
+ * When a tool returns an object implementing this interface, the MCP response will contain:
+ *
+ * <pre>{@code
+ * {
+ *   "content": [
+ *     {
+ *       "type": "text",
+ *       "text": "City: New York, Temperature: 25°C, Condition: Sunny"
+ *     }
+ *   ],
+ *   "structuredContent": {
+ *     "city": "New York",
+ *     "temperature": 25,
+ *     "condition": "Sunny"
+ *   }
+ * }
+ * }</pre>
+ *
+ * <h2>Implementation Requirements</h2>
+ *
+ * <ul>
+ *   <li>Implementing classes must provide meaningful text representation for direct AI model
+ *       consumption
+ *   <li>Fields of implementing classes will be automatically serialized as structured content
+ *   <li>Text content should be concise and clear for AI understanding
+ *   <li>Structured content should contain complete detailed information
+ * </ul>
+ *
+ * <h2>Default Implementation</h2>
+ *
+ * The interface provides a default implementation of {@link #asTextContent()} that returns the
+ * result of {@link Object#toString()}. If the default implementation doesn't meet requirements,
+ * implementing classes should override this method.
+ *
+ * @see McpServerTool MCP tool component that uses this interface
+ * @see McpSchema.CallToolResult MCP tool call result specification
+ * @author codeboyzhou
+ */
+public interface McpStructuredContent {
+  /**
+   * Returns the text representation of this structured content.
+   *
+   * <p>The text representation should provide a concise summary of the content, suitable for direct
+   * consumption by AI models. The result of this method will be used as the text content in the MCP
+   * response's {@code content} field.
+   *
+   * <p>Implementation Guidelines
+   *
+   * <ul>
+   *   <li><strong>Conciseness</strong>: Text should be brief, avoiding excessive details
+   *   <li><strong>Readability</strong>: Use natural language that's easy for AI to understand
+   *   <li><strong>Completeness</strong>: Include key information, but not necessarily all details
+   *   <li><strong>Consistency</strong>: Text content should be consistent with structured data
+   * </ul>
+   *
+   * <p>Examples For weather query results:
+   *
+   * <ul>
+   *   <li><strong>Good implementation</strong>: "City: New York, Temperature: 25°C, Condition:
+   *       Sunny"
+   *   <li><strong>Poor implementation</strong>: Returning full JSON strings or overly simplified
+   *       information
+   * </ul>
+   *
+   * @return the text representation of the structured content, should not return {@code null}
+   * @see Object#toString() default implementation uses this method
+   */
+  default String asTextContent() {
+    return toString();
+  }
+}

src/main/java/com/github/codeboyzhou/mcp/declarative/server/component/McpServerTool.java

@@ -1,12 +1,13 @@
 package com.github.codeboyzhou.mcp.declarative.server.component;
 
 import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaDefinition;
-import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaDefinitionProperty;
+import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaProperty;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpTool;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpToolParam;
 import com.github.codeboyzhou.mcp.declarative.enums.JavaTypeToJsonSchemaMapper;
 import com.github.codeboyzhou.mcp.declarative.reflect.InvocationResult;
 import com.github.codeboyzhou.mcp.declarative.reflect.MethodCache;
+import com.github.codeboyzhou.mcp.declarative.server.McpStructuredContent;
 import com.github.codeboyzhou.mcp.declarative.server.converter.McpToolParameterConverter;
 import com.github.codeboyzhou.mcp.declarative.util.JacksonHelper;
 import com.github.codeboyzhou.mcp.declarative.util.ReflectionHelper;
@@ -55,13 +56,15 @@ public McpServerFeatures.SyncToolSpecification create(Method method) {
     final String title = resolveComponentAttributeValue(toolMethod.title());
     final String description = resolveComponentAttributeValue(toolMethod.description());
 
-    McpSchema.JsonSchema paramSchema = createJsonSchema(methodCache.getParameters());
+    McpSchema.JsonSchema inputSchema = createJsonSchema(methodCache.getParameters());
+    Map<String, Object> outputSchema = createJsonSchemaDefinition(methodCache.getReturnType());
     McpSchema.Tool tool =
         McpSchema.Tool.builder()
             .name(name)
             .title(title)
             .description(description)
-            .inputSchema(paramSchema)
+            .inputSchema(inputSchema)
+            .outputSchema(outputSchema)
             .build();
 
     log.debug("Registering tool: {}", JacksonHelper.toJsonString(tool));
@@ -87,9 +90,20 @@ private McpSchema.CallToolResult invoke(
     List<Object> params = parameterConverter.convertAll(methodCache.getParameters(), arguments);
     InvocationResult invocation = ReflectionHelper.INSTANCE.invoke(instance, methodCache, params);
 
-    final boolean isError = invocation.isError();
-    McpSchema.Content content = new McpSchema.TextContent(invocation.result().toString());
-    return McpSchema.CallToolResult.builder().content(List.of(content)).isError(isError).build();
+    Object result = invocation.result();
+    String textContent = result.toString();
+    Object structuredContent = Map.of();
+
+    if (result instanceof McpStructuredContent mcpStructuredContent) {
+      textContent = mcpStructuredContent.asTextContent();
+      structuredContent = mcpStructuredContent;
+    }
+
+    return McpSchema.CallToolResult.builder()
+        .content(List.of(new McpSchema.TextContent(textContent)))
+        .structuredContent(structuredContent)
+        .isError(invocation.isError())
+        .build();
   }
 
   /**
@@ -151,14 +165,12 @@ private Map<String, Object> createJsonSchemaDefinition(Class<?> definitionClass)
     List<String> required = new ArrayList<>();
 
     Reflections reflections = injector.getInstance(Reflections.class);
-    Set<Field> definitionFields =
-        reflections.getFieldsAnnotatedWith(McpJsonSchemaDefinitionProperty.class);
+    Set<Field> definitionFields = reflections.getFieldsAnnotatedWith(McpJsonSchemaProperty.class);
     List<Field> fields =
         definitionFields.stream().filter(f -> f.getDeclaringClass() == definitionClass).toList();
 
     for (Field field : fields) {
-      McpJsonSchemaDefinitionProperty property =
-          field.getAnnotation(McpJsonSchemaDefinitionProperty.class);
+      McpJsonSchemaProperty property = field.getAnnotation(McpJsonSchemaProperty.class);
       if (property == null) {
         continue;
       }

src/main/java/com/github/codeboyzhou/mcp/declarative/util/ReflectionHelper.java

@@ -56,19 +56,19 @@ public InvocationResult invoke(Object instance, MethodCache methodCache, List<Ob
     InvocationResult.Builder builder = InvocationResult.builder();
     try {
       Object result = method.invoke(instance, params.toArray());
-      if (method.getReturnType() == void.class) {
-        builder.result("The method call succeeded but has a void return type");
-      } else {
-        final String resultIfNull = "The method call succeeded but the return value is null";
-        builder.result(Objects.requireNonNullElse(result, resultIfNull));
+
+      Class<?> returnType = method.getReturnType();
+      if (returnType == void.class || returnType == Void.class) {
+        return builder.result("The method call succeeded but has a void return type").build();
       }
+
+      final String resultIfNull = "The method call succeeded but the return value is null";
+      return builder.result(Objects.requireNonNullElse(result, resultIfNull)).build();
     } catch (Exception e) {
       final String errorMessage = "Error invoking method: " + methodCache.getMethodSignature();
       log.error(errorMessage, e);
-      builder.result(errorMessage);
-      builder.exception(e);
+      return builder.result(errorMessage).exception(e).build();
     }
-    return builder.build();
   }
 
   /**

src/test/java/com/github/codeboyzhou/mcp/declarative/McpServersTest.java

@@ -14,6 +14,8 @@
 import com.github.codeboyzhou.mcp.declarative.exception.McpServerConfigurationException;
 import com.github.codeboyzhou.mcp.declarative.server.McpSseServerInfo;
 import com.github.codeboyzhou.mcp.declarative.server.McpStreamableServerInfo;
+import com.github.codeboyzhou.mcp.declarative.server.McpStructuredContent;
+import com.github.codeboyzhou.mcp.declarative.test.TestMcpToolsStructuredContent;
 import com.github.codeboyzhou.mcp.declarative.test.TestSimpleMcpStdioServer;
 import com.github.codeboyzhou.mcp.declarative.util.StringHelper;
 import io.modelcontextprotocol.client.McpClient;
@@ -309,7 +311,7 @@ private void verifyPromptCalled(
 
   private void verifyToolsRegistered(McpSyncClient client) {
     List<McpSchema.Tool> tools = client.listTools().tools();
-    assertEquals(21, tools.size());
+    assertEquals(22, tools.size());
 
     verifyToolRegistered(tools, "toolWithDefaultName", "title", "description", Map.of());
     verifyToolRegistered(tools, "toolWithDefaultTitle", "Not specified", "description", Map.of());
@@ -399,6 +401,8 @@ private void verifyToolsRegistered(McpSyncClient client) {
         "Not specified",
         "Not specified",
         Map.of("param", Boolean.class));
+    verifyToolRegistered(
+        tools, "toolWithReturnStructuredContent", "Not specified", "Not specified", Map.of());
   }
 
   @SuppressWarnings("unchecked")
@@ -520,6 +524,12 @@ private void verifyToolsCalled(McpSyncClient client) {
         "toolWithBooleanClassParam",
         Map.of("param", true),
         "toolWithBooleanClassParam is called with param: true");
+    verifyToolCalled(
+        client,
+        "toolWithReturnStructuredContent",
+        Map.of(),
+        new TestMcpToolsStructuredContent.TestStructuredContent(1, 2, 3L, 4L, 5.0F, 6.0F, 7.0, 8.0)
+            .asTextContent());
   }
 
   private void verifyToolCalled(
@@ -530,5 +540,9 @@ private void verifyToolCalled(
     McpSchema.TextContent content = (McpSchema.TextContent) result.content().get(0);
     assertFalse(result.isError());
     assertEquals(expectedResult, content.text());
+
+    if (result.structuredContent() instanceof McpStructuredContent structuredContent) {
+      assertEquals(expectedResult, structuredContent.asTextContent());
+    }
   }
 }

src/test/java/com/github/codeboyzhou/mcp/declarative/test/TestMcpToolsStructuredContent.java

@@ -0,0 +1,39 @@
+package com.github.codeboyzhou.mcp.declarative.test;
+
+import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaProperty;
+import com.github.codeboyzhou.mcp.declarative.annotation.McpTool;
+import com.github.codeboyzhou.mcp.declarative.server.McpStructuredContent;
+
+public class TestMcpToolsStructuredContent {
+
+  public record TestStructuredContent(
+      @McpJsonSchemaProperty(description = "test int", required = true) int testInt,
+      @McpJsonSchemaProperty(description = "test integer") Integer testInteger,
+      @McpJsonSchemaProperty(description = "test long", required = true) long testLong,
+      @McpJsonSchemaProperty(description = "test long class") Long testLongClass,
+      @McpJsonSchemaProperty(description = "test float", required = true) float testFloat,
+      @McpJsonSchemaProperty(description = "test float class") Float testFloatClass,
+      @McpJsonSchemaProperty(description = "test double") double testDouble,
+      @McpJsonSchemaProperty(description = "test double class") Double testDoubleClass)
+      implements McpStructuredContent {
+
+    @Override
+    public String asTextContent() {
+      return String.format(
+          "testInt: %d, testInteger: %d, testLong: %d, testLongClass: %d, testFloat: %f, testFloatClass: %f, testDouble: %f, testDoubleClass: %f",
+          testInt,
+          testInteger,
+          testLong,
+          testLongClass,
+          testFloat,
+          testFloatClass,
+          testDouble,
+          testDoubleClass);
+    }
+  }
+
+  @McpTool
+  public TestStructuredContent toolWithReturnStructuredContent() {
+    return new TestStructuredContent(1, 2, 3L, 4L, 5.0F, 6.0F, 7.0, 8.0);
+  }
+}