refactor(annotation): Support @McpComponentScan and descriptionI18nKey() for backward compatibility

Author: codeboyzhou

src/main/java/com/github/codeboyzhou/mcp/declarative/common/GuiceInjectorModule.java

@@ -5,6 +5,7 @@
 import static org.reflections.scanners.Scanners.MethodsAnnotated;
 import static org.reflections.scanners.Scanners.TypesAnnotated;
 
+import com.github.codeboyzhou.mcp.declarative.annotation.McpComponentScan;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpI18nEnabled;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpPrompts;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpResources;
@@ -34,6 +35,12 @@ public GuiceInjectorModule(Class<?> mainClass) {
   @SuppressWarnings("unused")
   public Reflections provideReflections() {
     McpServerApplication application = mainClass.getAnnotation(McpServerApplication.class);
+    // Support @McpComponentScan for backward compatibility, will be removed in next version
+    if (application == null) {
+      McpComponentScan scan = mainClass.getAnnotation(McpComponentScan.class);
+      final String basePackage = determineBasePackage(scan);
+      return new Reflections(basePackage, TypesAnnotated, MethodsAnnotated, FieldsAnnotated);
+    }
     final String basePackage = determineBasePackage(application);
     return new Reflections(basePackage, TypesAnnotated, MethodsAnnotated, FieldsAnnotated);
   }
@@ -71,4 +78,17 @@ private String determineBasePackage(McpServerApplication application) {
     }
     return mainClass.getPackageName();
   }
+
+  @Deprecated
+  private String determineBasePackage(McpComponentScan scan) {
+    if (scan != null) {
+      if (!scan.basePackage().trim().isBlank()) {
+        return scan.basePackage();
+      }
+      if (scan.basePackageClass() != Object.class) {
+        return scan.basePackageClass().getPackageName();
+      }
+    }
+    return mainClass.getPackageName();
+  }
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerPromptFactory.java

@@ -44,7 +44,10 @@ public McpServerFeatures.AsyncPromptSpecification create(Class<?> clazz, Method
     McpPrompt promptMethod = method.getAnnotation(McpPrompt.class);
     final String name = StringHelper.defaultIfBlank(promptMethod.name(), method.getName());
     final String title = resolveComponentAttributeValue(promptMethod.title());
-    final String description = resolveComponentAttributeValue(promptMethod.description());
+    final String description =
+        resolveComponentAttributeValue(
+            StringHelper.defaultIfBlank(
+                promptMethod.description(), promptMethod.descriptionI18nKey()));
     List<McpSchema.PromptArgument> promptArguments = createPromptArguments(method);
     McpSchema.Prompt prompt = new McpSchema.Prompt(name, title, description, promptArguments);
     logger.debug("Registering prompt: {}", JsonHelper.toJson(prompt));
@@ -96,7 +99,10 @@ private List<McpSchema.PromptArgument> createPromptArguments(Method method) {
       McpPromptParam promptParam = param.getAnnotation(McpPromptParam.class);
       final String name = promptParam.name();
       final String title = resolveComponentAttributeValue(promptParam.title());
-      final String description = resolveComponentAttributeValue(promptParam.description());
+      final String description =
+          resolveComponentAttributeValue(
+              StringHelper.defaultIfBlank(
+                  promptParam.description(), promptParam.descriptionI18nKey()));
       final boolean required = promptParam.required();
       McpSchema.PromptArgument promptArgument =
           new McpSchema.PromptArgument(name, title, description, required);

src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerResourceFactory.java

@@ -37,7 +37,9 @@ public McpServerFeatures.AsyncResourceSpecification create(Class<?> clazz, Metho
     McpResource res = method.getAnnotation(McpResource.class);
     final String name = StringHelper.defaultIfBlank(res.name(), method.getName());
     final String title = resolveComponentAttributeValue(res.title());
-    final String description = resolveComponentAttributeValue(res.description());
+    final String description =
+        resolveComponentAttributeValue(
+            StringHelper.defaultIfBlank(res.description(), res.descriptionI18nKey()));
     McpSchema.Resource resource =
         McpSchema.Resource.builder()
             .uri(res.uri())

src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerToolFactory.java

@@ -49,7 +49,9 @@ public McpServerFeatures.AsyncToolSpecification create(Class<?> clazz, Method me
     McpTool toolMethod = method.getAnnotation(McpTool.class);
     final String name = StringHelper.defaultIfBlank(toolMethod.name(), method.getName());
     final String title = resolveComponentAttributeValue(toolMethod.title());
-    final String description = resolveComponentAttributeValue(toolMethod.description());
+    final String description =
+        resolveComponentAttributeValue(
+            StringHelper.defaultIfBlank(toolMethod.description(), toolMethod.descriptionI18nKey()));
     McpSchema.JsonSchema paramSchema = createJsonSchema(method);
     McpSchema.Tool tool =
         McpSchema.Tool.builder()
@@ -117,7 +119,11 @@ private McpSchema.JsonSchema createJsonSchema(Method method) {
 
       if (parameterType.getAnnotation(McpJsonSchemaDefinition.class) == null) {
         property.put("type", parameterType.getSimpleName().toLowerCase());
-        property.put("description", resolveComponentAttributeValue(toolParam.description()));
+        property.put(
+            "description",
+            resolveComponentAttributeValue(
+                StringHelper.defaultIfBlank(
+                    toolParam.description(), toolParam.descriptionI18nKey())));
       } else {
         final String parameterTypeSimpleName = parameterType.getSimpleName();
         property.put("$ref", "#/definitions/" + parameterTypeSimpleName);
@@ -163,7 +169,10 @@ private Map<String, Object> createJsonSchemaDefinition(Class<?> definitionClass)
 
       Map<String, Object> fieldProperties = new HashMap<>();
       fieldProperties.put("type", field.getType().getSimpleName().toLowerCase());
-      fieldProperties.put("description", resolveComponentAttributeValue(property.description()));
+      fieldProperties.put(
+          "description",
+          resolveComponentAttributeValue(
+              StringHelper.defaultIfBlank(property.description(), property.descriptionI18nKey())));
 
       final String fieldName = StringHelper.defaultIfBlank(property.name(), field.getName());
       properties.put(fieldName, fieldProperties);