feat(tool): Add support for complex JSON schema definitions

Author: codeboyzhou

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

@@ -0,0 +1,11 @@
+package com.github.codeboyzhou.mcp.declarative.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface McpJsonSchemaDefinition {
+}

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

@@ -0,0 +1,18 @@
+package com.github.codeboyzhou.mcp.declarative.annotation;
+
+import com.github.codeboyzhou.mcp.declarative.util.StringHelper;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface McpJsonSchemaDefinitionProperty {
+    String name() default StringHelper.EMPTY;
+
+    String description();
+
+    boolean required() default false;
+}

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

@@ -1,5 +1,7 @@
 package com.github.codeboyzhou.mcp.declarative.server;
 
+import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaDefinition;
+import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaDefinitionProperty;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpTool;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpToolParam;
 import com.github.codeboyzhou.mcp.declarative.util.ReflectionHelper;
@@ -64,26 +66,65 @@ public McpServerFeatures.SyncToolSpecification createComponentFrom(Class<?> claz
 
     private McpSchema.JsonSchema createJsonSchema(Method method) {
         Map<String, Object> properties = new HashMap<>();
+        Map<String, Object> definitions = new HashMap<>();
         List<String> required = new ArrayList<>();
 
         Set<Parameter> parameters = ReflectionHelper.getParametersAnnotatedWith(method, McpToolParam.class);
         for (Parameter parameter : parameters) {
             McpToolParam toolParam = parameter.getAnnotation(McpToolParam.class);
             final String parameterName = toolParam.name();
-            final String parameterType = parameter.getType().getName().toLowerCase();
+            Class<?> parameterType = parameter.getType();
+            Map<String, String> property = new HashMap<>();
 
-            Map<String, String> parameterProperties = Map.of(
-                "type", parameterType,
-                "description", toolParam.description()
-            );
-            properties.put(parameterName, parameterProperties);
+            if (parameterType.getAnnotation(McpJsonSchemaDefinition.class) == null) {
+                property.put("type", parameterType.getName().toLowerCase());
+                property.put("description", toolParam.description());
+            } else {
+                final String parameterTypeSimpleName = parameterType.getSimpleName();
+                property.put("$ref", "#/definitions/" + parameterTypeSimpleName);
+                Map<String, Object> definition = createJsonSchemaDefinition(parameterType);
+                definitions.put(parameterTypeSimpleName, definition);
+            }
+            properties.put(parameterName, property);
 
             if (toolParam.required()) {
                 required.add(parameterName);
             }
         }
 
-        return new McpSchema.JsonSchema(OBJECT_TYPE_NAME, properties, required, false);
+        final boolean hasAdditionalProperties = false;
+        return new McpSchema.JsonSchema(OBJECT_TYPE_NAME, properties, required, hasAdditionalProperties, definitions, definitions);
+    }
+
+    private Map<String, Object> createJsonSchemaDefinition(Class<?> definitionClass) {
+        Map<String, Object> definitionJsonSchema = new HashMap<>();
+        definitionJsonSchema.put("type", OBJECT_TYPE_NAME);
+
+        Map<String, Object> properties = new HashMap<>();
+        List<String> required = new ArrayList<>();
+
+        ReflectionHelper.doWithFields(definitionClass, field -> {
+            McpJsonSchemaDefinitionProperty property = field.getAnnotation(McpJsonSchemaDefinitionProperty.class);
+            if (property == null) {
+                return;
+            }
+
+            Map<String, Object> fieldProperties = new HashMap<>();
+            fieldProperties.put("type", field.getType().getName().toLowerCase());
+            fieldProperties.put("description", property.description());
+
+            final String fieldName = property.name().isBlank() ? field.getName() : property.name();
+            properties.put(fieldName, fieldProperties);
+
+            if (property.required()) {
+                required.add(fieldName);
+            }
+        });
+
+        definitionJsonSchema.put("properties", properties);
+        definitionJsonSchema.put("required", required);
+
+        return definitionJsonSchema;
     }
 
 }

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

@@ -3,11 +3,13 @@
 import io.modelcontextprotocol.spec.McpSchema;
 
 import java.lang.annotation.Annotation;
