feat(i18n): Add i18n support for MCP server component description

codeboyzhou · codeboyzhou · commit d8570c3e9563 · 2025-06-09T00:51:35.000+08:00
- Introduce ResourceBundle for handling localized descriptions
- Add descriptionI18nKey field to relevant annotations
- Update factory classes to use localized descriptions
- Modify getDescription method to handle both localized and default descriptions
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaDefinitionProperty.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaDefinitionProperty.java
@@ -12,7 +12,10 @@
 public @interface McpJsonSchemaDefinitionProperty {
     String name() default StringHelper.EMPTY;
 
-    String description();
+    String description() default StringHelper.EMPTY;
+
+    String descriptionI18nKey() default StringHelper.EMPTY;
 
     boolean required() default false;
+
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPrompt.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPrompt.java
@@ -13,5 +13,8 @@
 
     String name() default StringHelper.EMPTY;
 
-    String description();
+    String description() default StringHelper.EMPTY;
+
+    String descriptionI18nKey() default StringHelper.EMPTY;
+
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPromptParam.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPromptParam.java
@@ -1,5 +1,7 @@
 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;
@@ -11,7 +13,10 @@
 
     String name();
 
-    String description();
+    String description() default StringHelper.EMPTY;
+
+    String descriptionI18nKey() default StringHelper.EMPTY;
 
     boolean required() default false;
+
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpResource.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpResource.java
@@ -15,11 +15,14 @@
 
     String name() default StringHelper.EMPTY;
 
-    String description();
+    String description() default StringHelper.EMPTY;
+
+    String descriptionI18nKey() default StringHelper.EMPTY;
 
     String mimeType() default "text/plain";
 
     McpSchema.Role[] roles() default {McpSchema.Role.ASSISTANT, McpSchema.Role.USER};
 
     double priority() default 1.0;
+
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpTool.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpTool.java
@@ -13,5 +13,8 @@
 
     String name() default StringHelper.EMPTY;
 
-    String description();
+    String description() default StringHelper.EMPTY;
+
+    String descriptionI18nKey() default StringHelper.EMPTY;
+
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpToolParam.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpToolParam.java
@@ -1,5 +1,7 @@
 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;
@@ -10,7 +12,10 @@
 public @interface McpToolParam {
     String name();
 
-    String description();
+    String description() default StringHelper.EMPTY;
+
+    String descriptionI18nKey() default StringHelper.EMPTY;
 
     boolean required() default false;
+
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/AbstractMcpServerComponentFactory.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/AbstractMcpServerComponentFactory.java
@@ -2,12 +2,28 @@
 
 import com.google.inject.Injector;
 
+import java.util.Locale;
+import java.util.ResourceBundle;
+
 public abstract class AbstractMcpServerComponentFactory<T> implements McpServerComponentFactory<T> {
 
     protected final Injector injector;
 
+    private final ResourceBundle bundle;
+
     protected AbstractMcpServerComponentFactory(Injector injector) {
         this.injector = injector;
+        this.bundle = ResourceBundle.getBundle("i18n/mcp_server_component_descriptions", Locale.getDefault());
+    }
+
+    protected String getDescription(String descriptionI18nKey, String description) {
+        if (!descriptionI18nKey.isBlank() && bundle.containsKey(descriptionI18nKey)) {
+            bundle.getString(descriptionI18nKey);
+        }
+        if (!description.isBlank()) {
+            return description;
+        }
+        return "No description provided.";
     }
 
 }
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerPromptFactory.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerPromptFactory.java
@@ -38,7 +38,7 @@ protected McpServerPromptFactory(Injector injector) {
     public McpServerFeatures.AsyncPromptSpecification create(Class<?> clazz, Method method) {
         McpPrompt promptMethod = method.getAnnotation(McpPrompt.class);
         final String name = promptMethod.name().isBlank() ? method.getName() : promptMethod.name();
-        final String description = promptMethod.description();
+        final String description = getDescription(promptMethod.descriptionI18nKey(), promptMethod.description());
         List<McpSchema.PromptArgument> promptArguments = createPromptArguments(method);
         McpSchema.Prompt prompt = new McpSchema.Prompt(name, description, promptArguments);
         logger.debug("Registering prompt: {}", JsonHelper.toJson(prompt));
@@ -83,7 +83,7 @@ private List<McpSchema.PromptArgument> createPromptArguments(Method method) {
         for (Parameter param : params) {
             McpPromptParam promptParam = param.getAnnotation(McpPromptParam.class);
             final String name = promptParam.name();
-            final String description = promptParam.description();
+            final String description = getDescription(promptParam.descriptionI18nKey(), promptParam.description());
             final boolean required = promptParam.required();
             McpSchema.PromptArgument promptArgument = new McpSchema.PromptArgument(name, description, required);
             promptArguments.add(promptArgument);
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerResourceFactory.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerResourceFactory.java
@@ -31,10 +31,9 @@ protected McpServerResourceFactory(Injector injector) {
     public McpServerFeatures.AsyncResourceSpecification create(Class<?> clazz, Method method) {
         McpResource res = method.getAnnotation(McpResource.class);
         final String name = res.name().isBlank() ? method.getName() : res.name();
-        McpSchema.Resource resource = new McpSchema.Resource(
-            res.uri(), name, res.description(), res.mimeType(),
-            new McpSchema.Annotations(List.of(res.roles()), res.priority())
-        );
+        final String description = getDescription(res.descriptionI18nKey(), res.description());
+        McpSchema.Annotations annotations = new McpSchema.Annotations(List.of(res.roles()), res.priority());
+        McpSchema.Resource resource = new McpSchema.Resource(res.uri(), name, description, res.mimeType(), annotations);
         logger.debug("Registering resource: {}", JsonHelper.toJson(resource));
         return new McpServerFeatures.AsyncResourceSpecification(resource, (exchange, request) ->
             Mono.fromSupplier(() -> {
diff --git a/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerToolFactory.java b/src/main/java/com/github/codeboyzhou/mcp/declarative/server/factory/McpServerToolFactory.java
@@ -45,7 +45,8 @@ public McpServerFeatures.AsyncToolSpecification create(Class<?> clazz, Method me
         McpTool toolMethod = method.getAnnotation(McpTool.class);
         McpSchema.JsonSchema paramSchema = createJsonSchema(method);
         final String name = toolMethod.name().isBlank() ? method.getName() : toolMethod.name();
-        McpSchema.Tool tool = new McpSchema.Tool(name, toolMethod.description(), paramSchema);
+        final String description = getDescription(toolMethod.descriptionI18nKey(), toolMethod.description());
+        McpSchema.Tool tool = new McpSchema.Tool(name, description, paramSchema);
         logger.debug("Registering tool: {}", JsonHelper.toJson(tool));
         return new McpServerFeatures.AsyncToolSpecification(tool, (exchange, params) ->
             Mono.fromSupplier(() -> {
@@ -98,7 +99,7 @@ private McpSchema.JsonSchema createJsonSchema(Method method) {
 
             if (parameterType.getAnnotation(McpJsonSchemaDefinition.class) == null) {
                 property.put("type", parameterType.getSimpleName().toLowerCase());
-                property.put("description", toolParam.description());
+                property.put("description", getDescription(toolParam.descriptionI18nKey(), toolParam.description()));
             } else {
                 final String parameterTypeSimpleName = parameterType.getSimpleName();
                 property.put("$ref", "#/definitions/" + parameterTypeSimpleName);
@@ -135,7 +136,7 @@ private Map<String, Object> createJsonSchemaDefinition(Class<?> definitionClass)
 
             Map<String, Object> fieldProperties = new HashMap<>();
             fieldProperties.put("type", field.getType().getSimpleName().toLowerCase());
-            fieldProperties.put("description", property.description());
+            fieldProperties.put("description", getDescription(property.descriptionI18nKey(), property.description()));
 
             final String fieldName = property.name().isBlank() ? field.getName() : property.name();
             properties.put(fieldName, fieldProperties);
diff --git a/src/test/resources/i18n/mcp_server_component_descriptions.properties b/src/test/resources/i18n/mcp_server_component_descriptions.properties

Original file line number	Diff line number	Diff line change
`@@ -13,5 +13,8 @@`
`13`	`13`
`14`	`14`	`String name() default StringHelper.EMPTY;`
`15`	`15`
`16`		`- String description();`
	`16`	`+ String description() default StringHelper.EMPTY;`
	`17`	`+`
	`18`	`+ String descriptionI18nKey() default StringHelper.EMPTY;`
	`19`	`+`
`17`	`20`	`}`