+import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 import java.lang.reflect.Parameter;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Set;
+import java.util.function.Consumer;
 
 import static java.util.stream.Collectors.toSet;
 
@@ -23,6 +25,13 @@ public static Set<Parameter> getParametersAnnotatedWith(Method method, Class<? e
         return Set.of(parameters).stream().filter(p -> p.isAnnotationPresent(annotation)).collect(toSet());
     }
 
+    public static void doWithFields(Class<?> clazz, Consumer<Field> consumer) {
+        Field[] declaredFields = clazz.getDeclaredFields();
+        for (Field field : declaredFields) {
+            consumer.accept(field);
+        }
+    }
+
     public static Object invokeMethod(Class<?> clazz, Method method) throws Exception {
         Object object = clazz.getDeclaredConstructor().newInstance();
         return method.invoke(object);
@@ -48,14 +57,16 @@ private static Map<String, Object> asTypedParameters(McpSchema.JsonSchema schema
             Object parameterValue = parameters.get(parameterName);
             if (parameterValue == null) {
                 Map<String, Object> map = (Map<String, Object>) parameterProperties;
-                final String parameterType = map.get("type").toString();
-                if (isTypeOf(String.class, parameterType)) {
-                    typedParameters.put(parameterName, "");
-                } else if (isTypeOf(Integer.class, parameterType)) {
+                final String jsonSchemaType = map.getOrDefault("type", StringHelper.EMPTY).toString();
+                if (jsonSchemaType.isEmpty()) {
+                    typedParameters.put(parameterName, null);
+                } else if (isTypeOf(String.class, jsonSchemaType)) {
+                    typedParameters.put(parameterName, StringHelper.EMPTY);
+                } else if (isTypeOf(Integer.class, jsonSchemaType)) {
                     typedParameters.put(parameterName, 0);
-                } else if (isTypeOf(Number.class, parameterType)) {
+                } else if (isTypeOf(Number.class, jsonSchemaType)) {
                     typedParameters.put(parameterName, 0.0);
-                } else if (isTypeOf(Boolean.class, parameterType)) {
+                } else if (isTypeOf(Boolean.class, jsonSchemaType)) {
                     typedParameters.put(parameterName, false);
                 }
             } else {

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

@@ -0,0 +1,7 @@
+package com.github.codeboyzhou.mcp.declarative.util;
+
+public final class StringHelper {
+
+    public static final String EMPTY = "";
+
+}

src/test/java/com/github/codeboyzhou/mcp/declarative/server/TestMcpToolComplexJsonSchema.java

@@ -0,0 +1,13 @@
+package com.github.codeboyzhou.mcp.declarative.server;
+
+import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaDefinition;
+import com.github.codeboyzhou.mcp.declarative.annotation.McpJsonSchemaDefinitionProperty;
+
+@McpJsonSchemaDefinition
+public record TestMcpToolComplexJsonSchema(
+    @McpJsonSchemaDefinitionProperty(name = "username", description = "username", required = true) String name,
+    @McpJsonSchemaDefinitionProperty(description = "country") String country,
+    String school // for testing property without annotation
+) {
+
+}

src/test/java/com/github/codeboyzhou/mcp/declarative/server/TestMcpTools.java

@@ -7,6 +7,7 @@
 @McpTools
 public class TestMcpTools {
 
+    @SuppressWarnings("unused")
     @McpTool(name = "tool1", description = "tool1")
     public static String tool1(
         @McpToolParam(name = "name", description = "name", required = true) String name,
@@ -15,6 +16,7 @@ public static String tool1(
         return "Hello " + name + ", I am " + version;
     }
 
+    @SuppressWarnings("unused")
     @McpTool(description = "tool2")
     public static String tool2(
         @McpToolParam(name = "name", description = "name") String name,
@@ -23,4 +25,13 @@ public static String tool2(
         return "Hello " + name + ", I am " + version;
     }
 
+    @SuppressWarnings("unused")
+    @McpTool(description = "tool3")
+    public static String tool3(
+        @McpToolParam(name = "complexJsonSchema", description = "complexJsonSchema")
+        TestMcpToolComplexJsonSchema complexJsonSchema
+    ) {
+        return String.format("Hello, my name is %s, I am from %s", complexJsonSchema.name(), complexJsonSchema.country());
+    }
+
 }